Creating and using parsers
**************************

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

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

   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.

   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.

   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.

   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.

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