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

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

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

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

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.