terminal

README

terminal

Package terminal is a vt10x terminal emulation backend, influenced largely by st, rxvt, xterm, and iTerm as reference. Use it for terminal muxing, a terminal emulation frontend, or wherever else you need terminal emulation.

Installation

go get j4k.co/terminal

New to Go? Have a look at how import paths work.

Documentation

Overview

Package terminal is a vt10x terminal emulation backend, influenced largely by st, rxvt, xterm, and iTerm as reference. Use it for terminal muxing, a terminal emulation frontend, or wherever else you need terminal emulation.

In development, but very usable.

Index

• type ChangeFlag
• type Color
  • func (c Color) ANSI() bool
• type ModeFlag
• type State
  • func (t *State) Cell(x, y int) (ch rune, fg Color, bg Color)
  • func (t *State) Changed(change ChangeFlag) bool
  • func (t *State) Cursor() (int, int)
  • func (t *State) CursorVisible() bool
  • func (t *State) Lock()
  • func (t *State) Mode(mode ModeFlag) bool
  • func (t *State) ScrollDown(orig, n int)
  • func (t *State) ScrollUp(orig, n int)
  • func (t *State) Title() string
  • func (t *State) Unlock()
• type VT
  • func Create(state *State, rc io.ReadCloser) (*VT, error)
  • func Start(state *State, cmd *exec.Cmd) (*VT, *os.File, error)
  • func (t *VT) Close() error
  • func (t *VT) File() *os.File
  • func (t *VT) Parse() error
  • func (t *VT) Resize(cols, rows int)
  • func (t *VT) Write(p []byte) (int, error)

Types

type ChangeFlag

type ChangeFlag uint32

ChangeFlag represents possible state changes of the terminal.

const (
	ChangedScreen ChangeFlag = 1 << iota
	ChangedTitle
)

Terminal changes to occur in VT.ReadState

type Color

type Color uint16

Color maps to the ANSI colors [0, 16) and the xterm colors [16, 256).

const (
	Black Color = iota
	Red
	Green
	Yellow
	Blue
	Magenta
	Cyan
	LightGrey
	DarkGrey
	LightRed
	LightGreen
	LightYellow
	LightBlue
	LightMagenta
	LightCyan
	White
)

ANSI color values

const (
	DefaultFG Color = 0xff80 + iota
	DefaultBG
)

Default colors are potentially distinct to allow for special behavior. For example, a transparent background. Otherwise, the simple case is to map default colors to another color.

func (Color) ANSI

func (c Color) ANSI() bool

ANSI returns true if Color is within [0, 16).

type ModeFlag

type ModeFlag uint32

ModeFlag represents various terminal mode states.

const (
	ModeWrap ModeFlag = 1 << iota
	ModeInsert
	ModeAppKeypad
	ModeAltScreen
	ModeCRLF
	ModeMouseButton
	ModeMouseMotion
	ModeReverse
	ModeKeyboardLock
	ModeHide
	ModeEcho
	ModeAppCursor
	ModeMouseSgr
	Mode8bit
	ModeBlink
	ModeFBlink
	ModeFocus
	ModeMouseX10
	ModeMouseMany
	ModeMouseMask = ModeMouseButton | ModeMouseMotion | ModeMouseX10 | ModeMouseMany
)

Terminal modes

type State

type State struct {
	DebugLogger *log.Logger
	// contains filtered or unexported fields
}

State represents the terminal emulation state. Use Lock/Unlock methods to synchronize data access with VT.

func (*State) Cell

func (t *State) Cell(x, y int) (ch rune, fg Color, bg Color)

Cell returns the character code, foreground color, and background color at position (x, y) relative to the top left of the terminal.

func (*State) Changed

func (t *State) Changed(change ChangeFlag) bool

Changed returns true if change has occured.

func (*State) Cursor

func (t *State) Cursor() (int, int)

Cursor returns the current position of the cursor.

func (*State) CursorVisible

func (t *State) CursorVisible() bool

CursorVisible returns the visible state of the cursor.

func (*State) Lock

func (t *State) Lock()

Lock locks the state object's mutex.

func (*State) Mode

func (t *State) Mode(mode ModeFlag) bool

Mode tests if mode is currently set.

func (*State) ScrollDown

func (t *State) ScrollDown(orig, n int)

func (*State) ScrollUp

func (t *State) ScrollUp(orig, n int)

func (*State) Title

func (t *State) Title() string

Title returns the current title set via the tty.

func (*State) Unlock

func (t *State) Unlock()

Unlock resets change flags and unlocks the state object's mutex.

type VT

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

VT represents the virtual terminal emulator.

func Create

func Create(state *State, rc io.ReadCloser) (*VT, error)

Create initializes a virtual terminal emulator with the target state and io.ReadCloser input.

func Start

func Start(state *State, cmd *exec.Cmd) (*VT, *os.File, error)

Start initializes a virtual terminal emulator with the target state and a new pty file by starting the *exec.Command. The returned *os.File is the pty file.

func (*VT) Close

func (t *VT) Close() error

Close closes the pty or io.ReadCloser.

func (*VT) File

func (t *VT) File() *os.File

File returns the pty file.

func (*VT) Parse

func (t *VT) Parse() error

Parse blocks on read on pty or io.ReadCloser, then parses sequences until buffer empties. State is locked as soon as first rune is read, and unlocked when buffer is empty. TODO: add tests for expected blocking behavior

func (*VT) Resize

func (t *VT) Resize(cols, rows int)

Resize reports new size to pty and updates state.

func (*VT) Write

func (t *VT) Write(p []byte) (int, error)

Write parses input and writes terminal changes to state.