OptionParser

В этом модуле содержатся функции для парсинга командной строки.

Краткое описание

Типы

argv()
errors()
options()
parsed()

Функции

next(argv, opts \\ []): Функция низкого уровня, которая парсит один параметр.
parse(argv, opts \\ []): Парсит argv в список ключевых слов.
parse!(argv, opts \\ []): То же самое, что и parse/2, но вызывает исключение OptionParser.ParseError, если указаны какие-либо недопустимые параметры.
parse_head(argv, opts \\ []): Аналогично parse/2, но парсит только начало argv; как только он находит непереключатель, он прекращает парсинг.
parse_head!(argv, opts \\ []): То же самое, что и parse_head/2, но вызывает исключение OptionParser.ParseError, если указаны какие-либо недопустимые параметры.
split(string): Разделяет строку на фрагменты argv/0.
to_argv(enum, opts \\ []): Принимает перечисляемый список пар «ключ-значение» и преобразует его в argv/0.

Типы

argv()

argv() :: [String.t()]

errors()

errors() :: [{String.t(), String.t() | nil}]

options()

options() :: [switches: keyword(), strict: keyword(), aliases: keyword()]

parsed()

parsed() :: keyword()

Функции

next(argv, opts \\ [])

next(argv(), options()) ::
  {:ok, key :: atom(), value :: term(), argv()}
  | {:invalid, String.t(), String.t() | nil, argv()}
  | {:undefined, String.t(), String.t() | nil, argv()}
  | {:error, argv()}

Функция низкого уровня, которая парсит один параметр.

Она принимает те же параметры, что и parse/2 и parse_head/2, так как обе функции построены на основе этой функции. Эта функция может возвращать:

{:ok, key, value, rest} - параметр key с value был успешно распарсен
{:invalid, key, value, rest} - параметр key недопустим с value (возвращается, когда значение нельзя распарсить в соответствии с типом переключателя)
{:undefined, key, value, rest} - параметр key не определен (возвращается в строгом режиме, когда переключатель неизвестен)
{:error, rest} - переключатели отсутствуют в начале заданных argv

parse(argv, opts \\ [])

parse(argv(), options()) :: {parsed(), argv(), errors()}

Парсит argv в список ключевых слов.

Возвращает кортеж из трех элементов с формой {parsed, args, invalid}, где:

parsed — список ключевых слов распарсенных переключателей со вложенными кортежами {switch_name, value}; switch_name — атом, представляющий имя переключателя, а value — значение этого переключателя, распарсенное в соответствии с opts (см. раздел «Примеры» для получения дополнительной информации)
args — список оставшихся аргументов в argv в виде строк
invalid — список недопустимых параметров в виде {option_name, value}, где option_name — исходный параметр, а value — nil если параметр не был ожидаемым или строковое значение, если значение не имело ожидаемого типа для соответствующего параметра

Elixir преобразует переключатели в атомы с подчеркиванием, поэтому --source-path становится :source_path. Это сделано для лучшего соответствия соглашениям Elixir. Однако это означает, что переключатели не могут содержать подчеркивания, а переключатели, содержащие подчеркивания, всегда возвращаются в списке недопустимых переключателей.

При парсинге обычно указываются переключатели и их ожидаемые типы:

iex> OptionParser.parse(["--debug"], switches: [debug: :boolean])
{[debug: true], [], []}

iex> OptionParser.parse(["--source", "lib"], switches: [source: :string])
{[source: "lib"], [], []}

iex> OptionParser.parse(["--source-path", "lib", "test/enum_test.exs", "--verbose"],
...>                    switches: [source_path: :string, verbose: :boolean])
{[source_path: "lib", verbose: true], ["test/enum_test.exs"], []}

Мы рассмотрим допустимые переключатели и режимы работы парсера параметров ниже.

Параметры

Поддерживаются следующие параметры:

:switches или :strict — см. раздел «Определения переключателей» ниже
:allow_nonexistent_atoms — см. раздел «Парсинг динамических переключателей» ниже
:aliases — см. раздел «Псевдонимы» ниже

Определения переключателей

Переключатели можно указать с помощью одного из двух вариантов:

:switches — определяет некоторые переключатели и их типы. Эта функция по-прежнему пытается распарсить переключатели, которые не находятся в этом списке.
:strict — определяет строгие переключатели. Любой переключатель в argv, который не указан в списке, возвращается в списке недопустимых параметров.

Оба этих параметра принимают список ключевых слов кортежей {name, type}, где name — атом, определяющий имя переключателя, а type — атом, определяющий тип значения этого переключателя (см. раздел «Типы» ниже для возможных типов и дополнительной информации о приведении типов).

Обратите внимание, что вы должны указать только параметр :switches или :strict. Если вы укажете оба, будет выброшено исключение ArgumentError.

Типы

Переключатели, распарсенные функцией OptionParser, могут принимать ноль или один аргумент.

Следующие типы переключателей не принимают аргументов:

:boolean — устанавливает значение в true при передаче (см. также раздел «Переключатели с отрицанием» ниже)
:count — считает количество раз, когда переключатель используется

Следующие переключатели принимают один аргумент:

:integer — распарсивает значение как целое число
:float — распарсивает значение как число с плавающей точкой
:string — распарсивает значение как строку

Если переключатель нельзя распарсить в соответствии с заданным типом, он возвращается в списке недопустимых параметров.

Модификаторы

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

:keep — сохраняет дублированные элементы вместо их перезаписи; работает со всеми типами, кроме :count. Указание switch_name: :keep предполагает, что тип :switch_name будет :string.

Чтобы использовать :keep с типом, отличным от :string, используйте список в качестве типа для переключателя. Например: [foo: [:integer, :keep]].

Переключатели с отрицанием

Если переключатель SWITCH задан с типом :boolean, его можно также передать как --no-SWITCH, что установит параметр в false.

iex> OptionParser.parse(["--no-op", "path/to/file"], switches: [op: :boolean])
{[op: false], ["path/to/file"], []}

Парсинг динамических переключателей

OptionParser также включает динамический режим, где он попытается динамически распарсить переключатели. Это можно сделать, не указывая параметр :switches или :strict.

iex> OptionParser.parse(["--debug"])
{[debug: true], [], []}

Переключатели, за которыми следует значение, будут назначены это значение как строка. Переключатели без аргумента, такие как --debug в приведенных выше примерах, будут автоматически установлены в значение true.

Поскольку Elixir преобразует переключатели в атомы, динамический режим будет распарсить только переключатели, соответствующие атомам, используемым во время выполнения. Поэтому приведенный ниже код, вероятно, не распарсит заданный параметр, так как атом :option_parser_example нигде не используется:

OptionParser.parse(["--option-parser-example"])
# The :option_parser_example atom is not used anywhere below

Однако приведенный ниже код распарсит этот параметр, так как атом :option_parser_example используется где-то позже (или раньше):

{opts, _, _} = OptionParser.parse(["--option-parser-example"])
opts[:option_parser_example]

Другими словами, при использовании динамического режима Elixir сделает правильную вещь и распарсит только те параметры, которые используются во время выполнения, игнорируя все остальные. Если вы хотите распарсить все переключатели, независимо от того, существуют ли они или нет, вы можете принудительно создать атомы, передав allow_nonexistent_atoms: true в качестве параметра. Этот параметр полезен при создании приложений командной строки, которые принимают динамически названные аргументы, но следует использовать с осторожностью в долгоживущих системах.

Псевдонимы

Набор псевдонимов можно указать в параметре :aliases:

iex> OptionParser.parse(["-d"], aliases: [d: :debug])
{[debug: true], [], []}

Примеры

Ниже приведены примеры работы с различными типами и модификаторами:

iex> OptionParser.parse(["--unlock", "path/to/file"], strict: [unlock: :boolean])
{[unlock: true], ["path/to/file"], []}

iex> OptionParser.parse(["--unlock", "--limit", "0", "path/to/file"],
...>                    strict: [unlock: :boolean, limit: :integer])
{[unlock: true, limit: 0], ["path/to/file"], []}

iex> OptionParser.parse(["--limit", "3"], strict: [limit: :integer])
{[limit: 3], [], []}

iex> OptionParser.parse(["--limit", "xyz"], strict: [limit: :integer])
{[], [], [{"--limit", "xyz"}]}

iex> OptionParser.parse(["--verbose"], switches: [verbose: :count])
{[verbose: 1], [], []}

iex> OptionParser.parse(["-v", "-v"], aliases: [v: :verbose], strict: [verbose: :count])
{[verbose: 2], [], []}

iex> OptionParser.parse(["--unknown", "xyz"], strict: [])
{[], ["xyz"], [{"--unknown", nil}]}

iex> OptionParser.parse(["--limit", "3", "--unknown", "xyz"],
...>                    switches: [limit: :integer])
{[limit: 3, unknown: "xyz"], [], []}

iex> OptionParser.parse(["--unlock", "path/to/file", "--unlock", "path/to/another/file"], strict: [unlock: :keep])
{[unlock: "path/to/file", unlock: "path/to/another/file"], [], []}

parse!(argv, opts \\ [])

parse!(argv(), options()) :: {parsed(), argv()} | no_return()

То же самое, что и parse/2, но вызывает исключение OptionParser.ParseError, если указаны какие-либо недопустимые параметры.

Если ошибок нет, возвращается кортеж {parsed, rest}, где:

parsed — список распарсенных переключателей (то же, что и в parse/2)
rest — список аргументов (то же, что и в parse/2)

Примеры

iex> OptionParser.parse!(["--debug", "path/to/file"], strict: [debug: :boolean])
{[debug: true], ["path/to/file"]}

iex> OptionParser.parse!(["--limit", "xyz"], strict: [limit: :integer])
** (OptionParser.ParseError) 1 error found!
--limit : Expected type integer, got "xyz"

iex> OptionParser.parse!(["--unknown", "xyz"], strict: [])
** (OptionParser.ParseError) 1 error found!
--unknown : Unknown option

iex> OptionParser.parse!(["-l", "xyz", "-f", "bar"],
...>                     switches: [limit: :integer, foo: :integer], aliases: [l: :limit, f: :foo])
** (OptionParser.ParseError) 2 errors found!
-l : Expected type integer, got "xyz"
-f : Expected type integer, got "bar"

parse_head(argv, opts \\ [])

parse_head(argv(), options()) :: {parsed(), argv(), errors()}

Аналогично parse/2, но парсит только начало argv; как только он находит непереключатель, он прекращает парсинг.

См. parse/2 для получения дополнительной информации.

Пример

iex> OptionParser.parse_head(["--source", "lib", "test/enum_test.exs", "--verbose"],
...>                         switches: [source: :string, verbose: :boolean])
{[source: "lib"], ["test/enum_test.exs", "--verbose"], []}

iex> OptionParser.parse_head(["--verbose", "--source", "lib", "test/enum_test.exs", "--unlock"],
...>                         switches: [source: :string, verbose: :boolean, unlock: :boolean])
{[verbose: true, source: "lib"], ["test/enum_test.exs", "--unlock"], []}

parse_head!(argv, opts \\ [])

parse_head!(argv(), options()) :: {parsed(), argv()} | no_return()

То же самое, что и parse_head/2, но при этом генерирует исключение OptionParser.ParseError, если предоставлены какие-либо недопустимые параметры.

Если ошибок нет, возвращает кортеж {parsed, rest}, где:

parsed — список обработанных флагов (совпадает со значением в parse_head/2)
rest — список аргументов (совпадает со значением в parse_head/2)

Примеры

iex> OptionParser.parse_head!(["--source", "lib", "path/to/file", "--verbose"],
...>                         switches: [source: :string, verbose: :boolean])
{[source: "lib"], ["path/to/file", "--verbose"]}

iex> OptionParser.parse_head!(["--number", "lib", "test/enum_test.exs", "--verbose"],
...>                          strict: [number: :integer])
** (OptionParser.ParseError) 1 error found!
--number : Expected type integer, got "lib"

iex> OptionParser.parse_head!(["--verbose", "--source", "lib", "test/enum_test.exs", "--unlock"],
...>                          strict: [verbose: :integer, source: :integer])
** (OptionParser.ParseError) 2 errors found!
--verbose : Missing argument of type integer
--source : Expected type integer, got "lib"

split(string)

split(String.t()) :: argv()

Разделяет строку на фрагменты argv/0.

Эта функция разделяет заданную string строку на список строк похожим образом, как это делают многие оболочки.

Примеры

iex> OptionParser.split("foo bar")
["foo", "bar"]

iex> OptionParser.split("foo \"bar baz\"")
["foo", "bar baz"]

to_argv(enum, opts \\ [])

to_argv(Enumerable.t(), options()) :: argv()

Принимает перечисляемый объект со значениями key-value и преобразует его в argv/0.

Ключи должны быть атомами. Ключи со значением nil игнорируются, логические значения преобразуются в --key или --no-key (если значение соответственно true или false ), а все остальные значения преобразуются с помощью Kernel.to_string/1.

Рекомендуется передавать в to_argv/2 тот же набор options параметров, что и в parse/2. Некоторые флаги могут быть корректно реконструированы только с использованием информации о switches.

Примеры

iex>  OptionParser.to_argv([foo_bar: "baz"])
["--foo-bar", "baz"]
iex>  OptionParser.to_argv([bool: true, bool: false, discarded: nil])
["--bool", "--no-bool"]

Некоторые флаги будут выводить разные значения в зависимости от флага переключателя:

iex> OptionParser.to_argv([number: 2], switches: [])
["--number", "2"]
iex> OptionParser.to_argv([number: 2], switches: [number: :count])
["--number", "--number"]