Cmdliner.Arg
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 Arg.t
. Further constraints can be specified during the conversion to a term.
module Completion : sig ... end
Argument completion.
module Conv : sig ... end
Argument converters.
type 'a conv = 'a Conv.t
The type for argument converters. See the predefined converters.
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. If provided, none
is used with c
's formatter to document the value taken on absence; to document a more complex behaviour use the absent
argument of info
. If you cannot construct an 'a
value use some
.
some ?none c
is like some'
but none
is described as a string that will be rendered in bold. Use the absent
argument of info
to document more complex behaviours.
The type for information about command line arguments.
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 get the argument value from if the argument is absent from the command line and the variable is defined.
val info :
?deprecated:string ->
?absent:string ->
?docs:Manpage.section_name ->
?docv:string ->
?doc:string ->
?env:Cmd.Env.info ->
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
like "c"
) define short option names "-c"
, longer strings like "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).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 Manpage.s_options
. For positional arguments this defaults to Manpage.s_arguments
. However a positional argument is only listed if it has both a doc
and docv
specified.deprecated
, if specified the argument is deprecated and the string is a message output on standard error when the argument is used.absent
, if specified a documentation string that indicates what happens when the argument is absent. The document language can be used like in doc
. This overrides the automatic default value rendering that is performed by the combinators.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.
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.
flag_all
is like 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.
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.
vflag_all v l
is like 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.
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. Warning using vopt
is not recommended.
opt_all vopt c v i
is like 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.
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.
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.
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.
pos_right
is like pos_left
except it holds all the positional arguments found on the right of the specified positional argument.
required a
is a term that fails if a
's value is None
and evaluates to the value of Some
otherwise. Use this in combination with Arg.some'
for required positional arguments. Warning using this on optional arguments is not recommended.
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.
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 occurrence takes precedence over the others.
val man_format : Manpage.format Term.t
man_format
is a term that defines a --man-format
option and evaluates to a value that can be used with Manpage.print
.
val bool : bool conv
bool
converts values with bool_of_string
.
val char : char conv
char
converts values by ensuring the argument has a single char.
val int : int conv
int
converts values with int_of_string
.
val nativeint : nativeint conv
nativeint
converts values with Nativeint.of_string
.
val int32 : int32 conv
int32
converts values with Int32.of_string
.
val int64 : int64 conv
int64
converts values with Int64.of_string
.
val float : float conv
float
converts values with float_of_string
.
val string : string conv
string
converts values with the identity function.
val enum : ?docv:string -> (string * 'a) list -> 'a conv
enum l p
converts values such that string names in l
map to the corresponding value of type 'a
. docv
is the converter's documentation meta-variable, it defaults to ENUM
Warning. The type 'a
must be comparable with Stdlib.compare
.
list sep c
splits the argument at each sep
(defaults to ','
) character and converts each substrings with c
.
array sep c
splits the argument at each sep
(defaults to ','
) character and converts each substring with c
.
pair sep c0 c1
splits the argument at the first sep
character (defaults to ','
) and respectively converts the substrings with c0
and c1
.
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
.
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 filepath : string conv
filepath
is like string
but prints using Filename.quote
and completes both files and directories.
val dirpath : string conv
dirpath
is like string
but prints using Filename.quote
and completes directories.
Note. The following converters report errors whenever the requested file system object does not exist. This is only mildly useful since nothing guarantees you it will still exist at the time you act upon them, so you will have to treat these error anyways in your tool function. It is also unhelpful the file system object may be created by your tool, use filpath
and dirpath
in this case.
val file : string conv
file
converts a value with the identity function and checks with Sys.file_exists
that a file with that name exists. The string "-"
is parsed without checking it represents stdio
. It completes with both files directories.
val dir : string conv
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. It completes with directories.
val non_dir_file : string conv
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. The string "-"
is parsed without checking it represents stdio
. It completes with files.
doc_alts alts
documents the alternative tokens alts
according the number of alternatives. If quoted
is:
None
, the tokens are enclosed in manpage markup directives to render them in bold (manpage convention).Some true
, the tokens are quoted with doc_quote
.Some false
, the tokens are written as isThe resulting string can be used in sentences of the form "$(docv) must be %s"
.
doc_alts_enum quoted alts
is doc_alts quoted (List.map fst alts)
.
These identifiers are silently deprecated. For now there is no plan to remove them. But you should prefer to use the Conv
interface in new code.
val conv' : ?docv:string -> ('a Conv.parser * 'a Conv.fmt) -> 'a conv
Deprecated. Use Conv.make
instead.
val conv :
?docv:string ->
((string -> ('a, [ `Msg of string ]) Stdlib.result) * 'a Conv.fmt) ->
'a conv
Deprecated. Use Conv.make
instead.
val conv_parser : 'a conv -> string -> ('a, [ `Msg of string ]) Stdlib.result
Deprecated. Use Conv.parser
.
val parser_of_kind_of_string :
kind:string ->
(string -> 'a option) ->
string ->
('a, [ `Msg of string ]) Stdlib.result
Deprecated. parser_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.).