README

zzcsi builds.sr.ht status GoDoc go.dev reference

Package zzcsi implements the Control Sequence Introducer (CSI) functions supported by Xterm-compatible terminals. The most commonly used functions are to erase a line or the screen, manipulate the cursor or set the display attributes such as foreground and background colors, bold or italics, but many more functions are available. See the xterm documentation for more information on CSI sequences.

See the package documentation for details, API reference and usage example (alternatively, on pkg.go.dev).

This is a package in the zzterm family of Go packages, which aim to help build terminal-based programs with a focus on speed and memory efficiency.

Benchmarks

When using a buffer of sufficient capacity, CSI.AppendFunc can append the CSI escape sequence without allocation.

benchmark                       iter      time/iter   bytes alloc        allocs
---------                       ----      ---------   -----------        ------
BenchmarkCSI/Func-4          9971707   116.00 ns/op       24 B/op   2 allocs/op
BenchmarkCSI/FuncString-4    8935776   135.00 ns/op       32 B/op   3 allocs/op
BenchmarkCSI/AppendFunc-4   20534767    58.80 ns/op        0 B/op   0 allocs/op
BenchmarkCSI/DecodeArgs-4   20537282    55.00 ns/op        0 B/op   0 allocs/op

License

The BSD 3-Clause license.

Documentation

Overview

Package zzcsi implements functions for the execution of Control Sequence Introducer (CSI) sequences on xterm-compatible terminals. The complete documentation of CSI functions is available at [1].

Usage

All CSI functions are represented by the CSI type and a corresponding constant. Call Func to get the byte sequence to write to the terminal to execute a given CSI function. FuncString is the same but returns a string that can be easily inserted e.g. in a fmt.Fprintf call (for example, to wrap some text in a bold or colored attribute before resetting it to normal).

For efficient generation of CSI sequences, use AppendFunc to append the bytes to a caller-provided buffer.

[1]: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Functions-using-CSI-_-ordered-by-the-final-character_s_

Index

Examples

Constants

View Source
const (
	EraseScrBelow    = 0
	EraseScrAbove    = 1
	EraseScrAll      = 2
	EraseScrSavedLns = 3

	SelEraseScrBelow    = 0
	SelEraseScrAbove    = 1
	SelEraseScrAll      = 2
	SelEraseScrSavedLns = 3

	EraseLnRight = 0
	EraseLnLeft  = 1
	EraseLnAll   = 2

	SelEraseLnRight = 0
	SelEraseLnLeft  = 1
	SelEraseLnAll   = 2

	GraphicsAttrItemNumColorRegs = 1
	GraphicsAttrItemSixelPx      = 2
	GraphicsAttrItemReGISPx      = 3
	GraphicsAttrActionRead       = 1
	GraphicsAttrActionRst        = 2
	GraphicsAttrActionSet        = 3
	GraphicsAttrActionReadMax    = 4

	RstTitleModeSetLabelsHex  = 0
	RstTitleModeQryLabelsHex  = 1
	RstTitleModeSetLabelsUTF8 = 2
	RstTitleModeQryLabelsUTF8 = 3

	TabClrCurrentCol = 0
	TabClrAll        = 3

	SetModeKeybAction = 2
	SetModeIns        = 4
	SetModeSendRecv   = 12
	SetModeAutoNewln  = 20

	SetPrvModeAppCurKeys       = 1
	SetPrvModeUSASCIIChSet     = 2
	SetPrvMode132Cols          = 3
	SetPrvModeSmoothScrl       = 4
	SetPrvModeRevVid           = 5
	SetPrvModeOrig             = 6
	SetPrvModeAutoWrap         = 7
	SetPrvModeAutoRep          = 8
	SetPrvModeX10Mous          = 9
	SetPrvModeToolbar          = 10
	SetPrvModeBlinkATT         = 12
	SetPrvModeBlink            = 13
	SetPrvModeXORBlink         = 14
	SetPrvModePrnFF            = 18
	SetPrvModePrnExtFullScr    = 19
	SetPrvModeShowCur          = 25
	SetPrvModeShowScrlbar      = 30
	SetPrvModeFontShFn         = 35
	SetPrvModeTektronix        = 38
	SetPrvModeAllow80_132      = 40
	SetPrvModeMoreFix          = 41
	SetPrvModeNatlReplChSet    = 42
	SetPrvModeMargBl           = 44
	SetPrvModeRevWrap          = 45
	SetPrvModeLog              = 46
	SetPrvModeAltScrBuf        = 47
	SetPrvModeAppKeypad        = 66
	SetPrvModeBackArwBksp      = 67
	SetPrvModeLeftRightMarg    = 69
	SetPrvModeSixelScrl        = 80
	SetPrvModeNoClrScr         = 95
	SetPrvModeX11MousBtn       = 1000
	SetPrvModeX11MousHilite    = 1001
	SetPrvModeX11MousCell      = 1002
	SetPrvModeX11MousAll       = 1003
	SetPrvModeFocus            = 1004
	SetPrvModeUTF8Mous         = 1005
	SetPrvModeSGRMous          = 1006
	SetPrvModeAltScrl          = 1007
	SetPrvModeScrlBotOnOut     = 1010
	SetPrvModeScrlBotOnKey     = 1011
	SetPrvModeURXVTMous        = 1015
	SetPrvModeMetaKey          = 1034
	SetPrvModeAltNumLock       = 1035
	SetPrvModeESCOnMeta        = 1036
	SetPrvModeDELKeypad        = 1037
	SetPrvModeESCOnAlt         = 1039
	SetPrvModeKeepSel          = 1040
	SetPrvModeUseClipbSel      = 1041
	SetPrvModeBlUrg            = 1042
	SetPrvModePopOnBl          = 1043
	SetPrvModeReuseClipb       = 1044
	SetPrvModeSwitchAltScrBuf  = 1046
	SetPrvModeUseAltScrBuf     = 1047
	SetPrvModeSaveCur          = 1048
	SetPrvModeSaveCurAltScrBuf = 1049
	SetPrvModeTinfoTcap        = 1050
	SetPrvModeSun              = 1051
	SetPrvModeHP               = 1052
	SetPrvModeSCO              = 1053
	SetPrvModeLegacyKeyb       = 1060
	SetPrvModeVT220Keyb        = 1061
	SetPrvModeBrackPaste       = 2004

	MediaCopyPrnScr      = 0
	MediaCopyPrnContrOff = 4
	MediaCopyPrnContrOn  = 5
	MediaCopyHTMLScr     = 10
	MediaCopySVGScr      = 11

	MediaCopyDECPrnCurLn    = 1
	MediaCopyDECAutoPrnOff  = 4
	MediaCopyDECAutoPrnOn   = 5
	MediaCopyDECPrnCompDisp = 10
	MediaCopyDECPrnAll      = 11

	RstModeKeybAction = 2
	RstModeRepl       = 4
	RstModeSendRecv   = 12
	RstModeNormNewln  = 20

	RstPrvModeNormCurKeys       = 1
	RstPrvModeVT52              = 2
	RstPrvMode80Cols            = 3
	RstPrvModeJumpScrl          = 4
	RstPrvModeNormVid           = 5
	RstPrvModeNormCur           = 6
	RstPrvModeNoAutoWrap        = 7
	RstPrvModeNoAutoRep         = 8
	RstPrvModeNoX10Mous         = 9
	RstPrvModeNoToolbar         = 10
	RstPrvModeNoBlinkATT        = 12
	RstPrvModeNoBlink           = 13
	RstPrvModeNoXORBlink        = 14
	RstPrvModeNoPrnFF           = 18
	RstPrvModePrnScrlRegion     = 19
	RstPrvModeHideCur           = 25
	RstPrvModeHideScrlbar       = 30
	RstPrvModeNoFontShFn        = 35
	RstPrvModeDisallow80_132    = 40
	RstPrvModeNoMoreFix         = 41
	RstPrvModeNoNatlReplChSet   = 42
	RstPrvModeNoMargBl          = 44
	RstPrvModeNoRevWrap         = 45
	RstPrvModeNoLog             = 46
	RstPrvModeNormScrBuf        = 47
	RstPrvModeNumKeypad         = 66
	RstPrvModeBackArwDel        = 67
	RstPrvModeNoLeftRightMarg   = 69
	RstPrvModeNoSixelScrl       = 80
	RstPrvModeClrScr            = 95
	RstPrvModeNoX11MousBtn      = 1000
	RstPrvModeNoX11MousHilite   = 1001
	RstPrvModeNoX11MousCell     = 1002
	RstPrvModeNoX11MousAll      = 1003
	RstPrvModeNoFocus           = 1004
	RstPrvModeNoUTF8Mous        = 1005
	RstPrvModeNoSGRMous         = 1006
	RstPrvModeNoAltScrl         = 1007
	RstPrvModeNoScrlBotOnOut    = 1010
	RstPrvModeNoScrlBotOnKey    = 1011
	RstPrvModeNoURXVTMous       = 1015
	RstPrvModeNoMetaKey         = 1034
	RstPrvModeNoAltNumLock      = 1035
	RstPrvModeNoESCOnMeta       = 1036
	RstPrvModeVT220RemKeypad    = 1037
	RstPrvModeNoESCOnAlt        = 1039
	RstPrvModeNoKeepSel         = 1040
	RstPrvModeUsePriSel         = 1041
	RstPrvModeNoBlUrg           = 1042
	RstPrvModeNoPopOnBl         = 1043
	RstPrvModeNoSwitchAltScrBuf = 1046
	RstPrvModeUseNormScrBuf     = 1047
	RstPrvModeRstrCur           = 1048
	RstPrvModeRstrCurNormScrBuf = 1049
	RstPrvModeTinfoTcap         = 1050
	RstPrvModeSun               = 1051
	RstPrvModeHP                = 1052
	RstPrvModeSCO               = 1053
	RstPrvModeLegacyKeyb        = 1060
	RstPrvModeSunPCKeyb         = 1061
	RstPrvModeBrackPaste        = 2004

	ChAttrNorm             = 0
	ChAttrBold             = 1
	ChAttrDim              = 2
	ChAttrItalics          = 3
	ChAttrUnderline        = 4
	ChAttrBlink            = 5
	ChAttrInverse          = 7
	ChAttrHidden           = 8
	ChAttrCrossed          = 9
	ChAttrDoubleUnderline  = 21
	ChAttrNoBoldDim        = 22
	ChAttrNoItalics        = 23
	ChAttrNoUnderline      = 24
	ChAttrNoBlink          = 25
	ChAttrNoInverse        = 27
	ChAttrNoHidden         = 28
	ChAttrNoCrossed        = 29
	ChAttrFgBlack          = 30
	ChAttrFgRed            = 31
	ChAttrFgGreen          = 32
	ChAttrFgYellow         = 33
	ChAttrFgBlue           = 34
	ChAttrFgMagenta        = 35
	ChAttrFgCyan           = 36
	ChAttrFgWhite          = 37
	ChAttrFgDef            = 39
	ChAttrBgBlack          = 40
	ChAttrBgRed            = 41
	ChAttrBgGreen          = 42
	ChAttrBgYellow         = 43
	ChAttrBgBlue           = 44
	ChAttrBgMagenta        = 45
	ChAttrBgCyan           = 46
	ChAttrBgWhite          = 47
	ChAttrBgDef            = 49
	ChAttrFgBlackBright    = 90
	ChAttrFgRedBright      = 91
	ChAttrFgGreenBright    = 92
	ChAttrFgYellowBright   = 93
	ChAttrFgBlueBright     = 94
	ChAttrFgMagentaBright  = 95
	ChAttrFgCyanBright     = 96
	ChAttrFgWhiteBright    = 97
	ChAttrBgBlackBright    = 100
	ChAttrBgRedBright      = 101
	ChAttrBgGreenBright    = 102
	ChAttrBgYellowBright   = 103
	ChAttrBgBlueBright     = 104
	ChAttrBgMagentaBright  = 105
	ChAttrBgCyanBright     = 106
	ChAttrBgWhiteBright    = 107
	ChAttrNo16ColorFgBgDef = 100

	SetKeyModKeyb      = 0
	SetKeyModCurKeys   = 1
	SetKeyModFnKeys    = 2
	SetKeyModOtherKeys = 4

	RstKeyModKeyb      = 0
	RstKeyModCurKeys   = 1
	RstKeyModFnKeys    = 2
	RstKeyModOtherKeys = 4

	DevStatReport = 5
	DevStatCurPos = 6

	DisKeyModKeyb      = 0
	DisKeyModCurKeys   = 1
	DisKeyModFnKeys    = 2
	DisKeyModOtherKeys = 4

	DevStatDECCurPos         = 6
	DevStatDECPrn            = 15
	DevStatDECUDK            = 25
	DevStatDECKeyb           = 26
	DevStatDECLocator        = 53
	DevStatDECLocatorType    = 56
	DevStatDECMacroSpc       = 62
	DevStatDECMemChecksum    = 63
	DevStatDECDataIntegrity  = 75
	DevStatDECMultiSsnConfig = 85

	PtrModeNeverHide             = 0
	PtrModeHideIfNoMousTrack     = 1
	PtrModeAlwaysHideExceptLeave = 2
	PtrModeAlwaysHide            = 3

	SetConfLvlVT100 = 61
	SetConfLvlVT200 = 62
	SetConfLvlVT300 = 63
	SetConfLvlVT400 = 65
	SetConfLvlVT500 = 65
	SetConfLvl8Bit  = 0
	SetConfLvl7Bit  = 1
	SetConfLvl8bit2 = 2

	LdLEDsClrAll     = 0
	LdLEDsNumLock    = 1
	LdLEDsCapsLock   = 2
	LdLEDsScrlLock   = 3
	LdLEDsNoNumLock  = 21
	LdLEDsNoCapsLock = 22
	LdLEDsNoScrlLock = 23

	SetCurStyleBlinkBlock       = 0
	SetCurStyleBlinkBlockDef    = 1
	SetCurStyleNoBlinkBlock     = 2
	SetCurStyleBlinkUnderline   = 3
	SetCurStyleNoBlinkUnderline = 4
	SetCurStyleBlinkBar         = 5
	SetCurStyleNoBlinkBar       = 6

	ChProtAttrCanEraseDef = 0
	ChProtAttrCannotErase = 1
	ChProtAttrCanErase    = 2

	SetTitleModeSetLabelsHex  = 0
	SetTitleModeQryLabelsHex  = 1
	SetTitleModeSetLabelsUTF8 = 2
	SetTitleModeQryLabelsUTF8 = 3

	SetBlVolOff   = 0
	SetBlVolOff2  = 1
	SetBlVolLow   = 2
	SetBlVolLow2  = 3
	SetBlVolLow3  = 4
	SetBlVolHigh  = 5
	SetBlVolHigh2 = 6
	SetBlVolHigh3 = 7
	SetBlVolHigh4 = 8

	SetMargBlVolHigh  = 0
	SetMargBlVolHigh2 = 5
	SetMargBlVolHigh3 = 6
	SetMargBlVolHigh4 = 7
	SetMargBlVolHigh5 = 8
	SetMargBlVolOff   = 1
	SetMargBlVolLow   = 2
	SetMargBlVolLow2  = 3
	SetMargBlVolLow3  = 4

	PresStatErr     = 0
	PresStatCurInfo = 1
	PresStatTabStop = 2

	SelAttrChgExtStartToEnd  = 0
	SelAttrChgExtStartToEnd2 = 1
	SelAttrChgExtRectExact   = 2

	SelChecksumNoNegate             = 0
	SelChecksumNoReportVT100VidAttr = 1
	SelChecksumNoOmitBlanks         = 2
	SelChecksumOmitUninitCells      = 3
	SelChecksumNoMaskCell8          = 4
	SelChecksumNoMaskCell7          = 5

	LocatorRptOff     = 0
	LocatorRptOn      = 1
	LocatorRptOnce    = 2
	LocatorRptUnitDef = 0
	LocatorRptUnitPx  = 1
	LocatorRptUnitCh  = 2

	SelLocatorEvtsExplicit  = 0
	SelLocatorEvtsBtnDown   = 1
	SelLocatorEvtsNoBtnDown = 2
	SelLocatorEvtsBtnUp     = 3
	SelLocatorEvtsNoBtnUp   = 4

	PushVidAttrBold            = 1
	PushVidAttrDim             = 2
	PushVidAttrItalics         = 3
	PushVidAttrUnderline       = 4
	PushVidAttrBlink           = 5
	PushVidAttrInverse         = 7
	PushVidAttrHidden          = 8
	PushVidAttrCrossed         = 9
	PushVidAttrFgColor         = 10
	PushVidAttrBgColor         = 11
	PushVidAttrDoubleUnderline = 21

	ColsPerPgDef = 0
	ColsPerPg80  = 80
	ColsPerPg132 = 132
)

    List of known parameter constants for specific CSI functions.

    Variables

    This section is empty.

    Functions

    func DecodeArgs

    func DecodeArgs(b []byte, dst ...*uint64) int

      DecodeArgs decodes the numerical arguments of an escape sequence into the integer points provided in dst. It returns the number of arguments decoded, which is <= len(dst). It starts decoding arguments at the first byte that is a decimal digit, and continues decoding numbers as long as they are separated by semicolons.

      This is useful for some csi functions that trigger a reply from the terminal. Such a reply can be read e.g. with git.sr.ht/~mna/zzterm (which would read it as a key of type KeyESCSeq, and then the Input.Bytes can be passed as b to this function to get the arguments). A common example of such a reply is for the DevStat CSI function when DevStatCurPos is requested (the cursor position). The terminal replies with "CSI r ; c R" where "r" is the row and "c" the column. DecodeArgs can be used to get the row and column values from the reply bytes.

      Example
      Output:
      
      

      func IsCSI

      func IsCSI(b []byte) bool

        IsCSI returns true if b starts with the Control Sequence Introducer bytes ("\x1b[", or <ESC> followed by '[').

        func IsCSIString

        func IsCSIString(s string) bool

          IsCSIString returns true if s starts with the Control Sequence Introducer prefix (see IsCSI for details).

          Types

          type CSI

          type CSI byte

            CSI represents a Control Sequence Introducer function as supported by xterm-compatible terminals.

            See [1] for details.

            [1]: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Functions-using-CSI-_-ordered-by-the-final-character_s_
            
            const (
            	InsCh CSI = iota
            	ShLeft
            	CurUp
            	ShRight
            	CurDown
            	CurFwd
            	CurBwd
            	CurNextLn
            	CurPrevLn
            	CurColAbs
            	CurPos
            	CurFwdTab
            	EraseScr
            	SelEraseScr
            	EraseLn
            	SelEraseLn
            	InsLn
            	DelLn
            	DelCh
            	ScrlUp
            	GraphicsAttr
            	GraphicsAttr2Vals
            	ScrlDown
            	InitHiliteMous
            	RstTitleMode
            	EraseCh
            	CurBwdTab
            	ChColAbs
            	ChColRel
            	RepCh
            	PriDevAttr
            	TerDevAttr
            	SecDevAttr
            	ChLnAbs
            	ChLnRel
            	ChLnCol
            	TabClr
            	SetMode
            	SetPrvMode
            	MediaCopy
            	MediaCopyDEC
            	RstMode
            	RstPrvMode
            	ChAttr
            	ChAttrFgIRGB
            	ChAttrBgIRGB
            	ChAttrFgIx
            	ChAttrBgIx
            	ChAttrFgRGB
            	ChAttrBgRGB
            	SetKeyMod
            	RstKeyMod
            	DevStat
            	DisKeyMod
            	DevStatDEC
            	PtrMode
            	SoftRst
            	SetConfLvl
            	ANSIMode
            	DECPrvMode
            	PushVidAttrAlias
            	LdLEDs
            	SetCurStyle
            	ChProtAttr
            	PopVidAttrAlias
            	SetScrlRegn
            	RstrDECPrvMode
            	SetAttrRect
            	SaveCur
            	LeftRightMarg
            	SaveDECPrvMode
            	WinOps
            	SetTitleMode
            	SetBlVol
            	RevAttrRect
            	RstrCur
            	SetMargBlVol
            	CopyRect
            	PresStat
            	FilterRect
            	TermParams
            	SelAttrChgExt
            	FillRect
            	SelChecksum
            	ChecksumRect
            	LocatorRpt
            	EraseRect
            	SelLocatorEvts
            	PushVidAttr
            	SelEraseRect
            	RptSGR
            	ColsPerPg
            	LocatorPos
            	LnsPerScr
            	PopVidAttr
            	InsCol
            	DelCol
            )

              List of CSI functions.

              func (CSI) AppendFunc

              func (c CSI) AppendFunc(b []byte, args ...int) []byte

                AppendFunc is like Func except it appends the resulting sequence of bytes to b and returns the new slice. If b has a large enough capacity to hold the sequence, no allocation is made.

                func (CSI) Func

                func (c CSI) Func(args ...int) []byte

                  Func returns the sequence of bytes to execute this CSI function with the provided numeric arguments. Note that no validation is done regarding the number of arguments - if the function supports a single argument, only one will be inserted, if it supports many, all expected arguments will be inserted. If less arguments than those expected are provided, the remaining arguments are left unspecified (which usually results in a default value fallback).

                  func (CSI) FuncString

                  func (c CSI) FuncString(args ...int) string

                    FuncString is like Func except it returns a string value. This can be useful to insert e.g. in a printf-style string.

                    Example
                    Output:
                    
                    

                    Source Files