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 КОРОТКАЯ_ОПЦИЯ

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

-l или --long-option ДЛИННАЯ_ОПЦИЯ

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

-o или --old-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.