Module argparse

Command line parser, made with hierarchy of commands in mind.

Authors: Maxim Fedorov, (maximfca@gmail.com).

Description

Command line parser, made with hierarchy of commands in mind. Parser operates with arguments and commands, organised in a hierarchy. It is possible to define multiple commands, or none. Parsing always starts with root command, named after init:get_argument(progname). Empty command produces empty argument map:
   1> parse("", #{}).
      #{}
If root level command does not contain any sub-commands, parser returns plain map of argument names to their values:
   3> argparse:parse(["value"], #{arguments => [#{name => arg}]}).
   #{arg => "value"}

This map contains all arguments matching command line passed, initialised with corresponding values. If argument is omitted, but default value is specified for it, it is added to the map. When no default value specified, and argument is not present, corresponding key is not present in the map.

Missing required (field required is set to true for optional arguments, or missing for positional) arguments raises an error.

When there are sub-commands, parser returns argument map, deepest matched command name, and a sub-spec passed for this command:
   4> Cmd =  #{arguments => [#{name => arg}]}.
   #{arguments => [#{name => arg}]}
   5> argparse:parse(["cmd", "value"], #{commands => #{"cmd" => Cmd}}).
   {#{arg => "value"},{"cmd",#{arguments => [#{name => arg}]}}}

Data Types

arg_map()

arg_map() = #{term() => term()}

Arguments map: argument name to a term, produced by parser. Supplied to command handler

arg_type()

arg_type() = boolean | float | {float, [float()]} | {float, [{min, float()} | {max, float()}]} | int | {int, [integer()]} | {int, [{min, integer()} | {max, integer()}]} | string | {string, [string()]} | {string, string()} | {string, string(), [term()]} | binary | {binary, [binary()]} | {binary, binary()} | {binary, binary(), [term()]} | atom | {atom, [atom()]} | {atom, unsafe} | {custom, fun((string()) -> term())}

argparse_reason()

argparse_reason() = {invalid_command, cmd_path(), Field::atom(), Reason::string()} | {invalid_option, cmd_path(), Name::string(), Field::atom(), Reason::string()} | {unknown_argument, cmd_path(), Argument::string()} | {missing_argument, cmd_path(), argument()} | {invalid_argument, cmd_path(), argument(), Argument::string()}

argument()

argument() = #{name := atom() | string() | binary(), short => char(), long => string(), required => true, default => term(), type => arg_type(), action => store | {store, term()} | append | {append, term()} | count | extend, nargs => pos_integer() | maybe | {maybe, term()} | list | nonempty_list | all, help => string()}

cmd_path()

cmd_path() = [string()]

Command path, for deeply nested sub-commands

command()

command() = #{commands => command_map(), arguments => [argument()], help => string(), handler => handler()}

command_map()

command_map() = #{string() => command()}

Sub-commands are arranged into maps (cannot start with prefix)

command_spec()

command_spec() = {Name::string(), command()}

Command name with command spec

handler()

handler() = optional | fun((arg_map()) -> term()) | {module(), Fn::atom()} | {fun((arg_map()) -> term()), term()} | {module(), atom(), term()}

parse_result()

parse_result() = arg_map() | {arg_map(), command_spec()}

Result returned from parse/2,3: can be only argument map, or argument map with command_spec.

parser_options()

parser_options() = #{prefixes => [integer()], progname => string(), command => [string()]}

Function Index

format_error/1Format exception reasons produced by parse/2.
format_error/3Formats exception, and adds command usage information for command that was known/parsed when exception was raised.
help/1Equivalent to help(Command, #{}).
help/2 Returns help for Command formatted according to Options specified.
parse/2Equivalent to parse(Args, Command, #{}).
parse/3Parses supplied arguments according to expected command definition.
validate/1 Built-in types include basic validation abilities String and binary validation may use regex match (ignoring captured value).
validate/2Validate command specification, taking Options into account.

Function Details

format_error/1

format_error(Reason::argparse_reason()) -> string()

returns: string, ready to be printed via io:format().

Format exception reasons produced by parse/2. Exception of class error with reason {argparse, Reason} is normally raised, and format_error accepts only the Reason part, leaving other exceptions that do not belong to argparse out.

format_error/3

format_error(Reason::argparse_reason(), Command::command() | command_spec(), Options::parser_options()) -> string()

returns: string, ready to be printed via io:format().

Formats exception, and adds command usage information for command that was known/parsed when exception was raised.

help/1

help(Command::command() | command_spec()) -> string()

Equivalent to help(Command, #{}).

help/2

help(Command::command() | command_spec(), Options::parser_options()) -> string()

Returns help for Command formatted according to Options specified

parse/2

parse(Args::[string()], Command::command() | command_spec()) -> parse_result()

Equivalent to parse(Args, Command, #{}).

parse/3

parse(Args::[string()], Command::command() | command_spec(), Options::parser_options()) -> parse_result()

Args: command line arguments (e.g. init:get_plain_arguments())

returns: argument map, or argument map with deepest matched command definition.

Parses supplied arguments according to expected command definition.

validate/1

validate(Command::command()) -> command_spec()

Equivalent to validate(Command, #{}).

Built-in types include basic validation abilities String and binary validation may use regex match (ignoring captured value). For float, int, string, binary and atom type, it is possible to specify available choices instead of regex/min/max.

validate/2

validate(Command::command(), Options::parser_options()) -> command_spec()

Validate command specification, taking Options into account. Generates error signal when command specification is invalid.


Generated by EDoc