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

Резюме

complete [( -c | --command | -p | --path )] COMMAND
        [( -c | --command | -p | --path ) COMMAND]...
        [( -e | --erase )]
        [( -s | --short-option ) SHORT_OPTION]...
        [( -l | --long-option | -o | --old-option ) LONG_OPTION]...
        [( -a | --arguments ) OPTION_ARGUMENTS]
        [( -k | --keep-order )]
        [( -f | --no-files )]
        [( -F | --force-files )]
        [( -r | --require-parameter )]
        [( -x | --exclusive )]
        [( -w | --wraps ) WRAPPED_COMMAND]...
        [( -n | --condition ) CONDITION]
        [( -d | --description ) DESCRIPTION]
complete ( -C [STRING] | --do-complete[=STRING] )

Описание

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

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

• -c COMMAND или --command COMMAND указывает, что COMMAND — имя команды. Если -c или -p отсутствуют, будет использован один не-опциональный аргумент как имя команды.
• -p COMMAND или --path COMMAND указывает, что COMMAND — абсолютный путь к команде (возможно, содержащий подстановочные знаки).
• -e или --erase удаляет указанное автодополнение.
• -s SHORT_OPTION или --short-option=SHORT_OPTION добавляет короткую опцию в список автодополнений.
• -l LONG_OPTION или --long-option=LONG_OPTION добавляет опцию в стиле GNU в список автодополнений.
• -o LONG_OPTION или --old-option=LONG_OPTION добавляет опцию старого стиля в список автодополнений (см. подробности ниже).
• -a OPTION_ARGUMENTS или --arguments=OPTION_ARGUMENTS добавляет указанные аргументы опций в список автодополнений.
• -k или --keep-order сохраняет порядок OPTION_ARGUMENTS вместо сортировки в алфавитном порядке. Несколько вызовов complete с -k приводят к тому, что аргументы последних отображаются первыми.
• -f или --no-files указывает, что данное автодополнение не может быть после имени файла.
• -F или --force-files указывает, что данное автодополнение может следовать за именем файла, даже если другое применимое complete указало --no-files.
• -r или --require-parameter указывает, что данное автодополнение должно иметь аргумент опции, т.е. не может следовать за другой опцией.
• -x или --exclusive — сокращенная форма -r и -f.
• -w WRAPPED_COMMAND или --wraps=WRAPPED_COMMAND заставляет указанную команду унаследовать автодополнения от обернутой команды (см. подробности ниже).
• -n CONDITION или --condition CONDITION указывает, что это автодополнение должно быть использовано только в том случае, если УСЛОВИЕ (команда оболочки) возвращает 0. Это позволяет задавать автодополнения, которые должны использоваться только в определенных случаях.
• -C STRING или --do-complete=STRING заставляет complete попытаться найти все возможные автодополнения для указанной строки. Если СТРОКА отсутствует, используется текущая командная строка.

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

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

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

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

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

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

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

Опции -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.