ansiterm

README

go-ansiterm

This is a cross platform Ansi Terminal Emulation library. It reads a stream of Ansi characters and produces the appropriate function calls. The results of the function calls are platform dependent.

For example the parser might receive "ESC, [, A" as a stream of three characters. This is the code for Cursor Up (http://www.vt100.net/docs/vt510-rm/CUU). The parser then calls the cursor up function (CUU()) on an event handler. The event handler determines what platform specific work must be done to cause the cursor to move up one position.

The parser (parser.go) is a partial implementation of this state machine (http://vt100.net/emu/vt500_parser.png). There are also two event handler implementations, one for tests (test_event_handler.go) to validate that the expected events are being produced and called, the other is a Windows implementation (winterm/win_event_handler.go).

See parser_test.go for examples exercising the state machine and generating appropriate function calls.

---

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Documentation

Index

• Constants
• type AnsiEventHandler
• type AnsiParser
  • func CreateParser(initialState string, evtHandler AnsiEventHandler, opts ...Option) *AnsiParser
  • func (ap *AnsiParser) Parse(bytes []byte) (int, error)
• type Option
  • func WithLogf(f func(string, ...interface{})) Option

Constants

const (
	// ECMA-48 Set Graphics Rendition
	// Note:
	// -- Constants leading with an underscore (e.g., _ANSI_xxx) are unsupported or reserved
	// -- Fonts could possibly be supported via SetCurrentConsoleFontEx
	// -- Windows does not expose the per-window cursor (i.e., caret) blink times
	ANSI_SGR_RESET = 0
	ANSI_SGR_BOLD  = 1
	ANSI_SGR_DIM   = 2

	ANSI_SGR_UNDERLINE = 4

	ANSI_SGR_REVERSE = 7

	ANSI_SGR_BOLD_DIM_OFF = 22

	ANSI_SGR_UNDERLINE_OFF = 24

	ANSI_SGR_REVERSE_OFF = 27

	ANSI_SGR_FOREGROUND_BLACK   = 30
	ANSI_SGR_FOREGROUND_RED     = 31
	ANSI_SGR_FOREGROUND_GREEN   = 32
	ANSI_SGR_FOREGROUND_YELLOW  = 33
	ANSI_SGR_FOREGROUND_BLUE    = 34
	ANSI_SGR_FOREGROUND_MAGENTA = 35
	ANSI_SGR_FOREGROUND_CYAN    = 36
	ANSI_SGR_FOREGROUND_WHITE   = 37

	ANSI_SGR_FOREGROUND_DEFAULT = 39
	ANSI_SGR_BACKGROUND_BLACK   = 40
	ANSI_SGR_BACKGROUND_RED     = 41
	ANSI_SGR_BACKGROUND_GREEN   = 42
	ANSI_SGR_BACKGROUND_YELLOW  = 43
	ANSI_SGR_BACKGROUND_BLUE    = 44
	ANSI_SGR_BACKGROUND_MAGENTA = 45
	ANSI_SGR_BACKGROUND_CYAN    = 46
	ANSI_SGR_BACKGROUND_WHITE   = 47

	ANSI_SGR_BACKGROUND_DEFAULT = 49

	ANSI_MAX_CMD_LENGTH = 4096

	MAX_INPUT_EVENTS = 128
	DEFAULT_WIDTH    = 80
	DEFAULT_HEIGHT   = 24

	ANSI_BEL              = 0x07
	ANSI_BACKSPACE        = 0x08
	ANSI_TAB              = 0x09
	ANSI_LINE_FEED        = 0x0A
	ANSI_VERTICAL_TAB     = 0x0B
	ANSI_FORM_FEED        = 0x0C
	ANSI_CARRIAGE_RETURN  = 0x0D
	ANSI_ESCAPE_PRIMARY   = 0x1B
	ANSI_ESCAPE_SECONDARY = 0x5B
	ANSI_OSC_STRING_ENTRY = 0x5D
	ANSI_COMMAND_FIRST    = 0x40
	ANSI_COMMAND_LAST     = 0x7E
	DCS_ENTRY             = 0x90
	CSI_ENTRY             = 0x9B
	OSC_STRING            = 0x9D
	ANSI_PARAMETER_SEP    = ";"
	ANSI_CMD_G0           = '('
	ANSI_CMD_G1           = ')'
	ANSI_CMD_G2           = '*'
	ANSI_CMD_G3           = '+'
	ANSI_CMD_DECPNM       = '>'
	ANSI_CMD_DECPAM       = '='
	ANSI_CMD_OSC          = ']'
	ANSI_CMD_STR_TERM     = '\\'

	KEY_CONTROL_PARAM_2 = ";2"
	KEY_CONTROL_PARAM_3 = ";3"
	KEY_CONTROL_PARAM_4 = ";4"
	KEY_CONTROL_PARAM_5 = ";5"
	KEY_CONTROL_PARAM_6 = ";6"
	KEY_CONTROL_PARAM_7 = ";7"
	KEY_CONTROL_PARAM_8 = ";8"
	KEY_ESC_CSI         = "\x1B["
	KEY_ESC_N           = "\x1BN"
	KEY_ESC_O           = "\x1BO"

	FILL_CHARACTER = ' '
)

ANSI constants References: -- http://www.ecma-international.org/publications/standards/Ecma-048.htm -- http://man7.org/linux/man-pages/man4/console_codes.4.html -- http://manpages.ubuntu.com/manpages/intrepid/man4/console_codes.4.html -- http://en.wikipedia.org/wiki/ANSI_escape_code -- http://vt100.net/emu/dec_ansi_parser -- http://vt100.net/emu/vt500_parser.svg -- http://invisible-island.net/xterm/ctlseqs/ctlseqs.html -- http://www.inwap.com/pdp10/ansicode.txt

const LogEnv = "DEBUG_TERMINAL"

Types

type AnsiEventHandler

type AnsiEventHandler interface {
	// Print
	Print(b byte) error

	// Execute C0 commands
	Execute(b byte) error

	// CUrsor Up
	CUU(int) error

	// CUrsor Down
	CUD(int) error

	// CUrsor Forward
	CUF(int) error

	// CUrsor Backward
	CUB(int) error

	// Cursor to Next Line
	CNL(int) error

	// Cursor to Previous Line
	CPL(int) error

	// Cursor Horizontal position Absolute
	CHA(int) error

	// Vertical line Position Absolute
	VPA(int) error

	// CUrsor Position
	CUP(int, int) error

	// Horizontal and Vertical Position (depends on PUM)
	HVP(int, int) error

	// Text Cursor Enable Mode
	DECTCEM(bool) error

	// Origin Mode
	DECOM(bool) error

	// 132 Column Mode
	DECCOLM(bool) error

	// Erase in Display
	ED(int) error

	// Erase in Line
	EL(int) error

	// Insert Line
	IL(int) error

	// Delete Line
	DL(int) error

	// Insert Character
	ICH(int) error

	// Delete Character
	DCH(int) error

	// Set Graphics Rendition
	SGR([]int) error

	// Pan Down
	SU(int) error

	// Pan Up
	SD(int) error

	// Device Attributes
	DA([]string) error

	// Set Top and Bottom Margins
	DECSTBM(int, int) error

	// Index
	IND() error

	// Reverse Index
	RI() error

	// Flush updates from previous commands
	Flush() error
}

type AnsiParser

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

func CreateParser

func CreateParser(initialState string, evtHandler AnsiEventHandler, opts ...Option) *AnsiParser

func (*AnsiParser) Parse

func (ap *AnsiParser) Parse(bytes []byte) (int, error)

type Option

type Option func(*AnsiParser)

func WithLogf

func WithLogf(f func(string, ...interface{})) Option