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 NUMBER

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

-X или --max-args NUMBER

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

-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 завершается с кодом 0. В противном случае он выводит соответствующие сообщения об ошибках в stderr и завершается с кодом 1.

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

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

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

Но это не так:

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

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

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

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

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

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

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

См. команду 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 будет установлена в значение, связанное с обрабатываемым флагом.

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

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

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

Примеры OPTION_SPEC

Примеры OPTION_SPEC:

• h/help означает, что оба -h и --help являются допустимыми. Флаг является булевым и может использоваться более одного раза. Если любой из флагов используется, то _flag_h и _flag_help будут установлены в счёт того, сколько раз был замечен любой из флагов.
• 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/name выше, но нет альтернативы длинного флага для короткого флага -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

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

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