Module Cmdliner.Term

module Term: sig .. end

A term is evaluated by a program to produce a result. 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 t
const v is a term that evaluates to v.
val ($) : ('a -> 'b) t -> 'a t -> 'b t
f $ 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 t
app is Cmdliner.Term.($).
type 'a ret = [ `Error of bool * string
| `Help of [ `Groff | `Pager | `Plain ] * string option
| `Ok of 'a ]
The type for command return values. See Cmdliner.Term.ret.
val ret : 'a ret t -> 'a t
ret v is a term whose evaluation depends on the case to which v evaluates. With :
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.
val man_format : [ `Groff | `Pager | `Plain ] t
man_format is a term that defines a --man-format option and evaluates to a value that can be used with Cmdliner.Manpage.print.

Term information

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 info 
The type for term information.
val info : ?sdocs:string ->
?man:Cmdliner.Manpage.block list ->
?docs:string ->
?doc:string -> ?version:string -> string -> info
info sdocs man docs doc version name is a term information such that:
val name : info -> string
name ti is the name of the term information.


type 'a result = [ `Error of [ `Exn | `Parse | `Term ] | `Help | `Ok of 'a | `Version ] 
The type for evaluation results.
val eval : ?help:Format.formatter ->
?err: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 exeptions 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:Format.formatter ->
?err: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 default (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 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:

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