{0:manual Manual}

The user manual provides some patterns for writing certain kinds of line
editors.

{1:history History}

The command {! history} is a simple function whose argument is the current
input to the line editor and expects a list of strings of historical commands.

{! Bruit} does not control saving or restoring command histories, that is up to the
end user.

A simple history that uses the current input as a prefix filter might look something like
this:

{[
let h = ref []

let history prefix =
  if prefix <> "" then List.filter (fun s -> String.starts_with ~prefix s) !h
  else !h
]}

Within the command loop, you can save successful commands into the reference.

{1:hints Hints}

Hints are overlayed onto the current line editor. Supplying hints is fairly
straightforward using a {! Bruit.hint} function. This produces a string to
overlay alongside an {! Fmt.style}. Without the style it would be hard to
distinguish between what the user has written and what is being hinted at.

Often you will want to {! String.sub} the input from your hint:

{[
let hint s =
  if s = "" then None
  else
    if String.starts_with ~prefix:s "hello" then
      let len = String.length s in
      Some (String.sub "hello" len (5 - len), `Fg `Cyan)
    else
      None
]}  

{1:colours Using colours}

Different parts of the line editor can make use of colours in the terminal using
ANSI escape sequences. Depending on what you are trying to achieve, you can do this
in different ways.

For example, to style your prompt using ANSI escape sequences you can write them directly
into the string you pass as the prompt to {! Bruit.run}.

{[
let prompt =
  if sys_break then "[\x1b[31m130\x1b[0m] \x1b[33m>>\x1b[0m "
  else "\x1b[33m>>\x1b[0m "
]}

If you then link in {{: https://erratique.ch/software/fmt/doc/Fmt_tty}[Fmt_tty]} you can set up
the outputs:

{[
let () =
  Fmt_tty.setup_std_outputs ();
  (* ... *)
]}

{2 ANSI in the browser}

If you are using your line editor in the browser, {b and} you wish to have colours, then you will have
to ensure your HTML page has the {! Ansi.css} stylesheet (or a custom version) loaded.

{[
let () = 
  El.append_children (Document.head G.document)
    [ El.style [ El.txt' Ansi.css ] ];
]}