blob: d38e69d4f482947c29f204ccdaf82ae896128be7 (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
|
<h1 align="center">程序装配</h1>
<p align="center">
用 Setup 初始化你的程序
</p>
当程序启动时需要做一些初始化工作——比如解析全局参数、注册资源——你可以用 `#[program_setup]` 来组织这些逻辑。
## 用 Setup 做初始化
```rust
// Features: ["extra_macros"]
@@@use mingling::macros::program_setup;
@@@use mingling::Program;
#[program_setup]
fn my_setup(program: &mut Program<ThisProgram>) {
// 从参数中提取全局标志
program.global_flag(["-v", "--verbose"], |program| {
program.stdout_setting.verbose = true;
});
}
@@@
@@@fn main() {
@@@ let mut program = ThisProgram::new();
@@@ program.with_setup(MySetup);
@@@ program.exec_and_exit();
@@@}
@@@gen_program!();
```
`#[program_setup]` 标记的函数接收 `&mut Program<ThisProgram>`，你可以在里面做任何初始化操作。
在 `main` 里通过 `program.with_setup(...)` 注册即可使用。
> [!NOTE]
> `#[program_setup]` 需要 `extra_macros` 特性。没有此特性时，可以手动实现 `ProgramSetup` trait。
## 提取全局参数
Setup 里最常用的操作就是提取全局参数。Mingling 提供了几个辅助方法：
```rust
// Features: ["extra_macros"]
@@@use mingling::macros::program_setup;
@@@use mingling::Program;
#[program_setup]
fn my_setup(program: &mut Program<ThisProgram>) {
// 布尔标志
program.global_flag(["-v", "--verbose"], |program| {
program.stdout_setting.verbose = true;
});
// 带值的参数
program.global_argument("--name", |_program, value| {
// value 就是 "Alice"
let _ = value;
});
}
```
> [!TIP]
> `global_flag` 和 `global_argument` 会自动从 `program.args` 中移除已匹配的参数，这些参数不会进入管线。
## 内置 Setup
Mingling 提供了一些开箱即用的 Setup，覆盖了 CLI 程序最常见的需求：
| Setup | 功能 |
| --------------------------- | --------------------------------------------------------------------- |
| `BasicProgramSetup` | 解析 `--help`/`-h`、`--quiet`/`-q`、`--confirm`/`-C` |
| `DirectoryEnvironmentSetup` | 注册目录资源：当前目录、可执行目录、Home 目录、临时目录 |
| `ExitCodeSetup` | 通过 `ResExitCode` 控制程序退出码 |
| `StructuralRendererSetup` | 启用 `--json`、`--yaml` 等结构化输出（需 `structural_renderer` 特性） |
用法就是在 `main` 里加一行：
```rust
@@@use mingling::setup::BasicProgramSetup;
fn main() {
let mut program = ThisProgram::new();
program.with_setup(BasicProgramSetup);
program.exec_and_exit();
}
```
`BasicProgramSetup` 帮你处理了绝大多数 CLI 程序都需要的通用参数，省去自己手动解析的麻烦。
<p align="center" style="font-size: 0.85em; color: gray;">
Written by @Weicao-CatilGrass
</p>
|
