1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
|
<h1 align="center">Completion</h1>
<p align="center">
Fully dynamic completion system via the `comp` feature
</p>
Mingling's completion is **fully dynamic** — no static completion files, suggestions are computed at runtime based on the user's current input.
## Enable `comp`
```toml
# Cargo.toml
[dependencies.mingling]
features = ["comp"]
[build-dependencies.mingling]
features = [
"comp",
# Enable `builds` for build-time support
"builds"
]
```
## How it works
When the user presses `TAB`, the completion script calls the program's hidden subcommand `__comp`, which dynamically queries the best suggestions based on the provided `ShellContext`.
This hidden subcommand is auto-generated by `gen_program!()` when the `comp` feature is enabled. Its dispatcher is `CMDCompletion` — you need to add it to your program via `with_dispatcher`.
Completion flow:
1. Re-match the user's current input to a `Dispatcher`
2. Call the corresponding `#[completion]` function
3. The function returns a `Suggest` (file completion or a list of suggestions)
4. Notify the shell to display the suggestions
## Define completions
Use `#[completion(EntryType)]` to define completion logic for an Entry:
```rust
// Features: ["comp"]
@@@use mingling::prelude::*;
@@@use mingling::{ShellContext, Suggest, SuggestItem};
@@@use std::collections::BTreeSet;
@@@dispatcher!("greet", CMDGreet => EntryGreet);
#[completion(EntryGreet)]
fn complete_greet(ctx: &ShellContext) -> Suggest {
if ctx.previous_word == "greet" {
let mut items = BTreeSet::new();
items.insert(SuggestItem::new_with_desc("Alice".into(), "Likes to receive messages".into()));
items.insert(SuggestItem::new("World".into()));
Suggest::Suggest(items)
} else {
Suggest::FileCompletion
}
}
```
The `suggest!` macro is a more concise way to write the same thing:
```rust
// Features: ["comp"]
@@@use mingling::macros::suggest;
@@@fn example() {
suggest! {
"Alice": "Likes to receive messages",
"World"
};
@@@}
```
`ShellContext` holds the user's current input state (`previous_word`, `current_word`, `all_words`, etc.). `Suggest` has two variants: `Suggest::Suggest(list)` returns a suggestion list, `Suggest::FileCompletion` delegates file completion to the shell.
## Generate completion scripts
Call `build_comp_scripts` in `build.rs` to generate completion scripts (requires `builds` + `comp` features).
See [example-completion](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-completion).
<p align="center" style="font-size: 0.85em; color: gray;">
Written by @Weicao-CatilGrass
</p>
|
