module Arg:sig
..end
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 contraints 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'a
parser =string -> [ `Error of string | `Ok of 'a ]
type'a
printer =Format.formatter -> 'a -> unit
type'a
converter ='a parser * 'a printer
val some : ?none:string -> 'a converter -> 'a option converter
some 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.
type
env
val env_var : ?docs:string -> ?doc:string -> string -> env
env_var docs doc var
is an environment variables var
. doc
is the man page information of the environment variable; the
variables mentioned in Cmdliner.Arg.info
can be used in this documentation
string. doc
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 "ENVIRONMENT VARIABLES"
.type 'a
t
'a
.type
info
val info : ?docs:string ->
?docv:string ->
?doc:string -> ?env:env -> string list -> info
info 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
variable "$(docv)"
can be used to refer to the value of
docv
(see below). The variable "$(opt)"
will refer to a
long option of names
or a short one if there is no long
option. The variable "$(env)"
will refer to the environment
variable specified by env
(if any). These
functions can help with formatting argument values.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 "OPTIONS"
. For positional arguments this defaults
to "ARGUMENTS"
. However a positional argument is only listed
if it has both a doc
and docv
specified.val (&) : ('a -> 'b) -> 'a -> 'b
f & 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 t
flag 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 t
flag_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
occurence of the flag. It holds the empty list if the flag
is absent from the command line.val vflag : 'a -> ('a * info) list -> 'a t
vflag v [v
0,i
0;...]
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 i
k
values. The argument holds v
if the flag is absent from the
command line and the value v
k if the name under which it appears
is in i
k.
Note. Environment variable lookup is unsupported for
for these arguments.
val vflag_all : 'a list -> ('a * info) list -> 'a list t
vflag_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 occurence 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 converter -> 'a -> info -> 'a t
opt 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 converter ->
'a list -> info -> 'a list t
opt_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 occurence 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.
val pos : ?rev:bool ->
int ->
'a converter -> 'a -> info -> 'a t
pos rev n c v i
is an 'a
argument defined by the n
th
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 converter ->
'a list -> info -> 'a list t
pos_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 converter ->
'a list -> info -> 'a list t
pos_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 n
th 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 converter ->
'a list -> info -> 'a list t
pos_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.t
value a
is a term that evaluates to a
's value.val required : 'a option t -> 'a Cmdliner.Term.t
required 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.t
non_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.t
last 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 occurence takes precedence
over the others.val bool : bool converter
bool
converts values with bool_of_string
.val char : char converter
char
converts values by ensuring the argument has a single char.val int : int converter
int
converts values with int_of_string
.val nativeint : nativeint converter
nativeint
converts values with Nativeint.of_string
.val int32 : int32 converter
int32
converts values with Int32.of_string
.val int64 : int64 converter
int64
converts values with Int64.of_string
.val float : float converter
float
converts values with float_of_string
.val string : string converter
string
converts values with the identity function.val enum : (string * 'a) list -> 'a converter
enum 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
.
Raises Invalid_argument
if l
is empty.
val file : string converter
file
converts a value with the identity function and
checks with Sys.file_exists
that a file with that name exists.val dir : string converter
dir
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 converter
non_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 converter -> 'a list converter
list sep c
splits the argument at each sep
(defaults to ','
)
character and converts each substrings with c
.val array : ?sep:char -> 'a converter -> 'a array converter
array sep c
splits the argument at each sep
(defaults to ','
)
character and converts each substring with c
.val pair : ?sep:char ->
'a converter ->
'b converter -> ('a * 'b) converter
pair 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 converter ->
'b converter -> ('a * 'b) converter
val t3 : ?sep:char ->
'a converter ->
'b converter ->
'c converter -> ('a * 'b * 'c) converter
t3 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 converter ->
'b converter ->
'c converter ->
'd converter -> ('a * 'b * 'c * 'd) converter
t4 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 -> string
doc_quote s
quotes the string s
.val doc_alts : ?quoted:bool -> string list -> string
doc_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 -> string
doc_alts_enum quoted alts
is doc_alts quoted (List.map fst alts)
.