From 13408e79b940e9a33ca593ed30d1b20c54e01234 Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Tue, 30 Jun 2026 18:05:05 +0800
Subject: feat(docs): add Chinese and English documentation for Mingling
tutorials
Add comprehensive documentation covering Declare a Dispatcher, Declare a
Chain, Rendering Results, Multi-Command Program, Argument Parsing with
Picker and Clap, Program Setup, Error Handling, Help Info, Resource
System, Exit Code Control, Hook System, Testing, Completion, Structural
Rendering, and Core Concepts
---
docs/pages/8-setup-and-resources.md | 89 +++++++++++++++++++++++++++++++++++++
1 file changed, 89 insertions(+)
create mode 100644 docs/pages/8-setup-and-resources.md
(limited to 'docs/pages/8-setup-and-resources.md')
diff --git a/docs/pages/8-setup-and-resources.md b/docs/pages/8-setup-and-resources.md
new file mode 100644
index 0000000..3858e99
--- /dev/null
+++ b/docs/pages/8-setup-and-resources.md
@@ -0,0 +1,89 @@
+Program Setup
+
+ Initialize your program with Setup
+
+
+When a program needs to do some init work at startup—like parsing global args or registering resources—you can organize that logic with `#[program_setup]`.
+
+## Initialize with Setup
+
+```rust
+// Features: ["extra_macros"]
+@@@use mingling::macros::program_setup;
+@@@use mingling::Program;
+#[program_setup]
+fn my_setup(program: &mut Program) {
+ // Extract global flag from args
+ 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!();
+```
+
+A function annotated with `#[program_setup]` receives `&mut Program`, where you can do any init work.
+
+Register it in `main` via `program.with_setup(...)` to use it.
+
+> [!NOTE]
+> `#[program_setup]` requires the `extra_macros` feature. Without it, you can manually implement the `ProgramSetup` trait.
+
+## Extract Global Args
+
+The most common use of Setup is extracting global args. Mingling provides a few helper methods:
+
+```rust
+// Features: ["extra_macros"]
+@@@use mingling::macros::program_setup;
+@@@use mingling::Program;
+#[program_setup]
+fn my_setup(program: &mut Program) {
+ // Boolean flag
+ program.global_flag(["-v", "--verbose"], |program| {
+ program.stdout_setting.verbose = true;
+ });
+
+ // Flag with a value
+ program.global_argument("--name", |_program, value| {
+ // value is "Alice"
+ let _ = value;
+ });
+}
+```
+
+> [!TIP]
+> `global_flag` and `global_argument` automatically remove matched args from `program.args`, so they won't enter the pipeline.
+
+## Built-in Setup
+
+Mingling provides several ready-to-use Setups covering the most common CLI program needs:
+
+| Setup | Functionality |
+| --------------------------- | ------------------------------------------------------------------------------------------ |
+| `BasicProgramSetup` | Parses `--help`/`-h`, `--quiet`/`-q`, `--confirm`/`-C` |
+| `DirectoryEnvironmentSetup` | Registers directory resources: current dir, executable dir, home dir, temp dir |
+| `ExitCodeSetup` | Controls program exit code via `ResExitCode` |
+| `StructuralRendererSetup` | Enables `--json`, `--yaml` etc. structured output (requires `structural_renderer` feature) |
+
+Usage is just one line in `main`:
+
+```rust
+@@@use mingling::setup::BasicProgramSetup;
+fn main() {
+ let mut program = ThisProgram::new();
+ program.with_setup(BasicProgramSetup);
+ program.exec_and_exit();
+}
+```
+
+`BasicProgramSetup` handles common params that most CLI programs need, saving you the trouble of manual parsing.
+
+
+ Written by @Weicao-CatilGrass
+
--
cgit