# 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 constraints 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 ]

Deprecated. Use Arg.conv or Arg.conv' instead.

The type for argument parsers.

Deprecated. Use parser signatures of `val-conv` or `val-conv'`.

    type 'a printer = Stdlib.Format.formatter -> 'a -> unit

The type for converted argument printers.

    type 'a conv = 'a parser * 'a printer

The type for argument converters.

Warning. Do not use directly, use `val-conv` or `val-conv'`. This type will become abstract in the next major version of cmdliner.

    val conv : ?docv:string ->
           (string -> ('a, [ `Msg of string ]) Stdlib.result) * 'a printer ->
           'a conv

`conv ~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"`.

    val conv' : ?docv:string ->
           (string -> ('a, string) Stdlib.result) * 'a printer ->
           'a conv

`conv'` is like `val-conv` but the `Error` case has an unlabelled string.

    val conv_parser : 'a conv -> string -> ('a, [ `Msg of string ]) Stdlib.result

`conv_parser c` is the parser of `c`.

    val conv_printer : 'a conv -> 'a printer

`conv_printer c` is the printer of `c`.

    val conv_docv : 'a conv -> string

`conv_docv c` is `c`'s documentation meta-variable.

Warning. Currently always returns `"VALUE"` in the future will return the value given to `val-conv` or `val-conv'`.

    val parser_of_kind_of_string : kind:string ->
           (string -> 'a option) -> string -> ('a, [ `Msg of string ]) Stdlib.result

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

    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 `conv`'s printer to document the value taken on absence; to document a more complex behaviour use the `absent` argument of `val-info`.

    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.

## 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 'a t

The type for arguments holding data of type `'a`.

    type info

The type for information about command line arguments.

    val info : ?deprecated:string ->
           ?absent:string ->
           ?docs:string ->
           ?docv:string ->
           ?doc:string -> ?env:Cmdliner.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` (`"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 `Cmdliner.Manpage.s_options`. For positional arguments this defaults to `Cmdliner.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.

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

    val opt_all : ?vopt:'a ->
           'a conv ->
           '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 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 `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 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 `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 conv ->
           '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 occurrence takes precedence over the others.

## Predefined arguments

    val man_format : Cmdliner.Manpage.format Cmdliner.Term.t

`man_format` is a term that defines a `--man-format` option and evaluates to a value that can be used with `Cmdliner.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 : (string * 'a) list -> 'a conv

`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 `Stdlib.compare`.

- Raises `Invalid_argument` if `l` is empty.

    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.

    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.

    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.

    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

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

## 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 `Cmdliner.Arg.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

    type 'a converter = 'a conv

Deprecated. Use Arg.conv' function instead.

See `Cmdliner.Arg.conv'`.

    val pconv : ?docv:string ->
           'a parser * 'a printer -> 'a conv

Deprecated. Use Arg.conv or Arg.conv' function instead.

`pconv` is like `val-conv` or `val-conv'`, but uses a deprecated `Cmdliner.Arg.parser` signature.

    type env = Cmdliner.Cmd.Env.info

Deprecated. Use Cmd.Env.info instead.

See `Cmd.Env.type-info`

    val env_var : ?deprecated:string ->
           ?docs:string -> ?doc:string -> Cmdliner.Cmd.Env.var -> Cmdliner.Cmd.Env.info

Deprecated. Use Cmd.Env.info instead.

See `Cmd.Env.val-info`.