mirror of
https://github.com/TangentFoxy/argparse.git
synced 2025-07-27 18:42:20 +00:00
79 lines
2.1 KiB
ReStructuredText
79 lines
2.1 KiB
ReStructuredText
Shell completions
|
|
=================
|
|
|
|
Argparse can generate shell completion scripts for
|
|
`Bash <https://www.gnu.org/software/bash/>`_, `Zsh <https://www.zsh.org/>`_, and
|
|
`Fish <https://fishshell.com/>`_.
|
|
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``).
|
|
|
|
.. code-block:: lua
|
|
:linenos:
|
|
|
|
local parser = argparse()
|
|
:add_complete()
|
|
|
|
.. code-block:: none
|
|
|
|
$ lua script.lua -h
|
|
|
|
.. code-block:: none
|
|
|
|
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``:
|
|
|
|
.. code-block:: bash
|
|
|
|
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``:
|
|
|
|
.. code-block:: fish
|
|
|
|
script.lua --completion fish | source
|