Adding and configuring commands
*******************************

A command is a subparser invoked when its name is passed as an
argument. For example, in git CLI "add", "commit", "push", etc. are
commands. Each command has its own set of arguments and options, but
inherits options of its parent.

Commands can be added using ":command(name, description, epilog)"
method. Just as options, commands can have several aliases.

   parser:command "install i"

If a command it used, "true" is stored in the corresponding field of
the result table.

   $ lua script.lua install

   {
      install = true
   }

A typo will result in an appropriate error message.

   $ lua script.lua instal

   Usage: script.lua [-h] <command> ...

   Error: unknown command 'instal'
   Did you mean 'install'?


Getting name of selected command
================================

Use "command_target" property of the parser to store the name of used
command in a field of the result table.

   parser:command_target("command")
   parser:command("install")
   parser:command("remove")

   $ lua script.lua install

   {
      install = true,
      command = "install"
   }


Adding elements to commands
===========================

The Command class is a subclass of the Parser class, so all the
Parser's methods for adding elements work on commands, too.

   local install = parser:command "install"
   install:argument "rock"
   install:option "-f --from"

   $ lua script.lua install foo --from=bar

   {
      install = true,
      rock = "foo",
      from = "bar"
   }

Commands have their own usage and help messages.

   $ lua script.lua install

   Usage: script.lua install [-h] [-f <from>] <rock>

   Error: too few arguments

   $ lua script.lua install --help

   Usage: script.lua install [-h] [-f <from>] <rock>

   Arguments:
      rock

   Options:
      -h, --help            Show this help message and exit.
      -f <from>, --from <from>


Making a command optional
=========================

By default, if a parser has commands, using one of them is obligatory.

   local parser = argparse()
   parser:command "install"

   $ lua script.lua

   Usage: script.lua [-h] <command> ...

   Error: a command is required

This can be changed using "require_command" property.

   local parser = argparse()
      :require_command(false)
   parser:command "install"


Command summaries
=================

The description for commands shown in the parent parser help message
can be set with the "summary" property.

   parser:command "install"
      :summary "Install a rock."
      :description "A long description for the install command."

   $ lua script.lua --help

   Usage: script.lua [-h] <command> ...

   Options:
      -h, --help            Show this help message and exit.

   Commands:
      install               Install a rock.

   $ lua script.lua install --help

   Usage: script.lua install [-h]

   A long description for the install command.

   Options:
      -h, --help            Show this help message and exit.
