Arg (cmdliner.Cmdliner.Arg)

Argument converters

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.

val some' : ?none:'a -> 'a conv -> 'a option conv

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.

val some : ?none:string -> 'a conv -> 'a option conv

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.

Arguments

type 'a t

The type for arguments holding data of type 'a.

type info

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 ->
  ?doc_envs:Cmd.Env.info list ->
  ?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. 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. If unspecified is taken from the argument converter's, see Conv.docv.
doc_envs is a list of environment variable that are added to the manual of the command when the argument is used.
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. Use of the variable warns on stderr. This message which should be a capitalized sentence is preprended to doc and output on standard error when the environment variable ends up being 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.

In doc, deprecated, absent the documentation markup language can be used with following variables:

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

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

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. Automatic environment variable lookup is unsupported for for these arguments but an env in an info will be documented. Use an option and Term.env for manually looking something up.

val vflag_all : 'a list -> ('a * info) list -> 'a list t

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. Automatic environment variable lookup is unsupported for for these arguments but an env in an info will be documented. Use an option and Term.env for manually looking something up.

val opt : ?vopt:'a -> 'a conv -> '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. Warning using vopt is not recommended.

val opt_all : ?vopt:'a -> 'a conv -> 'a list -> info -> 'a list t

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.

Positional arguments

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 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 conv -> '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 conv -> '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 conv -> 'a list -> info -> 'a list t

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

Converting to terms

val value : 'a t -> 'a Term.t

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

val required : 'a option t -> 'a 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 in combination with Arg.some' for required positional arguments. Warning using this on optional arguments is not recommended.

val non_empty : 'a list t -> 'a list 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 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 occurrence takes precedence over the others.

Predefined arguments

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.

Predefined converters

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. A completion is added for the names.

Warning. The type 'a must be comparable with Stdlib.compare.

raises Invalid_argument
if l is empty.

val list : ?sep:char -> 'a conv -> 'a list conv

list 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 conv

array 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) conv

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 conv -> 'b conv -> ('a * 'b) conv

t2 is pair.

val t3 : ?sep:char -> 'a conv -> 'b conv -> 'c conv -> ('a * 'b * 'c) conv

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 conv ->
  'b conv ->
  'c conv ->
  'd conv ->
  ('a * 'b * 'c * 'd) conv

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.

Files and directories

val path : string conv

path is like string but prints using Filename.quote and completes both files and directories.

val filepath : string conv

filepath is like string but prints using Filename.quote and completes files.

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 they will still exist at the time you act upon them. So you will have to treat these error cases anyways in your tool function. It is also unhelpful if the file system object may be created by your tool. Rather use filepath and dirpath.

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

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:

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 is

The resulting string can be used in sentences of the form "$(docv) must be %s".

raises Invalid_argument
if alts is the empty list.

val doc_alts_enum : ?quoted:bool -> (string * 'a) list -> string

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

Deprecated

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.

type 'a printer = 'a Conv.fmt

Deprecated. Use Conv.fmt.

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 conv_printer : 'a conv -> 'a Conv.fmt

Deprecated. Use Conv.pp.

val conv_docv : 'a conv -> string

Deprecated. Use Conv.docv.

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