Module Lwt_read_line

module Lwt_read_line : sig..end

Interactive line input

Definitions ¶

exception Interrupt

Exception raised when the user press Ctrl^D

type edition_state = Text.t * Text.t

An edition state, it is a pair of two UTF-8 encoded strings:

the input before the cursor
the input after the cursor

type prompt = Lwt_term.styled_text

A prompt. It may contains colors.

type text_set = Set.Make(Text).t

Completion

type completion_result = {
  comp_state: edition_state;(* The new edition state *)  comp_words: text_set;(* A list of possibilities *)}

Result of a completion function:

type completion = edition_state -> completion_result Lwt.t

Type of a completion function. It takes as argument the current edition state.

Note: the thread launched by the completion function is cancelled using Lwt.cancel if the user continue typing text.

val lookup : Text.t -> text_set -> Text.t * text_set

lookup word words lookup for completion of word into words. It returns (prefix, possibilities) where possibilities are all words starting with word and prefix is the longest common prefix of possibilities.

val complete : 
  ?suffix:Text.t ->
  Text.t ->
  Text.t ->
  Text.t -> text_set -> completion_result

complete ?suffix before word after words basic completion functions. words is a list of possible completions for word.

If completion succeed suffix is append to the resulting text. It defaults to " ".

val print_words : 
  Lwt_text.output_channel -> int -> string list -> unit Lwt.t

print_words oc columns strs pretty-prints a list of words.

History

type history = Text.t list

Type of an history

val add_entry : Text.t -> history -> history

add_entry line history returns the history history plus line at the beginning. If line already appears at the beginning or contains only spaces, it is discarded.

val save_history : string -> history -> unit Lwt.t

save_history filename history saves history to filename. History is saved by separating lines with a null character.

val load_history : string -> history Lwt.t

load_history filename loads history from filename. Returns the empty history if the the file does not exit.

Clipboards

class clipboard :  object..end

Type of a clipboard.

val clipboard : clipboard

The global clipboard. All read-line instances which do not use a specific clipboard use this one.

High-level functions ¶

type completion_mode = [ `classic | `none | `real_time ]

The completion mode.

`classic means that when the user hit Tab a list of possible completions is proposed,

`real_time means that possible completions are shown to the user as he types, and he can navigate in them with Meta+left, Meta+right

`none means no completion at all

val read_line : 
  ?history:history ->
  ?complete:completion ->
  ?clipboard:clipboard ->
  ?mode:completion_mode ->
  ?prompt:prompt -> unit -> Text.t Lwt.t

readline ?history ?complete ?mode ?prompt () inputs some text from the user. If input is not a terminal, it defaults to Lwt_text.read_line Lwt_text.stdin.

mode : contains the current completion mode. It defaults to `real_time.

prompt : defaults to Lwt_term.Text "# "

type password_style = [ `clear | `empty | `text of Text.t ]

Style which indicate how the password is echoed to the user:

with `empty nothing is printed
with `clear the password is displayed has it
with `text ch all characters are replaced by ch

val read_password : 
  ?clipboard:clipboard ->
  ?style:password_style ->
  ?prompt:prompt -> unit -> Text.t Lwt.t

read_password ?clipboard ?clear ~prompt () inputs a password from the user. This function fails if input is not a terminal.

style : defaults to `text "*".

val read_keyword : 
  ?history:history ->
  ?case_sensitive:bool ->
  ?mode:completion_mode ->
  ?prompt:prompt ->
  values:(Text.t * 'a) list -> unit -> 'a Lwt.t

read_keyword ?history ?case_sensitive ?mode ~prompt ~keywords () reads one word which is a member of words. And returns which keyword the user choosed.

case_sensitive default to false.

val read_yes_no : 
  ?history:history ->
  ?mode:completion_mode ->
  ?prompt:prompt -> unit -> bool Lwt.t

read_yes_no ?history ?dynamic prompt () is the same as:

read_keyword ?history ?dynamic prompt [("yes", true); ("no", false)] ()

Low-level interaction ¶

This part allow you to implements your own read-line function, or just to use the readline engine in another context (message box, ...).

module Command : sig..end

Readline commands

module Engine : sig..end

Engine

module Terminal : sig..end

Rendering to the terminal

Advanced use ¶

module Control : sig..end

Controlling a running read-line instance