zztermcsi

package module
v0.0.0-...-773d5a4 Latest Latest
Warning

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

Go to latest
Published: Apr 3, 2020 License: BSD-3-Clause Imports: 3 Imported by: 0

README

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

Package zztermcsi 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          9259478   118.00 ns/op       24 B/op   2 allocs/op
BenchmarkCSI/FuncString-4    9003938   133.00 ns/op       32 B/op   3 allocs/op
BenchmarkCSI/AppendFunc-4   20808049    58.40 ns/op        0 B/op   0 allocs/op

License

The BSD 3-Clause license.

Documentation

Overview

Package zztermcsi 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 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
package main

import (
	"fmt"

	"git.sr.ht/~mna/zztermcsi"
)

func main() {
	bold := zztermcsi.ChAttr.FuncString(zztermcsi.ChAttrBold)
	norm := zztermcsi.ChAttr.FuncString(zztermcsi.ChAttrNoBoldDim)
	blueBlink := zztermcsi.ChAttr.FuncString(zztermcsi.ChAttrFgBlue, zztermcsi.ChAttrBlink)
	defNoBlink := zztermcsi.ChAttr.FuncString(zztermcsi.ChAttrFgDef, zztermcsi.ChAttrNoBlink)
	fmt.Printf("%sHello%s, %sworld!%s\n", bold, norm, blueBlink, defNoBlink)
}
Output:

Jump to

Keyboard shortcuts

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