Module CmdlineArgs.MoreLikeGNU


module MoreLikeGNU: S 


Handle errors


val quote : string -> string
Put a string in between guillemets. Used to quote strings that originate from outside a library or program. This makes error messages clearer.
exception Error of string
Raised when parsing the command line fails. Indicates error in user's input.
val error : string list -> 'a
Join the given pieces of a message with spaces and raise CmdlineArgs.S.Error.
exception BadDefinitions of string
Indicates that the definitions passed to this library are incorrect.

Define options


type importance = CmdlineArgsBase.importance = 
| Normal
| Unimportant (*do not show in the --help string*)
Decides about visibility of an option in the generated documentation strings.
type 'a meaning = 'a CmdlineArgsMeaning.meaning 
Defines type, parameter label and materialized meaning of an option.
type +'a description 
Definition of an option.
val opt : 'a meaning ->
string ->
?short:string ->
?importance:importance ->
string -> 'a description
opt meaning long ?short ?importance help constructs a definition of an command-line option. For convenience, wrappers like oConst and oInt are defined below: see Constructor functions used to define options. The opt function is not intended for normal usage. Parameters of the wrappers have the following meaning:

meaning describes how the option will be "materialized" for further processing. It represents meaning of the option. It is the final (or intermediate, if wanted) result of using this module.

long is the long form of the option. If the given string doesn't start with '-', Customs.default_long_prefix is prepended (e.g. "--" in case of GNU style). Empty string means there is no long form.

short is Some character to define the short form or None it there is no short form. "-" is prepended to the given character. The flag Customization.enforce_single_byte_shorts decides how long the character can be.

importance decides whether this option is shown in the documentation that --help shows.

help is shown when --help is executed (if not Unimportant) and in the manual. If the option has a parameter, the meaning argument carries its placeholder name. The help string doesn't define it (unlike the standard Arg.doc). All occurences of the placeholder name in the help string are italicized in the output of Nroff.format_manual.

Unary definition constructors like oInt have optional label parameter that provides placeholder name for option parameter. Nullary option definitions like oConst do not have this argument.
Raises BadDefinitions .


The usual --help and --version



type traditional =
| Help (*show usage help message and exit*)
| Version (*show version information and exit*)
| Manual of [ `Nroff ] (*generate a manpage*)
Meaning of traditional switches (and manpage generation added extra).
val traditional : traditional description list
Empty title and definitions of traditional switches (--help and --version). Also -help, if allowed by CmdlineArgs.Customization.
val traditional_enhanced : traditional description list
The traditional set enriched with the manpage generation option.

Generate documentation


module Summary: sig .. end
val summary : string -> 'a description list -> Summary.section
summary title definitions creates a summary of a list of options (a section). It has a title and zero or more option definitions. If the title is empty, the section is visually glued to a preceding section (if any). If there are no options the section is completely hidden (no title shown).
module PlainText: sig .. end
module Nroff: sig .. end
val simple_help_string : HSimpleDoc.text list -> Summary.section list -> string
simple_help_string usage_synopsis summary formats a help message that consists of the given usage synopsis and a table of options given by summary.

Handle pure arguments



Most of parse_* functions can raise CmdlineArgs.S.Error with a meaningful message.
val parse_Bool : string -> bool
val parse_Int : string -> int
val parse_Float : string -> float
val parse_RawPath : string -> HPath.t
val parse_Path : string -> HPath.t
val parse_String : 'a -> 'a
val parse_Symbol : string list -> string -> string
parse_Symbol atoms str returns str if it is found among atoms. Otherwise an CmdlineArgs.S.Error is raised.
val materialize_pure : 'a meaning -> string -> 'a
Used to handle pure arguments with given meaning. But normally, to translate pure arguments, parse_* functions can be used directly.
Raises Error .

Parse command line arguments


type parsed 
Intermediate form of the processed arguments.
val empty_parsed : parsed
Neutral element for CmdlineArgs.S.join_parsed.
val join_parsed : parsed -> parsed -> parsed
Put together the given processed arguments. They can come from independent sources.
val parse : Summary.section list -> string list -> parsed
First step of processing arguments. Parse them using the given a summary of option definitions. If the -- string is encoutered, it is always interpreted as: all the following arguments are pure arguments (not options).
Raises
val recognize : 'a description list ->
parsed -> 'a list * parsed
recognize section parsed returns (materialized, others). For all options that are recognized in the given section, it picks their meanings. In case of unary meanings, it also feeds them with parameters of the options. The value others keeps the parsed pieces of command line that are not recognized.

The recognize function calls are usually chained to recognize options from all sections. The not recognized part (others) consists of pure arguments and options that are defined but not yet extracted by recognize calls. These remaining others can be passed to the CmdlineArgs.S.final_take_pure function.

At this stage existence or nonexistence of parameters of options is enforced (where applicable).
Raises

val fold : ('a -> 'a) description list ->
'a -> parsed -> 'a * parsed
fold section initial parsed takes materialized meanings as picked by CmdlineArgs.S.recognize (let's call these meanings m1, m2, ..., mN) and applies them chained to the initial value in the following way: m1 (m2 (... (mN initial) ...)) (let's call this cumulated). The function fold returns (cumulated, others), where others are the parsed pieces that are not described in the given section.

The 'a -> 'a actions given by descriptions in the section can e.g. update individual fields of a record. In this case initial would contain default values and the record cumulated that binds multiple options is ready to be passed around.

val take_pure : parsed -> string list * parsed
Extracts pure arguments in a similar fashion to recognize.
val final_take_pure : parsed -> string list
Like CmdlineArgs.S.take_pure, but expects to consume all the parsed pieces. If it is not the case, it is assumed that the application logic rejects the remaining part of command line and final_take_pure raises CmdlineArgs.S.Error.
Raises Error .

Common actions


val exec_traditional : ?manual_sections:(string * string list) list ->
HSimpleDoc.text list ->
Summary.section list ->
?help_string:string -> string -> traditional list -> unit
Execute the recognized traditional options. If any option is given, all messages are printed and exit 0 called.
val cmdline_args : string list
Actual command line of the running program.
val parse_recognize_exc : ?args:string list ->
?traditional:traditional description list ->
?manual_sections:(string * string list) list ->
string ->
?usage_synopsis:string list ->
?formatted_usage_synopsis:HSimpleDoc.text list ->
'a description list -> 'a list * string list
parse_recognize_exc ?(args=cmdline_args) version_string ?usage_synopsis ?formatted_usage_synopsis definitions processes the given (or current) command line arguments and translates them to their meanings (i.e. to values produced according to option definitions). Returns (recognized, pure_args): meanings of recognized options and pure arguments. CmdlineArgs.S.traditional options are added to the given definitions and, if found in args, they are immediately executed (printing and exit 0).

If you need to handle more sections of option definitions and they have different 'a description types, call parse and recognize in separate steps.
Raises Error .

val parse_recognize : ?args:string list ->
?traditional:traditional description list ->
?manual_sections:(string * string list) list ->
string ->
?usage_synopsis:string list ->
?formatted_usage_synopsis:HSimpleDoc.text list ->
'a description list -> 'a list * string list
Like CmdlineArgs.S.parse_recognize_exc, but in case of CmdlineArgs.S.Error prints a message and calls exit 2.
val parse_fold_exc : ?args:string list ->
?traditional:traditional description list ->
?manual_sections:(string * string list) list ->
string ->
?usage_synopsis:string list ->
?formatted_usage_synopsis:HSimpleDoc.text list ->
('a -> 'a) description list -> 'a -> 'a * string list
parse_fold_exc ?(args=cmdline_args) version_string ?usage_synopsis ?formatted_usage_synopsis definitions initial is like CmdlineArgs.S.parse_recognize_exc, but the meanings of recognized options are folded.

The function processes the given (or current) command line arguments and folds their meanings with the CmdlineArgs.S.fold function. Returns (cumulated, pure_args): the result of the fold and pure arguments. CmdlineArgs.S.traditional options are added to the given definitions and, if found in args, they are immediately executed (printing and exit 0).

If you need to handle more sections of option definitions and they have different 'a description types, call parse and fold in separate steps.
Raises Error .

val parse_fold : ?args:string list ->
?traditional:traditional description list ->
?manual_sections:(string * string list) list ->
string ->
?usage_synopsis:string list ->
?formatted_usage_synopsis:HSimpleDoc.text list ->
('a -> 'a) description list -> 'a -> 'a * string list
Like CmdlineArgs.S.parse_fold_exc, but in case of CmdlineArgs.S.Error prints a message and calls exit 2.

Analyze just translated options


val take_flag_out : 'a list -> 'a -> bool * 'a list
take_flag_out lst flag picks all ocurrences of flag in lst. It returns (is_present, remaining), where is_present is true if some flag is found in lst. remaining contains lst with all flag occurences removed.

type 'a clash_policy =
| ForbidClash of string (*Only one is allowed. Part of an error message is given for the case of clash.*)
| Override (*Ignore all but the last one.*)
| SolveClash of ('a list -> 'a) (*Solve the conflict in the given way.*)
Describes how to handle multiple inequal meanings that refer to the same thing. The predicate passed to CmdlineArgs.S.take_value_out function defines what does it mean to "refer to the same thing".
val take_values_out : 'a list -> ('a -> 'b option) -> 'b list * 'a list
take_values_out lst extract returns (extracted, remaining). For each element x of the given lst, extract x can return Some y or None. All of such produced y become extracted. The list remaining contains elements for which extract returned None.
val take_value_out : 'a clash_policy ->
'b list -> ('b -> 'a option) -> 'a option * 'b list
take_value_out policy lst extract returns (extracted, remaining). For each element x of the given lst, extract x can return Some y or None. All of such produced y are considered by the given policy to choose a single extracted value. If no candidate y is found, extracted is None. The list remaining contains elements for which extract returned None.
Raises Error with a message "Contradictory dispositions related to: "^subject_description when the policy is ForbidClash subject_description and conflicting options are found.
val default : 'a -> ('b -> 'c -> 'a option * 'd) -> 'b -> 'c -> 'a * 'd
default default_value take_out lst what returns what take_out lst what produces, but the option value is unwrapped, so that instead (None, remaining) this function returns (default_value, remaining).

To be combined with CmdlineArgs.S.take_value_out.

val last : ('a -> 'b -> 'c * 'd list) -> 'a -> 'b -> 'c
last take_out lst what expects take_out lst what to consume all of the lst and return empty remaining list. Only the extracted value is returned.

To be combined with the above functions.
Raises Assert_failure when the take_out call turns out to be not the last one and some remaining elements are left.


Constructor functions used to define options



All parameters of these functions are explained in the description of the CmdlineArgs.S.opt function above. All of them can raise CmdlineArgs.S.BadDefinitions.
val oBool : (bool -> 'a) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oBoolOpt : (bool option -> 'a) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oSetBool : bool Pervasives.ref ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oSetBoolOpt : bool option Pervasives.ref ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oApplyBool : (bool -> unit) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oApplyBoolOpt : (bool option -> unit) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oInt : (int -> 'a) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oIntOpt : (int option -> 'a) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oSetInt : int Pervasives.ref ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oSetIntOpt : int option Pervasives.ref ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oApplyInt : (int -> unit) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oApplyIntOpt : (int option -> unit) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oFloat : (float -> 'a) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oFloatOpt : (float option -> 'a) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oSetFloat : float Pervasives.ref ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oSetFloatOpt : float option Pervasives.ref ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oApplyFloat : (float -> unit) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oApplyFloatOpt : (float option -> unit) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oRawPath : (HPath.t -> 'a) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oRawPathOpt : (HPath.t option -> 'a) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oSetRawPath : HPath.t Pervasives.ref ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oSetRawPathOpt : HPath.t option Pervasives.ref ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oApplyRawPath : (HPath.t -> unit) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oApplyRawPathOpt : (HPath.t option -> unit) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oPath : (HPath.t -> 'a) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oPathOpt : (HPath.t option -> 'a) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oSetPath : HPath.t Pervasives.ref ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oSetPathOpt : HPath.t option Pervasives.ref ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oApplyPath : (HPath.t -> unit) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oApplyPathOpt : (HPath.t option -> unit) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oRealPath : (HPath.t -> 'a) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oRealPathOpt : (HPath.t option -> 'a) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oSetRealPath : HPath.t Pervasives.ref ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oSetRealPathOpt : HPath.t option Pervasives.ref ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oApplyRealPath : (HPath.t -> unit) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oApplyRealPathOpt : (HPath.t option -> unit) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oString : (string -> 'a) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oStringOpt : (string option -> 'a) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oSetString : string Pervasives.ref ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oSetStringOpt : string option Pervasives.ref ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oApplyString : (string -> unit) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oApplyStringOpt : (string option -> unit) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oSymbol : string list * (string -> 'a) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oSymbolOpt : string list * (string option -> 'a) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oSetSymbol : string list * string Pervasives.ref ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oSetSymbolOpt : string list * string option Pervasives.ref ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oApplySymbol : string list * (string -> unit) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oApplySymbolOpt : string list * (string option -> unit) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
?label:string -> string -> 'a description
val oConst : 'a ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
string -> 'a description
val oSetTrue : bool Pervasives.ref ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
string -> 'a description
val oSetFalse : bool Pervasives.ref ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
string -> 'a description
val oApplyUnit : (unit -> unit) ->
string ->
?short:string ->
?importance:CmdlineArgsBase.importance ->
string -> 'a description