complete - редактирование командных автодополнений

Синопсис

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

Описание

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

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

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

-c или --command COMMAND

Указывает, что COMMAND — это имя команды. Если нет -c или -p, то в качестве команды будет использоваться один не-опциональный аргумент.

-p или --path COMMAND

Указывает, что COMMAND — это абсолютный путь к команде (возможно, содержащий подстановки шаблонов).

-e или --erase

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

-s или --short-option SHORT_OPTION

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

-l или --long-option LONG_OPTION

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

-o или --old-option LONG_OPTION

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

-a или --arguments ARGUMENTS

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

-k или --keep-order

Сохраняет порядок ARGUMENTS вместо сортировки в алфавитном порядке. Несколько вызовов complete с -k приведут к тому, что аргументы из последующих вызовов будут отображаться первыми.

-f или --no-files

Это автодополнение не может быть после имени файла.

-F или --force-files

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

-r или --require-parameter

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

-x или --exclusive

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

-w или --wraps WRAPPED_COMMAND

Заставляет указанную команду наследоваться от автодополнений WRAPPED_COMMAND (см. подробности ниже).

-n или --condition CONDITION

Это автодополнение должно использоваться только в том случае, если CONDITION (команда оболочки) возвращает 0. Это позволяет указать автодополнения, которые должны использоваться только в определённых случаях.

-C или --do-complete STRING

Заставляет complete пытаться найти все возможные автодополнения для указанной строки. Если STRING отсутствует, используется текущая командная строка.

--escape

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

-h или --help

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

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

• Короткие опции, например -a. Короткие опции имеют длину в один символ, предваряются одним дефисом и могут быть объединены (например, -la, что эквивалентно -l -a). Аргументы опций могут быть указаны путём добавления значения к опции (-w32) или, если указано --require-parameter, в следующем параметре (-w 32).
• Опции старого стиля, например -Wall или -name. Опции старого стиля могут иметь длину более одного символа, предваряются одним дефисом и не могут быть объединены. Аргументы опций указываются в следующем параметре (-ao null) или после = (-ao=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.