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

Для указания завершения используйте команду 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"

Также существуют специальные переключатели для указания того, что переключатель требует аргумента, для отключения завершения имён файлов, для создания завершений, доступных только в некоторых комбинациях и т.д.. Для полного описания различных переключателей, принимаемых командой complete, см. документацию по встроенной команде complete или напишите complete --help в оболочке fish.

В качестве более подробного примера вот комментированный фрагмент завершений для timedatectl systemd:

# 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. (Точный путь зависит от выбранного префикса установки и может незначительно отличаться).

Полезные функции для написания завершений

fish поставляется с несколькими функциями, которые очень полезны при написании завершений для конкретных команд. Большинство из этих функций начинаются со строки __fish_. Такие функции являются внутренними для fish и их имя и интерфейс могут измениться в будущих версиях Fish. Тем не менее, некоторые из них могут быть очень полезны при написании завершений. Некоторые из этих функций описаны здесь. Имейте в виду, что они могут быть удалены или изменены в будущих версиях Fish.

Функции, начинающиеся со строки __fish_print_, выводят список строк, разделённых символом новой строки. Например, __fish_print_filesystems выводит список всех известных файловых систем. Функции, начинающиеся со строки __fish_complete_, выводят список завершений с описаниями, разделённых символом табуляции.

• __fish_complete_directories STRING DESCRIPTION выполняет завершение путей для STRING, позволяя использовать только каталоги и предоставляя описание DESCRIPTION.
• __fish_complete_path STRING DESCRIPTION выполняет завершение путей для STRING, предоставляя описание DESCRIPTION.
• __fish_complete_groups выводит список всех пользовательских групп с членами группы в качестве описания.
• __fish_complete_pids выводит список всех идентификаторов процессов с именем команды в качестве описания.
• __fish_complete_suffix SUFFIX выполняет завершение файлов, но сначала сортирует файлы, заканчивающиеся на SUFFIX. Это полезно в сочетании с complete --keep-order.
• __fish_complete_users выводит список всех пользователей с полным именем в качестве описания.
• __fish_print_filesystems выводит список всех известных файловых систем. В настоящее время это статический список, не зависящий от того, какие файловые системы фактически понимает хост-операционная система.
• __fish_print_hostnames выводит список всех известных хост-имен. Эта функция ищет в fstab nfs-серверы, ssh для известных хостов и проверяет файл /etc/hosts.
• __fish_print_interfaces выводит список всех известных сетевых интерфейсов.
• __fish_print_packages выводит список всех установленных пакетов. Эта функция в настоящее время обрабатывает пакеты Debian, rpm и Gentoo.

Где размещать завершения

Завершения можно определять в командной строке или в конфигурационном файле, но их также можно загружать автоматически. Fish автоматически ищет все каталоги в списке переменной $fish_complete_path, и любые определённые завершения загружаются автоматически при необходимости. Файл завершений должен иметь имя, состоящее из имени завершаемой команды и суффикса .fish.

По умолчанию Fish ищет завершения в следующих местах, используя первый доступный найденный файл:

• Каталог для конечных пользователей, чтобы хранить свои собственные завершения, обычно ~/.config/fish/completions (управляется переменной среды XDG_CONFIG_HOME);
• Каталог для системных администраторов, чтобы устанавливать завершения для всех пользователей в системе, обычно /etc/fish/completions;
• Каталог для поставщиков стороннего программного обеспечения, чтобы поставлять собственные завершения для своего программного обеспечения, обычно /usr/share/fish/vendor_completions.d;
• Завершения, поставляемые с fish, обычно установленные в /usr/share/fish/completions и;
• Завершения, автоматически сгенерированные из руководства операционной системы, обычно хранящиеся в ~/.local/share/fish/generated_completions.

Эти пути управляются параметрами, заданными во время компиляции, установки или выполнения, и могут отличаться от указанных выше значений по умолчанию.

Этот широкий поиск может быть запутан. Если вы не уверены, ваши завершения, вероятно, должны быть в ~/.config/fish/completions.

Если вы написали новые завершения для распространённой Unix-команды, пожалуйста, рассмотрите возможность поделиться своей работой, отправив её по инструкциям в Дополнительная помощь и разработка

Если вы разрабатываете другую программу и хотите поставлять завершения вместе со своей программой, установите их в каталог завершений «vendor». Так как этот путь может меняться от системы к системе, следует использовать фреймворк pkgconfig для определения этого пути с помощью вывода pkg-config --variable completionsdir fish.