module Term:sig..end
Terms.
A term is evaluated by a program to produce a result, which can be turned into an exit status. A term made of terms referring to command line arguments implicitly defines a command line syntax.
type +'a t
The type for terms evaluating to values of type 'a.
val const : 'a -> 'a tconst v is a term that evaluates to v.
val ($) : ('a -> 'b) t -> 'a t -> 'b tf $ v is a term that evaluates to the result of applying
the evaluation of v to the one of f.
val app : ('a -> 'b) t -> 'a t -> 'b tapp is Cmdliner.Term.($).
val term_result : ?usage:bool ->
('a, [ `Msg of string ]) Stdlib.result t -> 'a tterm_result ~usage t evaluates to
`Ok v if t evaluates to Ok v`Error `Term with the error message e and usage shown according
to usage (defaults to false), if t evaluates to
Error (`Msg e).See also Cmdliner.Term.term_result'.
val term_result' : ?usage:bool ->
('a, string) Stdlib.result t -> 'a tterm_result' is like Cmdliner.Term.term_result but with a string
error case.
val cli_parse_result : ('a, [ `Msg of string ]) Stdlib.result t -> 'a tcli_parse_result t is a term that evaluates to:
`Ok v if t evaluates to Ok v.`Error `Parse with the error message e
if t evaluates to Error (`Msg e).See also Cmdliner.Term.cli_parse_result'.
val cli_parse_result' : ('a, string) Stdlib.result t -> 'a tcli_parse_result' is like Cmdliner.Term.cli_parse_result but with a string
error case.
val main_name : string tmain_name is a term that evaluates to the main command name;
that is the name of the tool.
val choice_names : string list tchoice_names is a term that evaluates to the names of the commands
that are children of the main command.
val with_used_args : 'a t -> ('a * string list) twith_used_args t is a term that evaluates to t tupled
with the arguments from the command line that where used to
evaluate t.
type'aret =[ `Error of bool * string
| `Help of Cmdliner.Manpage.format * string option
| `Ok of 'a ]
The type for command return values. See val-ret.
val ret : 'a ret t -> 'a tret v is a term whose evaluation depends on the case
to which v evaluates. With :
`Ok v, it evaluates to v.`Error (usage, e), the evaluation fails and Cmdliner prints
the error e and the term's usage if usage is true.`Help (format, name), the evaluation fails and Cmdliner prints
a manpage in format format. If name is None this is the
the main command's manpage. If name is Some c this is
the man page of the sub command c of the main command.Note. While not deprecated you are encouraged not use this API.
This interface is deprecated in favor of Cmdliner.Cmd. Follow
the compiler deprecation warning hints to transition.
Term information defines the name and man page of a term. For simple evaluation this is the name of the program and its man page. For multiple term evaluation, this is the name of a command and its man page.
type
The type for exit status information.
val exit_info : ?docs:string -> ?doc:string -> ?max:int -> int -> exit_infoexit_info ~docs ~doc min ~max describe the range of exit
statuses from min to max (defaults to min). doc is the
man page information for the statuses, defaults to "undocumented".
docs is the title of the man page section in which the statuses
will be listed, it defaults to Cmdliner.Manpage.s_exit_status.
In doc the documentation markup language
can be used with following variables:
$(status), the value of min.$(status_max), the value of max.val-infoval default_exits : exit_info listdefault_exits is information for exit status Cmdliner.Term.exit_status_success
added to Cmdliner.Term.default_error_exits.
val default_error_exits : exit_info listdefault_error_exits is information for exit statuses
Cmdliner.Term.exit_status_cli_error and Cmdliner.Term.exit_status_internal_error.
type
The type for environment variable information.
val env_info : ?docs:string -> ?doc:string -> string -> env_infoenv_info ~docs ~doc var describes an environment variable
var. doc is the man page information of the environment
variable, defaults to "undocumented". docs is the title of
the man page section in which the environment variable will be
listed, it defaults to Cmdliner.Manpage.s_environment.
In doc the documentation markup language
can be used with following variables:
$(env), the value of var.val-infotype
The type for term information.
val info : ?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 -> infoinfo sdocs man docs doc version name is a term information
such that:
name is the name of the program or the command.version is the version string of the program, ignored
for commands.doc is a one line description of the program or command used
for the NAME section of the term's man page. For commands this
description is also used in the list of commands of the main
term's man page.docs, only for commands, the title of the section of the main
term's 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_options).exits is a list of exit statuses that the term evaluation
may produce.envs is a list of environment variables that influence
the term's evaluation.man is the text of the man page for the term.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 name.$(mname) the main term's name.val name : info -> stringname ti is the name of the term information.
type'aresult =[ `Error of [ `Exn | `Parse | `Term ] | `Help | `Ok of 'a | `Version ]
The type for evaluation results.
`Ok v, the term evaluated successfully and v is the result.`Version, the version string of the main term was printed
on the help formatter.`Help, man page about the term was printed on the help formatter.`Error `Parse, a command line parse error occurred and was
reported on the error formatter.`Error `Term, a term evaluation error occurred and was reported
on the error formatter (see Term.val-ret').`Error `Exn, an exception e was caught and reported
on the error formatter (see the ~catch parameter of Cmdliner.Term.eval).val eval : ?help:Stdlib.Format.formatter ->
?err:Stdlib.Format.formatter ->
?catch:bool ->
?env:(string -> string option) ->
?argv:string array ->
'a t * info -> 'a resulteval help err catch argv (t,i) is the evaluation result
of t with command line arguments argv (defaults to Sys.argv).
If catch is 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).
env is used for environment variable lookup, the default
uses Sys.getenv.
val eval_choice : ?help:Stdlib.Format.formatter ->
?err:Stdlib.Format.formatter ->
?catch:bool ->
?env:(string -> string option) ->
?argv:string array ->
'a t * info ->
('a t * info) list -> 'a resulteval_choice help err catch argv (t,i) choices is like Cmdliner.Term.eval
except that if the first argument on the command line is not an option
name it will look in choices for a term whose information has this
name and evaluate it.
If the command name is unknown an error is reported. If the name
is unspecified the "main" term t is evaluated. i defines the
name and man page of the program.
val eval_peek_opts : ?version_opt:bool ->
?env:(string -> string option) ->
?argv:string array ->
'a t -> 'a option * 'a resulteval_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 tThe 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 Cmdliner.Term.eval and Cmdliner.Term.eval_choice 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.
Note. If you are using the following functions to handle
the evaluation result of a term you should add Cmdliner.Term.default_exits to
the term's information ~exits argument.
WARNING. You should avoid status codes strictly greater than 125 as those may be used by some shells.
val exit_status_success : intexit_status_success is 0, the exit status for success.
val exit_status_cli_error : intexit_status_cli_error is 124, an exit status for command line
parsing errors.
val exit_status_internal_error : intexit_status_internal_error is 125, an exit status for unexpected
internal errors.
val exit_status_of_result : ?term_err:int -> unit result -> intexit_status_of_result ~term_err r is an exit(3) status
code determined from r as follows:
Cmdliner.Term.exit_status_success if r is one of `Ok (), `Version, `Helpterm_err if r is `Error `Term, term_err defaults to 1.Cmdliner.Term.exit_status_cli_error if r is `Error `ParseCmdliner.Term.exit_status_internal_error if r is `Error `Exnval exit_status_of_status_result : ?term_err:int -> int result -> intexit_status_of_status_result is like Cmdliner.Term.exit_status_of_result
except for `Ok n where n is used as the status exit code.
val exit : ?term_err:int -> unit result -> unitexit ~term_err r is
Stdlib.exit @@ exit_status_of_result ~term_err r
val exit_status : ?term_err:int -> int result -> unitexit_status ~term_err r is
Stdlib.exit @@ exit_status_of_status_result ~term_err r