From 5a37d4a6acd4d8585a3747ab9d2e1832dc1b101b Mon Sep 17 00:00:00 2001 From: shannmu Date: Wed, 10 Jul 2024 00:22:23 +0800 Subject: [PATCH] docs: Add document comments how to source dynamic completions --- clap_complete/src/dynamic/shells/mod.rs | 144 ++++++++++++++++++++++++ 1 file changed, 144 insertions(+) diff --git a/clap_complete/src/dynamic/shells/mod.rs b/clap_complete/src/dynamic/shells/mod.rs index 6cfed97ed5e1..b518ec972633 100644 --- a/clap_complete/src/dynamic/shells/mod.rs +++ b/clap_complete/src/dynamic/shells/mod.rs @@ -16,6 +16,86 @@ use crate::dynamic::Completer as _; /// A subcommand definition to `flatten` into your CLI /// /// This provides a one-stop solution for integrating completions into your CLI +/// +/// # Examples +/// +/// The following example shows how to integrate completions into your CLI and generate completions. +/// +/// First, we should build an application. It helps if we separate out our `Command` definition into a separate file. +/// +/// ``` +/// // src/command.rs +/// use clap::FromArgMatches; +/// use clap::Subcommand; +/// +/// pub fn command() -> clap::Command { +/// let cmd = clap::Command::new("dynamic") +/// .arg( +/// clap::Arg::new("input") +/// .long("input") +/// .short('i') +/// .value_hint(clap::ValueHint::FilePath), +/// ) +/// .arg( +/// clap::Arg::new("format") +/// .long("format") +/// .short('F') +/// .value_parser(["json", "yaml", "toml"]), +/// ) +/// .args_conflicts_with_subcommands(true); +/// +/// cmd +/// } +/// ``` +/// +/// In our regular code, we can simply call this `command()` function to get the `Command`, then call +/// `clap_complete::dynamic::shells::CompleteCommand::augment_subcommands` to add the `complete` subcommand. +/// Finally, we call `get_matches()`, or any of the other normal methods directly after. For example: +/// +/// ```no_run +/// // src/main.rs +/// use clap::FromArgMatches; +/// use clap::Subcommand; +/// +/// pub fn command() -> clap::Command { +/// let cmd = clap::Command::new("dynamic") +/// .arg( +/// clap::Arg::new("input") +/// .long("input") +/// .short('i') +/// .value_hint(clap::ValueHint::FilePath), +/// ) +/// .arg( +/// clap::Arg::new("format") +/// .long("format") +/// .short('F') +/// .value_parser(["json", "yaml", "toml"]), +/// ) +/// .args_conflicts_with_subcommands(true); +/// +/// cmd +/// } +/// +/// fn main() { +/// let cmd = command::command(); +/// let cmd = clap_complete::dynamic::shells::CompleteCommand::augment_subcommands(cmd); +/// let matches = cmd.get_matches(); +/// if let Ok(completions) = +/// clap_complete::dynamic::shells::CompleteCommand::from_arg_matches(&matches) +/// { +/// completions.complete(&mut command()); +/// } +/// +/// // normal logic continues... +/// } +///``` +/// +/// Usage for `complete` subcommand: +/// +/// Seeing [Shell] for available shell names +/// +/// Seeing [CompleteArgs] how to source the completion script in a file or stdout: +/// #[derive(clap::Subcommand)] #[allow(missing_docs)] #[derive(Clone, Debug)] @@ -27,6 +107,70 @@ pub enum CompleteCommand { } /// Generally used via [`CompleteCommand`] +/// +/// This is the arguments for the `complete` subcommand. +/// +/// **NOTE**: We should replace the `completion.bash` to filename we wanted, also `completion.fish`, `completion.zsh`, `completion.ps1`, `completion.elv`. +/// +/// To generate shell completion scripts, we can use the `complete` subcommand as follows: +/// +/// - Bash +/// - `your_program complete --shell bash --register /path/to/completion.bash` +/// - `your_program complete --shell bash --register -` +/// - Fish: +/// - `your_program complete --shell fish --register /path/to/completion.fish` +/// - `your_program complete --shell fish --register -` +/// - Zsh: +/// - `your_program complete --shell zsh --register /path/to/completion.zsh` +/// - `your_program complete --shell zsh --register -` +/// - PowerShell: +/// - `your_program complete --shell powershell --register /path/to/completion.ps1` +/// - `your_program complete --shell powershell --register -` +/// - Elvish: +/// - `your_program complete --shell elvish --register /path/to/completion.elv` +/// - `your_program complete --shell elvish --register -` +/// +/// **Before we source the completion script, we need to add your program to the PATH. And then +/// we can source the completion script. Different shells have different ways to source the script.** +/// +/// ### How to source the generated completions as a file +/// - Bash +/// - `source /path/to/completion.bash` +/// - Fish +/// - `source /path/to/completion.fish` +/// - Zsh +/// - `source /path/to/completion.zsh` +/// - PowerShell +/// - `. /path/to/completion.ps1` +/// - Elvish +/// - `./path/to/completion.elv` +/// +/// ### How to source the generated completions when printed to stdout +/// - Bash +/// - `your_program complete --shell bash --register - > /path/to/completion.bash && source /path/to/completion.bash` +/// - Fish +/// - `your_program complete --shell fish --register - > /path/to/completion.fish && source /path/to/completion.fish` +/// - Zsh +/// - `your_program complete --shell zsh --register - > /path/to/completion.zsh && source /path/to/completion.zsh` +/// - PowerShell +/// - `your_program complete --shell powershell --register - > /path/to/completion.ps1 && . /path/to/completion.ps1` +/// - Elvish +/// - `your_program complete --shell elvish --register - > /path/to/completion.elv && ./path/to/completion.elv` +/// +/// ### How to add the above to your shell configuration file +/// - Bash +/// - `echo 'source /path/to/completion.bash' >> ~/.bashrc` +/// - Fish +/// - `echo 'source /path/to/completion.fish' >> ~/.config/fish/config.fish` +/// - `cp /path/to/completion.fish ~/.config/fish/completions/your_program.fish` +/// - Zsh +/// - `echo 'source /path/to/completion.zsh' >> ~/.zshrc` +/// - PowerShell +/// - `echo '. /path/to/completion.ps1' >> $PROFILE` +/// - Elvish +/// - `echo './path/to/completion.elv' >> ~/.elvish/rc.elv` +/// + #[derive(clap::Args)] #[command(arg_required_else_help = true)] #[command(group = clap::ArgGroup::new("complete").multiple(true).conflicts_with("register"))]