Cmdliner.Term

# Module Cmdliner.Term

    module Term: sig .. end

Terms.

A term is evaluated by a program to produce a result. 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.($)`.

    type 'a ret = [ `Error of bool * string
           | `Help of [ `Groff | `Pager | `Plain ] * 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 r`, it evaluates to `r`.
- ``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 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 man_format : [ `Groff | `Pager | `Plain ] 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`.

# 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 info

The type for term information.

    val info : ?sdocs:string ->
           ?man:Cmdliner.Manpage.block list ->
           ?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 `"COMMANDS"`).
- `man` is the text of the man page for the term. In the text, the variables `"$(tname)"` and `"$(mname)"` can respectively be used to refer to the value of `name` and the main term's name.
- `sdocs` defines the title of the section in which the standard `--help` and `--version` arguments are listed.

    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 occured and was reported on the error formatter.
- ``Error `Term`, a term evaluation error occured 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:Format.formatter ->
           ?err: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 exeptions 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:Format.formatter ->
           ?err: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 default (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.