# Module Cmdliner.Cmd

    module Cmd: sig .. end

Commands.

Command line syntaxes are implicitely defined by `Cmdliner.Term`s. A command value binds a syntax and its documentation to a command name.

A command can group a list of sub commands (and recursively). In this case your tool defines a tree of commands, each with its own command line syntax. The root of that tree is called the main command; it represents your tool and its name.

## Command information

Command information defines the name and documentation of a command.

    module Exit: sig .. end

Exit codes and their information.

    module Env: sig .. end

Environment variable and their information.

    type info

The type for information about commands.

    val info : ?deprecated:string ->
           ?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 command.
- `version` is the version string of the command line tool, this is only relevant for the main command and ignored otherwise.
- `deprecated`, if specified the command is deprecated and the string is a message output on standard error when the command is used.
- `doc` is a one line description of the command used for the `NAME` section of the command's man page and in command group listings.
- `docs`, for commands that are part of a group, the title of the section of the parent's command 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_common_options`).
- `exits` is a list of exit statuses that the command evaluation may produce, defaults to `Cmdliner.Cmd.Exit.defaults`.
- `envs` is a list of environment variables that influence the command's evaluation.
- `man` is the text of the man page for the command.
- `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) command's name.
- `$(mname)` the main command name.
- `$(iname)` the command invocation from main command to the command name.

## Commands

    type 'a t

The type for commands whose evaluation result in a value of type `'a`.

    val v : info -> 'a Cmdliner.Term.t -> 'a t

`v i t` is a command with information `i` and command line syntax parsed by `t`.

    val group : ?default:'a Cmdliner.Term.t ->
           info -> 'a t list -> 'a t

`group i ?default cmds` is a command with information `i` that groups sub commands `cmds`. `default` is the command line syntax to parse if no sub command is specified on the command line. If `default` is `None` (default), the tool errors when no sub command is specified.

    val name : 'a t -> string

`name c` is the name of `c`.

## Evaluation

These functions are meant to be composed with `Stdlib.exit`. The following exit codes may be returned by all these functions:

- `Cmdliner.Cmd.Exit.cli_error` if a parse error occurs.
- `Cmdliner.Cmd.Exit.internal_error` if the `~catch` argument is `true` (default) and an uncaught exception is raised.
- The value of `~term_err` (defaults to `Cmdliner.Cmd.Exit.cli_error`) if a term error occurs.

These exit codes are described in `Cmdliner.Cmd.Exit.defaults` which is the default value of the `?exits` argument of function `val-info`.

    val eval : ?help:Stdlib.Format.formatter ->
           ?err:Stdlib.Format.formatter ->
           ?catch:bool ->
           ?env:(string -> string option) ->
           ?argv:string array ->
           ?term_err:Exit.code ->
           unit t -> Exit.code

`eval cmd` is `Cmdliner.Cmd.Exit.ok` if `cmd` evaluates to `()`. See `Cmdliner.Cmd.eval_value` for other arguments.

    val eval' : ?help:Stdlib.Format.formatter ->
           ?err:Stdlib.Format.formatter ->
           ?catch:bool ->
           ?env:(string -> string option) ->
           ?argv:string array ->
           ?term_err:Exit.code ->
           Exit.code t -> Exit.code

`eval' cmd` is `c` if `cmd` evaluates to the exit code `c`. See `Cmdliner.Cmd.eval_value` for other arguments.

    val eval_result : ?help:Stdlib.Format.formatter ->
           ?err:Stdlib.Format.formatter ->
           ?catch:bool ->
           ?env:(string -> string option) ->
           ?argv:string array ->
           ?term_err:Exit.code ->
           (unit, string) Stdlib.result t -> Exit.code

`eval_result cmd` is:

- `Cmdliner.Cmd.Exit.ok` if `cmd` evaluates to `Ok ()`.
- `Cmdliner.Cmd.Exit.some_error` if `cmd` evaluates to `Error msg`. In this case `msg` is printed on `err`.

See `Cmdliner.Cmd.eval_value` for other arguments.

    val eval_result' : ?help:Stdlib.Format.formatter ->
           ?err:Stdlib.Format.formatter ->
           ?catch:bool ->
           ?env:(string -> string option) ->
           ?argv:string array ->
           ?term_err:Exit.code ->
           (Exit.code, string) Stdlib.result t ->
           Exit.code

`eval_result' cmd` is:

- `c` if `cmd` evaluates to `Ok c`.
- `Cmdliner.Cmd.Exit.some_error` if `cmd` evaluates to `Error msg`. In this case `msg` is printed on `err`.

See `Cmdliner.Cmd.eval_value` for other arguments.

### Low level evaluation

This interface gives more information on command evaluation results and lets you choose how to map evaluation results to exit codes.

    type 'a eval_ok = [ `Help | `Ok of 'a | `Version ]

The type for successful evaluation results.

    type eval_error = [ `Exn | `Parse | `Term ]

The type for erroring evaluation results.

    type 'a eval_exit = [ `Exit of Exit.code | `Ok of 'a ]

    val eval_value : ?help:Stdlib.Format.formatter ->
           ?err:Stdlib.Format.formatter ->
           ?catch:bool ->
           ?env:(string -> string option) ->
           ?argv:string array ->
           'a t ->
           ('a eval_ok, eval_error) Stdlib.result

`eval ~help ~err ~catch ~env ~argv cmd` is the evaluation result of `cmd` with:

- `argv` the command line arguments to parse (defaults to `Sys.argv`)
- `env` the function used for environment variable lookup (defaults to `Sys.getenv`).
- `catch` if `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`).

    val eval_value' : ?help:Stdlib.Format.formatter ->
           ?err:Stdlib.Format.formatter ->
           ?catch:bool ->
           ?env:(string -> string option) ->
           ?argv:string array ->
           ?term_err:int -> 'a t -> 'a eval_exit

`eval_value'` is like `Cmdliner.Cmd.eval_value`, but if the command term does not evaluate, returns an exit code like the evaluation function do (which can be `Cmdliner.Cmd.Exit.ok` in case help or version was requested).

    val eval_peek_opts : ?version_opt:bool ->
           ?env:(string -> string option) ->
           ?argv:string array ->
           'a Cmdliner.Term.t ->
           'a option * ('a eval_ok, eval_error) Stdlib.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 `val-eval_value` 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.