Documentation
¶
Overview ¶
Package vt is a terminal screen model: a byte stream in the xterm control sequence grammar goes in, a grid of cells, a cursor and a bounded scrollback come out. It is pure Go with no dependency, so the model a terminal widget renders is natively testable.
Safe by construction ¶
A Screen has no output channel: it cannot answer a device-status or device-attributes query, report a window size, echo a title, or say anything else that would reach a shell's input as if the user had typed it. Every string sequence (OSC, DCS, SOS, PM, APC) is consumed and discarded without being buffered: no OSC 52 clipboard write, no OSC 8 hyperlink, no title. What it obeys is layout and colour only: the C0 controls BS HT LF VT FF CR, the ESC functions IND NEL RI DECSC DECRC RIS, and the CSI functions CUU CUD CUF CUB CNL CPL CHA HPA CUP HVP VPA ED EL IL DL ICH DCH ECH SU SD DECSTBM SCOSC SCORC SGR, plus the private modes DECAWM (7) and DECTCEM (25). C1 controls are never obeyed: written as UTF-8 (U+0080-U+009F) they are dropped, and as raw 8-bit bytes they are invalid UTF-8, shown as U+FFFD. Bidi and other format characters (Unicode Cf, e.g. U+202E) are dropped too. CAN and SUB abort a sequence.
Every quantity is bounded: the grid size, the scrollback ring, a sequence's parameter count and values, and the length of a string sequence the parser swallows before it gives up and returns to text.
Reference: XTerm Control Sequences (invisible-island.net/xterm/ctlseqs).
Limitations: every rune occupies one cell (no East Asian wide cells), combining marks and format characters are dropped, there is no alternate screen and no reflow on resize.
Index ¶
- Constants
- type Attr
- type Cell
- type Color
- type Pos
- type Screen
- func (s *Screen) ClearScrollback()
- func (s *Screen) Cursor() (x, y int, visible bool)
- func (s *Screen) Line(i int) []Cell
- func (s *Screen) Lines() int
- func (s *Screen) Resize(cols, rows int)
- func (s *Screen) Row(y int) []Cell
- func (s *Screen) ScrollbackLen() int
- func (s *Screen) SetNewlineMode(on bool)
- func (s *Screen) Size() (cols, rows int)
- func (s *Screen) Text(from, to Pos) string
- func (s *Screen) Version() uint64
- func (s *Screen) Write(p []byte) (int, error)
- func (s *Screen) WriteString(str string) (int, error)
Constants ¶
const ( MaxCols = 1024 MaxRows = 512 // MaxScrollback bounds the ring New accepts. MaxScrollback = 100000 )
Bounds on what a stream can make the model hold.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cell ¶
Cell is one character cell. A zero Rune is a blank (nothing was written there); FG and BG are the colours the cell was written or erased with.
type Color ¶
type Color uint32
Color is a cell colour: the terminal's default, one of the 256 indexed colours, or a 24-bit RGB value. The zero value is the default colour, so a zero Cell is a blank cell in the default colours.
const Default Color = 0
Default is the terminal's default foreground or background colour.
func Indexed ¶
Indexed returns indexed colour n: 0-7 the standard colours, 8-15 their bright forms, 16-231 the 6x6x6 cube, 232-255 the grey ramp.
type Pos ¶
type Pos struct {
Line, Col int
}
Pos addresses a cell in the whole history: Line counts from the oldest scrollback line (0) through the visible screen, Col from the left (0).
type Screen ¶
type Screen struct {
// contains filtered or unexported fields
}
Screen is the terminal model. The zero value is not usable; call New.
func New ¶
New returns a cols x rows screen keeping up to scrollback lines of history. Sizes are clamped to [1, MaxCols] x [1, MaxRows] and the scrollback to [0, MaxScrollback].
func (*Screen) ClearScrollback ¶
func (s *Screen) ClearScrollback()
ClearScrollback drops the history.
func (*Screen) Cursor ¶
Cursor returns the cursor's position on the visible grid and whether it is shown.
func (*Screen) Line ¶
Line returns line i of the whole history (see Pos), nil when out of range. Scrollback lines keep the width they had when they scrolled off.
func (*Screen) Resize ¶
Resize reshapes the grid, keeping the top-left cells that still fit. When the grid loses rows below the cursor's, the top rows move into the scrollback so the cursor's line stays visible. The scroll region resets to the whole grid.
func (*Screen) Row ¶
Row returns visible row y (nil when out of range). The slice is the model's own: read it, do not keep or modify it.
func (*Screen) ScrollbackLen ¶
ScrollbackLen is the number of history lines above the visible grid.
func (*Screen) SetNewlineMode ¶
SetNewlineMode makes LF also return the carriage (what a terminal with LNM set, or xterm.js's convertEol, does), for output written with bare "\n" line ends.
func (*Screen) Text ¶
Text returns the text between from and to (inclusive, in either order): blanks become spaces, trailing blanks of each line are dropped, lines are joined with "\n". It is what a selection copies.
func (*Screen) Version ¶
Version changes every time Write or Resize changes the model, so a view can skip a frame when nothing moved.
Source Files