Mirrors/fish-shell
2
0
Fork 0
mirror of https://github.com/fish-shell/fish-shell synced 2024-12-26 21:03:12 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs: Add an annotated completion example

Browse source 
It's not _perfect_, but should hopefully ease the introduction a
teensy bit.

We use `timedatectl` because it's a reasonably simple command that
still uses subcommands and some generated candidates.

[ci skip]
This commit is contained in:
Fabian Homborg 2019-03-27 12:29:03 +01:00
parent 2a51e42ee0
commit 6a9079899d
1 changed files with 51 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

51
sphinx_doc_src/index.rst
View file

@ -570,6 +570,57 @@ To provide a list of possible completions for myprog, use the ``-a`` switch. If
There are also special switches for specifying that a switch requires an argument, to disable filename completion, to create completions that are only available in some combinations, etc.. For a complete description of the various switches accepted by the ``complete`` command, see the documentation for the `complete <cmds/complete.html>`_ builtin, or write ``complete --help`` inside the ``fish`` shell.
As a simple example, here's an excerpt of the completions for systemd's ``timedatectl``::
# All subcommands that timedatectl knows - this is useful for later.
set -l commands status set-time set-timezone list-timezones set-local-rtc set-ntp
# Disable file completions for the entire command
# because it does not take files anywhere
# Note that this can't be undone,
# so it's often better to only disable it for certain completions.
#
# File completions also need to be disabled
# if you wish to offer a certain set of files (e.g. just directories).
complete -c timedatectl -f
# This line offers the subcommands
# -"status",
# -"set-timezone",
# -"set-time"
# -"list-timezones"
# if no subcommand has been given so far.
#
# The `-n`/`--condition` option takes script as a string, which it executes.
# If it returns true, the completion is offered.
# Here the condition is the `__fish_seen_subcommands_from` helper function.
# If returns true if any of the given commands is used on the commandline,
# as determined by a simple heuristic.
# For more complex uses, you can write your own function.
# See e.g. the git completions for an example.
#
complete -c timedatectl -n "not __fish_seen_subcommand_from $commands" -a "status set-time set-timezone list-timezones"
# If the "set-timezone" subcommand is used,
# offer the output of `timedatectl list-timezones` as completions.
# Each line of output is used as a separate candidate,
# and anything after a tab is taken as the description.
# It's often useful to transform command output with `string` into that form.
complete -c timedatectl -n "__fish_seen_subcommand_from set-timezone" -a "(timedatectl list-timezones)"
# Completion candidates can also be described via `-d`,
# which is useful if the description is constant.
# Try to keep these short, because that means the user gets to see more at once.
complete -c timedatectl -n "not __fish_seen_subcommand_from $commands" -a "set-local-rtc" -d "Maintain RTC in local time"
# We can also limit options to certain subcommands by using conditions.
complete -c timedatectl -n "__fish_seen_subcommand_from set-local-rtc" -l adjust-system-clock -d 'Synchronize system clock from the RTC'
# These are simple options that can be used everywhere.
complete -c timedatectl -s h -l help -d 'Print a short help text and exit'
complete -c timedatectl -l version -d 'Print a short version string and exit'
complete -c timedatectl -l no-pager -d 'Do not pipe output into a pager'
For examples of how to write your own complex completions, study the completions in ``/usr/share/fish/completions``. (The exact path depends on your chosen installation prefix and may be slightly different)
.. _completion-func: