zzcsi

package module
Version: v0.1.0 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

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

import (
	"fmt"
	"io"

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

func main() {
	// Let's pretend that term is a terminal in raw mode
	var term io.ReadWriter

	// a typical usage would be to send a CSI function to get the cursor
	// position:
	//
	fn := zzcsi.DevStat.Func(zzcsi.DevStatCurPos)
	fmt.Fprint(term, fn)
	//
	// and then get the reply using the zzterm package, e.g.:
	//
	//  for {
	//  	k, err := input.ReadKey(term)
	//  	if err != nil {
	//  		log.Panic(err)
	//  	}
	//
	//  	switch k.Type() {
	//    case zzterm.KeyESCSeq:
	//      b := input.Bytes()
	//  	}
	//  }
	//
	// Let's pretend that's how we got that reply byte sequence:
	b := []byte("\x1b[12;33R")
	var row, col uint64
	n := zzcsi.DecodeArgs(b, &row, &col)
	if n != 2 {
		// oops, did not get both arguments, fail
	}
	// otherwise use row and col
}
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
package main

import (
	"fmt"

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

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

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL