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

Синтаксис

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

Описание

Эта команда упрощает обработку аргументов для скриптов и функций fish, аналогично тому, как это делают встроенные команды fish. Вы передаёте аргументы, определяющие известные параметры, за которыми следует строка --, а затем — аргументы для парсинга (которые могут также включать строку --). argparse затем устанавливает переменные, указывающие переданные параметры со значениями, и устанавливает $argv (и всегда $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 должны быть за которыми следует список коротких или длинных параметров, которые взаимно исключают друг друга. Вы можете использовать это несколько раз, чтобы определить несколько наборов взаимоисключающих параметров.
• -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
argparse 'h/help' 'n/name' -- $argv

Но это не так:

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

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

Спецификации параметров

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

• Необязательной буквенно-цифровой короткой буквы флага, за которой следует /, если короткая буква может использоваться тем, кто вызывает вашу команду, или, для обратной совместимости, -, если она не должна отображаться как допустимый короткий флаг (в этом случае она также не будет отображаться как переменная флага).
• Необязательное длинное имя флага. Если его нет, то можно использовать только короткую букву флага, и если её нет, то это ошибка.
• Ничего, если флаг — булевский, не принимающий аргумент, или целочисленный флаг, или
• =, если он требует значения, и сохраняется только последнее вхождение флага, или
• =?, если он принимает необязательное значение, и сохраняется только последнее вхождение флага, или
• =+, если он требует значения, и сохраняются все вхождения флага.
• Необязательно !, за которым следует скрипт fish для проверки значения. Обычно это будет функция для выполнения. Если возвращаемый статус равен нулю, значение флага является допустимым. Если ненулевой, значение недействительно. Любые сообщения об ошибках должны выводиться в 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. Он должен возвращать статус ноль, если значение флага является допустимым, иначе ненулевой статус, чтобы указать, что оно недопустимо.

Fish поставляется с функцией _validate_int, которая принимает --min и --max флаги. Предположим, ваша команда принимает флаги -m или --max, и минимальное допустимое значение равно нулю, а максимальное — 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 произошла ошибка, то выполнение программы завершится с ненулевым кодом состояния и будет выведено сообщение об ошибке на стандартный поток ошибок.