package term

import "src.elv.sh/pkg/cli/term"

Package term provides functionality for working with terminals.

Index

Package Files

buffer.go buffer_builder.go event.go file_reader_unix.go read_rune.go reader.go reader_unix.go setup.go setup_unix.go term.go writer.go

Variables

var DotHere = struct{ x struct{} }{}

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

var ErrStopped = errors.New("stopped")

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

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 Sanitize

func Sanitize(in, out *os.File)

Sanitize sanitizes the terminal after an external command has executed.

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 SetupGlobal

func SetupGlobal() func()

SetupGlobal sets up the terminal for the entire Elvish session.

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 {
    // CurrentBuffer returns the current buffer.
    CurrentBuffer() *Buffer
    // ResetCurrentBuffer resets the current buffer.
    ResetCurrentBuffer()
    // CommitBuffer updates the terminal display to reflect current buffer.
    CommitBuffer(bufNoti, buf *Buffer, fullRefresh bool) error
    // ClearScreen clears the terminal screen and places the cursor at the top
    // left corner.
    ClearScreen()
}

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.

Package term imports 15 packages (graph) and is imported by 6 packages. Updated now.

.
Tools for package owners.