package console-eio
Build not yet checkedInstall
dune-project
Dependency
Authors
Maintainers
Sources
sha256=37ad65f6833c65814b0673f009f6b656c5194608ca03519da2e63e1051d54f6e
sha512=7677067f1a3244779cdbc5c90a8b0e1eba30c3fd58281584ea3d4c46c3e219eef0668588ca0e2938799c61a3fa831ce2146eac73717214d7baf96b497bfcd892
doc/console-eio/Console_eio/Prompt/index.html
Module Console_eio.PromptSource
Questions asked on the terminal: a line, a yes or no, or a password.
Questions asked on the terminal.
A prompt writes a question on a formatter and reads the answer, one line, from an Eio flow. So while a fiber waits for an answer, other fibers run.
The terminal edits the line as the user types it. secret is the exception: it switches the terminal's echo off and edits the line with a Console_input editor, which shows a * for each grapheme cluster typed. A prompt with nobody to type an answer returns an Error instead of waiting for ever.
While a display opened by Console_eio.run is running, a question clears its progress rows from the screen until it is answered. Meanwhile, what the asking fiber prints goes straight out, and the display captures what other fibers print as usual.
The type for prompts.
v stdin is a prompt that reads answers from stdin.
ppfis where it writes questions (defaults toFmt.stderr, which keeps standard output for the program).interactivesays whether someone can answer (defaults to whetherstdinis a terminal, that is an Eio flow backed by a Unix descriptor for whichisattyis true). A prompt that is not interactive returnsErrorfor every question and writes nothing, instead of blocking on input that nobody will type.
Create one t per program and reuse it. It owns the read buffer, so two questions in a row do not lose the input between them.
The type for the errors of a question. `End_of_input means that the input ended before an answer, for example after Ctrl-D on a terminal. `Msg is any other error, including a prompt that is not interactive.
keys t f is Ok (f input). input holds the bytes of the keys typed on the terminal behind t's input. Each key can be read as soon as it is typed, and it is not echoed, as a game needs. A key that sends an escape sequence, such as an arrow, appears as those bytes, and f decodes them. Ctrl-C and Ctrl-Z still send their signals.
The terminal is restored to its original state when f returns or raises, when its fiber is cancelled, on SIGINT or SIGTERM, and while SIGTSTP stops the program. The rows of a display stay on the screen while f runs. The result is Error `End_of_input when f raises End_of_file, as its reads do at the end of the input. It is Error (`Msg _) when the input is not a terminal, when t is not interactive, or on a Unix.Unix_error. Any other exception from f is raised again.
pp_error formats an error, `End_of_input as "end of input" and `Msg m as m.
line t question writes question, then is the next line of input without its terminator (LF or CRLF). The question is flushed with no newline added. Each control character in it, except a line feed, is written as a space. The answer is returned as typed, spaces included. The result is Error `End_of_input when the input ends before a line feed. It is Error (`Msg _) when t is not interactive, or when the line is longer than 4096 bytes; the rest of that line is then skipped.
confirm t question asks question ^ " [y/N] ". It is true for an answer of "y" or "yes", ignoring case and surrounding whitespace, and false for any other line, including an empty one. Its errors are those of line.
secret t question is like line, but the answer is not shown. Instead, one * is written for each grapheme cluster typed, then a line feed when the answer ends. The answer is the bytes as typed, minus the keys that edit the line (Console_input.feed). It is never retained. As with line, more than 4096 bytes typed before the end of the line gives Error (`Msg _), and the rest of the line is skipped.
Masking switches echo off on the terminal behind t's input. So the result is also Error (`Msg _) when that input is not a terminal. question is written first, and echo goes off after it. Like getpass(3), secret then discards the keys typed before echo went off, because the terminal has already shown them. The terminal is restored to its original state on return, on an exception, and on SIGINT or SIGTERM.