emulator

Documentation

Overview

Package emulator provides a terminal emulator interface for Bubble Tea applications. It sits in between the bubbleterm bubble and a pty provider, handling terminal output, input, and resizing.

Index

• Constants
• Variables
• func ANSIEscape(fg Color, bg Color) []byte
• type ChangeReason
• type Color
  • func (c Color) Color() int
  • func (c Color) ColorRGB() (int, int, int)
  • func (c Color) ColorType() ColorType
  • func (c Color) Modes() []ColorMode
  • func (c Color) ResetMode(mode ColorMode) Color
  • func (c Color) ResetModes() Color
  • func (c Color) SetColor(color Color) Color
  • func (c Color) SetColorRGB(r int, g int, b int) Color
  • func (c Color) SetMode(mode ColorMode) Color
  • func (c Color) TestMode(mode ColorMode) bool
• type ColorMode
• type ColorType
• type EmittedFrame
• type Emulator
  • func New(cols, rows int) (*Emulator, error)
  • func (e *Emulator) Close() error
  • func (e *Emulator) FeedInput(data []byte)
  • func (e *Emulator) GetScreen() EmittedFrame
  • func (e *Emulator) ID() string
  • func (e *Emulator) IsProcessExited() bool
  • func (e *Emulator) Resize(cols, rows int) error
  • func (e *Emulator) SendKey(key string) error
  • func (e *Emulator) SendMouse(button int, x, y int, pressed bool) error
  • func (e *Emulator) SetFrameRate(fps int)
  • func (e *Emulator) SetOnExit(callback func(string))
  • func (e *Emulator) SetSize(cols, rows int) error
  • func (e *Emulator) StartCommand(cmd *exec.Cmd) error
  • func (e *Emulator) Write(data []byte) (int, error)
• type Line
  • func (l *Line) Append(text string, fg Color, bg Color)
  • func (l *Line) AppendRunes(runes []rune, fg Color, bg Color)
  • func (l *Line) Repeat(r rune, rep uint, fg Color, bg Color)
• type Pos
• type Region
  • func (r Region) Add(x, y int) Region
  • func (r Region) Clamp(rc Region) Region
• type StyledSpan
• type ViewFlag
• type ViewInt
• type ViewString

Constants

const (
	ColDefault Color = mask256color + 1 // outside the range
	ColBlack   Color = 0
	ColRed     Color = 1
	ColGreen   Color = 2
	ColYellow  Color = 3
	ColBlue    Color = 4
	ColMagenta Color = 5
	ColCyan    Color = 6
	ColWhite   Color = 7

	ModeBold      ColorMode = 1 << (0 + 24)
	ModeDim       ColorMode = 1 << (1 + 24)
	ModeItalic    ColorMode = 1 << (2 + 24)
	ModeUnderline ColorMode = 1 << (3 + 24)
	ModeBlink     ColorMode = 1 << (4 + 24) // or
	ModeReverse   ColorMode = 1 << (5 + 24)
	ModeInvisible ColorMode = 1 << (6 + 24)

	ColorType256 ColorType = 0
	ColorTypeRGB ColorType = 1
)

const (
	MMNone int = iota
	MMPress
	MMPressRelease
	MMPressReleaseMove
	MMPressReleaseMoveAll
)

Mouse modes for VIMouseMode

const (
	MEX10 int = iota
	MEUTF8
	MESGR
)

Mouse encodings for VIMouseEncoding

const ESC byte = 27

Variables

var (
	ErrPTYNotInitialized = errors.New("PTY not initialized")
	ErrInvalidSize       = errors.New("invalid terminal size")
)

var ColorModes = []ColorMode{
	ModeBold,
	ModeDim,
	ModeItalic,
	ModeUnderline,
	ModeBlink,
	ModeReverse,
	ModeInvisible,
}

var Colors8 = []Color{
	ColBlack,
	ColRed,
	ColGreen,
	ColYellow,
	ColBlue,
	ColMagenta,
	ColCyan,
	ColWhite,
}

Functions

func ANSIEscape

func ANSIEscape(fg Color, bg Color) []byte

ANSIEscape sequence to set this color

Types

type ChangeReason

type ChangeReason int

ChangeReason says what kind of change caused the region to change, for optimization etc.

const (
	// CRText means text is being printed normally.
	CRText ChangeReason = iota

	// CRClear means some area has been cleared
	CRClear

	// CRScroll means an area has been scrolled
	CRScroll

	// CRScreenSwitch means the screen has been switched between main and alt
	CRScreenSwitch

	// CRRedraw means the application requested a redraw with RedrawAll
	CRRedraw
)

type Color

type Color uint32

func (Color) Color

func (c Color) Color() int

func (Color) ColorRGB

func (c Color) ColorRGB() (int, int, int)

func (Color) ColorType

func (c Color) ColorType() ColorType

func (Color) Modes

func (c Color) Modes() []ColorMode

func (Color) ResetMode

func (c Color) ResetMode(mode ColorMode) Color

func (Color) ResetModes

func (c Color) ResetModes() Color

func (Color) SetColor

func (c Color) SetColor(color Color) Color

func (Color) SetColorRGB

func (c Color) SetColorRGB(r int, g int, b int) Color

func (Color) SetMode

func (c Color) SetMode(mode ColorMode) Color

func (Color) TestMode

func (c Color) TestMode(mode ColorMode) bool

type ColorMode

type ColorMode uint32

type ColorType

type ColorType uint32

type EmittedFrame

type EmittedFrame struct {
	Rows []string // Each row is a string with ANSI escape codes embedded
}

EmittedFrame represents a rendered frame from the terminal

type Emulator

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

Emulator is a headless terminal emulator that maintains internal state and renders to a framebuffer instead of directly to screen

func New

func New(cols, rows int) (*Emulator, error)

New creates a new headless terminal emulator

func (*Emulator) Close

func (e *Emulator) Close() error

Close shuts down the emulator

func (*Emulator) FeedInput

func (e *Emulator) FeedInput(data []byte)

FeedInput processes raw ANSI input (typically from PTY)

func (*Emulator) GetScreen

func (e *Emulator) GetScreen() EmittedFrame

GetScreen returns the current rendered screen as ANSI strings

func (*Emulator) ID

func (e *Emulator) ID() string

func (*Emulator) IsProcessExited

func (e *Emulator) IsProcessExited() bool

IsProcessExited returns true if the process has exited

func (*Emulator) Resize

func (e *Emulator) Resize(cols, rows int) error

Resize changes the terminal dimensions

func (*Emulator) SendKey

func (e *Emulator) SendKey(key string) error

SendKey sends a key event to the terminal

func (*Emulator) SendMouse

func (e *Emulator) SendMouse(button int, x, y int, pressed bool) error

SendMouse sends a mouse event to the terminal in SGR format

func (*Emulator) SetFrameRate

func (e *Emulator) SetFrameRate(fps int)

SetFrameRate sets the internal render loop framerate

func (*Emulator) SetOnExit

func (e *Emulator) SetOnExit(callback func(string))

SetOnExit sets a callback function that will be called when the process exits

func (*Emulator) SetSize

func (e *Emulator) SetSize(cols, rows int) error

SetSize sets the terminal size (same as Resize for now)

func (*Emulator) StartCommand

func (e *Emulator) StartCommand(cmd *exec.Cmd) error

StartCommand starts a command in the terminal

func (*Emulator) Write

func (e *Emulator) Write(data []byte) (int, error)

Write sends data to the PTY (keyboard input)

type Line

type Line struct {
	Spans []StyledSpan
	Text  []rune
	Width uint32
}

Line holds a list of text blocks with associated colors

func (*Line) Append

func (l *Line) Append(text string, fg Color, bg Color)

func (*Line) AppendRunes

func (l *Line) AppendRunes(runes []rune, fg Color, bg Color)

func (*Line) Repeat

func (l *Line) Repeat(r rune, rep uint, fg Color, bg Color)

type Pos

type Pos struct {
	X int
	Y int
}

Pos represents a position on the screen

type Region

type Region struct {
	X, Y, X2, Y2 int
}

Region is a non-inclusive rectangle on the screen. X2 and Y2 are not included in the region.

func (Region) Add

func (r Region) Add(x, y int) Region

func (Region) Clamp

func (r Region) Clamp(rc Region) Region

type StyledSpan

type StyledSpan struct {
	FG, BG Color
	// todo: should distinguish between width of characters on screen
	// and length in terms of number of runes
	Width uint32
}

StyledSpan has style colors, and a width

type ViewFlag

type ViewFlag int

ViewFlag is an enum of boolean flags on a terminal

const (
	VFBlinkCursor ViewFlag = iota
	VFShowCursor
	VFReportFocus
	VFBracketedPaste
)

type ViewInt

type ViewInt int

ViewInt is an enum of integer settings on a terminal

const (
	VIMouseMode ViewInt = iota
	VIMouseEncoding
)

type ViewString

type ViewString int

ViewString is an enum of string settings on a terminal

const (
	VSWindowTitle ViewString = iota
	VSCurrentDirectory
	VSCurrentFile
)