Module Cmdliner.Cmd

module Cmd: sig .. end

Commands.

Command line syntaxes are implicitely defined by Cmdliner.Terms. 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:

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

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:

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:

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:

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.

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:

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:

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.