package cmdtui

  1. Overview
  2. Docs
package cmdtui
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module CmdtuiSource

interactive command completion and execution for building REPLs

v0.4.3 — homepage

Consult the basics, and examples.

Cmdtui

Sourcetype 'a t

the type for command declarations

Sourceval 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

Sourceval ($) : ('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)
Sourceval 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)
    ])
Sourceval 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.

Sourcetype completion = {
  1. desc : string option;
  2. choices : string list option;
}
Sourceval 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

Sourceval int : int t

integer argument

Sourceval float : float t

floating point argument

Sourceval string : string t

string point argument

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

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

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