completers

[!WARNING] This crate is still a prototype, and is subject to BREAKING changes without notice.

A tiny Rust-native shell completion solution.

💡 Examples

See examples for a few examples of how to use this crate.

📖 Usage

Rust Part

First, define a completion handler function that takes a [Completion] struct as an argument and returns a vector of completion candidates:

use completers::Completion;

fn handler(_completion: Completion) -> Vec<String> {
    vec![]
}

Then, call [handle_completion] BEFORE any other command that writes to stdout in your main function:

use completers::{Completion, handle_completion};

fn main() {
    handle_completion(handler);
    // Other logic
}
#
# fn handler(_completion: Completion) -> Vec<String> {
#     vec![]
# }

Shell Part

Generate and evaluate the shell code via:

source <(COMPLETE=bash my_binary)

You should be able to complete your commands now. To enable completion across all your terminal sessions, you can add the above code to your completions directory, like:

mkdir -p ~/.local/share/bash-completion/completions # Create the directory if it doesn't exist
echo 'source <(COMPLETE=bash my_binary)' > ~/.local/share/bash-completion/completions/my_binary

The completers Binary

Currently, the completers binary does nothing.

⚙️ Mechanism

See MECHANISM.md for a detailed explanation of how this works, in case you're curious.

🎉 Credits

• clap, whose code and API is used as a reference. When clap's Rust-Native Completion Engine is stablized, this crate will be deprecated in favor of it.
• complete-alias, whose shell code helped a lot.

✅ TODO

• Escape special characters in generated shell code & completion candidates
• Completion delegation
  • Need to consider how to design the API
  • Prototypes available in prototype
• Extensibility (API?)