package matrix
Module Matrix_cli_unix.PromptSource
Questions asked at the terminal.
A prompt asks only a user at a terminal. A question about the program's input reads standard input in the terminal's canonical mode, where the user edits a line before Enter sends it. A question only the user can answer, such as a password, is asked on the controlling terminal (/dev/tty), as getpass(3) asks it, however the program's input is redirected. While a line or a secret is asked, a live region on its terminal is off the screen, and what the program prints on that terminal waits, to go out once the prompt has its answer, so that no line lands inside the question. While keys are read the region stays, so a program can draw a menu in it.
A prompt writes its question, then its hint in brackets when it shows one, such as [y/N] or a default, then a space. The question is adapted to the styling of the terminal it is written to (Outputs), for the program's color choice. A default answers an empty line, and a run where nobody can answer, such as with standard input a pipe, where a prompt without one is Error `Not_interactive and writes nothing.
A prompt leaves the interrupt, quit and suspend characters to the terminal, so Ctrl+C ends the job, the quit character quits it and Ctrl+Z stops it as at the shell's prompt. A prompt that changed the terminal's settings puts them back before the job stops and turns them on again when it continues, asking its question again on a new line.
A prompt blocks the thread that asks until it has its answer, waiting in system calls that release the runtime lock, so the program's other threads run while the user types. The fibers that share the thread wait with it. So an Eio program, whose fibers share their domain's thread, asks through Eio_unix.run_in_systhread, as in Eio_unix.run_in_systhread (fun () -> Prompt.line "Name?"), and its other fibers keep running.
The type for the reasons a prompt has no answer.
val line :
?color:Ansi.Styling.choice ->
?default:string ->
string ->
(string, error) Stdlib.resultline ~color ~default question writes question to standard error, with default as its hint, and is the line read from standard input, without its end. It is Error `Not_interactive when standard input is not a terminal.
val confirm :
?color:Ansi.Styling.choice ->
?default:bool ->
string ->
(bool, error) Stdlib.resultconfirm ~color ~default question asks question as line does, with the hint [y/n], or [Y/n] and [y/N] for a default of true and false. It is true for a line whose first character after its blanks is y or Y, and false for n or N, as the POSIX locale's yesexpr and noexpr read an answer. Another line, or an empty one without default, asks again.
val secret :
?color:Ansi.Styling.choice ->
?default:string ->
?mask:bool ->
string ->
(string, error) Stdlib.resultsecret ~color ~default ~mask question writes question to the controlling terminal and is the line read there, without its end, with the echo off (Tty.no_echo). Its hint never shows default. What was typed before the question is discarded, the terminal's settings are put back on every way out, and the line end the echo did not show is written after the answer. It is Error `Not_interactive when the process has no controlling terminal.
With ~mask:true (false by default), each character typed shows as *, so the user sees the keys reach the program, and anyone who sees the screen sees the secret's length. The keys are decoded, so a key that types no text, such as an arrow, is ignored, and the text of a key, a paste or an input method is typed, a line end in a paste ending the line. The terminal's erase character and Backspace erase the last character, its kill character every one, Ctrl+W the last word, and its end-of-file character on an empty line ends the input. The stars are erased once the line ends. On a dumb terminal, which cannot erase them, nothing shows.
val choose :
?color:Ansi.Styling.choice ->
?default:int ->
string ->
string list ->
(int, error) Stdlib.resultchoose ~color ~default question items is the index of the item of items the user picks from a menu, question above the items, drawn on the controlling terminal in a live region that redraws there whatever CI or the program's --progress choice say. Up and Down, or k and j, move the selection, which starts at default (0 by default), Enter picks it, and Escape picks default when there is one. Once picked, the question and the item stay in the scrollback. It is default, or Error `Not_interactive without one, writing nothing, when the process has no controlling terminal. An item shows as text on one line.
Raises Invalid_argument if items is empty or default is not an index of items.
keys f is Ok (f ks) where ks is the keys typed at the controlling terminal, read as they are typed (Tty.keys) while f runs, after which the settings are put back on every way out. ks blocks for each key it gives, ends when the terminal's input ends, and must be read once, inside f. An Escape is told from the start of a key's sequence by 50 milliseconds of silence. It is Error `Not_interactive when the process has no controlling terminal.
A menu that the keys move through is drawn on the terminal they are typed at, in a live region on an output made on /dev/tty with ~progress:`Tty, which redraws it whatever CI or the program's --progress choice say.