diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_sidebar.md | 1 | ||||
| -rw-r--r-- | docs/pages/3-features.md | 1 | ||||
| -rw-r--r-- | docs/pages/3-features/1-parser.md | 2 | ||||
| -rw-r--r-- | docs/pages/3-features/2-general-renderer.md | 2 | ||||
| -rw-r--r-- | docs/pages/3-features/3-comp.md | 111 | ||||
| -rw-r--r-- | docs/pages/3-features/4-async.md | 6 |
6 files changed, 121 insertions, 2 deletions
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 @@ </p> --- + +## 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-<TAB>`, it completes to `bin test-comp`. +> +> When the user inputs `bin test-comp -<TAB>`, it suggests `--age` / `--name`. +> +> When the user inputs `bin test-comp --name <TAB>`, 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 @@ +<h1 align="center">Async</h1> +<p align="center"> + Mingling's Features +</p> + +--- |
