parse(argv, opts \\ [])

It returns a three-element tuple with the form {parsed, args, invalid}, where:

parsed is a keyword list of parsed switches with {switch_name, value} tuples in it; switch_name is the atom representing the switch name while value is the value for that switch parsed according to opts (see the “Examples” section for more information)

args is a list of the remaining arguments in argv as strings

invalid is a list of invalid options as {option_name, value} where option_name is the raw option and value is nil if the option wasn’t expected or the string value if the value didn’t have the expected type for the corresponding option

Elixir converts switches to underscored atoms, so --source-path becomes :source_path. This is done to better suit Elixir conventions. However, this means that switches can’t contain underscores and switches that do contain underscores are always returned in the list of invalid switches.

Switch definitions

:switches - defines some switches and their types. This function still attempts to parse switches that are not in this list.

:strict - defines strict switches. Any switch in argv that is not specified in the list is returned in the invalid options list.

Both these options accept a keyword list of {name, type} tuples where name is an atom defining the name of the switch and type is an atom that specifies the type for the value of this switch (see the “Types” section below for the possible types and more information about type casting).

Note that you should only supply the :switches or the:strict option. If you supply both, an ArgumentError exception will be raised.

Parsing dynamic switches

OptionParser also includes a dynamic mode where it will attempt to parse switches dynamically. Such can be done by not specifying the :switches or :strict option.

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

Switches followed by a value will be assigned the value, as a string. Switches without an argument, like --debug in the examples above, will automatically be set to true.

Since Elixir converts switches to atoms, the dynamic mode will only parse switches that translate to atoms used by the runtime. Therefore, the code below likely won’t parse the given option since the :option_parser_example atom is never used anywhere:

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

However, the code below does since the :option_parser_example atom is used at some point later (or earlier) on:

In other words, when using dynamic mode, Elixir will do the correct thing and only parse options that are used by the runtime, ignoring all others. If you would like to parse all switches, regardless if they exist or not, you can force creation of atoms by passing allow_nonexistent_atoms: true as option. Such option is useful when you are building command-line applications that receive dynamically-named arguments but must be used with care on long-running systems.

Switches followed by a value will be assigned the value, as a string. Switches without an argument, like --debug in the examples above, will automatically be set to true.

to_argv(enum, opts \\ [])

Keys must be atoms. Keys with nil value are discarded, boolean values are converted to --key or --no-key (if the value is true or false, respectively), and all other values are converted using Kernel.to_string/1.

It is advised to pass to to_argv/2 the same set of options given to parse/2. Some switches can only be reconstructed correctly with the switches information in hand.