160 lines
6.8 KiB
Plaintext
160 lines
6.8 KiB
Plaintext
_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 conjuction 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 geneate 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 is expected and throw
|
|
and 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 => [[provider-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 resovled 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 exectuion 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 nhas 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.
|