Adding and configuring arguments
********************************

Positional arguments can be added using ":argument(name, description,
default, convert, args)" method. It returns an Argument instance,
which can be configured in the same way as Parsers. The "name"
property is required.

This and the following examples show contents of the result table
returned by *parser:parse()* when the script is executed with given
command-line arguments.

   parser:argument "input"

   $ lua script.lua foo

   {
      input = "foo"
   }

The data passed to the argument is stored in the result table at index
"input" because it is the argument's name. The index can be changed
using "target" property.


Setting number of consumed arguments
====================================

"args" property sets how many command line arguments the argument
consumes. Its value is interpreted as follows:

+---------------------------------------------------+-------------------------------+
| Value                                             | Interpretation                |
|===================================================|===============================|
| Number "N"                                        | Exactly "N" arguments         |
+---------------------------------------------------+-------------------------------+
| String "A-B", where "A" and "B" are numbers       | From "A" to "B" arguments     |
+---------------------------------------------------+-------------------------------+
| String "N+", where "N" is a number                | "N" or more arguments         |
+---------------------------------------------------+-------------------------------+
| String "?"                                        | An optional argument          |
+---------------------------------------------------+-------------------------------+
| String "*"                                        | Any number of arguments       |
+---------------------------------------------------+-------------------------------+
| String "+"                                        | At least one argument         |
+---------------------------------------------------+-------------------------------+

If more than one argument can be consumed, a table is used to store
the data.

   parser:argument("pair", "A pair of arguments.")
      :args(2)
   parser:argument("optional", "An optional argument.")
      :args "?"

   $ lua script.lua foo bar

   {
      pair = {"foo", "bar"}
   }

   $ lua script.lua foo bar baz

   {
      pair = {"foo", "bar"},
      optional = "baz"
   }


Setting argument choices
========================

The "choices" property can be used to restrict an argument to a set of
choices. Its value is an array of string choices.

   parser:argument "direction"
      :choices {"north", "south", "east", "west"}

   $ lua script.lua foo

   Usage: script.lua [-h] {north,south,east,west}

   Error: argument 'direction' must be one of 'north', 'south', 'east', 'west'
