特性
Mingling 的所有特性一览
## 特性 `all_serde_fmt`
**介绍:**
为 `general_renderer` 启用所有序列化格式（JSON、RON、TOML、YAML）的 serde 格式化支持。
开启此特性将自动启用 `json_serde_fmt`、`ron_serde_fmt`、`toml_serde_fmt`、`yaml_serde_fmt` 四个子特性。
## 特性 `async`
**介绍:**
启用异步运行时支持，允许 `#[chain]` 绑定 `async` 函数，例如：
```rust
// Features: ["async"]
pack!(StateFoo = ());
#[chain]
async fn handle_state_foo(foo: StateFoo) -> Next {
StateFoo::new(())
}
```
详见 [示例](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-async-support)
## 特性 `builds`
**介绍:**
启用部分需要在 `build.rs` 使用的脚本，目前包含：
1. `comp` 特性下的补全脚本生成：
```rust
// Features: ["builds", "comp"]
use mingling::build::build_comp_scripts;
fn main() {
// 为 `myprogram` 生成补全脚本
build_comp_scripts("myprogram").unwrap();
}
```
## 特性 `clap`
**介绍:**
启用与 [clap](https://crates.io/crates/clap) 命令行参数解析库的集成，方便构建 CLI 应用程序。
开启此特性后，可以使用 `#[dispatcher_clap]` 属性宏从 `clap::Parser` 结构体生成 dispatcher。
详见 [示例](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-clap-binding)
## 特性 `comp`
**介绍:**
启用代码补全功能，为交互式环境提供自动补全支持。
开启后可以使用 `#[completion]` 属性宏定义动态补全逻辑，并支持为 bash、zsh、fish、pwsh 等 shell 生成补全脚本。
详见 [示例](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-completion)
## 特性 `debug`
**介绍:**
启用调试相关功能，提供更详细的错误信息和诊断输出。
## 特性 `dispatch_tree`
**介绍:**
启用调度树机制，支持基于条件的分发和路由功能。
开启后，Mingling 在**编译时**将子命令结构硬编码为前缀树（Trie），实现极速的子命令查找。查找复杂度为 **O(n)**，其中 _n_ 是输入长度，而非命令数量。
详见 [示例](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-dispatch-tree)
## 特性 `extra_macros`
**介绍:**
启用额外的宏集合，提供更多便捷的语法糖和元编程能力。
例如，允许 `dispatcher!("greet")` 的缩写形式，自动生成 `CMDGreet` / `EntryGreet`。
| 宏 | 说明 |
|---|---|
| `empty_result!()` | 链中提前返回空结果的简写 |
| `entry!(Type, ["a", "b"])` | 构造入口类型的测试数据 |
| `#[program_setup]` | 声明程序初始化函数 |
| `dispatcher!("cmd.path")` **缩写形式** | 省略 `CMDStruct => EntryStruct`，名字自动推导 |
Details
### `empty_result!()`
```rust
// Features: ["extra_macros"]
pack!(StatePrev1 = ());
pack!(StatePrev2 = ());
pack!(StateNext = ());
#[chain]
fn handle_state_prev2(_p: StatePrev1) {
// 无 Next 的 #[chain] 可以直接不返回值
}
#[chain]
fn handle_state_prev1(_p: StatePrev1) -> Next {
let foo = 1;
let bar = 2;
if foo != bar {
// 当需要 Next 且不需要返回值，便可以使用它
empty_result!()
} else {
StateNext::new(()).into()
}
}
```
### `#[program_setup]`
```rust
// Features: ["extra_macros"]
use mingling::{macros::program_setup, Program};
fn main() {
let mut program = ThisProgram::new();
program.with_setup(NoErrorSetup);
program.exec_and_exit();
}
#[program_setup]
fn no_error_setup(program: &mut Program) {
program.global_flag(["--no-error"], |program| {
program.stdout_setting.error_output = false;
});
}
```
### `entry!`
```rust
// Features: ["extra_macros"]
use mingling::macros::entry;
pack!(EntryHello = Vec);
fn main() {
let result = handle_hello(entry!("--name", "Bob")).into();
// ... 此处为断言逻辑
}
#[chain]
fn handle_hello(args: EntryHello) {}
```
## 特性 `general_renderer`
**介绍:**
启用通用渲染器，提供基础的内容渲染能力。开启此特性将自动启用 `json_serde_fmt`。
开启后，用户可以通过 `--json` 或 `--yaml` 等标志获取结构化输出。
详见 [示例](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-general-renderer)
## 特性 `general_renderer_empty`
**介绍:**
启用通用渲染器的空实现版本，适用于不需要实际渲染功能的场景。此特性不启用任何 serde 格式化后端。
## 特性 `general_renderer_full`
**介绍:**
启用通用渲染器的完整实现，包含所有渲染功能和序列化格式支持。开启此特性将自动启用 `all_serde_fmt`。
## 特性 `json_serde_fmt`
**介绍:**
启用 JSON 格式的 serde 序列化/反序列化格式化支持。
## 特性 `nightly`
**介绍:**
启用仅在不稳定（Nightly）Rust 编译器中可用的实验性功能。
## 特性 `parser`
**介绍:**
启用解析器模块，提供文本解析和语法分析功能。
开启后可以使用 `Picker` 进行零成本的参数提取，支持 `pick()` 和 `pick_or()` 等方法。
详见 [示例](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-argument-parse)
## 特性 `repl`
**介绍:**
启用交互式 REPL（Read-Eval-Print Loop）环境支持。
开启后，可以通过 `program.exec_repl()` 将 CLI 转变为交互式 shell。
详见 [示例](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-repl-basic)
## 特性 `ron_serde_fmt`
**介绍:**
启用 RON（Rusty Object Notation）格式的 serde 序列化/反序列化格式化支持。
## 特性 `toml_serde_fmt`
**介绍:**
启用 TOML 格式的 serde 序列化/反序列化格式化支持。
## 特性 `yaml_serde_fmt`
**介绍:**
启用 YAML 格式的 serde 序列化/反序列化格式化支持。
Written by @Weicao-CatilGrass