vterm

package module
v0.0.0-...-91b0290 Latest Latest
Warning

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

Go to latest
Published: Aug 17, 2020 License: MIT Imports: 4 Imported by: 1

README

Package vterm

Package vterm wraps the libvterm C library to provide a virtual terminal implementation.

The Go API matches closely to the original C API and constants are interchangeable. Cell, Property and Attributes are in native Go format and converted when calling libvterm, which increases readability and reduces the number of cgo calls (but might be slower).

The Go API supports hooking output callback and VTermScreen callbacks.

Example

vt := vterm.New(80, 25)
defer vt.Free()

vt.ScreenCallback(vterm.ScreenCallback{
	Bell: func(data interface{}) bool {
		fmt.Println("Bell!!")
		return true
	},
}, nil)

// ESC [1;31m sets the foreground color to bright red
vt.Write([]byte("\x1b[1;31m呼呼呼~"))

c := vt.CellAt(0, 0)
fmt.Printf("Char: %c\n", c.Chars[0])

fr, fg, fb := vt.ConvertRGB(&c.Foreground)
fmt.Printf("Foreground: R%d G%d B%d\n", fr, fg, fb)
br, bg, bb := vt.ConvertRGB(&c.Background)
fmt.Printf("Background: R%d G%d B%d\n", br, bg, bb)

// Rings the bell!
vt.Write([]byte("\x07"))

Most of the VTermState object and Parser callbacks tend to be internal and are not exposed by the Go API. (There are functions about palettes and colors however)

The VTermScreen and VTermState objects are not separated from the VTerm object; All related methods has *VTerm as the receiver.

License

MIT (applies to all Go source, and go_*.h, go_*.c files by me)

libvterm(modified) - MIT

The original libvterm 0.1.3 included is modified; dynamic arrays are changed to alloca() and some NULL checks are added. Get the original here: http://www.leonerd.org.uk/code/libvterm/

Documentation

Overview

Package vterm wraps the libvterm C library to provide a virtual terminal implementation.

The Go API matches closely to the original C API and constants are interchangeable. However, Cell, Properties and Attributes are in native Go format and converted when calling libvterm, which increases readability and reduces the number of cgo calls (but might be slower).

The Go API supports hooking output callback and VTermScreen callbacks.

libvterm consists of several components: VTerm, VTermState, VTermScreen and a Parser. The VTerm has a State and a Screen object and the State has a built-in Parser. Most of the VTermState object and Parser callbacks tend to be internal and are not exposed by the Go API. (There are functions about palettes and colors however)

The VTermScreen and VTermState objects are not separated from the VTerm object; All related methods has *VTerm as the receiver.

The original libvterm included is modified; dynamic arrays are changed to alloca() and some NULL checks are added. Get the original here: http://www.leonerd.org.uk/code/libvterm/

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Cell

type Cell struct {
	Chars                  []rune    // Runes inside the cell (may be more than one)
	Width                  int       // The width of the cell on the vterm (1=one cell, 2=spans across 2 cells, etc.)
	Attrs                  CellAttrs // Attribues of the cell
	Foreground, Background Color     // Colors in the cell
}

Cell describes a screen cell

type CellAttrs

type CellAttrs struct {
	Underline    Underline // int(Underline), Has underline?/Underline Type
	Bold         bool      // bool, Uses bold(and bright) text?
	Italic       bool      // bool, Is italic?
	Blink        bool      // bool, Is blinking?
	Reverse      bool      // bool, Has background/foreground colors reversed?
	Strike       bool      // bool, Has strikeline?
	Font         int       // int, Uses alternative font? / Font number 0 to 9
	DoubleHeight int       // DECDHL double-height line flag (0=none 1=top 2=bottom)
	DoubleWidth  bool      // Is the cell on a double-width line as in DECDWL or DECDHL
}

CellAttrs describes the attributes of a screen cell

type Color

type Color C.VTermColor

Color is a VTerm color instance; it can be a palette color or a RGB one

func NewColorIndexed

func NewColorIndexed(pat uint8) *Color

NewColorIndexed constructs a new Color using the internal/standard palette.

func NewColorRGB

func NewColorRGB(r, g, b uint8) *Color

NewColorRGB constructs a new Color representing the given RGB values.

func (*Color) ConvertRGB

func (c *Color) ConvertRGB(vt *VTerm) (r, g, b uint8)

ConvertRGB calls vt.ConvertRGB(c).

func (*Color) Equal

func (c *Color) Equal(cb *Color) bool

Equal tests whether the two colors are equal.

func (*Color) Index

func (c *Color) Index() int

Index returns the palette index (0~255) if the color is indexed, -1 otherwise.

func (*Color) IsIndexed

func (c *Color) IsIndexed() bool

IsIndexed tells whether the color is indexed (from palette).

func (*Color) IsRGB

func (c *Color) IsRGB() bool

IsRGB tells whether the color is a RGB one.

type CursorShape

type CursorShape int

CursorShape describes the shape of the cursor. It's a vterm Property.

const (
	CursorShapeBlock     CursorShape // A solid block
	CursorShapeUnderline             // An underline
	CursorShapeBarLeft               // A vertial bar on the left of the cell
)

type Key

type Key int

Key is a speical key not represented by visible text.

const (
	KeyNone Key = iota

	KeyEnter
	KeyTab
	KeyBackspace
	KeyEscape

	KeyUp
	KeyDown
	KeyLeft
	KeyRight

	KeyInsert
	KeyDelete
	KeyHome
	KeyEnd
	KeyPageUp
	KeyPageDown

	KeyFunction0   Key = 256
	KeyFunctionMax Key = KeyFunction0 + 255
)

All the keys

const (
	KeyKeypad0 Key = 512 + iota
	KeyKeypad1
	KeyKeypad2
	KeyKeypad3
	KeyKeypad4
	KeyKeypad5
	KeyKeypad6
	KeyKeypad7
	KeyKeypad8
	KeyKeypad9
	KeyKeypadMultiply
	KeyKeypadPlus
	KeyKeypadComma
	KeyKeypadMinus
	KeyKeypadPeriod
	KeyKeypadDivide
	KeyKeypadEnter
	KeyKeypadEqual

	KeyMax   // Must be last
	KeyCount = KeyMax
)

Seperated to reset iota

func KeyFunction

func KeyFunction(n int) Key

KeyFunction returns the n-th function key code.

type Modifier

type Modifier int

Modifier is a bitmask regarding the states of the modifier keys (Ctrl, Alt, Shift).

const (
	ModifierNone  Modifier = 1 << iota // No modifier
	ModifierShift                      // Shift key
	ModifierAlt                        // Alt key
	ModifierCtrl                       // Ctrl key

	ModifierAllModsMask = ModifierShift | ModifierAlt | ModifierCtrl // All the modifier keys
)

type Mouse

type Mouse int

Mouse describes the moving/button states of the mouse. A vterm Property.

const (
	MouseNone  Mouse = iota // No action/Not using mouse
	MouseClick              // A button is pressed
	MouseDrag               // The cursor is moved when a button is pressed
	MouseMove               // The cursor is moved
)

type OutputCallback

type OutputCallback func([]byte, interface{})

OutputCallback is called on new terminal output (into the input of the slave)

type Pos

type Pos struct {
	Row, Col int
}

Pos describes a position on the terminal.

type Property

type Property int

Property describes the global state of a virtual terminal.

const (
	PropCursorVisible Property // bool, Is cursor visible?
	PropCursorBlink            // bool, Is cursor blinking?
	PropAltscreen              // bool, Is alt-screen active?
	PropTitle                  // string, Sets the vterm title
	PropIconName               // string, Icon name
	PropReverse                // bool, Is vterm in reverse-color?
	PropCursorShape            // int(CursorShape), Shape of the cursor
	PropMouse                  // int(MouseProp), State of the mouse cursor/button
)

type Rect

type Rect struct {
	StartRow, EndRow int
	StartCol, EndCol int
}

Rect describes a rectangle on the terminal.

type ScreenCallback

type ScreenCallback struct {
	Damage             func(r Rect, data interface{}) bool                     // A rectangle area on the screen has changed
	MoveRect           func(dest, src Rect, data interface{}) bool             // A rect on the screen is moved from src to dest
	MoveCursor         func(pos, oldpos Pos, data interface{}) bool            // Moves the cursor from oldpos to pos
	SetTermProp        func(prop Property, value Value, data interface{}) bool // A Property is set
	Bell               func(data interface{}) bool                             // Rings the bell
	Resize             func(rows, cols int, data interface{}) bool             // Terminal is resized
	ScrollbackPushLine func(cells []Cell, data interface{}) bool               // A line in the slice is poped from the top of terminal and pushed the scrollback stack
	ScrollbackPopLine  func(cells []Cell, data interface{}) bool               // Terminal is resized and a line is to be poped from the top of the scrollback stack into the slice; returns false if the stack is empty
}

ScreenCallback contains multiple callbacks called on screen changes. These functions return true if the action is successfully taken.

type ScreenCallbackObj

type ScreenCallbackObj interface {
	ScreenCbDamage(r Rect) bool
	ScreenCbMoveRect(dest, src Rect) bool
	ScreenCbMoveCursor(pos, oldpos Pos) bool
	ScreenCbSetTermProp(prop Property, value Value) bool
	ScreenCbBell() bool
	ScreenCbResize(rows, cols int) bool
	ScreenCbScrollbackPushLine(cells []Cell) bool
	ScreenCbScrollbackPopLine(cells []Cell) bool
}

ScreenCallbackObj is an interface object that wraps ScreenCallback in Go manner.

type Underline

type Underline int

Underline describes cell underline type

const (
	UnderlineNone   Underline = iota // No underline
	UnderlineSingle                  // Single underline
	UnderlineDouble                  // Double underline
	UnderlineCurly                   // Curly underline
)

type VTerm

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

VTerm holds the information for a Terminal. It must be explcitly freed by calling VTerm.Free().

func New

func New(rols, cols int) *VTerm

New creates a new VTerm instance

func (*VTerm) CellAt

func (vt *VTerm) CellAt(row, col int) Cell

CellAt retreives a cell at the given location.

func (*VTerm) ConvertRGB

func (vt *VTerm) ConvertRGB(c *Color) (r, g, b uint8)

ConvertRGB converts the Color instance to RGB format (if it is not) using VTermState's internal palette, and then returns the RGB values.

func (*VTerm) DefaultColors

func (vt *VTerm) DefaultColors() (fg, bg *Color)

DefaultColors returns the default foreground/background colors.

func (*VTerm) EnableAltscreen

func (vt *VTerm) EnableAltscreen(enable bool)

EnableAltscreen enables the screen alt-buffer

func (*VTerm) Free

func (vt *VTerm) Free()

Free frees the VTerm instance. It must be called before disposing the object

func (*VTerm) GetBufferCurrent

func (vt *VTerm) GetBufferCurrent() int

GetBufferCurrent returns the occupied space size of the internal buffer. Has no effect when OutputCallback is set.

func (*VTerm) GetBufferRemaining

func (vt *VTerm) GetBufferRemaining() int

GetBufferRemaining returns the remaining space size the internal buffer. Has no effect when OutputCallback is set.

func (*VTerm) GetBufferSize

func (vt *VTerm) GetBufferSize() int

GetBufferSize returns the current internal buffer size. Has no effect when OutputCallback is set.

func (*VTerm) GetSize

func (vt *VTerm) GetSize() (rols, cols int)

GetSize gets the apperence size of the terminal.

func (*VTerm) IsEOL

func (vt *VTerm) IsEOL(row, col int) bool

IsEOL tells whether the location is the end of a line.

func (*VTerm) IsUTF8

func (vt *VTerm) IsUTF8() bool

IsUTF8 tells whether the VTerm is to use UTF-8.

func (*VTerm) KeyboardEndPaste

func (vt *VTerm) KeyboardEndPaste()

KeyboardEndPaste disables pasting mode.

func (*VTerm) KeyboardKey

func (vt *VTerm) KeyboardKey(key Key, mod Modifier)

KeyboardKey sends a speical key to the vterm.

func (*VTerm) KeyboardPasteString

func (vt *VTerm) KeyboardPasteString(str string, mod Modifier)

KeyboardPasteString is a shortcut for pasting a string.

func (*VTerm) KeyboardStartPaste

func (vt *VTerm) KeyboardStartPaste()

KeyboardStartPaste enables pasting mode.

func (*VTerm) KeyboardUnichar

func (vt *VTerm) KeyboardUnichar(c rune, mod Modifier)

KeyboardUnichar sends a single rune to the vterm.

func (*VTerm) MouseButton

func (vt *VTerm) MouseButton(button int, pressed bool, mod Modifier)

MouseButton is used to update mouse button state (pressed/released). Left mouse button=1, middle=2, right=3; wheel up=4, wheel down=5. For mouse wheel keys you only need to call pressed=true.

func (*VTerm) MouseMove

func (vt *VTerm) MouseMove(row, col int, mod Modifier)

MouseMove is called when the mouse cursor is moved into another cell.

func (*VTerm) OutputCallback

func (vt *VTerm) OutputCallback(f OutputCallback, data interface{})

OutputCallback sets the output callback of the vterm object. If set to non-nil, VTerm.Read will have no effect.

func (*VTerm) OutputWriteTo

func (vt *VTerm) OutputWriteTo(w io.Writer)

OutputWriteTo is a shortcut for setting a callback that writes to a io.Writer.

func (*VTerm) PaletteColor

func (vt *VTerm) PaletteColor(index int) (col *Color)

PaletteColor gets the palette color of the given index.

func (*VTerm) Read

func (vt *VTerm) Read(p []byte) (int, error)

Read reads from the internal output buffer VTerm keeps (into the input of the slave). Has no effect when OutputCallback is set.

func (*VTerm) ScreenCallback

func (vt *VTerm) ScreenCallback(f ScreenCallback, data interface{})

ScreenCallback sets the screen callback of the vterm object. TODO Some fields in the ScreenCallback object can be nil while others are not.

func (*VTerm) ScreenCallbackObj

func (vt *VTerm) ScreenCallbackObj(i ScreenCallbackObj)

ScreenCallbackObj sets the screen callbacks with a interface object.

func (*VTerm) SetBoldHighbright

func (vt *VTerm) SetBoldHighbright(enabled bool)

SetBoldHighbright sets whether to use a brighter foreground on text set to bold.

func (*VTerm) SetDefaultColors

func (vt *VTerm) SetDefaultColors(fg, bg *Color)

SetDefaultColors sets the default foreground/background colors.

func (*VTerm) SetPaletteColor

func (vt *VTerm) SetPaletteColor(index int, col *Color)

SetPaletteColor sets the palette color for the given index.

func (*VTerm) SetSize

func (vt *VTerm) SetSize(rols, cols int)

SetSize sets the size of the terminal.

func (*VTerm) TextAt

func (vt *VTerm) TextAt(rect Rect) string

TextAt retreives the text on the terminal in the given area.

func (*VTerm) UseUTF8

func (vt *VTerm) UseUTF8(use bool)

UseUTF8 sets whether the VTerm is to use UTF-8. The default is true(not the same as libvterm)

func (*VTerm) Write

func (vt *VTerm) Write(p []byte) (int, error)

Write writes UTF-8 encoded data into the input of the VTerm (from the output of the slave)

type Value

type Value struct {
	Boolean bool
	Number  int
	String  string
	Color   *Color
}

Value contains one of the values given.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL