Terms
val const : 'a -> 'a t
const v
is a term that evaluates to v
.
f $ v
is a term that evaluates to the result of applying the evaluation of v
to the one of f
.
Interacting with Cmdliner's evaluation
The type for command return values. See ret
.
ret v
is a term whose evaluation depends on the case to which v
evaluates. With :
`Ok v
, it evaluates tov
.`Error (usage, e)
, the evaluation fails andCmdliner
prints the errore
and the term's usage ifusage
istrue
.`Help (format, name)
, the evaluation fails andCmdliner
prints the term's man page in the givenformat
(or the man page for a specificname
term in case of multiple term evaluation).
val term_result : ?usage:bool -> ('a, [ `Msg of string ]) Stdlib.result t -> 'a t
term_result ~usage t
evaluates to
`Ok v
ift
evaluates toOk v
`Error `Term
with the error messagee
and usage shown according tousage
(defaults tofalse
), ift
evaluates toError (`Msg e)
.
val cli_parse_result : ('a, [ `Msg of string ]) Stdlib.result t -> 'a t
cli_parse_result t
is a term that evaluates to:
`Ok v
ift
evaluates toOk v
.`Error `Parse
with the error messagee
ift
evaluates toError (`Msg e)
.
val main_name : string t
main_name
is a term that evaluates to the "main" term's name.
val choice_names : string list t
choice_names
is a term that evaluates to the names of the terms to choose from.
with_used_args t
is a term that evaluates to t
tupled with the arguments from the command line that where used to evaluate t
.
Term information
val exit_info : ?docs:string -> ?doc:string -> ?max:int -> int -> exit_info
exit_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 Manpage.s_exit_status
.
In doc
the documentation markup language can be used with following variables:
$(status)
, the value ofmin
.$(status_max)
, the value ofmax
.- The variables mentioned in
info
val default_exits : exit_info list
default_exits
is information for exit status exit_status_success
added to default_error_exits
.
val default_error_exits : exit_info list
default_error_exits
is information for exit statuses exit_status_cli_error
and exit_status_internal_error
.
val env_info : ?docs:string -> ?doc:string -> string -> env_info
env_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 Manpage.s_environment
.
In doc
the documentation markup language can be used with following variables:
$(env)
, the value ofvar
.- The variables mentioned in
info
val info : ?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 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 theNAME
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 toManpage.s_commands
).sdocs
defines the title of the section in which the standard--help
and--version
arguments are listed (defaults toManpage.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 aManpage.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 -> string
name ti
is the name of the term information.
Evaluation
The type for evaluation results.
`Ok v
, the term evaluated successfully andv
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 (seeTerm.ret
).`Error `Exn
, an exceptione
was caught and reported on the error formatter (see the~catch
parameter ofeval
).
val eval : ?help:Stdlib.Format.formatter -> ?err:Stdlib.Format.formatter -> ?catch:bool -> ?env:(string -> string option) -> ?argv:string array -> ('a t * info) -> 'a result
eval 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 result
eval_choice help err catch argv (t,i) choices
is like 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 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 int
.None
if a parse error would occur on the options oft
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
and 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.
Turning evaluation results into exit codes
exit_status_cli_error
is 124, an exit status for command line parsing errors.
exit_status_internal_error
is 125, an exit status for unexpected internal errors.
val exit_status_of_result : ?term_err:int -> 'a result -> int
exit_status_of_result ~term_err r
is an exit(3)
status code determined from r
as follows:
exit_status_success
ifr
is one of`Ok _
,`Version
,`Help
term_err
ifr
is`Error `Term
,term_err
defaults to1
.exit_status_cli_error
ifr
is`Error `Parse
exit_status_internal_error
ifr
is`Error `Exn
val exit_status_of_status_result : ?term_err:int -> int result -> int
exit_status_of_status_result
is like exit_status_of_result
except for `Ok n
where n
is used as the status exit code.
val exit : ?term_err:int -> 'a result -> unit
exit ~term_err r
is Stdlib.exit @@ exit_status_of_result ~term_err r
val exit_status : ?term_err:int -> int result -> unit
exit_status ~term_err r
is Stdlib.exit @@ exit_status_of_status_result ~term_err r