README
¶
zzcsi 
- Canonical repository: https://git.sr.ht/~mna/zzcsi
- Issues: https://todo.sr.ht/~mna/zzcsi
- Builds: https://builds.sr.ht/~mna/zzcsi
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 ¶
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 ¶
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 ¶
IsCSI returns true if b starts with the Control Sequence Introducer bytes ("\x1b[", or <ESC> followed by '[').
func IsCSIString ¶
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 ¶
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 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 ¶
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