Module complete 

Shell completion, answered by the program itself.

A generated script (script) registers a completion function with the shell; on Tab it runs the program as PROG __complete_word__ --shell SHELL --line LINE (see answer), and the program answers from its own help data (help::Command): flag names, a flag’s choices, subcommand names, or a request for the shell’s own file completion. The script stays a few lines and never goes stale: what can be typed is whatever the binary parses.

Args::completion_request answers the callback before the command line is parsed, and Args::completion_script writes the script.

What is completed:

• after - or --, the visible flags of the command reached so far, with their descriptions;
• a flag’s value (--color <TAB>, --color=<TAB>), from its choices, or what its Hint says the shell knows: files for a path or a word;
• elsewhere, subcommand names and a positional’s choices, or its hint’s.

A value’s type gives the hint (FromArg::HINT): a PathBuf, a String or an OsString is a file, and a number or a type of the program nothing a shell knows. A field says otherwise with #[arg(hint = "dir")], "command", "file" or "none". A value only the program knows is answered by a function, #[arg(complete = branches)], given what is typed of it; each candidate is one plain word, as the scripts quote nothing for the shell.

In a program, the callback is answered first and the script is printed on request, here by a flag of its own:

use winnow_args::Args;
use winnow_args::complete::Shell;

#[derive(Args)]
#[arg(name = "tool")]
struct Cli {
    /// Print a completion script: `source <(tool --completions bash)`.
    #[arg(long, value_name = "SHELL")]
    completions: Option<Shell>,
}

let args: Vec<_> = std::env::args_os().skip(1).collect();
if let Some(answer) = Cli::completion_request(&args) {
    print!("{answer}");
    return;
}
let cli = Cli::parse();
if let Some(shell) = cli.completions {
    print!("{}", Cli::completion_script(shell));
}

Structs

Candidate

One thing that can be typed at the cursor.

Completions

What can be typed at the cursor.

Enums

Hint

What a value is, when it is not one of a fixed set: what the shell is asked to complete itself.

Shell

The shells a script can be written for.

Constants

REQUEST

The word a completion script calls the program with.

Functions

answer

Answer a completion script’s callback: args is the command line after the program’s name. None when it is not a callback, so the program goes on to parse it.

complete

What can be typed as the last of words, the command line after the program’s name up to the cursor. The last word is the one being typed, empty after a space.

render

The answer as shell’s script reads it: one candidate a line, a description after a colon (zsh) or a tab (the others), and a line asking for what the shell completes itself when that fits: its mark, a tab, and the part of the word before what the shell is to complete.

script

The completion script for bin in shell, ready to be sourced or installed where the shell looks for completions.