Elixir

v1.0.5

Elixir v1.0.5 OptionParser

This module contains functions to parse command line arguments.

Summary

Types

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

Functions

next(argv, opts \\ [])

Low-level function that parses one option

parse(argv, opts \\ [])

Parses argv into a keywords list

parse_head(argv, opts \\ [])

Similar to parse/2 but only parses the head of argv; as soon as it finds a non-switch, it stops parsing

split(string)

Splits a string into argv chunks

to_argv(enum)

Receives a key-value enumerable and convert it to argv

Types 

argv :: [String.t]
errors :: [{String.t, String.t | nil}]
options :: [switches: Keyword.t, strict: Keyword.t, aliases: Keyword.t]

Functions

next(argv, opts \\ [])

Specs

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}

Low-level function that parses one option.

It accepts the same options as parse/2 and parse_head/2 as both functions are built on top of next. This function may return:

  • {:ok, key, value, rest} - the option key with value was successfully parsed

  • {:invalid, key, value, rest} - the option key is invalid with value (returned when the switch type does not match the one given via the command line)

  • {:undefined, key, value, rest} - the option key is undefined (returned on strict cases and the switch is unknown)

  • {:error, rest} - there are no switches at the top of the given argv
parse(argv, opts \\ [])

Specs

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

Parses argv into a keywords list.

It returns the parsed values, remaining arguments and the invalid options.

Examples

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"], []}

By default, Elixir will try to automatically parse switches. Switches without an argument, like --debug will automatically be set to true. Switches followed by a value will be assigned to the value, always as strings.

Note Elixir also converts the switches to underscore atoms, as --source-path becomes :source_path, to better suit Elixir conventions. This means that option names on the command line cannot contain underscores; such options will be reported as :undefined (in strict mode) or :invalid (in basic mode).

Switches

Many times though, it is better to explicitly list the available switches and their formats. The switches can be specified via two different options:

  • :strict - the switches are strict. Any switch that does not exist in the switch list is treated as an error.

  • :switches - defines some switches. Switches that does not exist in the switch list are still attempted to be parsed.

Note only :strict or :switches may be given at once.

For each switch, the following types are supported:

  • :boolean - marks the given switch as a boolean. Boolean switches

             never consume the following value unless it is `true` or
         `false`.
  • :integer - parses the switch as an integer.
  • :float - parses the switch as a float.
  • :string - returns the switch as a string.

If a switch can’t be parsed or is not specified in the strict case, the option is returned in the invalid options list (third element of the returned tuple).

The following extra “types” are supported:

  • :keep - keeps duplicated items in the list instead of overriding

Examples:

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(["--unknown", "xyz"], strict: [])
{[], ["xyz"], [{"--unknown", nil}]}

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

Negation switches

In case a switch is declared as boolean, it may be passed as --no-SWITCH which will set the option to false:

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

Aliases

A set of aliases can be given as options too:

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

Specs

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

Similar to parse/2 but only parses the head of argv; as soon as it finds a non-switch, it stops parsing.

See parse/2 for more information.

Example

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"], []}
split(string)

Specs

split(String.t) :: argv

Splits a string into argv chunks.

Examples

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

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

Specs

to_argv(Enumerable.t) :: argv

Receives a key-value enumerable and convert it to argv.

Keys must be atoms. Keys with nil value are discarded, boolean values are converted to --key or --no-key and all other values are converted using to_string/1.

Examples

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

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