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 завершается со статусом ноль. В противном случае он записывает соответствующие сообщения об ошибках в 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 для проверки значения. Обычно это будет функция для выполнения. Если выходной статус равен нулю, значение флага является допустимым. Если ненулевой, значение недействительно. Любые сообщения об ошибках должны быть выведены на 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 будут установлены в соответствии с тем, как был увиден любой из флагов, столько раз, сколько он был увиден. Таким образом, он может быть установлен в -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/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 произойдет ошибка, то программа завершится с ненулевым кодом возврата и выведет сообщения об ошибке в стандартный поток ошибок.

Ограничения

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

Например:

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

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

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