Module Cmdliner.Arg

The type for argument parsers.

deprecated

Use a parser with ('a, [ `Msg of string]) result results and conv.

The type for converted argument printers.

The type for argument converters.

WARNING. This type will become abstract in the next major version of cmdliner, use conv or pconv to construct values of this type.

deprecated

Use the conv type via the conv and pconv functions.

converter ~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".

pconv is like converter, but uses a deprecated parser signature.

conv_parser c 's c's parser.

conv_printer c is c's printer.

conv_docv c is c's documentation meta-variable.

WARNING. Currently always returns "VALUE" in the future will return the value given to conv or pconv.

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

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 "").

The type for environment variables and their documentation.

env_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 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 Manpage.s_environment.

The type for arguments holding data of type 'a.

The type for information about command line arguments.

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

f & v is f v, a right associative composition operator for specifying argument terms.

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₀,i₀;...] 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.

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.

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

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

pos_right is like pos_left except it holds all the positional arguments found on the right of the specified positional argument.

value a is a term that evaluates to a's value.

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

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.

man_format is a term that defines a --man-format option and evaluates to a value that can be used with Manpage.print.

bool converts values with bool_of_string.

char converts values by ensuring the argument has a single char.

int converts values with int_of_string.

nativeint converts values with Nativeint.of_string.

int32 converts values with Int32.of_string.

int64 converts values with Int64.of_string.

float converts values with float_of_string.

string converts values with the identity function.

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.

file converts a value with the identity function and checks with Sys.file_exists that a file with that name exists.

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.

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.

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.

t2 is pair.

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.

doc_quote s quotes the string s.

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

raises Invalid_argument

if alts is the empty string.

doc_alts_enum quoted alts is doc_alts quoted (List.map fst alts).