Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Erlang module to parse command line arguments using the GNU getopt syntax
Erlang

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
doc
ebin
examples
src
ChangeLog
Emakefile
LICENSE.txt
Makefile
README.markdown
TODO

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: ex.escript [-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.
Something went wrong with that request. Please try again.