term

Terminals and consoles: where human-readable output goes, and how it is styled, measured, captured and silenced.

Style options

The styling functions -- print, text and Style -- all accept the same keyword options:

Name	Type	Description
`fg`	`Sym`\|`Int`\|`Array`\|`Tuple`?	Foreground color
`bg`	`Sym`\|`Int`\|`Array`\|`Tuple`?	Background color
`bold`	`Bool`\|`Sym`?	Enables bold
`dim`	`Bool`\|`Sym`?	Enables dim intensity
`italic`	`Bool`\|`Sym`?	Enables italics
`underline`	`Bool`\|`Sym`?	Enables underlining
`blink`	`Bool`\|`Sym`?	Enables blinking
`reverse`	`Bool`\|`Sym`?	Reverses foreground and background
`hidden`	`Bool`\|`Sym`?	Hides text
`strikethrough`	`Bool`\|`Sym`?	Enables strikethrough

Attribute options accept true or :INHERIT:. false is not accepted.

Named colors are :BLACK:, :RED:, :GREEN:, :YELLOW:, :BLUE:, :MAGENTA:, :CYAN: and :WHITE:. Prefix the name with BRIGHT_ for a bright color, such as :BRIGHT_RED:. An Int selects a 256-color palette index, and a three-integer array or tuple an RGB color; numeric values must be 0 through 255. Color options also accept :INHERIT:.

A ValueError is raised for an attribute option whose value is neither true nor :INHERIT:, an unknown color name, a numeric value out of range, or an RGB value that is not three integers.

Types

Type	Description
`Console`	The console interface: where human-readable output goes.
`Geometry`	The dimensions of a terminal-backed `Console`.
`SinkConsole`	A `Console` over an ordinary sink.
`Style`	Reusable terminal style settings.
`Text`	Validated terminal presentation.

Functions

`capture[R] console block … -> R`

Runs a block with console installed as the ambient console, then flushes it and restores the previous one.

The override is inherited by all strands spawned inside the call.

Captured lines keep their terminator, since the capture reproduces what was written rather than reinterpreting it:

let lines = []
term.capture $lines do
  echo "Hello, Alice!"
assert_eq $lines ["Hello, Alice!\n"]

Put a prechomp in front of the sink to strip them:

let lines = []
term.capture (lines.prechomp()) do
  echo "Hello, Alice!"
assert_eq $lines ["Hello, Alice!"]

The scope always ends with a flush, so an unterminated print still arrives -- with no terminator, because none was written:

let out = []
term.capture $out do print hi
assert_eq $out ["hi"]

Parameters

Name	Type	Description
`console`	`(Console \| Sink[Value])`	Destination to install. A plain sink is wrapped in a `SinkConsole` using the requested `mode:`.
`block`	`(() -> R)`	Block to run.
`:mode?`	`(:LINE: \| :CHUNK:)`	Output mode when `console` is a plain sink. Defaults to `:LINE:`.

Errors

Exception	Condition
`ValueError`	`mode:` is given when `console` is already a `Console`, which fixes its own output mode

`echo ...args`

Prints arguments separated by spaces, followed by a newline.

Ordinary values are sanitized; Text arguments retain their styling, as does a FmtValue bound to one -- see Formatting. A Fmt is expanded segment by segment, so styling interpolated into one survives -- see Sequences.

Parameters

Name	Type	Description
`...args`		Values converted with `verbatim` and written safely.

Example

echo status: ready count: 3

`mute[R] block -> R`

Runs a block with default console-bound output silenced: echo, print, unredirected program stderr, and the rest.

Parameters

Name	Type	Description
`block`	`(() -> R)`	Block to run.

Example

# Nothing from this reaches the terminal.
mute do run printf "this will not be printed"

`output() -> Console`

Returns the current output console.

This is the one installed by an enclosing capture, or console if there is none, and it is where echo, print, diagnostics and unredirected child process output go.

`preformat text -> Text`

Validates existing ANSI-styled text.

SGR styling is canonicalized; other terminal controls, hyperlinks included, are removed.

Parameters

Name	Type	Description
`text`	`Str`	ANSI-formatted input.

Example

let formatted = preformat input
echo $formatted

`print ...args`

Prints concatenated values without separators or a trailing newline.

Also accepts the style options, for which :INHERIT: is a no-op here. Styling is omitted when stderr is not a terminal.

Parameters

Name	Type	Description
`...args`		Values converted to display strings.

Example

print "status: " ready fg: :GREEN: bold: true

`sub block … -> Str`

Runs a block and returns its console output as a string.

The console counterpart to proc.sub, which captures a strand's implicit output stream instead. Verbatim output is captured, which must be valid UTF-8.

Parameters

Name	Type	Description
`block`	`(() -> Value)`	Block to run.
`:chomp?`	`Bool`	Strip one trailing line ending, LF or CRLF. True by default.
`:can_style?`	`Bool`	Keep ANSI styling. False by default.

Example

let greeting = term.sub do greet Alice
assert_eq $greeting "Hello, Alice!"

`text ...args -> Text`

Constructs terminal text from concatenated values, styled or not.

Also accepts the style options, for which :INHERIT: leaves a setting to the surrounding style.

This is the general entry point for Text: styling is optional, and a plain text value is still what measures itself in terminal cells. For a reusable style with no text of its own, construct a Style directly.

Parameters

Name	Type	Description
`...args`		Values converted to display strings.

Example

let warning = text Warning fg: :YELLOW: bold: true
echo $warning

# Unstyled, for its measurement and layout methods.
let column = text $name
echo $column.clip(20, suffix: "…")

Values

`console`

The host Console, supplied by the application running Do, which may be taken over by an extension such as progress.

Unlike output(), it is not intercepted by an enclosing capture.

`default`

A Console that forwards every operation to whatever output() currently resolves to, resolved fresh on each call rather than once.

Bound as the main strand's implicit output when stdout is a terminal, so unnamed program output keeps following capture and progress takeover for the life of the process -- see Terminal output.