| Overview |  |
Authors: Maxim Fedorov, (maximfca@gmail.com).
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}]}}}
arg_map() = #{term() => term()}
Arguments map: argument name to a term, produced by parser. Supplied to command handler
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() = {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() = #{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()}
argument_help() = {string(), [string() | type | default]}
long description, default is [help, " (", type, ", ", default, ")"] - "floating-point long form argument, float, [3.14]"
cmd_path() = [string()]
Command path, for deeply nested sub-commands
command() = #{commands => command_map(), arguments => [argument()], help => hidden | string(), handler => handler()}
command_map() = #{string() => command()}
Sub-commands are arranged into maps (cannot start with prefix)
command_spec() = {Name::string(), command()}
Command name with command spec
handler() = optional | fun((arg_map()) -> term()) | {module(), Fn::atom()} | {fun((arg_map()) -> term()), term()} | {module(), atom(), term()}
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() = #{prefixes => [integer()], progname => string() | atom(), command => [string()]}
| format_error/1 | Format exception reasons produced by parse/2. |
| format_error/3 | Formats exception, and adds command usage information for command that was known/parsed when exception was raised. |
| help/1 | Equivalent to help(Command, #{}). |
| help/2 | Returns help for Command formatted according to Options specified. |
| parse/2 | Equivalent to parse(Args, Command, #{}). |
| parse/3 | Parses 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/2 | Validate command specification, taking Options into account. |
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(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(Command::command() | command_spec()) -> string()
Equivalent to help(Command, #{}).
help(Command::command() | command_spec(), Options::parser_options()) -> string()
Returns help for Command formatted according to Options specified
parse(Args::[string()], Command::command() | command_spec()) -> parse_result()
Equivalent to parse(Args, Command, #{}).
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(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(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