# config_rw

**Repository Path**: guoyucode/config_rw

## Basic Information

- **Project Name**: config_rw
- **Description**: rust实现: 配置文件读取与写入
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-27
- **Last Updated**: 2026-01-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Config RW

**Thread-safe Configuration Management Library with Read/Write and Auto Hot-Reload**  
**线程安全的配置管理库，支持读写操作及自动热重载**

## 🚀 Features | 特性

*   **Read & Write Config** | **配置读写**  
    Type-safe access (String, Integer, Float, Bool, JSON) with auto-save capability.  
    类型安全的访问（支持字符串、整数、浮点、布尔、JSON），更改会自动保存到文件。

*   **Auto Callback on Value Change** | **值变化自动回调**  
    Register callbacks triggered on any configuration value change (internal or external).  
    注册回调函数，当配置值发生任何变化时自动触发（支持内部和外部修改）。

*   **Key-specific Value Callbacks** | **特定键值回调** ✨ NEW  
    Monitor specific keys with type-safe generic callbacks (`Option<T: DeserializeOwned>`).  
    监听特定键的值变化，支持泛型类型安全回调（`Option<T: DeserializeOwned>`）。

*   **Thread Safety** | **线程安全**  
    Safe for concurrent access using `Arc` and `RwLock`.  
    基于 `Arc` 和 `RwLock` 保证并发访问安全。

## 📦 Installation | 安装

Add to `Cargo.toml` | 添加到 `Cargo.toml`:

```toml
[dependencies]
config_rw = "2.2.0"
```

## 💡 Usage Example | 使用示例

```rust
use std::sync::LazyLock;
use config_rw::ConfigState;

// Initialize global config instance
// 初始化全局配置实例
static CONFIG: LazyLock<ConfigState> = LazyLock::new(|| {
    ConfigState::init_config("config.toml")
});

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Register Global Change Callback
    //    Triggered on any value change (internal or external)
    // 1. 注册全局变更回调
    //    任何值变化时触发（内部或外部修改）
    CONFIG.add_change_callback(|config| {
        let new_val = config.get_string("app.name").unwrap_or_default();
        println!("📝 Config changed! app.name: {}", new_val);
    });

    // 2. Register Key-specific Value Callback (Generic)
    //    Callback receives Option<T>, fired immediately and on changes
    // 2. 注册特定键值回调（泛型版本）
    //    回调接收 Option<T>，添加时立即触发一次，之后值变化时触发
    CONFIG.add_callback_value("database.host", |v: Option<String>| {
        match v {
            Some(host) => println!("🔗 Host: {}", host),
            None => println!("⚠️ Host is null or deleted"),
        }
    });

    CONFIG.add_callback_value("database.port", |v: Option<i64>| {
        if let Some(port) = v {
            println!("🔌 Port: {}", port);
        }
    });

    CONFIG.add_callback_value("app.debug", |v: Option<bool>| {
        if let Some(debug) = v {
            println!("🐛 Debug mode: {}", debug);
        }
    });

    // 3. Write Configuration (Thread-safe & Auto-saved)
    //    Triggers callbacks when value actually changes
    // 3. 写入配置（线程安全且自动保存）
    //    当值真正发生变化时触发回调
    CONFIG.set_string("app.name", "MyApplication".to_string())?;
    CONFIG.set_i64("server.port", 8080)?;
    CONFIG.set_bool("app.debug", true)?;

    // 4. Read Configuration
    // 4. 读取配置
    let app_name = CONFIG.get_string("app.name").unwrap_or_default();
    println!("📖 App Name: {}", app_name);

    // Keep running - callbacks fire automatically on file changes
    // 保持运行 - 文件变化时回调会自动触发
    loop {
        std::thread::sleep(std::time::Duration::from_secs(1));
    }
}
```

## 📚 API Overview | API 概览

### Reading | 读取
*   `get_string("key")` → `Option<String>`
*   `get_i64("key")` → `Option<i64>`
*   `get_f64("key")` → `Option<f64>`
*   `get_bool("key")` → `Option<bool>`
*   `get_value("key")` → `Value` (serde_json)

### Writing | 写入
*   `set_string("key", val)` → `Result<()>`
*   `set_i64("key", val)` → `Result<()>`
*   `set_f64("key", val)` → `Result<()>`
*   `set_bool("key", val)` → `Result<()>`
*   `set_value("key", val)` → `Result<()>` (serde_json Value)

### Callbacks | 回调
*   `add_change_callback(Fn(Arc<ConfigArc>))` → Triggered on any value change / 任何值变化时触发
*   `add_callback_value<T>("key", Fn(Option<T>))` → Key-specific callback with generic type / 特定键泛型回调 ✨ NEW

### Lifecycle | 生命周期
*   `init_config("path")` → Initialize / 初始化
*   `get_arc()` → Get `Arc<ConfigArc>` reference / 获取内部 Arc 引用
*   `unload_watch()` → Stop file watcher / 停止文件监听

## 🔄 Changelog | 更新日志

### v2.2.0
- ✨ 新增 `add_callback_value<T, F>()` 泛型方法，支持 `Option<T: DeserializeOwned>` 类型回调
- 🔧 `add_change_callback` 现在对内部和外部修改都会触发（仅当值真正变化时）
- 🔧 新增 `ConfigState` 包装方法：`set_value`, `set_string`, `set_i64`, `set_f64`, `set_bool`
- 🔧 新增 `get_arc()` 方法获取内部 `Arc<ConfigArc>` 引用
- 🔧 新增 `serde` 依赖支持泛型反序列化

### v2.1.x
- 配置热重载和外部文件监听
- 双缓冲配置文档设计

## 📄 License | 许可证

MIT / Apache-2.0