Creating and using parsers

The argparse module is a function which, when called, creates an instance of the Parser class.

1
2
3
-- script.lua
local argparse = require "argparse"
local parser = argparse()

parser is now an empty parser which does not recognize any command line arguments or options.

Parsing command line arguments

:parse([argv]) method of the Parser class returns a table with processed data from the command line or argv array.

1
local args = parser:parse()

After this is executed with lua script.lua, args is an empty table because the parser is empty and no command line arguments were supplied.

Error handling

If the provided command line arguments are not recognized by the parser, it will print an error message and call os.exit(1).

$ lua script.lua foo
Usage: script.lua [-h]

Error: too many arguments

If halting the program is undesirable, :pparse([args]) method should be used. It returns boolean flag indicating success of parsing and result or error message.

An error can raised manually using :error() method.

1
parser:error("manual argument validation failed")
Usage: script.lua [-h]

Error: manual argument validation failed

Help option

As the automatically generated usage message states, there is a help option -h added to any parser by default.

When a help option is used, parser will print a help message and call os.exit(0).

$ lua script.lua -h
Usage: script.lua [-h]

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

Typo autocorrection

When an option is not recognized by the parser, but there is an option with a similar name, a suggestion is automatically added to the error message.

$ lua script.lua --hepl
Usage: script.lua [-h]

Error: unknown option '--hepl'
Did you mean '--help'?

Configuring parsers

Parsers have several properties affecting their behavior. For example, description and epilog properties set the text to be displayed in the help message after the usage message and after the listings of options and arguments, respectively. Another is name, which overwrites the name of the program which is used in the usage message (default value is inferred from command line arguments).

There are several ways to set properties. The first is to chain setter methods of Parser object.

1
2
3
4
local parser = argparse()
   :name "script"
   :description "A testing script."
   :epilog "For more info, see http://example.com"

The second is to call a parser with a table containing some properties.

1
2
3
4
5
local parser = argparse() {
   name = "script",
   description = "A testing script.",
   epilog "For more info, see http://example.com."
}

Finally, name. description and epilog properties can be passed as arguments when calling a parser.

1
local parser = argparse("script", "A testing script.", "For more info, see http://example.com.")