getopt/README.markdown

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([{Name, Short, Long, ArgSpec, Help}], Args :: string() | [string()]) ->
    {ok, {Options, NonOptionArgs}} | {error, {Reason, Data}}

usage([{Name, Short, Long, ArgSpec, Help}], ProgramName :: string()) -> ok

The parse/2 function receives a list of tuples with the command line option specifications. The type specification for the tuple is:

-type arg_type() :: 'atom' | 'binary' | 'boolean' | 'float' | 'integer' | 'string'.

-type arg_value() :: atom() | binary() | boolean() | float() | integer() | string().

-type arg_spec() :: arg_type() | {arg_type(), arg_value()} | undefined.

-type option_spec() :: {
                   Name    :: atom(),
                   Short   :: char() | undefined,
                   Long    :: string() | undefined,
                   ArgSpec :: arg_spec(),
                   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).
• ArgSpec: data type and optional default value the argument will be converted to.
• 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.

 {port, $p, "port", {integer, 5432}, "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 ex.escript with the following option specifications:

OptSpec =
    [
     {host,   $h,        "host",    {string, "localhost"}, "Database server host"},
     {port,   $p,        "port",    integer,               "Database server port"},
     {dbname, undefined, "dbname",  {string, "users"},     "Database name"},
     {xml,    $x,        undefined, undefined,             "Output data in XML"},
     {file,   undefined, undefined, string,                "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.