CLI.Completion

generates shell completion scripts from the same Parser or App that does the parsing, so the completions cannot drift from the flags the program actually accepts.

(IO.println &(CLI.Completion.bash &p "mytool"))
(IO.println &(CLI.Completion.App.zsh &app "mytool"))

bash, zsh and fish are supported, for a Parser and — under Completion.App — for an App. Descriptions, flag names and declared value sets are quoted and escaped for the target shell, so a description containing quotes, backslashes or dollar signs cannot break (or escape from) the generated script.

App

module

Module

bash

defn

(Fn [(Ref CLI.Parser a), (Ref String b)] String)

                        (bash p prog)

generates a bash completion script for the Parser p, to be installed for the program called prog.

The script completes long and short flag names (including --help/-h) after a leading dash, and completes the declared value set of a flag that has one. Anything else — the value of a flag without a declared value set, and every positional argument — falls back to the shell’s own file name completion, which is what a user expects when the library knows nothing more specific.

Flag descriptions are not part of the output: bash has nowhere to show them.

The script uses mapfile, so it needs bash 4 or newer.

fish

defn

(Fn [(Ref CLI.Parser a), (Ref String b)] String)

                        (fish p prog)

generates a fish completion script for the Parser p, to be installed for the program called prog.

The script is a flat list of complete rules, one per option: long and short flag names (including --help/-h) with their descriptions, and the declared value set of a flag that has one. A flag without a declared value set takes a value but keeps fish’s own file name completion, and so does every positional argument, which is what a user expects when the library knows nothing more specific.

A short name longer than one character is emitted as an old-style single-dash option, since fish’s -s takes exactly one character.

The result is meant to be dropped into ~/.config/fish/completions/ as prog.fish, or sourced directly.

zsh

defn

(Fn [(Ref CLI.Parser a), (Ref String b)] String)

                        (zsh p prog)

generates a zsh completion script for the Parser p, to be installed for the program called prog.

The script completes long and short flag names (including --help/-h) with their descriptions, and completes the declared value set of a flag that has one. Anything else — the value of a flag without a declared value set, and every positional argument — falls back to the shell’s own file name completion, which is what a user expects when the library knows nothing more specific.

The result works both as an autoloaded #compdef file and as a script that is sourced directly.