Module Tezos_clic.Clic
Argument parsers.
type ('a, 'ctx) parameter
The type for argument parsers, used for both positional and optional arguments.
The first type parameter is the OCaml type of the argument once parsed from its string notation. The second parameter is a context that is passed throughout the parsing of the command line. Some parameters (for instance a simple
int
) can remain polymorphic, while others need a context to be parsed. Of course, a command line can only contain parameters that bear the same context type.
val parameter : ?autocomplete:('ctx -> string list Tezos_error_monad.Error_monad.tzresult Lwt.t) -> ('ctx -> string -> 'a Tezos_error_monad.Error_monad.tzresult Lwt.t) -> ('a, 'ctx) parameter
Build an argument parser, combining a parsing function and an autocompletion function. The autocompletion must simply return the list of all valid values for the parameter.
Flags and Options
type ('a, 'ctx) arg
The type for optional arguments (and switches).
Extends a parser with a parameter name and a placeholder to display in help screens.
Also adds a documentation for the switch, that must be of the form
"lowercase short description\nOptional longer description."
.
val constant : 'a -> ('a, 'ctx) arg
val arg : doc:string -> ?short:char -> long:string -> placeholder:string -> ('a, 'ctx) parameter -> ('a option, 'ctx) arg
arg ~doc ~long ?short converter
creates an argument to a command. The~long
argument is the long format, without the double dashes. The?short
argument is the optional one letter shortcut. If the argument is not provided,None
is returned.
val default_arg : doc:string -> ?short:char -> long:string -> placeholder:string -> default:string -> ('a, 'ctx) parameter -> ('a, 'ctx) arg
Create an argument that will contain the
~default
value if it is not provided.
val switch : doc:string -> ?short:char -> long:string -> unit -> (bool, 'ctx) arg
Create a boolean switch. The value will be set to
true
if the switch is provided andfalse
if it is not.
Groups of Optional Arguments
val no_options : (unit, 'ctx) options
Include no optional parameters
val args2 : ('a, 'ctx) arg -> ('b, 'ctx) arg -> ('a * 'b, 'ctx) options
Include 2 optional parameters
val args3 : ('a, 'ctx) arg -> ('b, 'ctx) arg -> ('c, 'ctx) arg -> ('a * 'b * 'c, 'ctx) options
Include 3 optional parameters
val args4 : ('a, 'ctx) arg -> ('b, 'ctx) arg -> ('c, 'ctx) arg -> ('d, 'ctx) arg -> ('a * 'b * 'c * 'd, 'ctx) options
Include 4 optional parameters
val args5 : ('a, 'ctx) arg -> ('b, 'ctx) arg -> ('c, 'ctx) arg -> ('d, 'ctx) arg -> ('e, 'ctx) arg -> ('a * 'b * 'c * 'd * 'e, 'ctx) options
Include 5 optional parameters
val args6 : ('a, 'ctx) arg -> ('b, 'ctx) arg -> ('c, 'ctx) arg -> ('d, 'ctx) arg -> ('e, 'ctx) arg -> ('f, 'ctx) arg -> ('a * 'b * 'c * 'd * 'e * 'f, 'ctx) options
Include 6 optional parameters
val args7 : ('a, 'ctx) arg -> ('b, 'ctx) arg -> ('c, 'ctx) arg -> ('d, 'ctx) arg -> ('e, 'ctx) arg -> ('f, 'ctx) arg -> ('g, 'ctx) arg -> ('a * 'b * 'c * 'd * 'e * 'f * 'g, 'ctx) options
Include 7 optional parameters
val args8 : ('a, 'ctx) arg -> ('b, 'ctx) arg -> ('c, 'ctx) arg -> ('d, 'ctx) arg -> ('e, 'ctx) arg -> ('f, 'ctx) arg -> ('g, 'ctx) arg -> ('h, 'ctx) arg -> ('a * 'b * 'c * 'd * 'e * 'f * 'g * 'h, 'ctx) options
Include 8 optional parameters
val args9 : ('a, 'ctx) arg -> ('b, 'ctx) arg -> ('c, 'ctx) arg -> ('d, 'ctx) arg -> ('e, 'ctx) arg -> ('f, 'ctx) arg -> ('g, 'ctx) arg -> ('h, 'ctx) arg -> ('i, 'ctx) arg -> ('a * 'b * 'c * 'd * 'e * 'f * 'g * 'h * 'i, 'ctx) options
Include 9 optional parameters
val args10 : ('a, 'ctx) arg -> ('b, 'ctx) arg -> ('c, 'ctx) arg -> ('d, 'ctx) arg -> ('e, 'ctx) arg -> ('f, 'ctx) arg -> ('g, 'ctx) arg -> ('h, 'ctx) arg -> ('i, 'ctx) arg -> ('j, 'ctx) arg -> ('a * 'b * 'c * 'd * 'e * 'f * 'g * 'h * 'i * 'j, 'ctx) options
Include 10 optional parameters
val args11 : ('a, 'ctx) arg -> ('b, 'ctx) arg -> ('c, 'ctx) arg -> ('d, 'ctx) arg -> ('e, 'ctx) arg -> ('f, 'ctx) arg -> ('g, 'ctx) arg -> ('h, 'ctx) arg -> ('i, 'ctx) arg -> ('j, 'ctx) arg -> ('k, 'ctx) arg -> ('a * 'b * 'c * 'd * 'e * 'f * 'g * 'h * 'i * 'j * 'k, 'ctx) options
Include 11 optional parameters
val args12 : ('a, 'ctx) arg -> ('b, 'ctx) arg -> ('c, 'ctx) arg -> ('d, 'ctx) arg -> ('e, 'ctx) arg -> ('f, 'ctx) arg -> ('g, 'ctx) arg -> ('h, 'ctx) arg -> ('i, 'ctx) arg -> ('j, 'ctx) arg -> ('k, 'ctx) arg -> ('l, 'ctx) arg -> ('a * 'b * 'c * 'd * 'e * 'f * 'g * 'h * 'i * 'j * 'k * 'l, 'ctx) options
Include 12 optional parameters
val args13 : ('a, 'ctx) arg -> ('b, 'ctx) arg -> ('c, 'ctx) arg -> ('d, 'ctx) arg -> ('e, 'ctx) arg -> ('f, 'ctx) arg -> ('g, 'ctx) arg -> ('h, 'ctx) arg -> ('i, 'ctx) arg -> ('j, 'ctx) arg -> ('k, 'ctx) arg -> ('l, 'ctx) arg -> ('m, 'ctx) arg -> ('a * 'b * 'c * 'd * 'e * 'f * 'g * 'h * 'i * 'j * 'k * 'l * 'm, 'ctx) options
Include 13 optional parameters
val args14 : ('a, 'ctx) arg -> ('b, 'ctx) arg -> ('c, 'ctx) arg -> ('d, 'ctx) arg -> ('e, 'ctx) arg -> ('f, 'ctx) arg -> ('g, 'ctx) arg -> ('h, 'ctx) arg -> ('i, 'ctx) arg -> ('j, 'ctx) arg -> ('k, 'ctx) arg -> ('l, 'ctx) arg -> ('m, 'ctx) arg -> ('n, 'ctx) arg -> ('a * 'b * 'c * 'd * 'e * 'f * 'g * 'h * 'i * 'j * 'k * 'l * 'm * 'n, 'ctx) options
Include 14 optional parameters
val args15 : ('a, 'ctx) arg -> ('b, 'ctx) arg -> ('c, 'ctx) arg -> ('d, 'ctx) arg -> ('e, 'ctx) arg -> ('f, 'ctx) arg -> ('g, 'ctx) arg -> ('h, 'ctx) arg -> ('i, 'ctx) arg -> ('j, 'ctx) arg -> ('k, 'ctx) arg -> ('l, 'ctx) arg -> ('m, 'ctx) arg -> ('n, 'ctx) arg -> ('o, 'ctx) arg -> ('a * 'b * 'c * 'd * 'e * 'f * 'g * 'h * 'i * 'j * 'k * 'l * 'm * 'n * 'o, 'ctx) options
Include 15 optional parameters
val args16 : ('a, 'ctx) arg -> ('b, 'ctx) arg -> ('c, 'ctx) arg -> ('d, 'ctx) arg -> ('e, 'ctx) arg -> ('f, 'ctx) arg -> ('g, 'ctx) arg -> ('h, 'ctx) arg -> ('i, 'ctx) arg -> ('j, 'ctx) arg -> ('k, 'ctx) arg -> ('l, 'ctx) arg -> ('m, 'ctx) arg -> ('n, 'ctx) arg -> ('o, 'ctx) arg -> ('p, 'ctx) arg -> ('a * 'b * 'c * 'd * 'e * 'f * 'g * 'h * 'i * 'j * 'k * 'l * 'm * 'n * 'o * 'p, 'ctx) options
Include 16 optional parameters
val args17 : ('a, 'ctx) arg -> ('b, 'ctx) arg -> ('c, 'ctx) arg -> ('d, 'ctx) arg -> ('e, 'ctx) arg -> ('f, 'ctx) arg -> ('g, 'ctx) arg -> ('h, 'ctx) arg -> ('i, 'ctx) arg -> ('j, 'ctx) arg -> ('k, 'ctx) arg -> ('l, 'ctx) arg -> ('m, 'ctx) arg -> ('n, 'ctx) arg -> ('o, 'ctx) arg -> ('p, 'ctx) arg -> ('q, 'ctx) arg -> ('a * 'b * 'c * 'd * 'e * 'f * 'g * 'h * 'i * 'j * 'k * 'l * 'm * 'n * 'o * 'p * 'q, 'ctx) options
Include 17 optional parameters
Parameter based command lines
val param : name:string -> desc:string -> ('a, 'ctx) parameter -> ('b, 'ctx) params -> ('a -> 'b, 'ctx) params
A piece of data inside a command line
val prefix : string -> ('a, 'ctx) params -> ('a, 'ctx) params
A word in a command line. Should be descriptive.
val prefixes : string list -> ('a, 'ctx) params -> ('a, 'ctx) params
Multiple words given in sequence for a command line
val fixed : string list -> ('ctx -> unit Tezos_error_monad.Error_monad.tzresult Lwt.t, 'ctx) params
A fixed series of words that trigger a command.
val stop : ('ctx -> unit Tezos_error_monad.Error_monad.tzresult Lwt.t, 'ctx) params
End the description of the command line
val seq_of_param : (('ctx -> unit Tezos_error_monad.Error_monad.tzresult Lwt.t, 'ctx) params -> ('a -> 'ctx -> unit Tezos_error_monad.Error_monad.tzresult Lwt.t, 'ctx) params) -> ('a list -> 'ctx -> unit Tezos_error_monad.Error_monad.tzresult Lwt.t, 'ctx) params
Take a sequence of parameters instead of only a single one. Must be the last thing in the command line.
val non_terminal_seq : suffix:string list -> (('ctx -> unit Tezos_error_monad.Error_monad.tzresult Lwt.t, 'ctx) params -> ('a -> 'ctx -> unit Tezos_error_monad.Error_monad.tzresult Lwt.t, 'ctx) params) -> ('b -> 'c, 'ctx) params -> ('a list -> 'b -> 'c, 'ctx) params
Take a sequence of parameters followed by suffix keywords and further parameters. On execution, the suffix will be attempted to be matched before the sequence's parameters. Because of this, care must be taken that the sequence's parameters cannot be interpreted as the suffix keywords. For example, it shouldn't be used with parameters that can be arbitrary strings such as aliases.
Raises
Invalid_argument
when the given suffix is an empty list.
Commands
type group
=
{
name : string;
title : string;
}
Type of a group of commands. Groups have their documentation printed together and should include a descriptive title.
Output formatting
type format
=
|
Plain
|
Ansi
|
Html
Supported output formats. Currently: black and white, colors using ANSI escapes, and HTML.
val setup_formatter : Stdlib.Format.formatter -> format -> verbosity -> formatter_state
Updates the formatter's functions to interpret some semantic tags used in manual production. Returns the previous state of the formatter to restore it afterwards if needed.
Toplevel structure tags:
*
<document>
: a toplevel group *<title>
: a section title (just below a<document
) *<list>
: a list section (just below a<document
)Structure tags used internally for generating the manual:
*
<command>
: wraps the full documentation bloc for a command *<commandline>
: wraps the command line in a<command>
*<commanddoc>
: wraps everything but the command line in a<command>
Cosmetic tags for highlighting text:
*
<opt>
: optional arguments *<arg>
: positional arguments *<kwd>
: positional keywords *<hilight>
: search resultsVerbosity levels, in order, and how they are used in the manual:
*
<terse>
: titles, commands lines *<short>
: lists of arguments *<details>
: single line descriptions *<full>
: with long descriptionsWrapping a piece of text with a debug level means that the contents are only printed if the verbosity is equal to or above that level. Use prefix
=
for an exact match, or-
for the inverse interpretation.
val restore_formatter : Stdlib.Format.formatter -> formatter_state -> unit
Restore the formatter state after
setup_formatter
.
Parsing and error reporting
type Tezos_error_monad.Error_monad.error +=
Help : _ command option -> Tezos_error_monad.Error_monad.error
Help error (not really an error), thrown by
dispatch
andparse_global_options
.
type Tezos_error_monad.Error_monad.error +=
Version : Tezos_error_monad.Error_monad.error
Version error (not really an error), thrown by
parse_global_options
.
val dispatch : 'ctx command list -> 'ctx -> string list -> unit Tezos_error_monad.Error_monad.tzresult Lwt.t
Find and call the applicable command on the series of arguments.
- raises [Failure]
if the command list would be ambiguous.
val parse_global_options : ('a, 'ctx) options -> 'ctx -> string list -> ('a * string list) Tezos_error_monad.Error_monad.tzresult Lwt.t
Parse the global options, and return their value, with the rest of the command to be parsed.
val pp_cli_errors : Stdlib.Format.formatter -> executable_name:string -> global_options:(_, _) options -> default:(Stdlib.Format.formatter -> Tezos_error_monad.Error_monad.error -> unit) -> Tezos_error_monad.Error_monad.error list -> unit
Pretty prints the error messages to the given formatter.
executable_name
andglobal_options
are for help screens.default
is used to print non-CLI errors.
val autocompletion : script:string -> cur_arg:string -> prev_arg:string -> args:string list -> global_options:('a, 'ctx) options -> 'ctx command list -> 'ctx -> string list Tezos_error_monad.Error_monad.tzresult Lwt.t
Acts as
dispatch
, but stops if the given command up toprev_arg
is a valid prefix command, returning the list of valid next words, filtered withcur_arg
.
Manual
val add_manual : executable_name:string -> global_options:('a, 'ctx) options -> format -> Stdlib.Format.formatter -> 'ctx command list -> 'ctx command list
Add manual commands to a list of commands. For this to work, the command list must be complete. Commands added later will not appear in the manual.