Shell completions¶

Argparse can generate shell completion scripts for Bash, Zsh, and Fish. The completion scripts support completing options, commands, and argument choices.

The Parser methods :get_bash_complete(), :get_zsh_complete(), and :get_fish_complete() return completion scripts as a string.

Adding a completion option or command¶

A --completion option can be added to a parser using the :add_complete([value]) method. The optional value argument is a string or table used to configure the option (by calling the option with value).

local parser = argparse()
   :add_complete()

$ lua script.lua -h

Usage: script.lua [-h] [--completion {bash,zsh,fish}]

Options:
   -h, --help            Show this help message and exit.
   --completion {bash,zsh,fish}
                         Output a shell completion script for the specified shell.

A similar completion command can be added to a parser using the :add_complete_command([value]) method.

Using completions¶

Bash¶

Save the generated completion script at /usr/share/bash-completion/completions/script.lua or ~/.local/share/bash-completion/completions/script.lua.

Alternatively, add the following line to the ~/.bashrc:

source <(script.lua --completion bash)

Zsh¶

Save the completion script in the /usr/share/zsh/site-functions/ directory or any directory in the $fpath. The file name should be an underscore followed by the program name. A new directory can be added to to the $fpath by adding e.g. fpath=(~/.zfunc $fpath) in the ~/.zshrc before compinit.

Fish¶

Save the completion script at /usr/share/fish/vendor_completions.d/script.lua.fish or ~/.config/fish/completions/script.lua.fish.

Alternatively, add the following line to the file ~/.config/fish/config.fish:

script.lua --completion fish | source