Standard Library: std.io and std.cli
● Intermediate5 min
Every type, method and function of std.io and std.cli: what the spec lists, then each declaration in its source, with its examples and the line that declares it.
Spec 14.6 · learn it in Command-line Programs.
A declaration below shows what a program writes against: a type's fields, a function's parameters, what it gives, its contracts (require, ensure) and its examples. kavach test runs every example, so each one is true of the code.
What the spec lists
| Function | Gives |
|---|---|
io.read_line() -> String? | The next line typed (without its line ending), or none at the end of input. Needs Console |
io.read_hidden() -> String? | A line typed without being shown on the screen, for a password, when standard input is a terminal; otherwise an ordinary line, so a pipe can answer it. none at the end of input. Needs Console (decision 0036) |
io.write(text) | Prints text without a line end, shown at once (for a prompt, or a line drawn again with \r). Needs Console |
io.is_terminal() -> Bool | Whether standard output is a terminal: false for a file, a pipe or a test. Needs Console |
io.colors() -> Bool | Whether standard output shows colors: it is a terminal, and the environment variable NO_COLOR is not set (no-color.org). Needs Console |
cli.args() -> [String] | The program's arguments, without its own name. Needs Env |
cli.exit(code) | Ends the program at once with code. Needs Env |
cli.parse<T>() -> T ! CliError | The arguments, parsed into record type T, or into union type T of commands. Needs Env |
cli.on_stop(grace: 10.seconds) -> StopHold | A hold on the program's stop (5.8): while it is held, the first Ctrl+C, SIGTERM or closed terminal lets the program finish its work, for at most grace, instead of ending it at once |
hold.asked() -> Bool | Whether a stop has been asked for |
hold.done() | Lets go of the hold: once no hold is left after a stop was asked, the program ends |
std.cli · cli.kav
use std.cli: 1 type and 1 function. stdlib/cli/cli.kav
StopHold type
A hold on the program's stop: while it is kept, the first Ctrl+C, SIGTERM or closed terminal lets the program finish its work, for at most its grace, instead of ending it at once.
pub type StopHold {
id: Int
}done method
Lets go of the hold: once no hold is left after a stop was asked, the program ends, with the signal's exit code.
pub fn done(self)on_stop function
A hold on the program's stop, with grace to finish in.
pub fn on_stop(grace: Duration = 10.seconds) -> StopHold