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] )

Описание

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

• COMMAND — имя команды, для которой необходимо добавить автодополнение.
• SHORT_OPTION — односимвольный параметр команды.
• LONG_OPTION — многосимвольный параметр команды.
• OPTION_ARGUMENTS — параметр, содержащий список возможных аргументов параметра, разделенных пробелом, который может содержать подстановки команд.
• DESCRIPTION — описание того, что делают параметр и/или аргументы параметра.
• -c COMMAND или --command COMMAND указывает, что COMMAND — имя команды.
• -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 сохраняет порядок аргументов, указанных с помощью -a или --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 указывает командный интерпретатор оболочки, который должен вернуть 0, если автодополнение должно быть использовано. Это позволяет указать автодополнения, которые должны использоваться только в определённых случаях.
• -CSTRING или --do-complete=STRING заставляет complete попытаться найти все возможные автодополнения для указанной строки.
• -C или --do-complete без аргумента заставляет complete попытаться найти все возможные автодополнения для текущего буфера командной строки. Если оболочка не находится в интерактивном режиме, возвращается ошибка.
• -A и --authoritative больше ничего не делают и молча игнорируются.
• -u и --unauthoritative больше ничего не делают и молча игнорируются.

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

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

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

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

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

Пример

Короткий параметр -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. Обратите внимание, что это также может быть указано в объявлении функции.