配置变量

通过字符串类型API配置程序状态。

简介

当应用程序完成特定任务并退出时，配置可以在启动时加载并存储在专用配置对象中。

当应用程序长时间运行时，这可能不够，它可能希望

• 逐个更改配置设置。
• 配置的复杂分层组织。
• 一个可以查询和更新配置状态的接口。
• 可执行操作而不是只是变量。
• 支持需要其自己的配置的附加组件，这些配置位于前缀下。
• 支持在运行时创建的动态配置。

用法

此crate位于crates.io上，文档位于docs.rs。

在你的Cargo.toml中

[dependencies]
cvar = "0.3"

示例

有关特定主题和技术的更多示例，请参阅示例。

使用以下示例在本地上运行：cargo run --example readme-example。

pub struct ProgramState {
	number: i32,
	text: String,
}

impl ProgramState {
	pub fn poke(&mut self, args: &str) {
		self.text = format!("{}: {}", args, self.number);
	}
}

首先定义要交互的状态。这是普通的Rust代码，目的是你有一些需要通过字符串类型API进行交互的长期状态。

impl cvar::IVisit for ProgramState {
	fn visit(&mut self, f: &mut dyn FnMut(&mut dyn cvar::INode)) {
		f(&mut cvar::Property("number", &mut self.number, &42));
		f(&mut cvar::Property("text", &mut self.text, &String::new()));
		f(&mut cvar::Action("poke!", |args, _writer| self.poke(args)));
	}
}

下一步是实现IVisit特质。这个特质是这个crate功能的核心。

它的visit方法允许调用者发现结构中的交互元素。以“节点”类型（如Property或Action）包装所有交互元素并调用闭包。

注意节点的不确定性，这非常适合Rust的所有权模型，并避免了与借用检查器的冲突，因为节点暂时包装在底层变量和方法周围。

let mut program_state = ProgramState {
	number: 42,
	text: String::new(),
};

获得对程序状态的独特访问...

assert_eq!(cvar::console::get(&mut program_state, "number").unwrap(), "42");

cvar::console::set(&mut program_state, "number", "13").unwrap();
assert_eq!(program_state.number, 13);

通过控制台界面按文本名称和值获取或设置属性。

let mut writer = String::new();
cvar::console::invoke(&mut program_state, "poke!", "the value is", &mut writer);
assert_eq!(program_state.text, "the value is: 13");

通过访问者在其中定义的操作调用方法。

设计

配置是与程序状态交互的界面。用户通过文本进行交互，而程序有它们首选的数据类型。

配置管理器的目标是促进这种交互。这个库的范围更窄，仅提供识别可配置元素并通过文本与之交互的方法。

可配置的元素被称为 节点。每个 节点 都有一个 名称。节点有三种类型：属性、列表 和 动作。

• 属性 存储变量，并具有 默认值。

• 列表 定义一个层次结构。它包含 子节点。层次结构中的名称用点分隔，例如：list.foo。

• 动作 是可以带参数字符串调用的节点。它可以在其上下文中执行任意代码。

节点是短暂的，这意味着它们不会在程序状态旁边和穿插中存储其元数据。这避免了需要长时间持有的借用，并具有其他性能优势。

尽管提供了通用实现，但每个节点类型都是一个特质，可以具有自定义实现。

未来工作

实现标识符的自动补全以及属性值和动作的建议。

实现枚举和枚举标志支持的助手。

许可证

根据 MIT 许可证 许可，请参阅 license.txt。

贡献

除非您明确说明，否则您有意提交以包含在您的工作中的任何贡献，均应按照上述方式许可，不附加任何额外条款或条件。