argparse - обработка опций, переданных в скрипт или функцию fish

Синтаксис

argparse [OPTIONS] OPTION_SPEC ... -- [ARG ...]

Описание

Эта команда упрощает обработку аргументов для скриптов и функций fish. Вы передаёте аргументы, определяющие известные опции, за которыми следует литерал --, а затем аргументы для обработки (которые также могут включать литерал --). argparse затем устанавливает переменные, указывающие переданные опции со значениями, и устанавливает $argv для оставшихся аргументов. Смотрите раздел использование ниже.

Каждое указание опции (OPTION_SPEC) записывается на специфическом языке для домена, описанном ниже. Все OPTION_SPEC должны появляться после любых флагов argparse и перед --, разделяющим их от аргументов для обработки.

Каждая опция, увиденная в списке ARG, приведет к созданию переменных с именем _flag_X, где X - буква короткого флага, а длинное имя флага (если они определены). Например, опция --help может заставить argparse определить одну переменную, названную _flag_h, и другую, названную _flag_help.

Переменные будут установлены с локальной областью видимости (как если бы скрипт выполнил set -l _flag_X). Если флаг является булевым (то есть он просто передан или нет, у него нет значения), значениями являются короткий и длинный флаги, увиденные. Если опция не является булевой, значения будут нулём или более значениями, соответствующими значениям, собранным при обработке списка ARG. Если флаг не был увиден, переменная флага не будет установлена.

Опции

Доступны следующие argparse опции. Они должны появляться перед всеми OPTION_SPEC:

-n или --name

Имя команды для использования в сообщениях об ошибках. По умолчанию будет использовано текущее имя функции или argparse если выполняется вне функции.

-x или --exclusive OPTIONS

Список опций, которые взаимоисключающие, разделённые запятыми. Вы можете использовать это несколько раз, чтобы определить несколько наборов взаимоисключающих опций.

-N или --min-args ЧИСЛО

Минимальное количество допустимых аргументов, не являющихся опциями. По умолчанию ноль.

-X или --max-args ЧИСЛО

Максимальное количество допустимых аргументов, не являющихся опциями. По умолчанию бесконечность.

-i или --ignore-unknown

Игнорирует неизвестные опции, сохраняя их и их аргументы в $argv.

-s или --stop-nonopt

Приводит к остановке сканирования аргументов, как только увиден первый аргумент, не являющийся опцией. Среди прочего, это полезно для реализации подкоманд, имеющих собственные опции.

-h или --help

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

Использование

Для использования этой команды передайте описания опций (OPTION_SPEC), обязательный литерал --, а затем аргументы для обработки.

Простой пример:

argparse --name=my_function 'h/help' 'n/name=' -- $argv
or return

Если $argv пусто, то нет ничего для обработки, и argparse возвращает ноль, чтобы указать успех. Если $argv не пусто, проверяются флаги -h, --help, -n и --name. Если они найдены, они удаляются из аргументов, и устанавливаются локальные переменные, называемые _flag_OPTION, чтобы скрипт мог определить, какие опции были использованы. Если $argv не содержит ошибок, таких как отсутствие обязательного значения для опции, то argparse завершается со статусом ноль. В противном случае он записывает соответствующие сообщения об ошибках в stderr и завершается со статусом один.

or return означает, что функция возвращает статус argparse при ошибке, поэтому, если argparse завершился успешно.

Аргумент -- является обязательным. Вам не нужно включать описания опций или аргументы после --, но вы должны включить --. Например, это приемлемо:

set -l argv foo
argparse 'h/help' 'n/name' -- $argv
argparse --min-args=1 -- $argv

Но это не так:

set -l argv
argparse 'h/help' 'n/name' $argv

Первый -- позволяет команде argparse надёжно разделять описания опций и аргументы для argparse (например, --ignore-unknown) от аргументов команд, поэтому он обязателен.

Спецификации опций

Каждая спецификация опции состоит из:

• Необязательного буквенно-цифрового короткого флага, за которым следует / если короткий флаг может быть использован при вызове вашей команды, или для обратной совместимости - если он не должен быть доступен как действительный короткий флаг (в этом случае он также не будет доступен как переменная флага).
• Необязательное длинное имя флага; если оно отсутствует, можно использовать короткий флаг, а если и этого нет, то сообщается об ошибке.

• Ничего, если флаг является булевым и не принимает аргумент, или это целочисленный флаг, или

  • = если он требует значения и сохраняется только последнее вхождение флага, или
  • =? если он принимает необязательное значение и сохраняется только последнее вхождение флага, или
  • =+ если он требует значения и сохраняется каждое вхождение флага.
• Необязательно ! за которым следует скрипт fish для проверки значения. Обычно это будет вызываемая функция. Если возвращаемый код равен нулю, значение флага допустимо. Если ненулевой - значение недопустимо. Любые сообщения об ошибках должны быть выведены в стандартный вывод (а не в стандартный поток ошибок). См. раздел Проверка значения флага для получения дополнительной информации.

См. команду fish_opt для более удобного, но более подробного способа создания спецификаций опций.

Если флаг не используется при обработке аргументов, соответствующая переменная _flag_X не будет установлена.

Целочисленный флаг

Иногда команды принимают числа напрямую как опции, например foo -55. Для этого одна спецификация опции может иметь модификатор #, так что любое целое число будет распознаваться как этот флаг, и последнее число будет использоваться как его значение (как если бы = использовалось).

# должен следовать за буквой короткого флага (если она есть), и другие модификаторы, такие как =, не разрешены, за исключением - (для обратной совместимости):

m#maximum

Это не читает числа, заданные как +NNN, только те, которые выглядят как флаги - -NNN.

Примечание: необязательные аргументы

Опция, определённая с помощью =?, может принимать необязательные аргументы. Необязательные аргументы должны быть непосредственно связаны с опцией, к которой они относятся.

Это означает, что аргумент будет использоваться только для опции, если вы используете его так:

cmd --flag=value
# or
cmd  -fvalue

но не если вы используете его так:

cmd --flag value
# "value" here will be used as a positional argument
# and "--flag" won't have an argument.

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

Например:

grep --color auto
# Here "auto" will be used as the search string,
# "color" will not have an argument and will fall back to the default,
# which also *happens to be* auto.
grep --color always
# Here grep will still only use color "auto"matically
# and search for the string "always".

Это не специфично для argparse, но характерно для всех инструментов, использующих getopt(3) (если они имеют необязательные аргументы вообще). Пример grep иллюстрирует поведение GNU grep.

Проверка значения флага

Иногда вам нужно проверить значения опций. Например, является ли это допустимым целым числом в определённом диапазоне, или IP-адресом, или чем-то совершенно другим. Вы всегда можете сделать это после того, как argparse вернётся, но вы также можете попросить argparse выполнить проверку, выполнив произвольный скрипт fish. Для этого просто добавьте ! (восклицательный знак), а затем скрипт fish, который нужно выполнить. При выполнении этого кода будут определены три переменные:

• _argparse_cmd будет установлено в значение значения argparse --name.
• _flag_name будет установлено в короткий или длинный флаг, который обрабатывается.
• _flag_value будет установлено в значение, связанное с обрабатываемым флагом.

Эти переменные передаются функции как экспортированные локальные переменные.

Скрипт должен выводить любые сообщения об ошибках в стандартный вывод, а не в стандартный поток ошибок. Он должен возвращать состояние 0, если значение флага допустимо, и ненулевое состояние, чтобы указать, что оно недопустимо.

Fish поставляется с функцией _validate_int, которая принимает --min и --max флаги. Предположим, ваша команда принимает флаги -m или --max, и минимальное допустимое значение равно нулю, а максимальное — 5. Вы определили бы опцию следующим образом: m/max=!_validate_int --min 0 --max 5. По умолчанию, если вы просто вызываете _validate_int без этих флагов, просто проверяется, является ли значение допустимым целым числом без ограничений на минимальное или максимальное допустимое значение.

Вот несколько примеров проверки значений флагов:

# validate that a path is a directory
argparse 'p/path=!test -d "$_flag_value"' -- --path $__fish_config_dir
# validate that a function does not exist
argparse 'f/func=!not functions -q "$_flag_value"' -- -f alias
# validate that a string matches a regex
argparse 'c/color=!string match -rq \'^#?[0-9a-fA-F]{6}$\' "$_flag_value"' -- -c 'c0ffee'
# validate with a validator function
argparse 'n/num=!_validate_int --min 0 --max 99' -- --num 42

Примеры OPTION_SPEC

Некоторые примеры OPTION_SPEC:

• h/help означает, что и -h, и --help являются допустимыми. Флаг — булевый и может использоваться более одного раза. Если любой из флагов используется, то _flag_h и _flag_help будут установлены в соответствии с тем, как был увиден каждый из флагов, столько раз, сколько он был увиден. Таким образом, он может быть установлен в -h, -h и --help, а count $_flag_h даст «3».
• help означает, что допустим только --help. Флаг — булевый и может использоваться более одного раза. Если он используется, то _flag_help будет установлен, как описано выше. Также h-help (с произвольной короткой буквой) для обеспечения обратной совместимости.
• longonly= — это флаг --longonly, требующий опцию. Нет короткого флага или даже переменной короткого флага.
• n/name= означает, что и -n, и --name являются допустимыми. Требуется значение и может использоваться не более одного раза. Если флаг встречен, _flag_n и _flag_name будут установлены с единственным обязательным значением, связанным с флагом.
• n/name=? означает, что и -n, и --name являются допустимыми. Принимает необязательное значение и может использоваться не более одного раза. Если флаг встречен, _flag_n и _flag_name будут установлены со значением, связанным с флагом, если оно было предоставлено, иначе они будут установлены без значений.
• name=+ означает, что допустим только --name. Требуется значение и может использоваться более одного раза. Если флаг встречен, то _flag_name будет установлен со значениями, связанными с каждым случаем.
• x означает, что допустим только -x. Это булевый флаг, который может использоваться более одного раза. Если он встречен, то _flag_x будет установлен, как указано выше.
• x=, x=?, и x=+ аналогичны примерам n/имя выше, но нет альтернативы длинному флагу для короткого флага -x.
• #max (или #-max) означает, что флагом, соответствующим регулярному выражению “^--?\d+$”, являются допустимыми. При встрече они назначаются переменной _flag_max. Это позволяет указать любое допустимое целое положительное или отрицательное число, добавив перед ним одиночный «-». Многие команды поддерживают этот прием. Например, head -3 /a/file для вывода только первых трех строк из /a/file.
• n#max означает, что флагом, соответствующим регулярному выражению “^--?\d+$”, являются допустимыми. При встрече они назначаются переменным _flag_n и _flag_max. Это позволяет указать любое допустимое целое положительное или отрицательное число, добавив перед ним одиночный «-». Многие команды поддерживают этот прием. Например, head -3 /a/file для вывода только первых трех строк из /a/file. Вы также можете указать значение, используя любой из флагов: -n NNN или --max NNN в этом примере.
• #longonly приводит к тому, что последнее целочисленное значение опции хранится в _flag_longonly.

После обработки аргументов переменная argv устанавливается в локальной области видимости со всеми значениями, которые еще не были использованы во время обработки флагов. Если неопределенных значений нет, переменная устанавливается, но count $argv будет равно нулю.

Если во время обработки argparse возникает ошибка, выполнение завершится с ненулевым статусом и будут выведены сообщения об ошибках в stderr.

Ограничения

Одним из ограничений с --ignore-unknown является то, что если неизвестная опция указана в группе с известными опциями, вся группа останется в $argv. argparse не будет выполнять здесь никаких перестановок.

Например:

argparse --ignore-unknown h -- -ho
echo $_flag_h # is -h, because -h was given
echo $argv # is still -ho

Это ограничение может быть снято в будущем.

Кроме того, он может анализировать известные опции только до первой неизвестной опции в группе — неизвестная опция может принимать опции, поэтому неясно, что означает любой символ после неизвестной опции.