interactive command completion and execution for building REPLs
v0.4.3 — homepage
Consult the basics, and examples.
val const : 'a ‑> 'a t
const v
is a command that evaluates to v
.
You should use this to start your command definition by providing a
function (the action), for example:
const f
f $ v
is a command that evaluates to applying v
to f
.
You should use this to declare function parameters, for example:
let f a = a + 1
let cmd = Cmdtui.(const f $ int)
commands ?help spec
builds multiple commands from spec
.
spec
is a list with command_name, (doc, cmd_spec)
tuples.
The first element of the args
array is used to look up the command_name
in spec
, and then the rest of the array is used to build the arguments
for the command action.
doc
is used when showing the built-in help (the help
command).
help
is the command invoked to display the help (default: none).
For example:
let showf f = Printf.printf "%.3f\n" f
let add a b = a +. b
let cmd = Cmdtui.(commands [
"showf", "prints its floating point argument", (const showf $ float);
"add", "adds a floating point number", (const add $ float $ float)
])
val eval : 'a t ‑> string array ‑> 'a
eval spec args
evaluates the command args
using spec
.
If the command cannot be found or there are more elements in args
than
the command is declared with then Failure
is raised.
If there are fewer arguments then Invalid_argument
is raised.
val completion : 'a t ‑> string array ‑> completion option
completion spec args
returns possible completions if any
given the (partial) input string in args
val enum : desc:string ‑> (string * 'a) list ‑> 'a t
enum desc lst
is an argument with all possible values from lst
.
These are automatically considered as completions.
desc
is the name you give to this argument type and is shown as a hint.
val conv : ?desc:string ‑> ?choices:(unit ‑> string list) ‑> (string ‑> 'a) ‑> 'a t
conv ?desc ?choices of_string
is a custom argument of type 'a
that uses
of_string
to parse user provided arguments,
with optional description desc
.
Possible completions can be computed dynamically if you supply a
choices
function.
val split : string ‑> string array
split line
splits an input line
into arguments suitable for eval
and completion.
Using this module you can declare interactive command actions, their parameters (with types and dynamic completion).
Given a partial input string you can query for a completion using completion. Given a full input string you can evaluate the command with all its parameters using eval. Help can be autogenerated from a list of commands using commands.
This module doesn't depend on any particular terminal UI library.
For a quick start support is provided for lambda-term
in the
cmdtui_lambda_term
subpackage's Cmdtui_lambda_term module.
This allows to build an application:
by just defining a `a Cmdtui.t
, you get:
Example using cmdtui_lambda_term
:
open Lwt
let show state = Printf.printf "%.3f\n" f; return_unit
let add a state = return (state +. a)
let cmds = Cmdtui.(commands ~help:Cmdtui_lambda_term.display_help [
"showf", "prints the state (floating point)", (const show);
"add", "adds a number to the current state", (const add $ float)
])
let () = Cmdtui_lambda_term.run ~prompt:"test" cmds 0.
$ ocamlfind ocamlopt $(opam config var cmdtui:doc)/example.ml \ -package cmdtui.lambda-term -linkpkg -o example $ ./example
results in this:
──────────────────────────────────────────────────── test > add 42 example.native: [DEBUG] evaluating command [|add; 42 ──────────────────────────────────────────────────── test > show example.native: [DEBUG] evaluating command [|show|] 42.000 ──────────────────────────────────────────────────── test > add 1 example.native: [DEBUG] evaluating command [|add; 1| ──────────────────────────────────────────────────── test > show example.native: [DEBUG] evaluating command [|show|] 43.000 ──────────────────────────────────────────────────── test > add ┌─────────────────────────────────────────────────── │float └───────────────────────────────────────────────────