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

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

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

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

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

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

Ограничения

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

Например:

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

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

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