156 lines
5.0 KiB
Markdown
156 lines
5.0 KiB
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 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.
|