From 7d0cb15f58a0bec5c9fa29757ee5007c0a78f287 Mon Sep 17 00:00:00 2001 From: 魏曹先生 <1992414357@qq.com> Date: Mon, 20 Apr 2026 15:23:40 +0800 Subject: Add async feature documentation Add new async feature page and update sidebar and features list. Rename section headers in parser and general renderer for consistency. Expand completion documentation with usage and script generation details. --- docs/_sidebar.md | 1 + docs/pages/3-features.md | 1 + docs/pages/3-features/1-parser.md | 2 +- docs/pages/3-features/2-general-renderer.md | 2 +- docs/pages/3-features/3-comp.md | 111 ++++++++++++++++++++++++++++ docs/pages/3-features/4-async.md | 6 ++ 6 files changed, 121 insertions(+), 2 deletions(-) create mode 100644 docs/pages/3-features/4-async.md diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 45486aa..c893e72 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -12,3 +12,4 @@ - [Parser](./pages/3-features/1-parser) - [General Renderer](./pages/3-features/2-general-renderer) - [Completion](./pages/3-features/3-comp) + - [Async](./pages/3-features/4-async) diff --git a/docs/pages/3-features.md b/docs/pages/3-features.md index 04774ac..a2eac63 100644 --- a/docs/pages/3-features.md +++ b/docs/pages/3-features.md @@ -12,3 +12,4 @@ Mingling provides the following features for use: | [Parser](./pages/3-features/1-parser) | Converts user input into structured data | | [General Renderer](./pages/3-features/2-general-renderer) | Enables the `Renderer` to support serialization into different output formats | | [Completion](./pages/3-features/3-comp) | Enables the program to support dynamic command-line completion | +| [Async](./pages/3-features/4-async) | Provides async execution capabilities | diff --git a/docs/pages/3-features/1-parser.md b/docs/pages/3-features/1-parser.md index 75a83d8..9c48cfd 100644 --- a/docs/pages/3-features/1-parser.md +++ b/docs/pages/3-features/1-parser.md @@ -17,7 +17,7 @@ mingling = { } ``` -## Intro +## Usage `parser` provides the ability to transform user input into structured data. Its core concept is **pick**. diff --git a/docs/pages/3-features/2-general-renderer.md b/docs/pages/3-features/2-general-renderer.md index a19fd33..ec5474f 100644 --- a/docs/pages/3-features/2-general-renderer.md +++ b/docs/pages/3-features/2-general-renderer.md @@ -17,7 +17,7 @@ mingling = { } ``` -## Intro +## Setup `general_renderer` requires you to implement the `serde::Serialize` trait for **all** structs, so your project needs to include `serde` diff --git a/docs/pages/3-features/3-comp.md b/docs/pages/3-features/3-comp.md index 1d436dd..a871d10 100644 --- a/docs/pages/3-features/3-comp.md +++ b/docs/pages/3-features/3-comp.md @@ -4,3 +4,114 @@

--- + +## Enable Feature + +`comp` is the command-line completion feature provided by **Mingling**. Its approach is not static completion but rather dynamic completion by invoking your program itself. + +Enable this feature as follows: + +```toml +[dependencies] +mingling = { + version = "...", + features = ["comp"] +} +``` + +## Setup + +Once `comp` is enabled, `gen_program!` will automatically generate a `CompletionDispatcher`, which is a command with the node `__comp`: the completion script will call this subcommand. + +Add this [Dispatcher](pages/2-basic/3-dispatcher) to your [Program](pages/2-basic/1-program): + +```rust +fn main() { + let mut program = ThisProgram::new(); + program.with_dispatcher(CompletionDispatcher); + program.exec(); +} +``` + +## Usage + +You can use the `completion!` macro to bind completion logic to your command entry point. The syntax is as follows: + +```rust +// Define Dispatcher +dispatcher!("test-comp", + TestCompletionCommand => TestCompletionEntry +); + +// Establish completion logic, bound to `TestCompletionEntry` +#[completion(TestCompletionEntry)] +fn comp_test_comp_cmd(_ctx: &ShellContext) -> Suggest { + suggest!() +} +``` + +You can obtain the context passed by the shell via `ShellContext` and return the generated suggestions: + +```rust +#[completion(TestCompletionEntry)] +fn comp_test_comp_cmd(ctx: &ShellContext) -> Suggest { + if ctx.current_word.starts_with("-") { + // Comp flags + return suggest!( + "--name": "Names", + "--age": "Age" + ); + } + + if ctx.previous_word == "--name" { + return suggest!("Bob", "Alice"); // Comp names + } + + if ctx.previous_word == "--age" { + return suggest!(); // If typing age, suggest nothing + } + + suggest!() // Comp nothing +} +``` + +> 🎬 Logic +> +> When the user inputs `bin test-`, it completes to `bin test-comp`. +> +> When the user inputs `bin test-comp -`, it suggests `--age` / `--name`. +> +> When the user inputs `bin test-comp --name `, it suggests `Bob` / `Alice`. +> +> In other cases, no suggestions are generated. + +## Generate Completion Script + +Any shell requires registering a relevant completion script to enable your command's completion capability. However, **Mingling** provides a related build script: + +Please add the following to `build-dependencies` in your `Cargo.toml`: + +```toml +[build-dependencies] +mingling = { version = "...", features = ["comp"] } +``` + +Next, call the following logic in your project's `build.rs`: + +```rust +use mingling::build::build_comp_scripts; + +fn main() { + // Generate completion scripts for the current program + // build_comp_scripts().unwrap(); + + // Or specify a specific name + build_comp_scripts("your_cmd").unwrap(); +} +``` + +`build_comp_scripts` will generate the corresponding completion scripts based on your platform and output them to the `target` directory. + +> The completion script does not contain the actual completion logic; +> +> it is just a thin invocation layer. diff --git a/docs/pages/3-features/4-async.md b/docs/pages/3-features/4-async.md new file mode 100644 index 0000000..08cbb9a --- /dev/null +++ b/docs/pages/3-features/4-async.md @@ -0,0 +1,6 @@ +

Async

+

+ Mingling's Features +

+ +--- -- cgit