Skip to content
Kavachकवच

Standard Library: std.term

● Intermediate5 min

Every type, method and function of std.term: what the spec lists, then each declaration in its source, with its examples and the line that declares it.

Spec 14.13 · learn it in User Input.

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.

spec 14.13 · std.termthe examples, tested

What the spec lists

FunctionGives s…
term.black(s), term.red(s), term.green(s), term.yellow(s), term.blue(s), term.magenta(s), term.cyan(s), term.white(s), term.gray(s)in that color
term.bold(s)in bold
term.dim(s)faint
term.italic(s)in italics
term.underline(s)underlined
Function or methodDoes
term.progress(total) -> ProgressA bar for a job of total steps, drawn at 0%
bar.step(n) -> Progressn more steps are done: the bar is drawn again (only when its percentage changed)
bar.done()The job is over: the bar is drawn full, and its line ends
FunctionGives
term.prompt(question) -> String?Prints question and a space, and gives the line typed, or none at the end of input
term.prompt_int(question) -> Int?Asks for a whole number: an answer that isn't one gets Please type a whole number. and the question again; none at the end of input
term.prompt_float(question) -> Float?The same for a number (2.5, 3), with Please type a number.
term.prompt_secret(question) -> Secret?Asks for a password or a token, the typing not shown (io.read_hidden), and gives Secret(text: …); none at the end of input
term.confirm(question, default: Bool) -> BoolAsks a yes-or-no question, shown with [y/N] (or [Y/n] when default is true): y or yes gives true, n or no gives false, anything else, an empty line or the end of input gives default
term.choose(question, options: [String]) -> Int?Prints question and the options, numbered from 1, and asks for a number: gives the index (from 0) of the option chosen, or none when the answer is not one of them

std.term · term.kav

use std.term: 2 types and 20 functions. stdlib/term/term.kav

black function

s in black.

pub fn black(s: String) -> String uses Console

red function

s in red.

pub fn red(s: String) -> String uses Console

green function

s in green.

pub fn green(s: String) -> String uses Console

yellow function

s in yellow.

pub fn yellow(s: String) -> String uses Console

blue function

s in blue.

pub fn blue(s: String) -> String uses Console

magenta function

s in magenta.

pub fn magenta(s: String) -> String uses Console

cyan function

s in cyan.

pub fn cyan(s: String) -> String uses Console

white function

s in white.

pub fn white(s: String) -> String uses Console

gray function

s in gray.

pub fn gray(s: String) -> String uses Console

bold function

s in bold.

pub fn bold(s: String) -> String uses Console

dim function

s faint.

pub fn dim(s: String) -> String uses Console

italic function

s in italics.

pub fn italic(s: String) -> String uses Console

underline function

s underlined.

pub fn underline(s: String) -> String uses Console

Progress type

A progress bar (spec 14.13): the job's size, the steps done, and the percentage drawn last (-1 before the first).

pub type Progress {
    total: Int
    steps: Int
    shown: Int

    invariant total >= 0 and total <= 1_000_000_000_000
    invariant steps >= 0 and steps <= total
    invariant shown >= -1 and shown <= 100
}

step method

n more steps of the job are done: the bar is drawn again. Steps past the job's size leave it full.

pub fn step(self, n: Int) -> Progress uses Console
    require n >= 0 and n <= 1_000_000_000_000

done method

The job is over: the bar is drawn full and its line ends.

pub fn done(self) uses Console

progress function

A progress bar for a job of total steps, drawn at 0%.

pub fn progress(total: Int) -> Progress uses Console
    require total >= 0 and total <= 1_000_000_000_000

prompt function

Prints question and a space, and gives the line typed, or none at the end of input.

pub fn prompt(question: String) -> String? uses Console

prompt_int function

Asks for a whole number until the answer is one; none at the end of input.

pub fn prompt_int(question: String) -> Int? uses Console

prompt_float function

Asks for a number until the answer is one; none at the end of input.

pub fn prompt_float(question: String) -> Float? uses Console

Secret type

A password or a token, as term.prompt_secret gives it: text is a secret field, kept out of print and logs (spec 8.7).

pub type Secret {
    pub secret text: String
}

prompt_secret function

Asks for a password or a token, the typing not shown; none at the end of input.

pub fn prompt_secret(question: String) -> Secret? uses Console

confirm function

Asks a yes-or-no question; anything but a yes or a no gives default.

pub fn confirm(question: String, default: Bool) -> Bool uses Console

choose function

Prints question and options, numbered from 1, and gives the index (from 0) of the one chosen, or none for an answer that is not one.

pub fn choose(question: String, options: [String]) -> Int? uses Console