BREAKING: refactor modes and cursor

ansi/cursor.go

@@ -147,13 +147,13 @@ func CursorPreviousLine(n int) string {
 	return "\x1b[" + s + "F"
 }
 
-// MoveCursor (CUP) returns a sequence for moving the cursor to the given row
-// and column.
+// 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 MoveCursor(row, col int) string {
+func SetCursorPosition(col, row int) string {
 	if row < 0 {
 		row = 0
 	}
@@ -163,9 +163,9 @@ func MoveCursor(row, col int) string {
 	return "\x1b[" + strconv.Itoa(row) + ";" + strconv.Itoa(col) + "H"
 }
 
-// MoveCursorOrigin is a sequence for moving the cursor to the upper left
-// corner of the screen. This is equivalent to MoveCursor(1, 1).
-const MoveCursorOrigin = "\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)`.
+const CursorOrigin = "\x1b[1;1H"
 
 // SaveCursorPosition (SCP or SCOSC) is a sequence for saving the cursor
 // position.

ansi/mode.go

@@ -1,5 +1,7 @@
 package ansi
 
+import "strconv"
+
 // This file define uses multiple sequences to set (SM), reset (RM), and request
 // (DECRQM) different ANSI and DEC modes.
 //
@@ -21,110 +23,126 @@ package ansi
 // Where Pa is the mode number, and Ps is the mode value.
 // See: https://vt100.net/docs/vt510-rm/DECRPM.html
 
+// Mode represents an ANSI terminal mode.
+type Mode int
+
+// String returns the mode as a string.
+func (m Mode) String() string {
+	return strconv.Itoa(int(m))
+}
+
+// PrivateMode represents a private DEC terminal mode.
+type PrivateMode int
+
+// String returns the private mode as a string.
+func (m PrivateMode) String() string {
+	return "?" + strconv.Itoa(int(m))
+}
+
 // 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
 const (
-	CursorKeysMode = "?1"
+	CursorKeysMode = PrivateMode(1)
 
-	EnableCursorKeys  = "\x1b[" + CursorKeysMode + "h"
-	DisableCursorKeys = "\x1b[" + CursorKeysMode + "l"
-	RequestCursorKeys = "\x1b[" + CursorKeysMode + "$p"
+	EnableCursorKeys  = "\x1b[?1h"
+	DisableCursorKeys = "\x1b[?1l"
+	RequestCursorKeys = "\x1b[?1$p"
 )
 
 // Text Cursor Enable Mode (DECTCEM) is a mode that shows/hides the cursor.
 //
 // See: https://vt100.net/docs/vt510-rm/DECTCEM.html
 const (
-	CursorVisibilityMode = "?25"
+	CursorEnableMode = PrivateMode(25)
 
-	ShowCursor              = "\x1b[" + CursorVisibilityMode + "h"
-	HideCursor              = "\x1b[" + CursorVisibilityMode + "l"
-	RequestCursorVisibility = "\x1b[" + CursorVisibilityMode + "$p"
+	ShowCursor              = "\x1b[?25h"
+	HideCursor              = "\x1b[?25l"
+	RequestCursorVisibility = "\x1b[?25$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
 const (
-	MouseMode = "?1000"
+	MouseMode = PrivateMode(1000)
 
-	EnableMouse  = "\x1b[" + MouseMode + "h"
-	DisableMouse = "\x1b[" + MouseMode + "l"
-	RequestMouse = "\x1b[" + MouseMode + "$p"
+	EnableMouse  = "\x1b[?1000h"
+	DisableMouse = "\x1b[?1000l"
+	RequestMouse = "\x1b[?1000$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
 const (
-	MouseHiliteMode = "?1001"
+	MouseHiliteMode = PrivateMode(1001)
 
-	EnableMouseHilite  = "\x1b[" + MouseHiliteMode + "h"
-	DisableMouseHilite = "\x1b[" + MouseHiliteMode + "l"
-	RequestMouseHilite = "\x1b[" + MouseHiliteMode + "$p"
+	EnableMouseHilite  = "\x1b[?1001h"
+	DisableMouseHilite = "\x1b[?1001l"
+	RequestMouseHilite = "\x1b[?1001$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
 const (
-	MouseCellMotionMode = "?1002"
+	MouseCellMotionMode = PrivateMode(1002)
 
-	EnableMouseCellMotion  = "\x1b[" + MouseCellMotionMode + "h"
-	DisableMouseCellMotion = "\x1b[" + MouseCellMotionMode + "l"
-	RequestMouseCellMotion = "\x1b[" + MouseCellMotionMode + "$p"
+	EnableMouseCellMotion  = "\x1b[?1002h"
+	DisableMouseCellMotion = "\x1b[?1002l"
+	RequestMouseCellMotion = "\x1b[?1002$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
 const (
-	MouseAllMotionMode = "?1003"
+	MouseAllMotionMode = PrivateMode(1003)
 
-	EnableMouseAllMotion  = "\x1b[" + MouseAllMotionMode + "h"
-	DisableMouseAllMotion = "\x1b[" + MouseAllMotionMode + "l"
-	RequestMouseAllMotion = "\x1b[" + MouseAllMotionMode + "$p"
+	EnableMouseAllMotion  = "\x1b[?1003h"
+	DisableMouseAllMotion = "\x1b[?1003l"
+	RequestMouseAllMotion = "\x1b[?1003$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
 const (
-	ReportFocusMode = "?1004"
+	ReportFocusMode = PrivateMode(1004)
 
-	EnableReportFocus  = "\x1b[" + ReportFocusMode + "h"
-	DisableReportFocus = "\x1b[" + ReportFocusMode + "l"
-	RequestReportFocus = "\x1b[" + ReportFocusMode + "$p"
+	EnableReportFocus  = "\x1b[?1004h"
+	DisableReportFocus = "\x1b[?1004l"
+	RequestReportFocus = "\x1b[?1004$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
 const (
-	MouseSgrExtMode = "?1006"
+	MouseSgrExtMode = PrivateMode(1006)
 
-	EnableMouseSgrExt  = "\x1b[" + MouseSgrExtMode + "h"
-	DisableMouseSgrExt = "\x1b[" + MouseSgrExtMode + "l"
-	RequestMouseSgrExt = "\x1b[" + MouseSgrExtMode + "$p"
+	EnableMouseSgrExt  = "\x1b[?1006h"
+	DisableMouseSgrExt = "\x1b[?1006l"
+	RequestMouseSgrExt = "\x1b[?1006$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
 const (
-	AltScreenBufferMode = "?1049"
+	AltScreenBufferMode = PrivateMode(1049)
 
-	EnableAltScreenBuffer  = "\x1b[" + AltScreenBufferMode + "h"
-	DisableAltScreenBuffer = "\x1b[" + AltScreenBufferMode + "l"
-	RequestAltScreenBuffer = "\x1b[" + AltScreenBufferMode + "$p"
+	EnableAltScreenBuffer  = "\x1b[?1049h"
+	DisableAltScreenBuffer = "\x1b[?1049l"
+	RequestAltScreenBuffer = "\x1b[?1049$p"
 )
 
 // Bracketed Paste Mode is a mode that determines whether pasted text is
@@ -133,23 +151,23 @@ const (
 // See: https://cirw.in/blog/bracketed-paste
 // See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Bracketed-Paste-Mode
 const (
-	BracketedPasteMode = "?2004"
+	BracketedPasteMode = PrivateMode(2004)
 
-	EnableBracketedPaste  = "\x1b[" + BracketedPasteMode + "h"
-	DisableBracketedPaste = "\x1b[" + BracketedPasteMode + "l"
-	RequestBracketedPaste = "\x1b[" + BracketedPasteMode + "$p"
+	EnableBracketedPaste  = "\x1b[?2004h"
+	DisableBracketedPaste = "\x1b[?2004l"
+	RequestBracketedPaste = "\x1b[?2004$p"
 )
 
 // Synchronized Output Mode is a mode that determines whether output is
 // synchronized with the terminal.
 //
 // See: https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036
 const (
-	SyncdOutputMode = "?2026"
+	SyncdOutputMode = PrivateMode(2026)
 
-	EnableSyncdOutput  = "\x1b[" + SyncdOutputMode + "h"
-	DisableSyncdOutput = "\x1b[" + SyncdOutputMode + "l"
-	RequestSyncdOutput = "\x1b[" + SyncdOutputMode + "$p"
+	EnableSyncdOutput  = "\x1b[?2026h"
+	DisableSyncdOutput = "\x1b[?2026l"
+	RequestSyncdOutput = "\x1b[?2026$p"
 )
 
 // Grapheme Clustering Mode is a mode that determines whether the terminal
@@ -159,21 +177,21 @@ const (
 //
 // See: https://github.com/contour-terminal/terminal-unicode-core
 const (
-	GraphemeClusteringMode = "?2027"
+	GraphemeClusteringMode = PrivateMode(2027)
 
-	EnableGraphemeClustering  = "\x1b[" + GraphemeClusteringMode + "h"
-	DisableGraphemeClustering = "\x1b[" + GraphemeClusteringMode + "l"
-	RequestGraphemeClustering = "\x1b[" + GraphemeClusteringMode + "$p"
+	EnableGraphemeClustering  = "\x1b[?2027h"
+	DisableGraphemeClustering = "\x1b[?2027l"
+	RequestGraphemeClustering = "\x1b[?2027$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
 const (
-	Win32InputMode = "?9001"
+	Win32InputMode = PrivateMode(9001)
 
-	EnableWin32Input  = "\x1b[" + Win32InputMode + "h"
-	DisableWin32Input = "\x1b[" + Win32InputMode + "l"
-	RequestWin32Input = "\x1b[" + Win32InputMode + "$p"
+	EnableWin32Input  = "\x1b[?9001h"
+	DisableWin32Input = "\x1b[?9001l"
+	RequestWin32Input = "\x1b[?9001$p"
 )

ansi/parser_decode.go

@@ -40,15 +40,15 @@ const (
 // [Cmd] and [Param] types to unpack command intermediates and markers as well
 // as parameters.
 //
-// Zero [p.Cmd] means the CSI, DCS, or ESC sequence is invalid. Moreover, checking the
+// 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 [p.Cmd] in the most significant byte, the
+// 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. [p.Cmd & 0xff]. Use the [Cmd] type to unpack the
+// 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.
 //

ansi/screen.go

@@ -2,12 +2,14 @@ package ansi
 
 import "strconv"
 
-// EraseDisplay (ED) clears the screen or parts of the screen. Possible values:
+// 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 screen and delete all lines saved in the scrollback buffer.
+//	 3: Clear entire display which delete all lines saved in the scrollback buffer (xterm).
 //
 //	CSI <n> J
 //
@@ -22,9 +24,10 @@ func EraseDisplay(n int) string {
 // EraseDisplay constants.
 // These are the possible values for the EraseDisplay function.
 const (
-	EraseDisplayBelow  = "\x1b[0J"
-	EraseDisplayAbove  = "\x1b[1J"
-	EraseEntireDisplay = "\x1b[2J"
+	EraseScreenBelow   = "\x1b[0J"
+	EraseScreenAbove   = "\x1b[1J"
+	EraseEntireScreen  = "\x1b[2J"
+	EraseEntireDisplay = "\x1b[3J"
 )
 
 // EraseLine (EL) clears the current line or parts of the line. Possible values: