Previous  Up  

Module Cmdliner.Arg

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 contraints can be specified during the conversion to a term.


Argument converters

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 ]
The type for argument parsers.
type 'a printer = Format.formatter -> 'a -> unit
The type for converted argument printers.
type 'a converter = 'a parser * 'a printer
The type for argument converters.
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 "").

Arguments and their information

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
The type for environment variables and their documentation.
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
The type for arguments holding data of type 'a.
type info
The type for information about command line arguments.
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. 


val (&) : ('a -> 'b) -> 'a -> 'b
f & v is f v, a right associative composition operator for specifying argument terms.

Optional arguments

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

Positional arguments

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

Arguments as terms


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.

Predefined converters


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
Cmdliner.Arg.t2 is Cmdliner.Arg.pair.
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.

Documentation formatting helpers


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