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.

to_argv(enum)

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

Типы

argv()

argv() :: [String.t]

errors()

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

options()

options() :: [switches: Keyword.t, strict: Keyword.t, aliases: Keyword.t]

parsed()

parsed() :: Keyword.t

Функции

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

Без каких-либо параметров эта функция попытается обработать все переключатели в argv.

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

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

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

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

Параметры

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

• :switches или :strict - см. раздел «Определения переключателей» ниже
• :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"], []}

Псевдонимы

Набор псевдонимов может быть указан в параметре :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"])
{[source: "lib"], ["test/enum_test.exs", "--verbose"], []}

iex> OptionParser.parse_head(["--verbose", "--source", "lib", "test/enum_test.exs", "--unlock"])
{[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"])
{[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.

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

Примеры

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

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

to_argv(enum)

to_argv(Enumerable.t) :: argv

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

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

Примеры

iex>  OptionParser.to_argv([foo_bar: "baz"])
["--foo-bar", "baz"]

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