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()

Принимает перечисляемый объект ключ-значение и преобразует его в 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"]