Module `Cmdliner.Cmd`Source

Commands.

Command line syntaxes are implicitely defined by Term.t values. A command value binds a term and its documentation to a command name.

A command can group a list of subcommands (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.

Sourcemodule Exit : sig ... end

Exit codes and their information.

Sourcemodule Env : sig ... end

Environment variable and their information.

type info

The type for information about commands.

val info : 
  ?deprecated:string ->
  ?man_xrefs:Manpage.xref list ->
  ?man:Manpage.block list ->
  ?envs:Env.info list ->
  ?exits:Exit.info list ->
  ?sdocs:Manpage.section_name ->
  ?docs:Manpage.section_name ->
  ?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. Use of the variable warns on stderr. This message which should be a capitalized sentence is preprended to doc and output on standard error when the environment variable ends up being 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 Manpage.s_commands).
sdocs defines the title of the section in which the standard --help and --version arguments are listed (defaults to Manpage.s_common_options).
exits is a list of exit statuses that the command evaluation may produce, defaults to 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 Manpage.s_see_also section.

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

$(tool) the main, topmost, command name.
$(cmd) the command invocation from main command to the command name.
$(cmd.name) the command's name.
$(cmd.parent) the command's parent or the main command if none.

Previously some of these names were refered to as $(tname), $(mname) and $(iname), they still work but do not use them, they are obscure.

Commands

type 'a t

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

val make : info -> 'a Term.t -> 'a t

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

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

v is an old name for make which should be preferred.

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

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

val name : 'a t -> string

name c is the name of c.

Evaluation

Read Which Cmd evaluation function should I use? in the cookbook if you struggle to choose between this menagerie of evaluation functions.

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

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

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

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

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

val eval' : 
  ?help:Format.formatter ->
  ?err: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 eval_value for other arguments.

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

eval_result cmd is:

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

See eval_value for other arguments.

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

eval_result' cmd is:

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

See 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. All evaluation functions are wrappers around eval_value.

type 'a eval_ok = [

| `Ok of 'a
(*
The term of the command evaluated to this value.
*)
| `Version
(*
The version of the main cmd was requested.
*)
| `Help
(*
Help was requested.
*)

]

The type for successful evaluation results.

type eval_error = [

| `Parse
(*
A parse error occurred.
*)
| `Term
(*
A term evaluation error occurred.
*)
| `Exn
(*
An uncaught exception occurred.
*)

]

The type for erroring evaluation results.

val eval_value : 
  ?help:Format.formatter ->
  ?err:Format.formatter ->
  ?catch:bool ->
  ?env:(string -> string option) ->
  ?argv:string array ->
  'a t ->
  ('a eval_ok, eval_error) 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, version messages or completions, (defaults to Format.std_formatter). Note that the completion protocol needs to output '\n' line ending, if you are outputing to a channel make sure it is in binary mode to avoid newline translation (this is done automatically before completion when help is Format.std_formatter).
err is the formatter used to print error messages (defaults to Format.err_formatter).

type 'a eval_exit = [

| `Ok of 'a
(*
The term of the command evaluated to this value.
*)
| `Exit of Exit.code
(*
The evaluation wants to exit with this code.
*)

]

The type for evaluation exits.

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

eval_value' is like eval_value, but if the command term does not evaluate to Ok (`Ok v), returns an exit code like the higher-level evaluation functions do (which can be Exit.ok in case help or version was requested).

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

WARNING. You are highly encouraged not to use this function it may be removed in the future.

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

Install

dune-project
Dependency

Authors

Maintainers

Sources

doc/cmdliner/Cmdliner/Cmd/index.html

Module `Cmdliner.Cmd`Source

Command information

Commands

Evaluation

Low level evaluation

package cmdliner

Install

dune-project Dependency

Authors

Maintainers

Sources

doc/cmdliner/Cmdliner/Cmd/index.html

Module Cmdliner.CmdSource

Command information

Commands

Evaluation

Low level evaluation

dune-project
Dependency

Module `Cmdliner.Cmd`Source