aboutsummaryrefslogtreecommitdiff
path: root/docs/pages/11-resource-system.md
diff options
context:
space:
mode:
author魏曹先生 <1992414357@qq.com>2026-06-30 18:05:05 +0800
committer魏曹先生 <1992414357@qq.com>2026-06-30 18:05:05 +0800
commit13408e79b940e9a33ca593ed30d1b20c54e01234 (patch)
tree282549991a3f31791401ca2f3255b9318679d2e9 /docs/pages/11-resource-system.md
parent29867ab5c0b40378a33318d989c809f90fc7d3aa (diff)
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
Diffstat (limited to 'docs/pages/11-resource-system.md')
-rw-r--r--docs/pages/11-resource-system.md89
1 files changed, 89 insertions, 0 deletions
diff --git a/docs/pages/11-resource-system.md b/docs/pages/11-resource-system.md
new file mode 100644
index 0000000..b54938a
--- /dev/null
+++ b/docs/pages/11-resource-system.md
@@ -0,0 +1,89 @@
+<h1 align="center">Using the Resource System</h1>
+<p align="center">
+ A hands-on guide to resources
+</p>
+
+Resources are Mingling's mechanism for managing global state. Any type that implements `Default + Clone` can be a resource.
+
+## Define a Resource
+
+```rust
+// Any type implementing Default + Clone can be used as a resource
+#[derive(Default, Clone)]
+struct ResCurrentDir(String);
+
+// Register with the Program
+fn main() {
+ let mut program = ThisProgram::new();
+ program.with_resource(ResCurrentDir(".".into()));
+ program.exec_and_exit();
+}
+```
+
+Since `ResCurrentDir` implements both `Default` and `Clone`, the framework automatically implements `ResourceMarker` for it — no manual impl needed.
+
+## Inject & Use
+
+In a Chain or Renderer, simply declare the resource in the parameter list:
+
+```rust
+@@@#[derive(Default, Clone)]
+@@@struct ResCurrentDir(String);
+@@@dispatcher!("pwd", CMDPrintWorkingDir => EntryPrintWorkingDir);
+@@@pack!(ResultPath = String);
+// Inject read-only resource via &T
+#[chain]
+fn handle_pwd(_args: EntryPrintWorkingDir, cwd: &ResCurrentDir) -> Next {
+ ResultPath::new(cwd.0.clone()).to_render()
+}
+
+#[renderer]
+fn render_path(result: ResultPath) {
+ r_println!("{}", *result);
+}
+```
+
+## Modify a Resource
+
+Use `&mut T` to inject a mutable resource:
+
+```rust
+@@@#[derive(Default, Clone)]
+@@@struct ResVisitCount(u32);
+@@@dispatcher!("visit", CMDVisit => EntryVisit);
+@@@pack!(ResultDone = ());
+#[chain]
+fn handle_visit(_args: EntryVisit, counter: &mut ResVisitCount) -> Next {
+ counter.0 += 1;
+ ResultDone::default()
+}
+
+#[renderer]
+fn render_done(_done: ResultDone, counter: &ResVisitCount) {
+ r_println!("visit count is : {}", counter.0);
+}
+```
+
+## Use Multiple Resources
+
+A Chain can inject any number of resources at once — the framework matches them by type automatically:
+
+```rust
+@@@#[derive(Default, Clone)] struct ResConfig(String);
+@@@#[derive(Default, Clone)] struct ResCounter(u32);
+@@@dispatcher!("test", CMDTest => EntryTest);
+@@@pack!(ResultDone = ());
+// Inject both read-only and mutable resources
+#[chain]
+fn handle_test(_args: EntryTest, config: &ResConfig, counter: &mut ResCounter) -> Next {
+ println!("config: {}", config.0);
+ counter.0 += 1;
+ ResultDone::default().to_render()
+}
+```
+
+For deeper topics like `ResourceMarker`, lazy loading with `LazyRes`, etc., see [Core Concepts: Resource System](pages/concepts/2-resource).
+
+<p align="center" style="font-size: 0.85em; color: gray;">
+ Written by @Weicao-CatilGrass
+</p>