View Source cli behaviour (argparse v2.0.0)

Command line utility behaviour. Usage example:

From an escript main/1 function (requires -mode(compile)):
       cli:run(Args).
Or, to limit cli behaviour discovery,
       cli:run(Args, #{modules => ?MODULE, progname => ?MODULE}).
Other options available for run/2:
  • modules:
    • all_loaded - search all loaded modules (code:all_loaded/0) for cli behaviour
    • module() - use this module (must export cli/0)
    • [module()] - list of modules (must export cli/0)
  • warn: set to suppress suppresses warnings logged
  • error: defines what action is taken upon parser error. Use ok to completely ignore the error (historical behaviour, useful for testing), error to raise an exception, halt to halt the emulator with exit code 1 (default behaviour), and {halt, non_neg_integer()} for a custom exit code halting the emulator
  • help: set to false suppresses printing usage when parser produces an error, and disables default --help/-h behaviour
  • prefixes: prefixes passed to argparse
  • progname: specifies executable name instead of 'erl'

Warnings are printed to OTP logger, unless suppressed.

cli framework attempts to create a handler for each command exported, including intermediate (non-leaf) commands, if it can find function exported with suitable signature.

cli examples are available on GitHub

Link to this section Summary

Functions

Equivalent to run(Args, #{}).

CLI entry point, parses arguments and executes selected function. Finds all modules loaded, and implementing cli behaviour, then matches a command and runs handler defined for a command.

Link to this section Types

-type run_options() ::
    #{modules => all_loaded | module() | [module()],
      warn => suppress | warn,
      help => boolean(),
      error => ok | error | halt | {halt, non_neg_integer()},
      prefixes => [integer()],
      default => term(),
      progname => string() | atom()}.

Link to this section Callbacks

Link to this section Functions

-spec run(Args :: [string()]) -> term().

Equivalent to run(Args, #{}).

-spec run([string()], run_options()) -> term().
CLI entry point, parses arguments and executes selected function. Finds all modules loaded, and implementing cli behaviour, then matches a command and runs handler defined for a command.