term

package
v0.18.0-rc2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 19, 2022 License: BSD-2-Clause Imports: 16 Imported by: 0

Documentation

Overview

Package term provides functionality for working with terminals.

Index

Constants

This section is empty.

Variables

View Source 
var DotHere = struct{ x struct{} }{}

DotHere is a special argument to MarkLines to mark the position of the dot.

View Source 
var ErrStopped = errors.New("stopped")

ErrStopped is returned by Reader when Close is called during a ReadEvent or ReadRawEvent method.

Functions

func BuffersHeight 

func BuffersHeight(bufs ...*Buffer) (l int)

BuffersHeight computes the combined height of a number of buffers.

func CellsWidth 

func CellsWidth(cs []Cell) int

CellsWidth returns the total width of a Cell slice.

func CompareCells 

func CompareCells(r1, r2 []Cell) (bool, int)

CompareCells returns whether two Cell slices are equal, and when they are not, the first index at which they differ.

func IsReadErrorRecoverable 

func IsReadErrorRecoverable(err error) bool

IsReadErrorRecoverable returns whether an error returned by Reader is recoverable.

func Setup 

func Setup(in, out *os.File) (func() error, error)

Setup sets up the terminal so that it is suitable for the Reader and Writer to use. It returns a function that can be used to restore the original terminal config.

func SetupForEval added in v0.18.0 

func SetupForEval(in, out *os.File) func()

SetupForEval sets up the terminal for evaluating Elvish code. It returns a function to call after the evaluation finishes.

Types

type Buffer 

type Buffer struct {
	Width int
	// Lines the content of the buffer.
	Lines Lines
	// Dot is what the user perceives as the cursor.
	Dot Pos
}

Buffer reflects a continuous range of lines on the terminal.

The Unix terminal API provides only awkward ways of querying the terminal Buffer, so we keep an internal reflection and do one-way synchronizations (Buffer -> terminal, and not the other way around). This requires us to exactly match the terminal's idea of the width of characters (wcwidth) and where to insert soft carriage returns, so there could be bugs.

func NewBuffer 

func NewBuffer(width int) *Buffer

NewBuffer builds a new buffer, with one empty line.

func (*Buffer) Buffer 

func (b *Buffer) Buffer() *Buffer

Buffer returns itself.

func (*Buffer) Col 

func (b *Buffer) Col() int

Col returns the column the cursor is in.

func (*Buffer) Cursor 

func (b *Buffer) Cursor() Pos

Cursor returns the current position of the cursor.

func (*Buffer) Extend 

func (b *Buffer) Extend(b2 *Buffer, moveDot bool)

Extend adds all lines from b2 to the bottom of this buffer. If moveDot is true, the dot is updated to match the dot of b2.

func (*Buffer) ExtendRight 

func (b *Buffer) ExtendRight(b2 *Buffer)

ExtendRight extends bb to the right. It pads each line in b to be b.Width and appends the corresponding line in b2 to it, making new lines when b2 has more lines than bb.

func (*Buffer) TTYString 

func (b *Buffer) TTYString() string

TTYString returns a string for representing the buffer on the terminal.

func (*Buffer) TrimToLines 

func (b *Buffer) TrimToLines(low, high int)

TrimToLines trims a buffer to the lines [low, high).

type BufferBuilder 

type BufferBuilder struct {
	Width, Col, Indent int
	// EagerWrap controls whether to wrap line as soon as the cursor reaches the
	// right edge of the terminal. This is not often desirable as it creates
	// unneessary line breaks, but is is useful when echoing the user input.
	// will otherwise
	EagerWrap bool
	// Lines the content of the buffer.
	Lines Lines
	// Dot is what the user perceives as the cursor.
	Dot Pos
}

BufferBuilder supports building of Buffer.

func NewBufferBuilder 

func NewBufferBuilder(width int) *BufferBuilder

NewBufferBuilder makes a new BufferBuilder, initially with one empty line.

func (*BufferBuilder) Buffer 

func (bb *BufferBuilder) Buffer() *Buffer

Buffer returns a Buffer built by the BufferBuilder.

func (*BufferBuilder) Cursor 

func (bb *BufferBuilder) Cursor() Pos

func (*BufferBuilder) MarkLines 

func (bb *BufferBuilder) MarkLines(args ...interface{}) *BufferBuilder

MarkLines is like calling WriteStyled with ui.MarkLines(args...), but accepts an additional special parameter DotHere to mark the position of the dot.

func (*BufferBuilder) Newline 

func (bb *BufferBuilder) Newline() *BufferBuilder

Newline starts a newline.

func (*BufferBuilder) SetDotHere 

func (bb *BufferBuilder) SetDotHere() *BufferBuilder

func (*BufferBuilder) SetEagerWrap 

func (bb *BufferBuilder) SetEagerWrap(v bool) *BufferBuilder

func (*BufferBuilder) SetIndent 

func (bb *BufferBuilder) SetIndent(indent int) *BufferBuilder

func (*BufferBuilder) Write 

func (bb *BufferBuilder) Write(text string, ts ...ui.Styling) *BufferBuilder

Write is equivalent to calling WriteStyled with ui.T(text, style...).

func (*BufferBuilder) WriteRuneSGR 

func (bb *BufferBuilder) WriteRuneSGR(r rune, style string) *BufferBuilder

WriteRuneSGR writes a single rune to a buffer with an SGR style, wrapping the line when needed. If the rune is a control character, it will be written using the caret notation (like ^X) and gets the additional style of styleForControlChar.

func (*BufferBuilder) WriteSpaces 

func (bb *BufferBuilder) WriteSpaces(w int, ts ...ui.Styling) *BufferBuilder

WriteSpaces writes w spaces with the given styles.

func (*BufferBuilder) WriteStringSGR 

func (bb *BufferBuilder) WriteStringSGR(text, style string) *BufferBuilder

WriteStringSGR writes a string to a buffer with a SGR style.

func (*BufferBuilder) WriteStyled 

func (bb *BufferBuilder) WriteStyled(t ui.Text) *BufferBuilder

WriteStyled writes a styled text.

type Cell 

type Cell struct {
	Text  string
	Style string
}

Cell is an indivisible unit on the screen. It is not necessarily 1 column wide.

type CursorPosition 

type CursorPosition Pos

CursorPosition represents a report of the current cursor position from the terminal driver, usually as a response from a cursor position request.

type Event 

type Event interface {
	// contains filtered or unexported methods
}

Event represents an event that can be read from the terminal.

type FatalErrorEvent 

type FatalErrorEvent struct{ Err error }

FatalErrorEvent represents an error that affects the Reader's ability to continue reading events. After sending a FatalError, the Reader makes no more attempts at continuing to read events and wait for Stop to be called.

type KeyEvent 

type KeyEvent ui.Key

KeyEvent represents a key press.

func K 

func K(r rune, mods ...ui.Mod) KeyEvent

K constructs a new KeyEvent.

type Line 

type Line []Cell

Line stores a single line.

type Lines 

type Lines [][]Cell

Lines stores multiple lines.

type MouseEvent 

type MouseEvent struct {
	Pos
	Down bool
	// Number of the Button, 0-based. -1 for unknown.
	Button int
	Mod    ui.Mod
}

MouseEvent represents a mouse event (either pressing or releasing).

type NonfatalErrorEvent 

type NonfatalErrorEvent struct{ Err error }

NonfatalErrorEvent represents an error that can be gradually recovered. After sending a NonfatalError, the Reader will continue to read events. Note that one anamoly in the terminal might cause multiple NonfatalError events to be sent.

type PasteSetting 

type PasteSetting bool

PasteSetting indicates the start or finish of pasted text.

type Pos 

type Pos struct {
	Line, Col int
}

Pos is a line/column position.

type Reader 

type Reader interface {
	// ReadEvent reads a single event from the terminal.
	ReadEvent() (Event, error)
	// ReadRawEvent reads a single raw event from the terminal. The concept of
	// raw events is applicable where terminal events are represented as escape
	// sequences sequences, such as most modern Unix terminal emulators. If
	// the concept is not applicable, such as in the Windows console, it is
	// equivalent to ReadEvent.
	ReadRawEvent() (Event, error)
	// Close releases resources associated with the Reader. Any outstanding
	// ReadEvent or ReadRawEvent call will be aborted, returning ErrStopped.
	Close()
}

Reader reads events from the terminal.

func NewReader 

func NewReader(f *os.File) Reader

NewReader creates a new Reader on the given terminal file.

TODO: NewReader should return an error as well. Right now failure to initialize Reader panics.

type Writer 

type Writer interface {
	// Buffer returns the current buffer.
	Buffer() *Buffer
	// ResetBuffer resets the current buffer.
	ResetBuffer()
	// UpdateBuffer updates the terminal display to reflect current buffer.
	UpdateBuffer(bufNoti, buf *Buffer, fullRefresh bool) error
	// ClearScreen clears the terminal screen and places the cursor at the top
	// left corner.
	ClearScreen()
	// ShowCursor shows the cursor.
	ShowCursor()
	// HideCursor hides the cursor.
	HideCursor()
}

Writer represents the output to a terminal.

func NewWriter 

func NewWriter(f io.Writer) Writer

NewWriter returns a Writer that writes VT100 sequences to the given io.Writer.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.