ethers.js/docs.wrm/cli/plugin.wrm

_section: Making Your Own @<cli-diy>

The //cli// library is meant to make it easy to create command
line utilities of your own.

_subsection: CLI @<cli-cli> @SRC<cli:class.CLI>

A **CLI** handles parsing all the command-line flags, options and arguments
and instantiates a [[cli-plugin]] to process the command.

A **CLI** may support multiple [[cli-plugin]]'s in which case the first
argument is used to determine which to run (or if no arguments, the default
plugin will be selected) or may be designed to be standalone, in which case
exactly one [[cli-plugin]] will be used and no command argument is allowed.


_property: addPlugin(command, pluginClass) => void  @<cli-addplugin> @SRC<cli/cli>
Add a //plugin// class for the //command//. After all options and flags
have been consumed, the first argument will be consumed and the
associated plugin class will be instantiated and run.

_property: setPlugin(pluginClass) => void  @<cli-setplugin> @SRC<cli/cli>
Set a dedicated [[cli-plugin]] class which will handle all input. This
may not be used in conjunction with addPlugin and will not automatically
accept a command from the arguments.

_property: showUsage([ message = "" [ , status = 0 ] ]) => never  @<cli-showusage> @SRC<cli/cli>
Shows the usage help screen for the CLI and terminates.

_property: run(args) => Promise<void>  @<cli-run> @SRC<cli/cli:CLI.run>
Usually the value of //args// passed in will be ``process.argv.slice(2)``.


_subsection: Plugin  @<cli-plugin> @SRC<cli:class.Plugin>

Each **Plugin** manages each command of a CLI and is executed in phases.

If the usage (i.e. help) of a CLI is requested, the static methods ``getHelp``
and ``getOptionHelp`` are used to generate the help screen.

Otherwise, a plugin is instantiated and the ``prepareOptions`` is called. Each
plugin **must** call ``super.prepareOptions``, otherwise the basic options are
not yet processed. During this time a Plugin should consume all the flags and
options it understands, since any left over flags or options will cause the
CLI to bail and issue an //unknown option// error. This should throw if a value
for a given option is invalid or some combination of options and flags is not
allowed.

Once the prepareOptions is complete (the returned promise is resolved), the ``prepareArguments``
is called. This should validate the number of arguments expected and throw
an error if there are too many or too few arguments or if any arguments do not
make sense.

Once the prepareArguments is complete (the returned promise is resolved), the ``run``
is called.

_property: plugin.network => [[providers-Network]]
The network this plugin is running for.

_property: plugin.provider => [[Provider]]
The provider for this plugin is running for.

_property: plugin.accounts => Array<[[Signer]]>
The accounts passed into the plugin using ``--account``,
``--account-rpc`` and ``--account-void`` which this plugin can use.

_property: plugin.gasLimit => [[BigNumber]]
The gas limit this plugin should use. This is null if unspecified.

_property: plugin.gasPrice => [[BigNumber]]
The gas price this plugin should use. This is null if unspecified.

_property: plugin.nonce => number
The initial nonce for the account this plugin should use.


_heading: Methods

_property: plugin.prepareOptions(argParser [ , verifyOnly = false ]) => Promise<void>  @<plugin-prepareoptions> @SRC<cli/cli:Plugin.prepareOptions>

_property: plugin.prepareArgs(args) =>  Promise<void>  @<plugin-prepareargs> @SRC<cli/cli>

_property: plugin.run() => Promise<void>  @<plugin-run> @SRC<cli/cli:Plugin.run>

_property: plugin.getAddress(addressOrName [ , message = "", [ allowZero = false ] ]) => Promise<string>  @<plugin-getaddress> @SRC<cli/cli:Plugin.getAddress>
A plugin should use this method to resolve an address. If the resolved address is
the zero address and //allowZero// is not true, an error is raised.

_property: plugin.dump(header, info) => void  @<plugin-dump> @SRC<cli/cli:Plugin.dump>
Dumps the contents of //info// to the console with a //header// in a nicely
formatted style. In the future, plugins may support a JSON output format
which will automatically work with this method.

_property: plugin.throwUsageError([ message = "" ]) => never  @<plugin-throwusageerror> @SRC<cli/cli>
Stops execution of the plugin and shows the help screen of the plugin with
the optional //message//.

_property: plugin.throwError(message) => never  @<plugin-throwerror> @SRC<cli/cli>
Stops execution of the plugin and shows //message//.

_heading: Static Methods

_property: Plugin.getHelp => Help  @<plugin-gethelp> @SRC<cli/cli>
Each subclass should implement this static method which is used to
generate the help screen.

_property: Plugin.getOptionHelp => Array<Help>  @<plugin-getoptionshelp> @SRC<cli/cli>
Each subclass should implement this static method if it supports
additional options which is used to generate the help screen.


_subsection: ArgParser @<cli-argparser> @SRC<cli:class.ArgParser>

The **ArgParser** is used to parse a command line into flags, options
and arguments.

_code: @lang<shell>

/home/ethers> ethers --account wallet.json --yes send ricmoo.eth 1.0
#  An Option ----------^                     ^   ^
#    - name =  "account"                     |   |
#    - value = "wallet.json"                 |   |
#  A Flag -----------------------------------+   |
#    - name  = "yes"                             |
#    - value = true                              |
#  Arguments ------------------------------------+
#    - count = 3
#    - [ "send", "ricmoo.eth", "1.0" ]

_null:

Flags are simple binary options (such as the ``--yes``), which are true if present
otherwise false.

Options require a single parameter follow them on the command line
(such as ``--account wallet.json``, which has the name ``account`` and the value
``wallet.json``)

Arguments are all other values on the command line, and are not accessed through
the **ArgParser** directly.

When a CLI is run, an **ArgParser** is used to validate the command line by using
prepareOptions, which consumes all flags and options leaving only the arguments
behind, which are then passed into prepareArgs.

_property: argParser.consumeFlag(name) => boolean  @<argparser-consumeflag> @SRC<cli/cli>
Remove the flag //name// and return true if it is present.

_property: argParser.consumeMultiOptions(names) => Array<{ name: string, value: string}>  @<argparser-consumemultioptions> @SRC<cli/cli>
Remove all options which match any name in the Array of //names//
with their values returning the list (in order) of values.

_property: argParser.consumeOption(name) => string  @<argparser-consumeoption> @SRC<cli/cli>
Remove the option with its value for //name// and return the value. This
will throw a UsageError if the option is included multiple times.

_property: argParser.consumeOptions(name) => Array<string>  @<argparser-consumeoptions> @SRC<cli/cli>
Remove all options with their values for //name// and return the list
(in order) of values.