View Source args (argparse v2.0.0)
init:get_argument(progname). Empty command produces empty argument map: 1> parse("", #{}).
#{} 3> args: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> args:parse(["cmd", "value"], #{commands => #{"cmd" => Cmd}}).
{#{arg => "value"},{"cmd",#{arguments => [#{name => arg}]}}}Link to this section Summary
Types
Arguments map: argument name to a term, produced by parser. Supplied to command handler
Command path, for deeply nested sub-commands
Sub-commands are arranged into maps (cannot start with prefix)
Command name with command spec
Result returned from parse/2,3: can be only argument map, or argument map with command_spec.
Functions
Format exception reasons produced by parse/2. Exception of class error with reason {args, Reason} is normally raised, and format_error accepts only the Reason part, leaving other exceptions that do not belong to argparse out.
Formats exception, and adds command usage information for command that was known/parsed when exception was raised.
Equivalent to help(Command, #{}).
Returns help for Command formatted according to Options specified
Equivalent to parse(Args, Command, #{}).
Parses supplied arguments according to expected command definition.
Equivalent to validate(Command, #{}).
Validate command specification, taking Options into account. Generates error signal when command specification is invalid.
Link to this section Types
-type arg_map() :: #{term() => term()}.
-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())}.
-type 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()}.
-type argument() :: #{name := atom() | string() | binary(), short => char(), long => string(), required => boolean(), 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 => hidden | string() | argument_help()}.
-type argument_help() :: {string(), [string() | type | default]}.
-type cmd_path() :: [string()].
-type command() :: #{commands => command_map(), arguments => [argument()], help => hidden | string(), handler => handler()}.
-type command_map() :: #{string() => command()}.
-type command_spec() :: {Name :: [string()], command()}.
-type parse_result() :: arg_map() | {arg_map(), command_spec()}.
-type parser_options() ::
#{prefixes => [integer()],
default => term(),
progname => string() | atom(),
command => [string()]}.
Link to this section Functions
-spec format_error(Reason :: argparse_reason()) -> string().
-spec format_error(argparse_reason(), command() | command_spec(), parser_options()) -> string().
-spec help(command() | command_spec()) -> string().
Equivalent to help(Command, #{}).
-spec help(command() | command_spec(), parser_options()) -> string().
-spec parse(Args :: [string()], command() | command_spec()) -> parse_result().
Equivalent to parse(Args, Command, #{}).
-spec parse(Args :: [string()], command() | command_spec(), Options :: parser_options()) -> parse_result().
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.-spec validate(command(), parser_options()) -> {Progname :: string(), command()}.