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.

1
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.

1
2
3
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.

1
2
3
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.

1
2
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.

1
2
3
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.

1
2
3
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.