# 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`.

If

`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 * 'value) list -> unit -> 'value 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