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

© 2021 fish-shell developers
Licensed under the GNU General Public License, version 2.
https://fishshell.com/docs/3.3/cmds/argparse.html