Terminal — essence

Printing for the program's reader, inspecting for its author, and reading its input.

At a glance

Declared: namespace Terminal
The namespace has no for type, so every member is a static, called as Terminal.print(…).
Modes: StreamWhere written text lands: #Output carries what the Program answers with, and #Error what it complains about.

Writing

print

on Terminal

static print<infer Value is Printable>(
	_ value: Value,
	to stream: Stream = #Output,
) -> {}

Prints a value and a newline, for the reader of the Program.

The value renders through its own toString. A String prints as its text, without the quotes a Literal is written with. The line goes to #Output unless to names a different Stream.

NameTypeDescription

_Valuethe value to print, rendered by its Printable conformance.

toStream = #Outputthe Stream the line lands on; #Output when it is left out.

write

on Terminal

static write(_ text: String, to stream: Stream = #Output) -> {}

Writes text exactly as given, with no newline and nothing added.

This is the primitive print is built on. The text goes to #Output unless to names a different Stream.

In a browser, where the host has no streams, the text lands on the console as a line instead. A console has no way to continue a line.

NameTypeDescription

_Stringthe text to write, unchanged.

toStream = #Outputthe Stream the text lands on; #Output when it is left out.

Inspecting

inspect

on Terminal

static inspect<infer Value>(_ value: Value) -> Value

Prints the structure of a value for the author of the Program, and answers with that value.

Strings print quoted, Cases print as their tags, and Records and Lists are laid out. The value needs no conformance. The answer is the value itself, so a call wraps any Expression without changing what that Expression evaluates to.

NameTypeDescription

_Valuethe value to inspect

Returns the value it was given, unchanged.

describe

on Terminal

static describe<infer Value>(_ value: Value) -> String

Answers the structure of a value as a String, for the author of the Program.

This is the rendering inspect writes. Strings are quoted, Cases print as their tags, and Records and Lists are laid out. The value needs no conformance.

NameTypeDescription

_Valuethe value to describe

Returns the structural rendering.

Example

expect Terminal.describe("Ada")::is("\"Ada\"")
expect Terminal.describe(Stream#Error)::is("Stream#Error")
expect Terminal.describe([1, 2])::is("[ 1, 2 ]")

Reading input

readLine

on Terminal

static readLine() -> Optional<String>

Answers the next line of the Program's input, or nothing at the end of it.

The line break is not part of the line. A line ends at \n, at \r, or at the \r\n a Windows host writes. The last line of an input that ends without a break is a line. A host with no input answers nothing, as write falls back to the console on a host with no stream.

Returns the next line, or nothing at the end of the input.

readAll

on Terminal

static readAll() -> String

Answers everything left in the Program's input, as one String.

The text is unchanged, so a break at the end of the input is part of the answer. A text that ends with a break has an empty last line when lines() splits it, which is what a trailing break means there. A host with no input answers the empty String.

Returns the rest of the input, unchanged.

ask

on Terminal

static ask(_ prompt: String) -> Optional<String>

Writes a prompt with no newline, then answers the next line of the input.

The prompt goes to #Output. The answer is readLine's, so it is nothing at the end of the input.

NameTypeDescription

_Stringthe prompt to write before reading

Returns the line that follows the prompt, or nothing at the end of the input.

Modes

Each mode below is a choice whose cases carry no payload. You pass one to a method to choose how the method works. Every mode has is, isNot and toString, and cases() on its name lists its cases, as in Stream.cases(). None of them is written out for a mode: Protocols says where each one comes from.

Stream

choice Stream {
	Output,
	Error,
}

Where written text lands: #Output carries what the Program answers with, and #Error what it complains about.

#Output is what a call that names no Stream gets.

Cases #Output, #Error

Taken by

Terminal.print(_:to:), default #Output
Terminal.write(_:to:), default #Output