complete - редактирование завершения команд

Синтаксис

complete ((-c | --command) | (-p | --path)) COMMAND [OPTIONS]
complete (-C | --do-complete) [--escape] STRING

Описание

complete определяет, удаляет или выводит список завершений для команды.

Для ознакомления с написанием собственных завершений, см. Написание собственных завершений в руководстве fish.

Доступны следующие опции:

-c или --command КОМАНДА

Указывает, что КОМАНДА - имя команды. Если нет опций -c или -p, то в качестве команды будет использоваться первый не являющийся опцией аргумент.

-p или --path КОМАНДА

Указывает, что КОМАНДА - абсолютный путь к команде (возможно содержащий подстановки по шаблону).

-e или --erase

Удаляет указанное завершение.

-s или --short-option SHORT_OPTION

Добавляет короткую опцию в список завершений.

-l или --long-option LONG_OPTION

Добавляет опцию в стиле GNU в список завершений.

-o или --old-option OPTION

Добавляет опцию старого стиля, короткую или длинную (см. подробности ниже).

-a или --arguments АРГУМЕНТЫ

Добавляет указанные аргументы опции в список завершений.

-k или --keep-order

Сохраняет порядок АРГУМЕНТОВ вместо сортировки по алфавиту. Несколько complete вызовов с -k приводят к тому, что аргументы из более поздних вызовов отображаются первыми.

-f или --no-files

Данное завершение не может следовать за именем файла.

-F или --force-files

Это завершение может следовать за именем файла, даже если другая соответствующая complete опция указана как --no-files.

-r или --require-parameter

Данное завершение должно иметь аргумент опции, т.е. не может следовать за другой опцией.

-x или --exclusive

Сокращение для -r и -f.

-w или --wraps ОБРАМЛЁННАЯ_КОМАНДА

Заставляет указанную команду наследовать завершения от ОБРАМЛЁННОЙ_КОМАНДЫ (см. подробности ниже).

-n или --condition УСЛОВИЕ

Это завершение должно использоваться только в том случае, если УСЛОВИЕ (команда оболочки) возвращает 0. Это позволяет указать завершения, которые должны использоваться только в некоторых случаях. Если указано несколько условий, fish будет пытаться их выполнить в указанном порядке, пока одно из них не завершится неудачно или все не завершатся успешно.

-C или --do-complete СТРОКА

Заставляет complete попытаться найти все возможные завершения для указанной строки. Если СТРОКА отсутствует, используется текущая команда.

--escape

При использовании с -C, экранирует специальные символы в завершениях.

-h или --help

Отображает справку по использованию этой команды.

Командные завершения в fish основаны на понятии опций и аргументов. Опция - это параметр, начинающийся с дефиса, например -h, -help или --help. Аргументы - параметры, не начинающиеся с дефиса. Fish распознаёт три стиля опций, аналогичных стилям библиотеки GNU getopt. Эти стили:

• Короткие опции, как -a. Короткие опции состоят из одного символа, предваряются одиночным дефисом и могут быть сгруппированы (например, -la, что эквивалентно -l -a). Аргументы опции могут быть указаны путём добавления значения к опции (-w32), или, если --require-parameter задана, в следующем параметре (-w 32).
• Опции старого стиля, длинные, например -Wall или -name или даже короткие, например -a. Опции старого стиля могут состоять из более чем одного символа, предваряются одиночным дефисом и не могут быть сгруппированы. Аргументы опций задаются по умолчанию после пробела (-foo null) или после = (-foo=null).
• Длинные опции в стиле GNU, например --colors. Длинные опции в стиле GNU могут состоять из более чем одного символа, предваряются двумя дефисами и не могут быть сгруппированы. Аргументы опций могут быть указаны после = (--quoting-style=shell), или, если --require-parameter задана, в следующем параметре (--quoting-style shell).

Несколько команд и путей могут быть заданы в одном вызове для определения одних и тех же завершений для нескольких команд.

Несколько переключателей команд и обрамлённых команд также могут быть заданы для определения нескольких завершений в одном вызове.

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

Когда -a или --arguments указаны вместе с длинными, короткими или опциями старого стиля, указанные аргументы завершаются только как аргументы для любых указанных опций. Если -a или --arguments указаны без каких-либо длинных, коротких или опций старого стиля, указанные аргументы используются при завершении не являющихся опциями аргументов команды (кроме завершения аргумента опции, который был задан с -r или --require-parameter).

Подстановки команд, найденные в ARGUMENTS, должны возвращать список аргументов, разделённых новой строкой, и каждый аргумент может необязательно иметь табуляцию, за которой следует описание аргумента. Описания, заданные таким образом, переопределяют описания, заданные с помощью -d или --description.

Описания, заданные с помощью --description, также используются для группирования опций, заданных с помощью -s, -o или -l. Опции с одинаковым (непустым) описанием будут перечислены как один кандидат, и один из них будет выбран. Если описание пустое или не было указано, это пропускается.

Опции -w или --wraps заставляют указанную команду наследовать завершения от другой команды, «обрамляя» другую команду. Команда обрамления также может иметь дополнительные завершения. Команда может обрамлять несколько команд, и обрамление является транзитивным: если A обрамляет B, а B обрамляет C, то A автоматически наследует все завершения C. Обрамление можно удалить с помощью опций -e или --erase. Обрамление работает только для завершений, указанных с помощью -c или --command, и игнорируется при указании завершений с помощью -p или --path.

При удалении завершений можно удалить все завершения для определенной команды, указав complete -c COMMAND -e, или указать определённую опцию завершения для удаления.

Когда complete вызывается без чего-либо, что определяет или удаляет завершения (опции, аргументы, обрамление, ...), он вместо этого отображает соответствующие завершения. Так complete без каких-либо аргументов показывает все загруженные завершения, complete -c foo показывает все загруженные завершения для foo. Поскольку завершения автозагружаются, их сначала нужно активировать.

Примеры

Короткие опции -o для команды gcc требуют аргумента файла:

complete -c gcc -s o -r

Короткие опции -d для команды grep требует одну из read, skip или recurse:

complete -c grep -s d -x -a "read skip recurse"

Команда su принимает любое имя пользователя в качестве аргумента. Имена пользователей предоставляются как первое поле, разделённое двоеточием, в файле /etc/passwd. Это может быть задано как:

complete -x -c su -d "Username" -a "(cat /etc/passwd | cut -d : -f 1)"

Команда rpm имеет несколько различных режимов. Если флаг -e или --erase был задан, rpm должен удалить один или несколько пакетов, в этом случае несколько переключателей, связанных с удалением пакетов, являются допустимыми, например, переключатель nodeps.

Это можно записать как:

complete -c rpm -n "__fish_contains_opt -s e erase" -l nodeps -d "Don't check dependencies"

где __fish_contains_opt - функция, проверяющая буфер командной строки на наличие указанного набора опций.

Для реализации алиаса используйте опцию -w или --wraps:

complete -c hub -w git

Теперь hub наследует все завершения из git. Обратите внимание, что это также можно указать в объявлении функции (function thing -w otherthing).

complete -c git

Отображает все завершения для git.

Любая команда foo, которая не поддерживает группирование нескольких коротких опций в одной строке (не поддерживающая -xf как сокращение для -x -f) или короткой опции и её значения в одной строке (не поддерживающая -d9 вместо -d 9). должна быть указана как опция старого стиля с одним символом вместо короткой опции; например, complete -c foo -o s; complete -c foo -o v никогда не предложит foo -ov, а скорее foo -o -v.