module Arg:sig..end
Terms for command line arguments.
This module provides functions to define terms that evaluate to the arguments provided on the command line.
Basic constraints, like the argument type or repeatability, are
specified by defining a value of type Cmdliner.Arg.t. Further constraints can
be specified during the conversion to a term.
An argument converter transforms a string argument of the command line to an OCaml value. Predefined converters are provided for many types of the standard library.
type'aparser =string -> [ `Error of string | `Ok of 'a ]
The type for argument parsers.
type'aprinter =Stdlib.Format.formatter -> 'a -> unit
The type for converted argument printers.
type'aconv ='a parser * 'a printer
The type for argument converters.
WARNING. This type will become abstract in the next
major version of cmdliner, use Cmdliner.Arg.conv or Cmdliner.Arg.pconv
to construct values of this type.
type'aconverter ='a conv
Cmdliner.Arg.conv type via the Cmdliner.Arg.conv and Cmdliner.Arg.pconv
functions.val conv : ?docv:string ->
(string -> ('a, [ `Msg of string ]) Stdlib.result) * 'a printer ->
'a convconverter ~docv (parse, print) is an argument converter
parsing values with parse and printing them with
print. docv is a documentation meta-variable used in the
documentation to stand for the argument value, defaults to
"VALUE".
val pconv : ?docv:string ->
'a parser * 'a printer -> 'a convpconv is like Cmdliner.Arg.converter, but uses a deprecated Cmdliner.Arg.parser
signature.
val conv_parser : 'a conv -> string -> ('a, [ `Msg of string ]) Stdlib.resultconv_parser c 's c's parser.
val conv_printer : 'a conv -> 'a printerconv_printer c is c's printer.
val conv_docv : 'a conv -> stringconv_docv c is c's documentation meta-variable.
WARNING. Currently always returns "VALUE" in the future
will return the value given to Cmdliner.Arg.conv or Cmdliner.Arg.pconv.
val parser_of_kind_of_string : kind:string ->
(string -> 'a option) -> string -> ('a, [ `Msg of string ]) Stdlib.resultparser_of_kind_of_string ~kind kind_of_string is an argument
parser using the kind_of_string function for parsing and kind
to report errors (e.g. could be "an integer" for an int parser.).
val some : ?none:string -> 'a conv -> 'a option convsome none c is like the converter c except it returns
Some value. It is used for command line arguments
that default to None when absent. none is what to print to
document the absence (defaults to "").
Argument information defines the man page information of an argument and, for optional arguments, its names. An environment variable can also be specified to read the argument value from if the argument is absent from the command line and the variable is defined.
typeenv =Cmdliner.Term.env_info
The type for environment variables and their documentation.
val env_var : ?docs:string -> ?doc:string -> string -> envenv_var docs doc var is an environment variables var. doc
is the man page information of the environment variable, the
documentation markup language with the variables
mentioned in Cmdliner.Arg.info be used; it defaults to "See option.
$(opt)."docs is the title of the man page section in which
the environment variable will be listed, it defaults to
Cmdliner.Manpage.s_environment.
type 'a t
The type for arguments holding data of type 'a.
type
The type for information about command line arguments.
val info : ?docs:string ->
?docv:string ->
?doc:string -> ?env:env -> string list -> infoinfo docs docv doc env names defines information for
an argument.
names defines the names under which an optional argument
can be referred to. Strings of length 1 ("c") define
short option names ("-c"), longer strings ("count")
define long option names ("--count"). names must be empty
for positional arguments.env defines the name of an environment variable which is
looked up for defining the argument if it is absent from the
command line. See environment variables for
details.doc is the man page information of the argument.
The documentation language can be used and
the following variables are recognized:
"$(docv)" the value of docv (see below)."$(opt)", one of the options of names, preference
is given to a long one."$(env)", the environment var specified by env (if any).docv is for positional and non-flag optional arguments.
It is a variable name used in the man page to stand for their value.docs is the title of the man page section in which the argument
will be listed. For optional arguments this defaults
to Cmdliner.Manpage.s_options. For positional arguments this defaults
to Cmdliner.Manpage.s_arguments. However a positional argument is only
listed if it has both a doc and docv specified.val (&) : ('a -> 'b) -> 'a -> 'bf & v is f v, a right associative composition operator for
specifying argument terms.
The information of an optional argument must have at least
one name or Invalid_argument is raised.
val flag : info -> bool tflag i is a bool argument defined by an optional flag
that may appear at most once on the command line under one of
the names specified by i. The argument holds true if the
flag is present on the command line and false otherwise.
val flag_all : info -> bool list tflag_all is like Cmdliner.Arg.flag except the flag may appear more than
once. The argument holds a list that contains one true value per
occurrence of the flag. It holds the empty list if the flag
is absent from the command line.
val vflag : 'a -> ('a * info) list -> 'a tvflag v [v0,i0;...] is an 'a argument defined
by an optional flag that may appear at most once on
the command line under one of the names specified in the ik
values. The argument holds v if the flag is absent from the
command line and the value vk if the name under which it appears
is in ik.
Note. Environment variable lookup is unsupported for for these arguments.
val vflag_all : 'a list -> ('a * info) list -> 'a list tvflag_all v l is like Cmdliner.Arg.vflag except the flag may appear more
than once. The argument holds the list v if the flag is absent
from the command line. Otherwise it holds a list that contains one
corresponding value per occurrence of the flag, in the order found on
the command line.
Note. Environment variable lookup is unsupported for for these arguments.
val opt : ?vopt:'a ->
'a conv -> 'a -> info -> 'a topt vopt c v i is an 'a argument defined by the value of
an optional argument that may appear at most once on the command
line under one of the names specified by i. The argument holds
v if the option is absent from the command line. Otherwise
it has the value of the option as converted by c.
If vopt is provided the value of the optional argument is itself
optional, taking the value vopt if unspecified on the command line.
val opt_all : ?vopt:'a ->
'a conv ->
'a list -> info -> 'a list topt_all vopt c v i is like Cmdliner.Arg.opt except the optional argument may
appear more than once. The argument holds a list that contains one value
per occurrence of the flag in the order found on the command line.
It holds the list v if the flag is absent from the command line.
The information of a positional argument must have no name
or Invalid_argument is raised. Positional arguments indexing
is zero-based.
Warning. The following combinators allow to specify and
extract a given positional argument with more than one term.
This should not be done as it will likely confuse end users and
documentation generation. These over-specifications may be
prevented by raising Invalid_argument in the future. But for now
it is the client's duty to make sure this doesn't happen.
val pos : ?rev:bool ->
int -> 'a conv -> 'a -> info -> 'a tpos rev n c v i is an 'a argument defined by the nth
positional argument of the command line as converted by c.
If the positional argument is absent from the command line
the argument is v.
If rev is true (defaults to false), the computed
position is max-n where max is the position of
the last positional argument present on the command line.
val pos_all : 'a conv ->
'a list -> info -> 'a list tpos_all c v i is an 'a list argument that holds
all the positional arguments of the command line as converted
by c or v if there are none.
val pos_left : ?rev:bool ->
int ->
'a conv ->
'a list -> info -> 'a list tpos_left rev n c v i is an 'a list argument that holds
all the positional arguments as converted by c found on the left
of the nth positional argument or v if there are none.
If rev is true (defaults to false), the computed
position is max-n where max is the position of
the last positional argument present on the command line.
val pos_right : ?rev:bool ->
int ->
'a conv ->
'a list -> info -> 'a list tpos_right is like Cmdliner.Arg.pos_left except it holds all the positional
arguments found on the right of the specified positional argument.
val value : 'a t -> 'a Cmdliner.Term.tvalue a is a term that evaluates to a's value.
val required : 'a option t -> 'a Cmdliner.Term.trequired a is a term that fails if a's value is None and
evaluates to the value of Some otherwise. Use this for required
positional arguments (it can also be used for defining required
optional arguments, but from a user interface perspective this
shouldn't be done, it is a contradiction in terms).
val non_empty : 'a list t -> 'a list Cmdliner.Term.tnon_empty a is term that fails if a's list is empty and
evaluates to a's list otherwise. Use this for non empty lists
of positional arguments.
val last : 'a list t -> 'a Cmdliner.Term.tlast a is a term that fails if a's list is empty and evaluates
to the value of the last element of the list otherwise. Use this
for lists of flags or options where the last occurrence takes precedence
over the others.
val man_format : Cmdliner.Manpage.format Cmdliner.Term.tman_format is a term that defines a --man-format option and
evaluates to a value that can be used with Cmdliner.Manpage.print.
val bool : bool convbool converts values with bool_of_string.
val char : char convchar converts values by ensuring the argument has a single char.
val int : int convint converts values with int_of_string.
val nativeint : nativeint convnativeint converts values with Nativeint.of_string.
val int32 : int32 convint32 converts values with Int32.of_string.
val int64 : int64 convint64 converts values with Int64.of_string.
val float : float convfloat converts values with float_of_string.
val string : string convstring converts values with the identity function.
val enum : (string * 'a) list -> 'a convenum l p converts values such that unambiguous prefixes of string names
in l map to the corresponding value of type 'a.
Warning. The type 'a must be comparable with Pervasives.compare.
Invalid_argument if l is empty.val file : string convfile converts a value with the identity function and
checks with Sys.file_exists that a file with that name exists.
val dir : string convdir converts a value with the identity function and checks
with Sys.file_exists and Sys.is_directory
that a directory with that name exists.
val non_dir_file : string convnon_dir_file converts a value with the identity function and checks
with Sys.file_exists and Sys.is_directory
that a non directory file with that name exists.
val list : ?sep:char -> 'a conv -> 'a list convlist sep c splits the argument at each sep (defaults to ',')
character and converts each substrings with c.
val array : ?sep:char -> 'a conv -> 'a array convarray sep c splits the argument at each sep (defaults to ',')
character and converts each substring with c.
val pair : ?sep:char ->
'a conv -> 'b conv -> ('a * 'b) convpair sep c0 c1 splits the argument at the first sep character
(defaults to ',') and respectively converts the substrings with
c0 and c1.
val t2 : ?sep:char ->
'a conv -> 'b conv -> ('a * 'b) conv
val t3 : ?sep:char ->
'a conv ->
'b conv ->
'c conv -> ('a * 'b * 'c) convt3 sep c0 c1 c2 splits the argument at the first two sep
characters (defaults to ',') and respectively converts the
substrings with c0, c1 and c2.
val t4 : ?sep:char ->
'a conv ->
'b conv ->
'c conv ->
'd conv -> ('a * 'b * 'c * 'd) convt4 sep c0 c1 c2 c3 splits the argument at the first three sep
characters (defaults to ',') respectively converts the substrings
with c0, c1, c2 and c3.
val doc_quote : string -> stringdoc_quote s quotes the string s.
val doc_alts : ?quoted:bool -> string list -> stringdoc_alts alts documents the alternative tokens alts according
the number of alternatives. If quoted is true (default)
the tokens are quoted. The resulting string can be used in
sentences of the form "$(docv) must be %s".
Invalid_argument if alts is the empty string.val doc_alts_enum : ?quoted:bool -> (string * 'a) list -> stringdoc_alts_enum quoted alts is doc_alts quoted (List.map fst alts).