# Module Cmdliner.Term

    module Term: sig .. end

Terms.

A term is evaluated by a program to produce a result, which can be turned into an exit status. A term made of terms referring to command line arguments implicitly defines a command line syntax.

## Terms

    type +'a t

The type for terms evaluating to values of type 'a.

    val const : 'a -> 'a t

`const v` is a term that evaluates to `v`.

    val ($) : ('a -> 'b) t -> 'a t -> 'b t

`f $ v` is a term that evaluates to the result of applying the evaluation of `v` to the one of `f`.

    val app : ('a -> 'b) t -> 'a t -> 'b t

`app` is `Cmdliner.Term.($)`.

## Interacting with Cmdliner's evaluation

    type 'a ret = [ `Error of bool * string
           | `Help of Cmdliner.Manpage.format * string option
           | `Ok of 'a ]

The type for command return values. See `Cmdliner.Term.ret`.

    val ret : 'a ret t -> 'a t

`ret v` is a term whose evaluation depends on the case to which `v` evaluates. With :

- ``Ok v`, it evaluates to `v`.
- ``Error (usage, e)`, the evaluation fails and `Cmdliner` prints the error `e` and the term's usage if `usage` is `true`.
- ``Help (format, name)`, the evaluation fails and `Cmdliner` prints the term's man page in the given `format` (or the man page for a specific `name` term in case of multiple term evaluation).

    val term_result : ?usage:bool ->
           ('a, [ `Msg of string ]) Stdlib.result t -> 'a t

`term_result ~usage t` evaluates to

- ``Ok v` if `t` evaluates to `Ok v`
- ``Error `Term` with the error message `e` and usage shown according to `usage` (defaults to `false`), if `t` evaluates to `Error (`Msg e)`.

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

`cli_parse_result t` is a term that evaluates to:

- ``Ok v` if `t` evaluates to `Ok v`.
- ``Error `Parse` with the error message `e` if `t` evaluates to `Error (`Msg e)`.

    val main_name : string t

`main_name` is a term that evaluates to the "main" term's name.

    val choice_names : string list t

`choice_names` is a term that evaluates to the names of the terms to choose from.

    val with_used_args : 'a t -> ('a * string list) t

`with_used_args t` is a term that evaluates to `t` tupled with the arguments from the command line that where used to evaluate `t`.

## Term information

Term information defines the name and man page of a term. For simple evaluation this is the name of the program and its man page. For multiple term evaluation, this is the name of a command and its man page.

    type exit_info

The type for exit status information.

    val exit_info : ?docs:string -> ?doc:string -> ?max:int -> int -> exit_info

`exit_info ~docs ~doc min ~max` describe the range of exit statuses from `min` to `max` (defaults to `min`). `doc` is the man page information for the statuses, defaults to `"undocumented"`. `docs` is the title of the man page section in which the statuses will be listed, it defaults to `Cmdliner.Manpage.s_exit_status`.

In `doc` the documentation markup language can be used with following variables:

- `$(status)`, the value of `min`.
- `$(status_max)`, the value of `max`.
- The variables mentioned in `Cmdliner.Term.info`

    val default_exits : exit_info list

`default_exits` is information for exit status `Cmdliner.Term.exit_status_success` added to `Cmdliner.Term.default_error_exits`.

    val default_error_exits : exit_info list

`default_error_exits` is information for exit statuses `Cmdliner.Term.exit_status_cli_error` and `Cmdliner.Term.exit_status_internal_error`.

    type env_info

The type for environment variable information.

    val env_info : ?docs:string -> ?doc:string -> string -> env_info

`env_info ~docs ~doc var` describes an environment variable `var`. `doc` is the man page information of the environment variable, defaults to `"undocumented"`. `docs` is the title of the man page section in which the environment variable will be listed, it defaults to `Cmdliner.Manpage.s_environment`.

In `doc` the documentation markup language can be used with following variables:

- `$(env)`, the value of `var`.
- The variables mentioned in `Cmdliner.Term.info`

    type info

The type for term information.

    val info : ?man_xrefs:Cmdliner.Manpage.xref list ->
           ?man:Cmdliner.Manpage.block list ->
           ?envs:env_info list ->
           ?exits:exit_info list ->
           ?sdocs:string ->
           ?docs:string ->
           ?doc:string -> ?version:string -> string -> info

`info sdocs man docs doc version name` is a term information such that:

- `name` is the name of the program or the command.
- `version` is the version string of the program, ignored for commands.
- `doc` is a one line description of the program or command used for the `NAME` section of the term's man page. For commands this description is also used in the list of commands of the main term's man page.
- `docs`, only for commands, the title of the section of the main term's man page where it should be listed (defaults to `Cmdliner.Manpage.s_commands`).
- `sdocs` defines the title of the section in which the standard `--help` and `--version` arguments are listed (defaults to `Cmdliner.Manpage.s_options`).
- `exits` is a list of exit statuses that the term evaluation may produce.
- `envs` is a list of environment variables that influence the term's evaluation.
- `man` is the text of the man page for the term.
- `man_xrefs` are cross-references to other manual pages. These are used to generate a `Cmdliner.Manpage.s_see_also` section.

`doc`, `man`, `envs` support the documentation markup language in which the following variables are recognized:

- `$(tname)` the term's name.
- `$(mname)` the main term's name.

    val name : info -> string

`name ti` is the name of the term information.

## Evaluation

    type 'a result = [ `Error of [ `Exn | `Parse | `Term ] | `Help | `Ok of 'a | `Version ]

The type for evaluation results.

- ``Ok v`, the term evaluated successfully and `v` is the result.
- ``Version`, the version string of the main term was printed on the help formatter.
- ``Help`, man page about the term was printed on the help formatter.
- ``Error `Parse`, a command line parse error occurred and was reported on the error formatter.
- ``Error `Term`, a term evaluation error occurred and was reported on the error formatter (see `Cmdliner.Term.ret`).
- ``Error `Exn`, an exception `e` was caught and reported on the error formatter (see the `~catch` parameter of `Cmdliner.Term.eval`).

    val eval : ?help:Stdlib.Format.formatter ->
           ?err:Stdlib.Format.formatter ->
           ?catch:bool ->
           ?env:(string -> string option) ->
           ?argv:string array ->
           'a t * info -> 'a result

`eval help err catch argv (t,i)` is the evaluation result of `t` with command line arguments `argv` (defaults to `Sys.argv`).

If `catch` is `true` (default) uncaught exceptions are intercepted and their stack trace is written to the `err` formatter.

`help` is the formatter used to print help or version messages (defaults to `Format.std_formatter`). `err` is the formatter used to print error messages (defaults to `Format.err_formatter`).

`env` is used for environment variable lookup, the default uses `Sys.getenv`.

    val eval_choice : ?help:Stdlib.Format.formatter ->
           ?err:Stdlib.Format.formatter ->
           ?catch:bool ->
           ?env:(string -> string option) ->
           ?argv:string array ->
           'a t * info ->
           ('a t * info) list -> 'a result

`eval_choice help err catch argv (t,i) choices` is like `Cmdliner.Term.eval` except that if the first argument on the command line is not an option name it will look in `choices` for a term whose information has this name and evaluate it.

If the command name is unknown an error is reported. If the name is unspecified the "main" term `t` is evaluated. `i` defines the name and man page of the program.

    val eval_peek_opts : ?version_opt:bool ->
           ?env:(string -> string option) ->
           ?argv:string array ->
           'a t -> 'a option * 'a result

`eval_peek_opts version_opt argv t` evaluates `t`, a term made of optional arguments only, with the command line `argv` (defaults to `Sys.argv`). In this evaluation, unknown optional arguments and positional arguments are ignored.

The evaluation returns a pair. The first component is the result of parsing the command line `argv` stripped from any help and version option if `version_opt` is `true` (defaults to `false`). It results in:

- `Some _` if the command line would be parsed correctly given the partial knowledge in `t`.
- `None` if a parse error would occur on the options of `t`

The second component is the result of parsing the command line `argv` without stripping the help and version options. It indicates what the evaluation would result in on `argv` given the partial knowledge in `t` (for example it would return ``Help` if there's a help option in `argv`). However in contrasts to `Cmdliner.Term.eval` and `Cmdliner.Term.eval_choice` no side effects like error reporting or help output occurs.

Note. Positional arguments can't be peeked without the full specification of the command line: we can't tell apart a positional argument from the value of an unknown optional argument.

## Turning evaluation results into exit codes

Note. If you are using the following functions to handle the evaluation result of a term you should add `Cmdliner.Term.default_exits` to the term's information `~exits` argument.

WARNING. You should avoid status codes strictly greater than 125 as those may be used by some shells.

    val exit_status_success : int

`exit_status_success` is 0, the exit status for success.

    val exit_status_cli_error : int

`exit_status_cli_error` is 124, an exit status for command line parsing errors.

    val exit_status_internal_error : int

`exit_status_internal_error` is 125, an exit status for unexpected internal errors.

    val exit_status_of_result : ?term_err:int -> 'a result -> int

`exit_status_of_result ~term_err r` is an `exit(3)` status code determined from `r` as follows:

- `Cmdliner.Term.exit_status_success` if `r` is one of ``Ok _`, ``Version`, ``Help`
- `term_err` if `r` is ``Error `Term`, `term_err` defaults to `1`.
- `Cmdliner.Term.exit_status_cli_error` if `r` is ``Error `Parse`
- `Cmdliner.Term.exit_status_internal_error` if `r` is ``Error `Exn`

    val exit_status_of_status_result : ?term_err:int -> int result -> int

`exit_status_of_status_result` is like `Cmdliner.Term.exit_status_of_result` except for ``Ok n` where `n` is used as the status exit code.

    val exit : ?term_err:int -> 'a result -> unit

`exit ~term_err r` is `Stdlib.exit @@ exit_status_of_result ~term_err r`

    val exit_status : ?term_err:int -> int result -> unit

`exit_status ~term_err r` is `Stdlib.exit @@ exit_status_of_status_result ~term_err r`