Создание собственных завершений

Для указания завершения используйте команду complete. complete принимает в качестве параметра имя команды, для которой необходимо указать завершение. Например, чтобы добавить завершение для программы myprog, нужно начать команду завершения с complete -c myprog ...

Для предоставления списка возможных завершений для myprog используйте переключатель -a. Если myprog принимает аргументы start и stop, это можно указать как complete -c myprog -a 'start stop'. Аргумент переключателя -a всегда представляет собой строку. Во время завершения она будет разбита на токены пробелами и табуляцией, и произойдёт расширение переменных, подстановка команд и другие формы параметрического расширения.

fish имеет специальный синтаксис для поддержки указания переключателей, принимаемых командой. Переключатели -s, -l и -o используются для указания короткого переключателя (один символ, например, -l), переключателя в стиле GNU (например, --color) и переключателя старого стиля (например, -shuffle) соответственно. Если у команды «myprog» есть опция «-o», которую также можно записать как --output, и которая может принимать дополнительное значение «yes» или «no», это можно указать, написав:

complete -c myprog -s o -l output -a "yes no"

В полном вызове выше, аргументы -a применяются, когда опция -o/--output была задана, поэтому они предлагаются для:

> myprog -o<TAB>
> myprog --output=<TAB>

По умолчанию, аргументы опций являются необязательными, поэтому кандидаты предлагаются только непосредственно присоединёнными, поэтому в данном случае они не предлагаются:

> myprog -o <TAB>

Обычно опции требуют параметр, поэтому вы бы дали --require-parameter / -r:

complete -c myprog -s o -l output -ra "yes no"

что предлагает yes/no в этих случаях:

> myprog -o<TAB>
> myprog --output=<TAB>
> myprog -o <TAB>
> myprog --output <TAB>

В последних двух случаях файлы также будут предложены, потому что завершение файлов включено по умолчанию.

Вы можете либо отключить завершение файлов для отдельной опции:

complete -c myprog -s o -l output --no-files -ra "yes no"

или со специфическим условием:

complete -c myprog -f --condition '__fish_seen_subcommand_from somesubcommand'

или вы можете отключить завершение файлов глобально для команды:

complete -c myprog -f

Если вы отключили их глобально, вы можете включить их только для определенного условия или опции с помощью опции --force-files / -F:

# Disable files by default
complete -c myprog -f
# but reenable them for --config-file
complete -c myprog -l config-file --force-files -r

В полном вызове выше, аргументы -a применяются, когда опция -o/--output была задана, поэтому они предлагаются для:

> myprog -o<TAB>
> myprog --output=<TAB>

По умолчанию, аргументы опций являются необязательными, поэтому кандидаты предлагаются только непосредственно присоединёнными, поэтому в данном случае они не предлагаются:

> myprog -o <TAB>

Обычно опции требуют параметр, поэтому вы бы дали --require-parameter / -r:

complete -c myprog -s o -l output -ra "yes no"

что предлагает yes/no в этих случаях:

> myprog -o<TAB>
> myprog --output=<TAB>
> myprog -o <TAB>
> myprog --output <TAB>

В последних двух случаях файлы также будут предложены, потому что завершение файлов включено по умолчанию.

Вы можете либо отключить завершение файлов для отдельной опции:

complete -c myprog -s o -l output --no-files -ra "yes no"

или со специфическим условием:

complete -c myprog -f --condition '__fish_seen_subcommand_from somesubcommand'

или вы можете отключить завершение файлов глобально для команды:

complete -c myprog -f

Если вы отключили их глобально, вы можете включить их только для определенного условия или опции с помощью опции --force-files / -F:

# Disable files by default
complete -c myprog -f
# but reenable them for --config-file
complete -c myprog -l config-file --force-files -r

В качестве более подробного примера, вот комментированный фрагмент завершений для 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 be undone by using "-F".
#
# File completions also need to be disabled
# if you want to have more control over what files are offered
# (e.g. just directories, or just files ending in ".mp3").
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'

Для примеров написания собственных сложных завершений, изучите завершения в /usr/share/fish/completions. (Точный путь зависит от выбранного префикса установки и может незначительно отличаться).