Module Cmdliner.Term

Terms.

A term made of terms referring to command line arguments implicitly defines a command line syntax fragment. Terms are associated to command values Cmd.t which are evaluated to eventually produce an exit code.

Nowadays terms are best defined using the Cmdliner.Term.Syntax. See examples in the blueprints.

Terms

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 app : ('a -> 'b) t -> 'a t -> 'b t

app f v is a term that evaluates to the result applying the evaluation of v to the one of f.

val map : ('a -> 'b) -> 'a t -> 'b t

map f t is app (const f) t.

val product : 'a t -> 'b t -> ('a * 'b) t

product t0 t1 is app (app (map (fun x y -> (x, y)) t0) t1)

val ($) : ('a -> 'b) t -> 'a t -> 'b t

f $ v is app f v.

module Syntax : sig ... end

let operators.

Interacting with Cmd.t evaluation

These special terms allow to interact with the low-level evaluation process performed on commands.

val term_result : ?usage:bool -> ('a, [ `Msg of string ]) Stdlib.result t -> 'a t

term_result is such that:

  • term_result ~usage (Ok v) evaluates to Ok (`Ok v).
  • term_result ~usage (Error (`Msg e)) evaluates to Error `Term with the error message e and usage shown according to usage (defaults to false)

See also term_result'.

val term_result' : ?usage:bool -> ('a, string) Stdlib.result t -> 'a t

term_result' is like term_result but with a string error case.

val cli_parse_result : ('a, [ `Msg of string ]) Stdlib.result t -> 'a t

cli_parse_result is such that:

  • cli_parse_result (Ok v) evaluates Ok (`Ok v)).} {- [cli_parse_result (Error (`Msg e))] evaluates Error `Parse.

See also cli_parse_result'.

val cli_parse_result' : ('a, string) Stdlib.result t -> 'a t

cli_parse_result' is like cli_parse_result but with a string error case.

val main_name : string t

main_name is a term that evaluates to the main command name; that is the name of the tool.

val choice_names : string list t

choice_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) t

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.

type 'a ret = [
  1. | `Help of Manpage.format * string option
  2. | `Error of bool * string
  3. | `Ok of 'a
]

The type for command return values. See ret.

val ret : 'a ret t -> 'a t

ret 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 subcommand c of the main command.
val env : (string -> string option) t

env is the env argument given to command evaluation functions. If you need to refine the environment lookup done by Cmdliner's machinery you should use this rather than direct calls to Sys.getenv_opt.