Module CmdlineArgs

module CmdlineArgs: sig .. end
Parse command line arguments and format the help string and a manual. Allows to marginalize impure handling of options (e.g. CmdlineArgs.S.oBool is suggested instead of the desctructive CmdlineArgs.S.oSetBool). The CmdlineArgs.MoreLikeGNU module 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: Bool, Int, Float, String for primitive types; Path and RawPath for Path.t (BatGenPath.OfString.t); Symbol for 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 oSet* and oApply*, which are impure).

The postfix Opt means that the parameter is optional and its type 'a is promoted to 'a option.

For example 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.

The prefixes Set and 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 CmdlineArgs.S.parse. Then, switches that belong to various groups are recognized by CmdlineArgs.S.recognize. Finally, 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 oInt.

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 meanings.

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.

type parameter_placement_short = [ `Catenated | `CatenatedOrSeparated | `EqualitySign | `Separated ] 
type parameter_placement_long = [ `EqualitySign | `Separated ] 
module type Customization = sig .. end
module type S = sig .. end
module Make: 
functor (Customs : Customization) -> S
module MoreLikeGNU: S 
module MoreLikeStdlibArg: S