term

Documentation

Overview

Package term holds the canonical terminal-capability primitives: the colour-mode ladder, the TTY check (adr-49, brief invariant 13), and the window size a question is drawn at (Size, through golang.org/x/term). It is deliberately banner-independent — the bare-invocation banner (itd-112) is its first consumer and the styled grill (itd-110) its declared second; a surface that wants decoration resolves its mode here rather than minting a parallel copy.

Index

• Variables
• func IsTerminal(f *os.File) bool
• func ReadHidden(in *os.File, out io.Writer) (line string, err error)
• func Size(f *os.File, getenv func(string) string) (cols, rows int)
• func UTF8Locale(getenv func(string) string) bool
• type ColorMode
  • func ResolveColorMode(getenv func(string) string, noColorFlag bool) ColorMode
• type Hooks
• type RawSession
  • func StartRaw(f *os.File, h Hooks) (*RawSession, error)
  • func (s *RawSession) Guard()
  • func (s *RawSession) Restore() error
  • func (s *RawSession) Suspend() error

Variables

var ErrInterrupted = errors.New("interrupted")

ErrInterrupted is Ctrl-C during a hidden read: the terminal is restored, a newline written, and nothing is returned. A front door exits 130 on it, as a shell reports an interrupted command.

Functions

func IsTerminal

func IsTerminal(f *os.File) bool

IsTerminal reports whether f is a terminal: the kernel answers a termios get on its descriptor, which is how isatty(3) decides. A character-device test is not enough, because /dev/null is a character device, and stdin redirected from it (or a closed fd 0, which the Go runtime reopens on /dev/null) would read as a person at a terminal. This is the one canonical check; no call site hand-rolls a Stat/ModeCharDevice test.

The descriptor is reached through SyscallConn rather than Fd, so the file keeps its non-blocking mode. A platform without a termios probe here answers false: a consent gate then declines as having no terminal to ask at.

func ReadHidden

func ReadHidden(in *os.File, out io.Writer) (line string, err error)

ReadHidden reads one line, a key pasted at the terminal, without echo (spc-2610031241482088, "The key on hidden input"). It is golang.org/x/term's password read, its line reader with echo off, run inside a RawSession, so the terminal is touched in one way only and restored on every exit: a return, an error, a panic (the deferred Guard), Ctrl-C (which raw mode delivers as a byte, and which ends the read with ErrInterrupted), and SIGINT, SIGTERM or SIGHUP sent from outside (the session's own handler). Enter on an empty line, or Ctrl-D, returns "" and no error: the caller refuses an empty answer. out is where the read writes the line ending Enter leaves; nothing of what is typed is ever written to it.

func Size

func Size(f *os.File, getenv func(string) string) (cols, rows int)

Size is the window f is a terminal for, in columns and rows, read through golang.org/x/term before each question so a resize between questions is honoured (spc-2610030911534855). When f answers no size (it is not a terminal, or the terminal reports zero), the width is COLUMNS when that is a positive whole number and 80 otherwise, and the height is LINES, else 24.

The descriptor is reached through SyscallConn rather than Fd, as IsTerminal does, so the file keeps its non-blocking mode.

func UTF8Locale

func UTF8Locale(getenv func(string) string) bool

UTF8Locale reports whether the locale advertises UTF-8. Block art (half and shade blocks) assumes UTF-8; without it a decorated surface renders its text lines only. Checked in POSIX order: LC_ALL, LC_CTYPE, LANG.

Types

type ColorMode

type ColorMode int

ColorMode is one rung of the colour ladder.

const (
	// Mono means no colour at all: decoration degrades to plain glyphs,
	// never to blank output.
	Mono ColorMode = iota
	// Ansi16 is the 16-colour floor for colour-capable terminals.
	Ansi16
	// Ansi256 is the xterm-256 palette.
	Ansi256
	// TrueColor is 24-bit colour, rendered straight from hex.
	TrueColor
)

func ResolveColorMode

func ResolveColorMode(getenv func(string) string, noColorFlag bool) ColorMode

ResolveColorMode resolves the ladder for stdout decoration. Precedence, descending: the surface's --no-color flag; the NO_COLOR convention (present AND non-empty — presence alone does not count); TERM dumb or unset (cron, bare containers) forces Mono even when COLORTERM leaks through a multiplexer; COLORTERM truecolor/24bit; a 256color TERM; else the 16-colour floor.

type Hooks

type Hooks struct {
	Resized   func()
	Continued func()
}

Hooks are what a session calls on its signal goroutine: Resized on SIGWINCH, and Continued on a SIGCONT after raw mode is entered again. Either may be nil. A hook that panics restores the terminal before the panic goes on.

type RawSession

type RawSession struct {
	// contains filtered or unexported fields
}

RawSession is one stretch of raw mode on a terminal (spc-2610030911534855, "The answer loop"), and the only place abcd touches termios: no call site handles the terminal's modes itself.

The terminal is restored on every exit. Restore is idempotent (sync.Once) and is reached from:

• the caller's deferred Guard, on every return, an error included;
• Guard again on a panic, which restores and then panics on with the same value;
• the caller, on Ctrl-C, which raw mode delivers as the byte 0x03 because it clears ISIG;
• the session's own handler for SIGINT, SIGTERM and SIGHUP sent from outside, which restores and then re-raises the signal with its default action, so the process ends as that signal ends it. A signal the process was started ignoring (nohup's SIGHUP) stays ignored.

Suspend is Ctrl-Z (0x1a under raw mode): restore, stop with SIGTSTP, and on SIGCONT enter raw mode again. A SIGCONT after a stop from outside enters raw mode again too. SIGWINCH and SIGCONT reach the caller through Hooks, run on the session's signal goroutine, so a caller that draws from a hook serialises the drawing itself.

func StartRaw

func StartRaw(f *os.File, h Hooks) (*RawSession, error)

StartRaw puts f, the terminal a person answers at, into raw mode and returns the session that restores it. It refuses a descriptor that is not a terminal, or a terminal that refuses raw mode, and then leaves nothing behind: no signal registration and no goroutine.

The signal handler is registered before raw mode is entered, so no signal can find the terminal raw and unwatched.

func (*RawSession) Guard

func (s *RawSession) Guard()

Guard is the caller's deferred restore: `defer s.Guard()` directly, so its recover sees the caller's panic. It restores, then panics on with the recovered value, if there was one.

func (*RawSession) Restore

func (s *RawSession) Restore() error

Restore puts the terminal back as StartRaw found it and ends the session: the signal registration is stopped and the signal goroutine told to end. Only the first call does anything; every later one returns nil, so a late call never undoes a change made after the session ended.

func (*RawSession) Suspend

func (s *RawSession) Suspend() error

Suspend is Ctrl-Z: it restores the terminal, stops the process group with SIGTSTP as the terminal's own Ctrl-Z would, and once continued enters raw mode again. The caller redraws after it returns. On an ended session it does nothing.