From 6a9079899d77dee483bbae96cb124cf3c84009e0 Mon Sep 17 00:00:00 2001 From: Fabian Homborg Date: Wed, 27 Mar 2019 12:29:03 +0100 Subject: [PATCH] docs: Add an annotated completion example 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] --- sphinx_doc_src/index.rst | 51 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/sphinx_doc_src/index.rst b/sphinx_doc_src/index.rst index 687efeec3..974c97097 100644 --- a/sphinx_doc_src/index.rst +++ b/sphinx_doc_src/index.rst @@ -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 `_ 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: