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 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.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
.
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.~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.
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.
typeeval_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:
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
formatterhelp
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_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.