aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/_sidebar.md1
-rw-r--r--docs/pages/3-features.md1
-rw-r--r--docs/pages/3-features/1-parser.md2
-rw-r--r--docs/pages/3-features/2-general-renderer.md2
-rw-r--r--docs/pages/3-features/3-comp.md111
-rw-r--r--docs/pages/3-features/4-async.md6
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>
+
+---