Console

The console interface: where human-readable output goes.

A console is a write-only Io. Besides write, it reports how output should look on its device and makes buffered output visible with flush. (put), write_all and the rest come from Io, so a function that accepts an Io can write to a console.

Console is abstract. The implementations provided are the host console (term.console) and IoConsole. The host console has no close.

Subclassing

Do classes may subclass Console to implement one. Supply write and flush; the capability members come from the base:

Console	`can_style`	`is_tty`	`geometry()`
`Console` (the base)	`false`	`false`	no dimensions
Host (`term.console`)	styling policy	usable terminal	the terminal's size
`IoConsole`	as constructed	`false`	no dimensions

class Recorder: term.Console
  pub field lines

  def (init) self
    term.Console.(init) $self
    self.lines = []

  pub def write self *data
    let line = ""
    for piece = data
      line = "$line$piece"
    self.lines.push $line
    line.len

  pub def flush _self
    nil

let recorder = Recorder()
term.capture $recorder do echo hello
assert_eq $recorder.lines ["hello\n"]

Override line_ending to change what echo appends; the base reports "\n".

A console whose own methods call echo does not recurse: while a write is being dispatched, console output falls through to the host.

Inherits from: io.Io

Constructor

`Console()`

Initializes the base console. A subclass calls this from its own (init).

Fields

can_style @ Bool ^[get]

Whether the console supports ANSI styling.

is_tty @ Bool ^[get]

Whether the console is usable as a terminal.

This is the determinative test, unlike geometry(), whose dimensions may be unknown for a real terminal that cannot report its size.

The host console reports false while an extension such as progress has taken the terminal over, even though geometry() still reports the terminal's size.

line_ending @ (Str | Bin) ^[get]

The line ending appropriate to this console's device.

The console owns the policy but does not apply it: echo passes this to write as the last piece of the line. It is read once, when the console is installed, so changing it afterward does not affect an installation already in effect.

term.console.write done $term.console.line_ending

Every built-in console reports "\n": a console is a terminal-shaped stream rather than a file, and echo writes LF on Windows too. A subclass may report something else, and echo will honor it. For a file's native ending use shell.line_ending instead.

writable @ Bool ^[get]

Whether the console writes, which the base reports as true.

Methods

`flush()`

Makes buffered output visible.

`geometry() -> Geometry`

Returns the console's dimensions.

A stream has neither dimension, and a real terminal may not report one or both, so each is advisory. Use is_tty to test for a real terminal.

Example

let width = (term.console.geometry().cols || 80)

`write *data -> Int`

Writes bytes verbatim.

A caller that wants a terminated line passes the text and its terminator to one write rather than making two calls -- concurrent strands writing to the same console would otherwise interleave between the text and its terminator.

Parameters

Name	Type	Description
`*data`	`(Str \| Bin)`	Pieces to write, in order.

Returns

The number of bytes written.

Example

term.console.write b"\x1b[2K" "\r"