module CmdlineArgs:Parse command line arguments and format the help string and a manual. Allows to marginalize impure handling of options (e.g.
CmdlineArgs.S.oBoolis suggested instead of the desctructive
CmdlineArgs.MoreLikeGNUmodule tries to mimic GNU style.
The command line of an executed program contains arguments. If an argument starts with
"-", it represents one or more options. An option can be given a parameter. This parameter string is parsed and passed to a specific constructor function. Other arguments (that are not options nor option parameters) are called "pure arguments" here.
This library deals mostly with options. Pure arguments can be parsed the same way option parameters are, but they are returned as a simple list.
CmdlineArgs currently provides no helpers for higher-level manipulation (as e.g. enforcing some grammar rules to the argument list as a whole). This shouldn't be an obstacle because
CmdlineArgs works as a parser and translator (contrary to the
Arg module which works as a parser and executor).
The easiest way to go is to use
CmdlineArgs.S.parse_recognize that acts on only single group of option descriptions (with "--help" and "--version" added). Each option is translated to its meaning (excluding impure options, which are not translated but executed).
In general, one can provide multiple groups of options. The
meaning types of the groups are independet, so one can join descriptions of options from separate program components without introducing a big single sum type. The used grouping can be reflected in the formatted documentation, if titles of groups are nonempty.
Options are defined by constructor functions like
oConst (listed in Constructor functions used to define options). All of them are prefixed with "o". The rest of the name consists of a core part and other prefixes and suffixes. The core part denotes parameter type:
String for primitive types;
string constrained to a given set of symbols (atoms).
The first parameter of each
o* function is the meaning of option. In case of
CmdlineArgs.S.oConst it is just anything. In other cases it is a function that constructs the meaning (this not applies to
oApply*, which are impure).
Opt means that the parameter is optional and its type
'a is promoted to
oInt (fun nn -> Iterations nn) "iterations" "do N iterations" defines a command-line option that has only a long form "--iterations" with one mandatory integer argument. When parsed, it is translated e.g. to
Iterations 5 which is the meaning of the option. The last string given to
oInt is a help string.
Apply are provided for compatiblity with the Arg module. One wishing to handle arguments destructively has to invent some strategy to avoid using global mutable parameters before command line arguments are interpreted and the impure
meanings are executed.
The three kinds of options dealing with paths are:
RawPath to parse path and use it unchanged;
Path to translate relative path to absolute wrt the current working directory.
RealPath to solve symlinks and normalize the path to make it absolute (like the
realpath function of POSIX).
The command line is processed in a few stages. At first, a list of strings given as a command line arguments is parsed by
Then, switches that belong to various groups are recognized by
take_pure can collect the anonymous (pure) arguments. Possibly at this stage, some unwanted remnants are left (i.e. those not picked up by
recognize calls), so
CmdlineArgs.S.final_take_pure raises an
CmdlineArgs.S.Error which displays them.
The result of
CmdlineArgs.S.recognize is a list of meanings (materialized options). It is what is given in a first argument to the constructor functions like
Repeated options can be handled as mutually exclusive or cumulative. E.g. when only one "bar" setting is to be accepted, no overriding allowed, calling
"foo --bar=4 --bar=5" should be rejected. Such contradictions are detected at the final stage with
CmdlineArgs.S.take_value_out, which works on
Some defects of definitions are detected at run-time (
CmdlineArgs.S.BadDefinitions with a message is raised). When an error in the command line or its meaning is detected,
CmdlineArgs.S.Error with a message is raised.
A working example of
CmdlineArgs utilization is provided by the mleternal project.
[ `Catenated | `CatenatedOrSeparated | `EqualitySign | `Separated ]
[ `EqualitySign | `Separated ]
module type Customization =
module type S =