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
