ansi

package module
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Oct 24, 2024 License: MIT Imports: 14 Imported by: 189

Documentation

Overview

Package ansi defines common ANSI escape sequences based on the ECMA-48 specs.

All sequences use 7-bit C1 control codes, which are supported by most terminal emulators. OSC sequences are terminated by a BEL for wider compatibility with terminals.

Index

Constants

View Source 
const (
	// SP is the space character (Char: \x20).
	SP = 0x20
	// DEL is the delete character (Caret: ^?, Char: \x7f).
	DEL = 0x7F
)
View Source 
const (
	// NUL is the null character (Caret: ^@, Char: \0).
	NUL = 0x00
	// SOH is the start of heading character (Caret: ^A).
	SOH = 0x01
	// STX is the start of text character (Caret: ^B).
	STX = 0x02
	// ETX is the end of text character (Caret: ^C).
	ETX = 0x03
	// EOT is the end of transmission character (Caret: ^D).
	EOT = 0x04
	// ENQ is the enquiry character (Caret: ^E).
	ENQ = 0x05
	// ACK is the acknowledge character (Caret: ^F).
	ACK = 0x06
	// BEL is the bell character (Caret: ^G, Char: \a).
	BEL = 0x07
	// BS is the backspace character (Caret: ^H, Char: \b).
	BS = 0x08
	// HT is the horizontal tab character (Caret: ^I, Char: \t).
	HT = 0x09
	// LF is the line feed character (Caret: ^J, Char: \n).
	LF = 0x0A
	// VT is the vertical tab character (Caret: ^K, Char: \v).
	VT = 0x0B
	// FF is the form feed character (Caret: ^L, Char: \f).
	FF = 0x0C
	// CR is the carriage return character (Caret: ^M, Char: \r).
	CR = 0x0D
	// SO is the shift out character (Caret: ^N).
	SO = 0x0E
	// SI is the shift in character (Caret: ^O).
	SI = 0x0F
	// DLE is the data link escape character (Caret: ^P).
	DLE = 0x10
	// DC1 is the device control 1 character (Caret: ^Q).
	DC1 = 0x11
	// DC2 is the device control 2 character (Caret: ^R).
	DC2 = 0x12
	// DC3 is the device control 3 character (Caret: ^S).
	DC3 = 0x13
	// DC4 is the device control 4 character (Caret: ^T).
	DC4 = 0x14
	// NAK is the negative acknowledge character (Caret: ^U).
	NAK = 0x15
	// SYN is the synchronous idle character (Caret: ^V).
	SYN = 0x16
	// ETB is the end of transmission block character (Caret: ^W).
	ETB = 0x17
	// CAN is the cancel character (Caret: ^X).
	CAN = 0x18
	// EM is the end of medium character (Caret: ^Y).
	EM = 0x19
	// SUB is the substitute character (Caret: ^Z).
	SUB = 0x1A
	// ESC is the escape character (Caret: ^[, Char: \e).
	ESC = 0x1B
	// FS is the file separator character (Caret: ^\).
	FS = 0x1C
	// GS is the group separator character (Caret: ^]).
	GS = 0x1D
	// RS is the record separator character (Caret: ^^).
	RS = 0x1E
	// US is the unit separator character (Caret: ^_).
	US = 0x1F
)

C0 control characters.

These range from (0x00-0x1F) as defined in ISO 646 (ASCII). See: https://en.wikipedia.org/wiki/C0_and_C1_control_codes

View Source 
const (
	// PAD is the padding character.
	PAD = 0x80
	// HOP is the high octet preset character.
	HOP = 0x81
	// BPH is the break permitted here character.
	BPH = 0x82
	// NBH is the no break here character.
	NBH = 0x83
	// IND is the index character.
	IND = 0x84
	// NEL is the next line character.
	NEL = 0x85
	// SSA is the start of selected area character.
	SSA = 0x86
	// ESA is the end of selected area character.
	ESA = 0x87
	// HTS is the horizontal tab set character.
	HTS = 0x88
	// HTJ is the horizontal tab with justification character.
	HTJ = 0x89
	// VTS is the vertical tab set character.
	VTS = 0x8A
	// PLD is the partial line forward character.
	PLD = 0x8B
	// PLU is the partial line backward character.
	PLU = 0x8C
	// RI is the reverse index character.
	RI = 0x8D
	// SS2 is the single shift 2 character.
	SS2 = 0x8E
	// SS3 is the single shift 3 character.
	SS3 = 0x8F
	// DCS is the device control string character.
	DCS = 0x90
	// PU1 is the private use 1 character.
	PU1 = 0x91
	// PU2 is the private use 2 character.
	PU2 = 0x92
	// STS is the set transmit state character.
	STS = 0x93
	// CCH is the cancel character.
	CCH = 0x94
	// MW is the message waiting character.
	MW = 0x95
	// SPA is the start of guarded area character.
	SPA = 0x96
	// EPA is the end of guarded area character.
	EPA = 0x97
	// SOS is the start of string character.
	SOS = 0x98
	// SGCI is the single graphic character introducer character.
	SGCI = 0x99
	// SCI is the single character introducer character.
	SCI = 0x9A
	// CSI is the control sequence introducer character.
	CSI = 0x9B
	// ST is the string terminator character.
	ST = 0x9C
	// OSC is the operating system command character.
	OSC = 0x9D
	// PM is the privacy message character.
	PM = 0x9E
	// APC is the application program command character.
	APC = 0x9F
)

C1 control characters.

These range from (0x80-0x9F) as defined in ISO 6429 (ECMA-48). See: https://en.wikipedia.org/wiki/C0_and_C1_control_codes

View Source 
const (
	SystemClipboard  = 'c'
	PrimaryClipboard = 'p'
)

Clipboard names.

View Source 
const (
	KittyDisambiguateEscapeCodes = 1 << iota
	KittyReportEventTypes
	KittyReportAlternateKeys
	KittyReportAllKeysAsEscapeCodes
	KittyReportAssociatedKeys

	KittyAllFlags = KittyDisambiguateEscapeCodes | KittyReportEventTypes |
		KittyReportAlternateKeys | KittyReportAllKeysAsEscapeCodes | KittyReportAssociatedKeys
)

Kitty keyboard protocol progressive enhancement flags. See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/#progressive-enhancement

View Source 
const (
	CursorKeysMode = PrivateMode(1)

	EnableCursorKeys  = "\x1b[?1h"
	DisableCursorKeys = "\x1b[?1l"
	RequestCursorKeys = "\x1b[?1$p"
)

Application Cursor Keys (DECCKM) is a mode that determines whether the cursor keys send ANSI cursor sequences or application sequences.

See: https://vt100.net/docs/vt510-rm/DECCKM.html

View Source 
const (
	CursorEnableMode = PrivateMode(25)

	ShowCursor              = "\x1b[?25h"
	HideCursor              = "\x1b[?25l"
	RequestCursorVisibility = "\x1b[?25$p"
)

Text Cursor Enable Mode (DECTCEM) is a mode that shows/hides the cursor.

See: https://vt100.net/docs/vt510-rm/DECTCEM.html

View Source 
const (
	MouseMode = PrivateMode(1000)

	EnableMouse  = "\x1b[?1000h"
	DisableMouse = "\x1b[?1000l"
	RequestMouse = "\x1b[?1000$p"
)

VT Mouse Tracking is a mode that determines whether the mouse reports on button press and release.

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Mouse-Tracking

View Source 
const (
	MouseHiliteMode = PrivateMode(1001)

	EnableMouseHilite  = "\x1b[?1001h"
	DisableMouseHilite = "\x1b[?1001l"
	RequestMouseHilite = "\x1b[?1001$p"
)

VT Hilite Mouse Tracking is a mode that determines whether the mouse reports on button presses, releases, and highlighted cells.

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Mouse-Tracking

View Source 
const (
	MouseCellMotionMode = PrivateMode(1002)

	EnableMouseCellMotion  = "\x1b[?1002h"
	DisableMouseCellMotion = "\x1b[?1002l"
	RequestMouseCellMotion = "\x1b[?1002$p"
)

Cell Motion Mouse Tracking is a mode that determines whether the mouse reports on button press, release, and motion events.

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Mouse-Tracking

View Source 
const (
	MouseAllMotionMode = PrivateMode(1003)

	EnableMouseAllMotion  = "\x1b[?1003h"
	DisableMouseAllMotion = "\x1b[?1003l"
	RequestMouseAllMotion = "\x1b[?1003$p"
)

All Mouse Tracking is a mode that determines whether the mouse reports on button press, release, motion, and highlight events.

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Mouse-Tracking

View Source 
const (
	ReportFocusMode = PrivateMode(1004)

	EnableReportFocus  = "\x1b[?1004h"
	DisableReportFocus = "\x1b[?1004l"
	RequestReportFocus = "\x1b[?1004$p"
)

Report Focus is a mode that makes the terminal report focus-in and focus-out events.

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-FocusIn_FocusOut

View Source 
const (
	MouseSgrExtMode = PrivateMode(1006)

	EnableMouseSgrExt  = "\x1b[?1006h"
	DisableMouseSgrExt = "\x1b[?1006l"
	RequestMouseSgrExt = "\x1b[?1006$p"
)

SGR Mouse Extension is a mode that determines whether the mouse reports events formatted with SGR parameters.

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Mouse-Tracking

View Source 
const (
	AltScreenBufferMode = PrivateMode(1049)

	EnableAltScreenBuffer  = "\x1b[?1049h"
	DisableAltScreenBuffer = "\x1b[?1049l"
	RequestAltScreenBuffer = "\x1b[?1049$p"
)

Alternate Screen Buffer is a mode that determines whether the alternate screen buffer is active.

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-The-Alternate-Screen-Buffer

View Source 
const (
	BracketedPasteMode = PrivateMode(2004)

	EnableBracketedPaste  = "\x1b[?2004h"
	DisableBracketedPaste = "\x1b[?2004l"
	RequestBracketedPaste = "\x1b[?2004$p"
)

Bracketed Paste Mode is a mode that determines whether pasted text is bracketed with escape sequences.

See: https://cirw.in/blog/bracketed-paste See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Bracketed-Paste-Mode

View Source 
const (
	SyncdOutputMode = PrivateMode(2026)

	EnableSyncdOutput  = "\x1b[?2026h"
	DisableSyncdOutput = "\x1b[?2026l"
	RequestSyncdOutput = "\x1b[?2026$p"
)

Synchronized Output Mode is a mode that determines whether output is synchronized with the terminal.

See: https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036

View Source 
const (
	GraphemeClusteringMode = PrivateMode(2027)

	EnableGraphemeClustering  = "\x1b[?2027h"
	DisableGraphemeClustering = "\x1b[?2027l"
	RequestGraphemeClustering = "\x1b[?2027$p"
)

Grapheme Clustering Mode is a mode that determines whether the terminal should look for grapheme clusters instead of single runes in the rendered text. This makes the terminal properly render combining characters such as emojis.

See: https://github.com/contour-terminal/terminal-unicode-core

View Source 
const (
	Win32InputMode = PrivateMode(9001)

	EnableWin32Input  = "\x1b[?9001h"
	DisableWin32Input = "\x1b[?9001l"
	RequestWin32Input = "\x1b[?9001$p"
)

Win32Input is a mode that determines whether input is processed by the Win32 console and Conpty.

See: https://github.com/microsoft/terminal/blob/main/doc/specs/%234999%20-%20Improved%20keyboard%20handling%20in%20Conpty.md

View Source 
const (
	EraseScreenBelow   = "\x1b[0J"
	EraseScreenAbove   = "\x1b[1J"
	EraseEntireScreen  = "\x1b[2J"
	EraseEntireDisplay = "\x1b[3J"
)

EraseDisplay constants. These are the possible values for the EraseDisplay function.

View Source 
const (
	EraseLineRight  = "\x1b[0K"
	EraseLineLeft   = "\x1b[1K"
	EraseEntireLine = "\x1b[2K"
)

EraseLine constants. These are the possible values for the EraseLine function.

View Source 
const CursorDown1 = "\x1b[B"

CursorDown1 is a sequence for moving the cursor down one cell.

This is equivalent to CursorDown(1).

View Source 
const CursorLeft1 = "\x1b[D"

CursorLeft1 is a sequence for moving the cursor left one cell.

This is equivalent to CursorLeft(1).

View Source 
const CursorOrigin = "\x1b[1;1H"

CursorOrigin is a sequence for moving the cursor to the upper left corner of the display. This is equivalent to `SetCursorPosition(1, 1)`.

View Source 
const CursorRight1 = "\x1b[C"

CursorRight1 is a sequence for moving the cursor right one cell.

This is equivalent to CursorRight(1).

View Source 
const CursorUp1 = "\x1b[A"

CursorUp1 is a sequence for moving the cursor up one cell.

This is equivalent to CursorUp(1).

View Source 
const DisableKittyKeyboard = "\x1b[>0u"

DisableKittyKeyboard is a sequence to push zero into the terminal Kitty Keyboard stack to disable the protocol.

This is equivalent to PushKittyKeyboard(0).

View Source 
const DisableModifyOtherKeys = "\x1b[>4;0m"

DisableModifyOtherKeys disables the modifyOtherKeys mode. 

CSI > 4 ; 0 m

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Functions-using-CSI-_-ordered-by-the-final-character_s_ See: https://invisible-island.net/xterm/manpage/xterm.html#VT100-Widget-Resources:modifyOtherKeys

View Source 
const EnableModifyOtherKeys1 = "\x1b[>4;1m"

EnableModifyOtherKeys1 enables the modifyOtherKeys mode 1. 

CSI > 4 ; 1 m

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Functions-using-CSI-_-ordered-by-the-final-character_s_ See: https://invisible-island.net/xterm/manpage/xterm.html#VT100-Widget-Resources:modifyOtherKeys

View Source 
const EnableModifyOtherKeys2 = "\x1b[>4;2m"

EnableModifyOtherKeys2 enables the modifyOtherKeys mode 2. 

CSI > 4 ; 2 m

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Functions-using-CSI-_-ordered-by-the-final-character_s_ See: https://invisible-island.net/xterm/manpage/xterm.html#VT100-Widget-Resources:modifyOtherKeys

View Source 
const RequestBackgroundColor = "\x1b]11;?\x07"

RequestBackgroundColor is a sequence that requests the current default terminal background color.

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands

View Source 
const RequestCursorColor = "\x1b]12;?\x07"

RequestCursorColor is a sequence that requests the current terminal cursor color.

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands

View Source 
const RequestCursorPosition = "\x1b[6n"

RequestCursorPosition (CPR) is an escape sequence that requests the current cursor position. 

CSI 6 n

The terminal will report the cursor position as a CSI sequence in the following format: 

CSI Pl ; Pc R

Where Pl is the line number and Pc is the column number. See: https://vt100.net/docs/vt510-rm/CPR.html

View Source 
const RequestExtendedCursorPosition = "\x1b[?6n"

RequestExtendedCursorPosition (DECXCPR) is a sequence for requesting the cursor position report including the current page number. 

CSI ? 6 n

The terminal will report the cursor position as a CSI sequence in the following format: 

CSI ? Pl ; Pc ; Pp R

Where Pl is the line number, Pc is the column number, and Pp is the page number. See: https://vt100.net/docs/vt510-rm/DECXCPR.html

View Source 
const RequestForegroundColor = "\x1b]10;?\x07"

RequestForegroundColor is a sequence that requests the current default terminal foreground color.

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands

View Source 
const RequestKittyKeyboard = "\x1b[?u"

RequestKittyKeyboard is a sequence to request the terminal Kitty keyboard protocol enabled flags.

See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/

View Source 
const RequestModifyOtherKeys = "\x1b[?4m"

RequestModifyOtherKeys requests the modifyOtherKeys mode. 

CSI ? 4  m

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Functions-using-CSI-_-ordered-by-the-final-character_s_ See: https://invisible-island.net/xterm/manpage/xterm.html#VT100-Widget-Resources:modifyOtherKeys

View Source 
const RequestPrimaryClipboard = "\x1b]52;p;?\x07"

RequestPrimaryClipboard is a sequence for requesting the primary clipboard.

This is equivalent to RequestClipboard(PrimaryClipboard).

View Source 
const RequestPrimaryDeviceAttributes = "\x1b[c"

RequestPrimaryDeviceAttributes is a control sequence that requests the terminal's primary device attributes (DA1). 

CSI c

See https://vt100.net/docs/vt510-rm/DA1.html

View Source 
const RequestSystemClipboard = "\x1b]52;c;?\x07"

RequestSystemClipboard is a sequence for requesting the system clipboard.

This is equivalent to RequestClipboard(SystemClipboard).

View Source 
const RequestXTVersion = "\x1b[>0q"

RequestXTVersion is a control sequence that requests the terminal's XTVERSION. It responds with a DSR sequence identifying the version. 

CSI > Ps q
DCS > | text ST

See https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-PC-Style-Function-Keys

View Source 
const ResetBackgroundColor = "\x1b]111\x07"

ResetBackgroundColor is a sequence that resets the default terminal background color.

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands

View Source 
const ResetCursorColor = "\x1b]112\x07"

ResetCursorColor is a sequence that resets the terminal cursor color.

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands

View Source 
const ResetForegroundColor = "\x1b]110\x07"

ResetForegroundColor is a sequence that resets the default terminal foreground color.

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands

View Source 
const ResetPrimaryClipboard = "\x1b]52;p;\x07"

ResetPrimaryClipboard is a sequence for resetting the primary clipboard.

This is equivalent to ResetClipboard(PrimaryClipboard).

View Source 
const ResetStyle = "\x1b[m"

ResetStyle is a SGR (Select Graphic Rendition) style sequence that resets all attributes. See: https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters

View Source 
const ResetSystemClipboard = "\x1b]52;c;\x07"

ResetSystemClipboard is a sequence for resetting the system clipboard.

This is equivalent to ResetClipboard(SystemClipboard).

View Source 
const RestoreCursor = "\x1b8"

RestoreCursor (DECRC) is an escape sequence that restores the cursor position. 

ESC 8

See: https://vt100.net/docs/vt510-rm/DECRC.html

View Source 
const RestoreCursorPosition = "\x1b[u"

RestoreCursorPosition (RCP or SCORC) is a sequence for restoring the cursor position. 

CSI u

This acts like Restore, except the cursor stays on the same page where the cursor was saved.

See: https://vt100.net/docs/vt510-rm/SCORC.html

View Source 
const SaveCursor = "\x1b7"

SaveCursor (DECSC) is an escape sequence that saves the current cursor position. 

ESC 7

See: https://vt100.net/docs/vt510-rm/DECSC.html

View Source 
const SaveCursorPosition = "\x1b[s"

SaveCursorPosition (SCP or SCOSC) is a sequence for saving the cursor position. 

CSI s

This acts like Save, except the page number where the cursor is located is not saved.

See: https://vt100.net/docs/vt510-rm/SCOSC.html

Variables

This section is empty.

Functions

func CursorDown 

func CursorDown(n int) string

CursorDown (CUD) returns a sequence for moving the cursor down n cells. 

CSI n B

See: https://vt100.net/docs/vt510-rm/CUD.html

func CursorLeft 

func CursorLeft(n int) string

CursorLeft (CUB) returns a sequence for moving the cursor left n cells. 

CSI n D

See: https://vt100.net/docs/vt510-rm/CUB.html

func CursorNextLine 

func CursorNextLine(n int) string

CursorNextLine (CNL) returns a sequence for moving the cursor to the beginning of the next line n times. 

CSI n E

See: https://vt100.net/docs/vt510-rm/CNL.html

func CursorPreviousLine 

func CursorPreviousLine(n int) string

CursorPreviousLine (CPL) returns a sequence for moving the cursor to the beginning of the previous line n times. 

CSI n F

See: https://vt100.net/docs/vt510-rm/CPL.html

func CursorRight 

func CursorRight(n int) string

CursorRight (CUF) returns a sequence for moving the cursor right n cells. 

CSI n C

See: https://vt100.net/docs/vt510-rm/CUF.html

func CursorUp 

func CursorUp(n int) string

CursorUp (CUU) returns a sequence for moving the cursor up n cells. 

CSI n A

See: https://vt100.net/docs/vt510-rm/CUU.html

func DecodeSequence added in v0.2.0 

func DecodeSequence[T string | []byte](b T, state byte, p *Parser) (seq T, width int, n int, newState byte)

DecodeSequence decodes the first ANSI escape sequence or a printable grapheme from the given data. It returns the sequence slice, the number of bytes read, the cell width for each sequence, and the new state.

The cell width will always be 0 for control and escape sequences, 1 for ASCII printable characters, and the number of cells other Unicode characters occupy. It uses the uniseg package to calculate the width of Unicode graphemes and characters. This means it will always do grapheme clustering (mode 2027).

Passing a non-nil *Parser as the last argument will allow the decoder to collect sequence parameters, data, and commands. The parser cmd will have the packed command value that contains intermediate and marker characters. In the case of a OSC sequence, the cmd will be the OSC command number. Use Cmd and Param types to unpack command intermediates and markers as well as parameters.

Zero Cmd means the CSI, DCS, or ESC sequence is invalid. Moreover, checking the validity of other data sequences, OSC, DCS, etc, will require checking for the returned sequence terminator bytes such as ST (ESC \\) and BEL).

We store the command byte in Cmd in the most significant byte, the marker byte in the next byte, and the intermediate byte in the least significant byte. This is done to avoid using a struct to store the command and its intermediates and markers. The command byte is always the least significant byte i.e. [Cmd & 0xff]. Use the Cmd type to unpack the command, intermediate, and marker bytes. Note that we only collect the last marker character and intermediate byte.

The [p.Params] slice will contain the parameters of the sequence. Any sub-parameter will have the parser.HasMoreFlag set. Use the Param type to unpack the parameters.

Example: 

var state byte // the initial state is always zero [NormalState]
p := NewParser(32, 1024) // create a new parser with a 32 params buffer and 1024 data buffer (optional)
input := []byte("\x1b[31mHello, World!\x1b[0m")
for len(input) > 0 {
	seq, width, n, newState := DecodeSequence(input, state, p)
	log.Printf("seq: %q, width: %d", seq, width)
	state = newState
	input = input[n:]
}

func DeleteLine 

func DeleteLine(n int) string

DeleteLine (DL) deletes n lines at the current cursor position. Existing lines are moved up. 

CSI <n> M

See: https://vt100.net/docs/vt510-rm/DL.html

func Equal added in v0.2.0 

func Equal[T string | []byte](a, b T) bool

Equal returns true if the given byte slices are equal.

func EraseDisplay 

func EraseDisplay(n int) string

EraseDisplay (ED) clears the display or parts of the display. A screen is the shown part of the terminal display excluding the scrollback buffer. Possible values: 

 0: Clear from cursor to end of screen.
 1: Clear from cursor to beginning of the screen.
 2: Clear entire screen (and moves cursor to upper left on DOS).
 3: Clear entire display which delete all lines saved in the scrollback buffer (xterm).

CSI <n> J

See: https://vt100.net/docs/vt510-rm/ED.html

func EraseLine 

func EraseLine(n int) string

EraseLine (EL) clears the current line or parts of the line. Possible values: 

0: Clear from cursor to end of line.
1: Clear from cursor to beginning of the line.
2: Clear entire line.

The cursor position is not affected. 

CSI <n> K

See: https://vt100.net/docs/vt510-rm/EL.html

func Execute 

func Execute(w io.Writer, s string) (int, error)

Execute is a function that "execute" the given escape sequence by writing it to the provided output writter.

This is a syntactic sugar over io.WriteString.

func FirstGraphemeCluster added in v0.2.0 

func FirstGraphemeCluster[T string | []byte](b T, state int) (T, T, int, int)

FirstGraphemeCluster returns the first grapheme cluster in the given string or byte slice. This is a syntactic sugar function that wraps uniseg.FirstGraphemeClusterInString and uniseg.FirstGraphemeCluster.

func Hardwrap 

func Hardwrap(s string, limit int, preserveSpace bool) string

Hardwrap wraps a string or a block of text to a given line length, breaking word boundaries. This will preserve ANSI escape codes and will account for wide-characters in the string. When preserveSpace is true, spaces at the beginning of a line will be preserved.

func HasApcPrefix added in v0.2.0 

func HasApcPrefix[T string | []byte](b T) bool

HasApcPrefix returns true if the given byte slice has an APC prefix.

func HasCsiPrefix added in v0.2.0 

func HasCsiPrefix[T string | []byte](b T) bool

HasCsiPrefix returns true if the given byte slice has a CSI prefix.

func HasDcsPrefix added in v0.2.0 

func HasDcsPrefix[T string | []byte](b T) bool

HasDcsPrefix returns true if the given byte slice has a DCS prefix.

func HasEscPrefix added in v0.2.0 

func HasEscPrefix[T string | []byte](b T) bool

HasEscPrefix returns true if the given byte slice has an ESC prefix.

func HasOscPrefix added in v0.2.0 

func HasOscPrefix[T string | []byte](b T) bool

HasOscPrefix returns true if the given byte slice has an OSC prefix.

func HasPmPrefix added in v0.2.0 

func HasPmPrefix[T string | []byte](b T) bool

HasPmPrefix returns true if the given byte slice has a PM prefix.

func HasPrefix added in v0.2.0 

func HasPrefix[T string | []byte](b, prefix T) bool

HasPrefix returns true if the given byte slice has prefix.

func HasSosPrefix added in v0.2.0 

func HasSosPrefix[T string | []byte](b T) bool

HasSosPrefix returns true if the given byte slice has a SOS prefix.

func HasStPrefix added in v0.2.0 

func HasStPrefix[T string | []byte](b T) bool

HasStPrefix returns true if the given byte slice has a ST prefix.

func HasSuffix added in v0.2.0 

func HasSuffix[T string | []byte](b, suffix T) bool

HasSuffix returns true if the given byte slice has suffix.

func Index added in v0.2.0 

func Index[T string | []byte](data, b T) int

Index returns the index of the first occurrence of the given byte slice in the data. It returns -1 if the byte slice is not found.

func InsertLine 

func InsertLine(n int) string

InsertLine (IL) inserts n blank lines at the current cursor position. Existing lines are moved down. 

CSI <n> L

See: https://vt100.net/docs/vt510-rm/IL.html

func KittyKeyboard added in v0.2.0 

func KittyKeyboard(flags, mode int) string

KittyKeyboard returns a sequence to request keyboard enhancements from the terminal. The flags argument is a bitmask of the Kitty keyboard protocol flags. While mode specifies how the flags should be interpreted.

Possible values for flags mask: 

1:  Disambiguate escape codes
2:  Report event types
4:  Report alternate keys
8:  Report all keys as escape codes
16: Report associated text

Possible values for mode: 

1: Set given flags and unset all others
2: Set given flags and keep existing flags unchanged
3: Unset given flags and keep existing flags unchanged

See https://sw.kovidgoyal.net/kitty/keyboard-protocol/#progressive-enhancement

func ModifyOtherKeys added in v0.2.0 

func ModifyOtherKeys(mode int) string

ModifyOtherKeys returns a sequence that sets XTerm modifyOtherKeys mode. The mode argument specifies the mode to set. 

0: Disable modifyOtherKeys mode.
1: Enable modifyOtherKeys mode 1.
2: Enable modifyOtherKeys mode 2.

CSI > 4 ; mode m

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Functions-using-CSI-_-ordered-by-the-final-character_s_ See: https://invisible-island.net/xterm/manpage/xterm.html#VT100-Widget-Resources:modifyOtherKeys

func Params 

func Params(p []byte) [][]uint

Params parses and returns a list of control sequence parameters.

Parameters are positive integers separated by semicolons. Empty parameters default to zero. Parameters can have sub-parameters separated by colons.

Any non-parameter bytes are ignored. This includes bytes that are not in the range of 0x30-0x3B.

See ECMA-48 § 5.4.1.

func PopKittyKeyboard 

func PopKittyKeyboard(n int) string

PopKittyKeyboard returns a sequence to pop n number of flags from the terminal Kitty Keyboard stack. 

CSI < flags u

See https://sw.kovidgoyal.net/kitty/keyboard-protocol/#progressive-enhancement

func PushKittyKeyboard 

func PushKittyKeyboard(flags int) string

PushKittyKeyboard returns a sequence to push the given flags to the terminal Kitty Keyboard stack.

Possible values for flags mask: 

0:  Disable all features
1:  Disambiguate escape codes
2:  Report event types
4:  Report alternate keys
8:  Report all keys as escape codes
16: Report associated text

CSI > flags u

See https://sw.kovidgoyal.net/kitty/keyboard-protocol/#progressive-enhancement

func PutParser added in v0.3.1 

func PutParser(p *Parser)

PutParser returns a parser to a sync pool. The parser is reset automatically.

func RequestClipboard 

func RequestClipboard(c byte) string

RequestClipboard returns a sequence for requesting the clipboard.

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands

func RequestTermcap 

func RequestTermcap(caps ...string) string

RequestTermcap (XTGETTCAP) requests Termcap/Terminfo strings. 

DCS + q <Pt> ST

Where <Pt> is a list of Termcap/Terminfo capabilities, encoded in 2-digit hexadecimals, separated by semicolons.

See: https://man7.org/linux/man-pages/man5/terminfo.5.html See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands

func ResetClipboard 

func ResetClipboard(c byte) string

ResetClipboard returns a sequence for resetting the clipboard.

This is equivalent to SetClipboard(c, "").

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands 

func ResetHyperlink(params ...string) string

ResetHyperlink returns a sequence for resetting the hyperlink.

This is equivalent to SetHyperlink("", params...).

See: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda

func ScreenPassthrough 

func ScreenPassthrough(seq string, limit int) string

ScreenPassthrough wraps the given ANSI sequence in a DCS passthrough sequence to be sent to the outer terminal. This is used to send raw escape sequences to the outer terminal when running inside GNU Screen. 

DCS <data> ST

Note: Screen limits the length of string sequences to 768 bytes (since 2014). Use zero to indicate no limit, otherwise, this will chunk the returned string into limit sized chunks.

See: https://www.gnu.org/software/screen/manual/screen.html#String-Escapes See: https://git.savannah.gnu.org/cgit/screen.git/tree/src/screen.h?id=c184c6ec27683ff1a860c45be5cf520d896fd2ef#n44

func ScrollDown 

func ScrollDown(n int) string

ScrollDown (SD) scrolls the screen down n lines. New lines are added at the top of the screen. 

CSI <n> T

See: https://vt100.net/docs/vt510-rm/SD.html

func ScrollUp 

func ScrollUp(n int) string

ScrollUp (SU) scrolls the screen up n lines. New lines are added at the bottom of the screen. 

CSI <n> S

See: https://vt100.net/docs/vt510-rm/SU.html

func SetBackgroundColor 

func SetBackgroundColor(c color.Color) string

SetBackgroundColor returns a sequence that sets the default terminal background color. 

OSC 11 ; color ST
OSC 11 ; color BEL

Where color is the encoded color number.

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands

func SetClipboard 

func SetClipboard(c byte, d string) string

SetClipboard returns a sequence for manipulating the clipboard. 

OSC 52 ; Pc ; Pd ST
OSC 52 ; Pc ; Pd BEL

Where Pc is the clipboard name and Pd is the base64 encoded data. Empty data or invalid base64 data will reset the clipboard.

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands

func SetCursorColor 

func SetCursorColor(c color.Color) string

SetCursorColor returns a sequence that sets the terminal cursor color. 

OSC 12 ; color ST
OSC 12 ; color BEL

Where color is the encoded color number.

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands

func SetCursorPosition added in v0.4.0 

func SetCursorPosition(col, row int) string

SetCursorPosition (CUP) returns a sequence for setting the cursor to the given row and column. 

CSI n ; m H

See: https://vt100.net/docs/vt510-rm/CUP.html

func SetCursorStyle added in v0.2.2 

func SetCursorStyle(style int) string

SetCursorStyle (DECSCUSR) returns a sequence for changing the cursor style. 

CSI Ps SP q

Where Ps is the cursor style: 

0: Blinking block
1: Blinking block (default)
2: Steady block
3: Blinking underline
4: Steady underline
5: Blinking bar (xterm)
6: Steady bar (xterm)

See: https://vt100.net/docs/vt510-rm/DECSCUSR.html See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h4-Functions-using-CSI-_-ordered-by-the-final-character-lparen-s-rparen:CSI-Ps-SP-q.1D81

func SetForegroundColor 

func SetForegroundColor(c color.Color) string

SetForegroundColor returns a sequence that sets the default terminal foreground color. 

OSC 10 ; color ST
OSC 10 ; color BEL

Where color is the encoded color number.

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands 

func SetHyperlink(uri string, params ...string) string

SetHyperlink returns a sequence for starting a hyperlink. 

OSC 8 ; Params ; Uri ST
OSC 8 ; Params ; Uri BEL

To reset the hyperlink, omit the URI.

See: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda

func SetIconName 

func SetIconName(s string) string

SetIconName returns a sequence for setting the icon name. 

OSC 1 ; title ST
OSC 1 ; title BEL

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Operating-System-Commands

func SetIconNameWindowTitle 

func SetIconNameWindowTitle(s string) string

SetIconNameWindowTitle returns a sequence for setting the icon name and window title. 

OSC 0 ; title ST
OSC 0 ; title BEL

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Operating-System-Commands

func SetPointerShape added in v0.2.2 

func SetPointerShape(shape string) string

SetPointerShape returns a sequence for changing the mouse pointer cursor shape. Use "default" for the default pointer shape. 

OSC 22 ; Pt ST
OSC 22 ; Pt BEL

Where Pt is the pointer shape name. The name can be anything that the operating system can understand. Some common names are:

  • copy
  • crosshair
  • default
  • ew-resize
  • n-resize
  • text
  • wait

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Operating-System-Commands

func SetPrimaryClipboard 

func SetPrimaryClipboard(d string) string

SetPrimaryClipboard returns a sequence for setting the primary clipboard.

This is equivalent to SetClipboard(PrimaryClipboard, d).

func SetScrollingRegion 

func SetScrollingRegion(t, b int) string

SetScrollingRegion (DECSTBM) sets the top and bottom margins for the scrolling region. The default is the entire screen. 

CSI <top> ; <bottom> r

See: https://vt100.net/docs/vt510-rm/DECSTBM.html

func SetSystemClipboard 

func SetSystemClipboard(d string) string

SetSystemClipboard returns a sequence for setting the system clipboard.

This is equivalent to SetClipboard(SystemClipboard, d).

func SetWindowTitle 

func SetWindowTitle(s string) string

SetWindowTitle returns a sequence for setting the window title. 

OSC 2 ; title ST
OSC 2 ; title BEL

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Operating-System-Commands

func StringWidth 

func StringWidth(s string) int

StringWidth returns the width of a string in cells. This is the number of cells that the string will occupy when printed in a terminal. ANSI escape codes are ignored and wide characters (such as East Asians and emojis) are accounted for.

func Strip 

func Strip(s string) string

Strip removes ANSI escape codes from a string.

func TmuxPassthrough 

func TmuxPassthrough(seq string) string

TmuxPassthrough wraps the given ANSI sequence in a special DCS passthrough sequence to be sent to the outer terminal. This is used to send raw escape sequences to the outer terminal when running inside Tmux. 

DCS tmux ; <escaped-data> ST

Where <escaped-data> is the given sequence in which all occurrences of ESC (0x1b) are doubled i.e. replaced with ESC ESC (0x1b 0x1b).

Note: this needs the `allow-passthrough` option to be set to `on`.

See: https://github.com/tmux/tmux/wiki/FAQ#what-is-the-passthrough-escape-sequence-and-how-do-i-use-it

func Truncate 

func Truncate(s string, length int, tail string) string

Truncate truncates a string to a given length, adding a tail to the end if the string is longer than the given length. This function is aware of ANSI escape codes and will not break them, and accounts for wide-characters (such as East Asians and emojis).

func Wordwrap 

func Wordwrap(s string, limit int, breakpoints string) string

Wordwrap wraps a string or a block of text to a given line length, not breaking word boundaries. This will preserve ANSI escape codes and will account for wide-characters in the string. The breakpoints string is a list of characters that are considered breakpoints for word wrapping. A hyphen (-) is always considered a breakpoint.

Note: breakpoints must be a string of 1-cell wide rune characters.

func Wrap 

func Wrap(s string, limit int, breakpoints string) string

Wrap wraps a string or a block of text to a given line length, breaking word boundaries if necessary. This will preserve ANSI escape codes and will account for wide-characters in the string. The breakpoints string is a list of characters that are considered breakpoints for word wrapping. A hyphen (-) is always considered a breakpoint.

Note: breakpoints must be a string of 1-cell wide rune characters.

Types

type ApcSequence 

type ApcSequence struct {
	// Data contains the raw data of the sequence.
	Data []byte
}

ApcSequence represents an APC sequence.

func (ApcSequence) Bytes 

func (s ApcSequence) Bytes() []byte

Bytes implements Sequence.

func (ApcSequence) Clone 

func (s ApcSequence) Clone() Sequence

Clone implements Sequence.

func (ApcSequence) String 

func (s ApcSequence) String() string

String implements Sequence.

type Attr 

type Attr = int

Attr is a SGR (Select Graphic Rendition) style attribute. 

const (
	ResetAttr                        Attr = 0
	BoldAttr                         Attr = 1
	FaintAttr                        Attr = 2
	ItalicAttr                       Attr = 3
	UnderlineAttr                    Attr = 4
	SlowBlinkAttr                    Attr = 5
	RapidBlinkAttr                   Attr = 6
	ReverseAttr                      Attr = 7
	ConcealAttr                      Attr = 8
	StrikethroughAttr                Attr = 9
	NoBoldAttr                       Attr = 21 // Some terminals treat this as double underline.
	NormalIntensityAttr              Attr = 22
	NoItalicAttr                     Attr = 23
	NoUnderlineAttr                  Attr = 24
	NoBlinkAttr                      Attr = 25
	NoReverseAttr                    Attr = 27
	NoConcealAttr                    Attr = 28
	NoStrikethroughAttr              Attr = 29
	BlackForegroundColorAttr         Attr = 30
	RedForegroundColorAttr           Attr = 31
	GreenForegroundColorAttr         Attr = 32
	YellowForegroundColorAttr        Attr = 33
	BlueForegroundColorAttr          Attr = 34
	MagentaForegroundColorAttr       Attr = 35
	CyanForegroundColorAttr          Attr = 36
	WhiteForegroundColorAttr         Attr = 37
	ExtendedForegroundColorAttr      Attr = 38
	DefaultForegroundColorAttr       Attr = 39
	BlackBackgroundColorAttr         Attr = 40
	RedBackgroundColorAttr           Attr = 41
	GreenBackgroundColorAttr         Attr = 42
	YellowBackgroundColorAttr        Attr = 43
	BlueBackgroundColorAttr          Attr = 44
	MagentaBackgroundColorAttr       Attr = 45
	CyanBackgroundColorAttr          Attr = 46
	WhiteBackgroundColorAttr         Attr = 47
	ExtendedBackgroundColorAttr      Attr = 48
	DefaultBackgroundColorAttr       Attr = 49
	ExtendedUnderlineColorAttr       Attr = 58
	DefaultUnderlineColorAttr        Attr = 59
	BrightBlackForegroundColorAttr   Attr = 90
	BrightRedForegroundColorAttr     Attr = 91
	BrightGreenForegroundColorAttr   Attr = 92
	BrightYellowForegroundColorAttr  Attr = 93
	BrightBlueForegroundColorAttr    Attr = 94
	BrightMagentaForegroundColorAttr Attr = 95
	BrightCyanForegroundColorAttr    Attr = 96
	BrightWhiteForegroundColorAttr   Attr = 97
	BrightBlackBackgroundColorAttr   Attr = 100
	BrightRedBackgroundColorAttr     Attr = 101
	BrightGreenBackgroundColorAttr   Attr = 102
	BrightYellowBackgroundColorAttr  Attr = 103
	BrightBlueBackgroundColorAttr    Attr = 104
	BrightMagentaBackgroundColorAttr Attr = 105
	BrightCyanBackgroundColorAttr    Attr = 106
	BrightWhiteBackgroundColorAttr   Attr = 107

	RGBColorIntroducerAttr      Attr = 2
	ExtendedColorIntroducerAttr Attr = 5
)

SGR (Select Graphic Rendition) style attributes. See: https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters

type BasicColor 

type BasicColor uint8

BasicColor is an ANSI 3-bit or 4-bit color with a value from 0 to 15. 

const (
	// Black is the ANSI black color.
	Black BasicColor = iota

	// Red is the ANSI red color.
	Red

	// Green is the ANSI green color.
	Green

	// Yellow is the ANSI yellow color.
	Yellow

	// Blue is the ANSI blue color.
	Blue

	// Magenta is the ANSI magenta color.
	Magenta

	// Cyan is the ANSI cyan color.
	Cyan

	// White is the ANSI white color.
	White

	// BrightBlack is the ANSI bright black color.
	BrightBlack

	// BrightRed is the ANSI bright red color.
	BrightRed

	// BrightGreen is the ANSI bright green color.
	BrightGreen

	// BrightYellow is the ANSI bright yellow color.
	BrightYellow

	// BrightBlue is the ANSI bright blue color.
	BrightBlue

	// BrightMagenta is the ANSI bright magenta color.
	BrightMagenta

	// BrightCyan is the ANSI bright cyan color.
	BrightCyan

	// BrightWhite is the ANSI bright white color.
	BrightWhite
)

func (BasicColor) RGBA 

func (c BasicColor) RGBA() (uint32, uint32, uint32, uint32)

RGBA returns the red, green, blue and alpha components of the color. It satisfies the color.Color interface.

type Cmd added in v0.2.0 

type Cmd int

Cmd represents a sequence command. This is used to pack/unpack a sequence command with its intermediate and marker characters. Those are commonly found in CSI and DCS sequences.

func (Cmd) Command added in v0.2.0 

func (c Cmd) Command() int

Command returns the command byte of the CSI sequence.

func (Cmd) Intermediate added in v0.2.0 

func (c Cmd) Intermediate() int

Intermediate returns the intermediate byte of the CSI sequence. An intermediate byte is in the range of 0x20-0x2F. This includes these characters from ' ', '!', '"', '#', '$', '%', '&', ”', '(', ')', '*', '+', ',', '-', '.', '/'. Zero is returned if the sequence does not have an intermediate byte.

func (Cmd) Marker added in v0.2.0 

func (c Cmd) Marker() int

Marker returns the marker byte of the CSI sequence. This is always gonna be one of the following '<' '=' '>' '?' and in the range of 0x3C-0x3F. Zero is returned if the sequence does not have a marker.

type Color 

type Color interface {
	color.Color
}

Color is a color that can be used in a terminal. ANSI (including ANSI256) and 24-bit "true colors" fall under this category.

type ControlCode 

type ControlCode byte

ControlCode represents a control code character. This is a character that is not printable and is used to control the terminal. This would be a character in the C0 or C1 set in the range of 0x00-0x1F and 0x80-0x9F.

func (ControlCode) Bytes 

func (c ControlCode) Bytes() []byte

Bytes implements Sequence.

func (ControlCode) Clone 

func (c ControlCode) Clone() Sequence

Clone implements Sequence.

func (ControlCode) String 

func (c ControlCode) String() string

String implements Sequence.

type CsiSequence 

type CsiSequence struct {
	// Params contains the raw parameters of the sequence.
	// This is a slice of integers, where each integer is a 32-bit integer
	// containing the parameter value in the lower 31 bits and a flag in the
	// most significant bit indicating whether there are more sub-parameters.
	Params []int

	// Cmd contains the raw command of the sequence.
	// The command is a 32-bit integer containing the CSI command byte in the
	// lower 8 bits, the private marker in the next 8 bits, and the intermediate
	// byte in the next 8 bits.
	//
	//  CSI ? u
	//
	// Is represented as:
	//
	//  'u' | '?' << 8
	Cmd int
}

CsiSequence represents a control sequence introducer (CSI) sequence.

The sequence starts with a CSI sequence, CSI (0x9B) in a 8-bit environment or ESC [ (0x1B 0x5B) in a 7-bit environment, followed by any number of parameters in the range of 0x30-0x3F, then by any number of intermediate byte in the range of 0x20-0x2F, then finally with a single final byte in the range of 0x20-0x7E. 

CSI P..P I..I F

See ECMA-48 § 5.4.

func (CsiSequence) Bytes 

func (s CsiSequence) Bytes() []byte

Bytes returns the byte representation of the sequence. The bytes will always be in the 7-bit format i.e (ESC [ P..P I..I F).

func (CsiSequence) Clone 

func (s CsiSequence) Clone() Sequence

Clone returns a copy of the CSI sequence.

func (CsiSequence) Command 

func (s CsiSequence) Command() int

Command returns the command byte of the CSI sequence.

func (CsiSequence) HasMore 

func (s CsiSequence) HasMore(i int) bool

HasMore returns true if the parameter has more sub-parameters.

func (CsiSequence) Intermediate 

func (s CsiSequence) Intermediate() int

Intermediate returns the intermediate byte of the CSI sequence. An intermediate byte is in the range of 0x20-0x2F. This includes these characters from ' ', '!', '"', '#', '$', '%', '&', ”', '(', ')', '*', '+', ',', '-', '.', '/'. Zero is returned if the sequence does not have an intermediate byte.

func (CsiSequence) Len 

func (s CsiSequence) Len() int

Len returns the number of parameters in the sequence. This will return the number of parameters in the sequence, excluding any sub-parameters.

func (CsiSequence) Marker 

func (s CsiSequence) Marker() int

Marker returns the marker byte of the CSI sequence. This is always gonna be one of the following '<' '=' '>' '?' and in the range of 0x3C-0x3F. Zero is returned if the sequence does not have a marker.

func (CsiSequence) Param 

func (s CsiSequence) Param(i int) int

Param returns the parameter at the given index. It returns -1 if the parameter does not exist.

func (CsiSequence) Range 

func (s CsiSequence) Range(fn func(i int, param int, hasMore bool) bool)

Range iterates over the parameters of the sequence and calls the given function for each parameter. The function should return false to stop the iteration.

func (CsiSequence) String 

func (s CsiSequence) String() string

String returns a string representation of the sequence. The string will always be in the 7-bit format i.e (ESC [ P..P I..I F).

func (CsiSequence) Subparams 

func (s CsiSequence) Subparams(i int) []int

Subparams returns the sub-parameters of the given parameter. It returns nil if the parameter does not exist.

type DcsSequence 

type DcsSequence struct {
	// Params contains the raw parameters of the sequence.
	// This is a slice of integers, where each integer is a 32-bit integer
	// containing the parameter value in the lower 31 bits and a flag in the
	// most significant bit indicating whether there are more sub-parameters.
	Params []int

	// Data contains the string raw data of the sequence.
	// This is the data between the final byte and the escape sequence terminator.
	Data []byte

	// Cmd contains the raw command of the sequence.
	// The command is a 32-bit integer containing the DCS command byte in the
	// lower 8 bits, the private marker in the next 8 bits, and the intermediate
	// byte in the next 8 bits.
	//
	//  DCS > 0 ; 1 $ r <data> ST
	//
	// Is represented as:
	//
	//  'r' | '>' << 8 | '$' << 16
	Cmd int
}

DcsSequence represents a Device Control String (DCS) escape sequence.

The DCS sequence is used to send device control strings to the terminal. The sequence starts with the C1 control code character DCS (0x9B) or ESC P in 7-bit environments, followed by parameter bytes, intermediate bytes, a command byte, followed by data bytes, and ends with the C1 control code character ST (0x9C) or ESC \ in 7-bit environments.

This follows the parameter string format. See ECMA-48 § 5.4.1

func (DcsSequence) Bytes 

func (s DcsSequence) Bytes() []byte

Bytes returns the byte representation of the sequence. The bytes will always be in the 7-bit format i.e (ESC P p..p i..i F <data> ESC \).

func (DcsSequence) Clone 

func (s DcsSequence) Clone() Sequence

Clone returns a copy of the DCS sequence.

func (DcsSequence) Command 

func (s DcsSequence) Command() int

Command returns the command byte of the CSI sequence.

func (DcsSequence) HasMore 

func (s DcsSequence) HasMore(i int) bool

HasMore returns true if the parameter has more sub-parameters.

func (DcsSequence) Intermediate 

func (s DcsSequence) Intermediate() int

Intermediate returns the intermediate byte of the DCS sequence. An intermediate byte is in the range of 0x20-0x2F. This includes these characters from ' ', '!', '"', '#', '$', '%', '&', ”', '(', ')', '*', '+', ',', '-', '.', '/'. Zero is returned if the sequence does not have an intermediate byte.

func (DcsSequence) Len 

func (s DcsSequence) Len() int

Len returns the number of parameters in the sequence. This will return the number of parameters in the sequence, excluding any sub-parameters.

func (DcsSequence) Marker 

func (s DcsSequence) Marker() int

Marker returns the marker byte of the DCS sequence. This is always gonna be one of the following '<' '=' '>' '?' and in the range of 0x3C-0x3F. Zero is returned if the sequence does not have a marker.

func (DcsSequence) Param 

func (s DcsSequence) Param(i int) int

Param returns the parameter at the given index. It returns -1 if the parameter does not exist.

func (DcsSequence) Range 

func (s DcsSequence) Range(fn func(i int, param int, hasMore bool) bool)

Range iterates over the parameters of the sequence and calls the given function for each parameter. The function should return false to stop the iteration.

func (DcsSequence) String 

func (s DcsSequence) String() string

String returns a string representation of the sequence. The string will always be in the 7-bit format i.e (ESC P p..p i..i f <data> ESC \).

func (DcsSequence) Subparams 

func (s DcsSequence) Subparams(i int) []int

Subparams returns the sub-parameters of the given parameter. It returns nil if the parameter does not exist.

type EscSequence 

type EscSequence int

EscSequence represents an escape sequence.

func (EscSequence) Bytes 

func (e EscSequence) Bytes() []byte

Bytes implements Sequence.

func (EscSequence) Clone 

func (e EscSequence) Clone() Sequence

Clone implements Sequence.

func (EscSequence) Command 

func (e EscSequence) Command() int

Command returns the command byte of the escape sequence.

func (EscSequence) Intermediate 

func (e EscSequence) Intermediate() int

Intermediate returns the intermediate byte of the escape sequence.

func (EscSequence) String 

func (e EscSequence) String() string

String implements Sequence.

type ExtendedColor 

type ExtendedColor uint8

ExtendedColor is an ANSI 256 (8-bit) color with a value from 0 to 255.

func (ExtendedColor) RGBA 

func (c ExtendedColor) RGBA() (uint32, uint32, uint32, uint32)

RGBA returns the red, green, blue and alpha components of the color. It satisfies the color.Color interface.

type Mode added in v0.4.0 

type Mode int

Mode represents an ANSI terminal mode.

func (Mode) String added in v0.4.0 

func (m Mode) String() string

String returns the mode as a string.

type OscSequence 

type OscSequence struct {
	// Data contains the raw data of the sequence including the identifier
	// command.
	Data []byte

	// Cmd contains the raw command of the sequence.
	Cmd int
}

OscSequence represents an OSC sequence.

The sequence starts with a OSC sequence, OSC (0x9D) in a 8-bit environment or ESC ] (0x1B 0x5D) in a 7-bit environment, followed by positive integer identifier, then by arbitrary data terminated by a ST (0x9C) in a 8-bit environment, ESC \ (0x1B 0x5C) in a 7-bit environment, or BEL (0x07) for backwards compatibility. 

OSC Ps ; Pt ST
OSC Ps ; Pt BEL

See ECMA-48 § 5.7.

func (OscSequence) Bytes 

func (s OscSequence) Bytes() []byte

Bytes returns the byte representation of the OSC sequence. To be more compatible with different terminal, this will always return a 7-bit formatted sequence, terminated by BEL.

func (OscSequence) Clone 

func (s OscSequence) Clone() Sequence

Clone returns a copy of the OSC sequence.

func (OscSequence) Command 

func (s OscSequence) Command() int

Command returns the command of the OSC sequence.

func (OscSequence) Params 

func (s OscSequence) Params() []string

Params returns the parameters of the OSC sequence split by ';'. The first element is the identifier command.

func (OscSequence) String 

func (s OscSequence) String() string

String returns the string representation of the OSC sequence. To be more compatible with different terminal, this will always return a 7-bit formatted sequence, terminated by BEL.

type Param added in v0.2.0 

type Param int

Param represents a sequence parameter. Sequence parameters with sub-parameters are packed with the HasMoreFlag set. This is used to unpack the parameters from a CSI and DCS sequences.

func (Param) HasMore added in v0.2.0 

func (s Param) HasMore() bool

HasMore returns true if the parameter has more sub-parameters.

func (Param) Param added in v0.2.0 

func (s Param) Param() int

Param returns the parameter at the given index. It returns -1 if the parameter does not exist.

type Parser 

type Parser struct {
	// Params contains the raw parameters of the sequence.
	// These parameters used when constructing CSI and DCS sequences.
	Params []int

	// Data contains the raw data of the sequence.
	// These data used when constructing OSC, DCS, SOS, PM, and APC sequences.
	Data []byte

	// DataLen keeps track of the length of the data buffer.
	// If DataLen is -1, the data buffer is unlimited and will grow as needed.
	// Otherwise, DataLen is limited by the size of the Data buffer.
	DataLen int

	// ParamsLen keeps track of the number of parameters.
	// This is limited by the size of the Params buffer.
	//
	// This is also used when collecting UTF-8 runes to keep track of the
	// number of rune bytes collected.
	ParamsLen int

	// Cmd contains the raw command along with the private marker and
	// intermediate bytes of the sequence.
	// The first lower byte contains the command byte, the next byte contains
	// the private marker, and the next byte contains the intermediate byte.
	//
	// This is also used when collecting UTF-8 runes treating it as a slice of
	// 4 bytes.
	Cmd int

	// State is the current state of the parser.
	State byte
}

Parser represents a DEC ANSI compatible sequence parser.

It uses a state machine to parse ANSI escape sequences and control characters. The parser is designed to be used with a terminal emulator or similar application that needs to parse ANSI escape sequences and control characters. See package parser for more information.

func GetParser added in v0.3.1 

func GetParser() *Parser

GetParser returns a parser from a sync pool.

func NewParser 

func NewParser(paramsSize, dataSize int) *Parser

NewParser returns a new parser with the given sizes allocated. If dataSize is zero, the underlying data buffer will be unlimited and will grow as needed.

func (*Parser) Advance 

func (p *Parser) Advance(dispatcher ParserDispatcher, b byte, more bool) parser.Action

Advance advances the parser with the given dispatcher and byte.

func (*Parser) Parse 

func (p *Parser) Parse(dispatcher ParserDispatcher, b []byte)

Parse parses the given dispatcher and byte buffer.

func (*Parser) Reset 

func (p *Parser) Reset()

Reset resets the parser to its initial state.

func (*Parser) StateName 

func (p *Parser) StateName() string

StateName returns the name of the current state.

type ParserDispatcher 

type ParserDispatcher func(Sequence)

ParserDispatcher is a function that dispatches a sequence.

type PmSequence 

type PmSequence struct {
	// Data contains the raw data of the sequence.
	Data []byte
}

PmSequence represents a PM sequence.

func (PmSequence) Bytes 

func (s PmSequence) Bytes() []byte

Bytes implements Sequence.

func (PmSequence) Clone 

func (s PmSequence) Clone() Sequence

Clone implements Sequence.

func (PmSequence) String 

func (s PmSequence) String() string

String implements Sequence.

type PrivateMode added in v0.4.0 

type PrivateMode int

PrivateMode represents a private DEC terminal mode.

func (PrivateMode) String added in v0.4.0 

func (m PrivateMode) String() string

String returns the private mode as a string.

type Rune 

type Rune rune

Rune represents a printable character.

func (Rune) Bytes 

func (r Rune) Bytes() []byte

Bytes implements Sequence.

func (Rune) Clone 

func (r Rune) Clone() Sequence

Clone implements Sequence.

func (Rune) String 

func (r Rune) String() string

String implements Sequence.

type Sequence 

type Sequence interface {
	// String returns the string representation of the sequence.
	String() string
	// Bytes returns the byte representation of the sequence.
	Bytes() []byte
	// Clone returns a copy of the sequence.
	Clone() Sequence
}

Sequence represents an ANSI sequence. This can be a control sequence, escape sequence, a printable character, etc.

type SosSequence 

type SosSequence struct {
	// Data contains the raw data of the sequence.
	Data []byte
}

SosSequence represents a SOS sequence.

func (SosSequence) Bytes 

func (s SosSequence) Bytes() []byte

Bytes implements Sequence.

func (SosSequence) Clone 

func (s SosSequence) Clone() Sequence

Clone implements Sequence.

func (SosSequence) String 

func (s SosSequence) String() string

String implements Sequence.

type State added in v0.2.0 

type State = byte

State represents the state of the ANSI escape sequence parser used by DecodeSequence. 

const (
	NormalState State = iota
	MarkerState
	ParamsState
	IntermedState
	EscapeState
	StringState
)

ANSI escape sequence states used by DecodeSequence.

type Style 

type Style []string

Style represents an ANSI SGR (Select Graphic Rendition) style.

func (Style) BackgroundColor 

func (s Style) BackgroundColor(c Color) Style

BackgroundColor appends the background color style attribute to the style.

func (Style) Bold 

func (s Style) Bold() Style

Bold appends the bold style attribute to the style.

func (Style) Conceal 

func (s Style) Conceal() Style

Conceal appends the conceal style attribute to the style.

func (Style) CurlyUnderline 

func (s Style) CurlyUnderline() Style

CurlyUnderline appends the curly underline style attribute to the style. This is a convenience method for UnderlineStyle(CurlyUnderlineStyle).

func (Style) DashedUnderline 

func (s Style) DashedUnderline() Style

DashedUnderline appends the dashed underline style attribute to the style. This is a convenience method for UnderlineStyle(DashedUnderlineStyle).

func (Style) DefaultBackgroundColor 

func (s Style) DefaultBackgroundColor() Style

DefaultBackgroundColor appends the default background color style attribute to the style.

func (Style) DefaultForegroundColor 

func (s Style) DefaultForegroundColor() Style

DefaultForegroundColor appends the default foreground color style attribute to the style.

func (Style) DefaultUnderlineColor 

func (s Style) DefaultUnderlineColor() Style

DefaultUnderlineColor appends the default underline color style attribute to the style.

func (Style) DottedUnderline 

func (s Style) DottedUnderline() Style

DottedUnderline appends the dotted underline style attribute to the style. This is a convenience method for UnderlineStyle(DottedUnderlineStyle).

func (Style) DoubleUnderline 

func (s Style) DoubleUnderline() Style

DoubleUnderline appends the double underline style attribute to the style. This is a convenience method for UnderlineStyle(DoubleUnderlineStyle).

func (Style) Faint 

func (s Style) Faint() Style

Faint appends the faint style attribute to the style.

func (Style) ForegroundColor 

func (s Style) ForegroundColor(c Color) Style

ForegroundColor appends the foreground color style attribute to the style.

func (Style) Italic 

func (s Style) Italic() Style

Italic appends the italic style attribute to the style. 

func (s Style) NoBlink() Style

NoBlink appends the no blink style attribute to the style.

func (Style) NoBold 

func (s Style) NoBold() Style

NoBold appends the no bold style attribute to the style.

func (Style) NoConceal added in v0.1.2 

func (s Style) NoConceal() Style

NoConceal appends the no conceal style attribute to the style.

func (Style) NoItalic 

func (s Style) NoItalic() Style

NoItalic appends the no italic style attribute to the style.

func (Style) NoReverse 

func (s Style) NoReverse() Style

NoReverse appends the no reverse style attribute to the style.

func (Style) NoStrikethrough 

func (s Style) NoStrikethrough() Style

NoStrikethrough appends the no strikethrough style attribute to the style.

func (Style) NoUnderline 

func (s Style) NoUnderline() Style

NoUnderline appends the no underline style attribute to the style.

func (Style) NormalIntensity 

func (s Style) NormalIntensity() Style

NormalIntensity appends the normal intensity style attribute to the style. 

func (s Style) RapidBlink() Style

RapidBlink appends the rapid blink style attribute to the style.

func (Style) Reset 

func (s Style) Reset() Style

Reset appends the reset style attribute to the style.

func (Style) Reverse 

func (s Style) Reverse() Style

Reverse appends the reverse style attribute to the style. 

func (s Style) SlowBlink() Style

SlowBlink appends the slow blink style attribute to the style.

func (Style) Strikethrough 

func (s Style) Strikethrough() Style

Strikethrough appends the strikethrough style attribute to the style.

func (Style) String 

func (s Style) String() string

String returns the ANSI SGR (Select Graphic Rendition) style sequence for the given style.

func (Style) Styled 

func (s Style) Styled(str string) string

Styled returns a styled string with the given style applied.

func (Style) Underline 

func (s Style) Underline() Style

Underline appends the underline style attribute to the style.

func (Style) UnderlineColor 

func (s Style) UnderlineColor(c Color) Style

UnderlineColor appends the underline color style attribute to the style.

func (Style) UnderlineStyle added in v0.3.0 

func (s Style) UnderlineStyle(u UnderlineStyle) Style

UnderlineStyle appends the underline style attribute to the style.

type TrueColor 

type TrueColor uint32

TrueColor is a 24-bit color that can be used in the terminal. This can be used to represent RGB colors.

For example, the color red can be represented as: 

TrueColor(0xff0000)

func (TrueColor) RGBA 

func (c TrueColor) RGBA() (uint32, uint32, uint32, uint32)

RGBA returns the red, green, blue and alpha components of the color. It satisfies the color.Color interface.

type UnderlineStyle added in v0.3.0 

type UnderlineStyle = int

UnderlineStyle represents an ANSI SGR (Select Graphic Rendition) underline style. 

const (
	// NoUnderlineStyle is the default underline style.
	NoUnderlineStyle UnderlineStyle = iota
	// SingleUnderlineStyle is a single underline style.
	SingleUnderlineStyle
	// DoubleUnderlineStyle is a double underline style.
	DoubleUnderlineStyle
	// CurlyUnderlineStyle is a curly underline style.
	CurlyUnderlineStyle
	// DottedUnderlineStyle is a dotted underline style.
	DottedUnderlineStyle
	// DashedUnderlineStyle is a dashed underline style.
	DashedUnderlineStyle
)

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.