cmdtui 0.4.3 (latest) · OCaml Package

interactive command completion and execution for building REPLs

v0.4.3 — homepage

Cmdtui

type 'a t

the type for command declarations

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

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

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)

val commands : 
  ?help:((string * string) list -> 'a) ->
  (string * (Arg.doc * 'a t)) list ->
  'a t

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.

type completion = {

desc : string option;
choices : string list option;

}

val completion : 'a t -> string array -> completion option

completion spec args returns possible completions if any given the (partial) input string in args

Command argument types

val int : int t

integer argument

val float : float t

floating point argument

val string : string t

string point argument

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.

Basics

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:

shows a prompt
reads input from the user
shows hints for type parameters
provide built-in help for existing commands and key bindings
executes the command on pressing enter
binds F10 to exit

Examples

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                                              
└───────────────────────────────────────────────────