Getopt for Erlang
=================

Command-line parsing module that uses a syntax similar to that of GNU Getopt.


Requirements
------------

You should only need a somewhat recent version of Erlang/OTP, though the module
has only been tested with Erlang R13B.


Installation
------------

To compile the module you simply run 'make'.

To run the unit tests run 'make test'.

To run the example module run 'make example'.

To build the (very) limited documentation run 'make docs'.


Usage
-----

The *getopt* module provides two functions:

    parse([#option{}], Args :: string() | [string()]) ->
        {ok, {Options, NonOptionArgs}} | {error, {Reason, Data}}

    usage([#option{}], ProgramName :: string()) -> ok

The ``parse/2`` function receives a list of ``#option{}`` records (defined in
``getopt.hrl``) with the command line option specifications. The ``#option{}``
record has the following elements:

    -record(option, {
              name              :: atom(),
              short             :: char() | undefined,
              long              :: string() | undefined,
              arg               :: getopt_arg_type() | {getopt_arg_type(), getopt_arg()} | undefined.
              help              :: string() | undefined
             }).

The fields of the record are:

  - ``name``: name of the option.
  - ``short``: character for the short option (e.g. $i for -i).
  - ``long``: string for the long option (e.g. "info" for --info).
  - ``arg``: data type the argument will be converted to with an optional default value. It can either be an atom() (one of: 'atom', 'binary', 'boolean', 'float', 'integer', 'string') or a tuple with an atom() and the default value for that argument.
  - ``help``: help message that is shown for the option when usage/2 is called.

The second parameter holds the list of arguments as passed to the ``main/1``
function in escripts.

e.g.

     #option{name     = port,
             short    = $p,
             long     = "port",
             arg      = {integer, 5432},
             help     = "Database server port"
            }

If the function is successful parsing the command line arguments it will return
a tuple containing the parsed options and the non-option arguments. The options
will be represented by a list of key-value pairs with the ``name`` of the
option as *key* and the argument from the command line as *value*. If the option
doesn't have an argument, only the atom corresponding to its ``name`` will be
added to the list of options. For the example given above we could get something
like ``{port, 5432}``. The non-option arguments are just a list of strings with
all the arguments that did not have corresponding options.

e.g. For a program named ``ex1.escript`` with the following option specifications:

    OptSpec =
        [
         #option{name     = host,
                 short    = $h,
                 long     = "host",
                 arg      = {string, "localhost"},
                 help     = "Database server host"
                },
         #option{name     = port,
                 short    = $p,
                 long     = "port",
                 arg      = integer,
                 help     = "Database server port"
                },
         #option{name     = dbname,
                 long     = "dbname",
                 arg      = {string, "users"},
                 help     = "Database name"
                },
         #option{name     = xml,
                 short    = $x,
                 help     = "Output data in XML"
                },
         #option{name     = file,
                 arg      = string,
                 help     = "Output file"
                }
        ].

And this command line:

    Args = "-h myhost --port 1000 -x myfile.txt dummy1 dummy2"

Which could also be passed in the format the ``main/1`` function receives the arguments in escripts:

    Args = ["-h", "myhost", "--port", "1000", "-x", "myfile.txt", "dummy1", "dummy2"].

The call to ``getopt:parse/2``:

    getopt:parse(OptSpec, Args).

Will return:

    {ok,{[{host,"myhost"},
          {port,1000},
          xml,
          {file,"myfile.txt"},
          {dbname,"users"}],
         ["dummy1","dummy2"]}}

Also, the call to ``getopt:usage/2``:

    getopt:usage(OptSpec, "ex1").

Will show (on *stdout*):

    Usage: ex1 [-h <host>] [-p <port>] [--dbname <dbname>] [-x] <file>

      -h, --host                    Database server host
      -p, --port                    Database server port
      --dbname                      Database name
      -x                            Output data in XML
      <file>                        Output file


Known limitations
-----------------

  - The syntax for non-option arguments that start with '-' (e.g. -a -- -b)
    is not supported yet.


Known problems
--------------

Currently, with Erlang R13B (and older versions), escripts cannot use the
``-include()`` preprocessor directive so you're forced to install the *getopt*
package in Erlang's library path for your escripts to be able to include the
``getopt.hrl`` header file that defines the ``#option{}`` record used by the
functions in the *getopt* module.