cmdliner 1.3.0 · OCaml Package

Commands.

Command line syntaxes are implicitely defined by 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:Manpage.xref list ->
  ?man: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 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, 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 Term.t -> 'a t

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

val group : ?default:'a 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:

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

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.

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

]

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 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: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, returns an exit code like the evaluation function 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

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.

package cmdliner

Command information

Commands

Evaluation

Low level evaluation