vt

package module
v1.8.5 Latest Latest
Warning

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

 Go to latest Published: Apr 21, 2026 License: BSD-3-Clause Imports: 20 Imported by: 16

README

vt GoDoc License Go Report Card

This is a package for dealing with terminal emulators.

It is version 2 of xyproto/vt100.

The Orbiton editor and the Algernon web server uses vt.

General info
  • License: BSD-3
  • Version: 1.8.5

Documentation

Index

Examples

Constants

View Source 
const (
	KeyPageDown = 250 // Page Down
	KeyPageUp   = 251 // Page Up
	KeyLeft     = 252 // Left Arrow
	KeyUp       = 253 // Up Arrow
	KeyRight    = 254 // Right Arrow
	KeyDown     = 255 // Down Arrow

	KeyShiftTab = 273 // Shift-Tab / Backtab
	KeyF1       = 274 // F1
	KeyF2       = 275 // F2
	KeyF3       = 276 // F3
	KeyF4       = 277 // F4
	KeyDelete   = 278 // Delete / Forward-Delete

	KeyF5  = 279 // F5
	KeyF6  = 280 // F6
	KeyF7  = 281 // F7
	KeyF8  = 282 // F8
	KeyF9  = 283 // F9
	KeyF10 = 284 // F10
	KeyF11 = 285 // F11
	KeyF12 = 286 // F12

	KeyCtrlInsert    = 258 // Ctrl-Insert
	KeyAltUp         = 259 // Alt-Up
	KeyAltDown       = 260 // Alt-Down
	KeyAltRight      = 261 // Alt-Right
	KeyAltLeft       = 262 // Alt-Left
	KeyCtrlUp        = 263 // Ctrl-Up
	KeyCtrlDown      = 264 // Ctrl-Down
	KeyCtrlRight     = 265 // Ctrl-Right
	KeyCtrlLeft      = 266 // Ctrl-Left
	KeyShiftUp       = 267 // Shift-Up
	KeyShiftDown     = 268 // Shift-Down
	KeyShiftRight    = 269 // Shift-Right
	KeyShiftLeft     = 270 // Shift-Left
	KeyShiftHome     = 271 // Shift-Home
	KeyShiftEnd      = 272 // Shift-End
	KeyCtrlHome      = 287 // Ctrl-Home
	KeyCtrlEnd       = 288 // Ctrl-End
	KeyAltHome       = 289 // Alt-Home
	KeyAltEnd        = 290 // Alt-End
	KeyCtrlPageUp    = 291 // Ctrl-Page Up
	KeyCtrlPageDown  = 292 // Ctrl-Page Down
	KeyShiftPageUp   = 293 // Shift-Page Up
	KeyShiftPageDown = 294 // Shift-Page Down
	KeyCtrlDelete    = 295 // Ctrl-Delete
	KeyShiftDelete   = 296 // Shift-Delete
)

Key codes returned by TTY.Key() and TTY.KeyCode() for special keys. Arrow keys and navigation keys are assigned codes above 127 to avoid collision with ASCII control characters and printable characters.

View Source 
const NoColor string = "\033[0m"

NoColor is the escape sequence for resetting all color attributes

Variables

View Source 
var (
	Pink              = LightMagenta
	Gray              = DarkGray
	BackgroundWhite   = BackgroundLightGray
	BackgroundGray    = BackgroundLightGray
	BackgroundDefault = DefaultBackground
)
View Source 
var DarkColorMap = map[string]AttributeColor{
	"black":        Black,
	"red":          Red,
	"green":        Green,
	"yellow":       Yellow,
	"blue":         Blue,
	"magenta":      Magenta,
	"cyan":         Cyan,
	"gray":         DarkGray,
	"white":        LightGray,
	"lightwhite":   White,
	"darkred":      Red,
	"darkgreen":    Green,
	"darkyellow":   Yellow,
	"darkblue":     Blue,
	"darkmagenta":  Magenta,
	"darkcyan":     Cyan,
	"darkgray":     DarkGray,
	"lightred":     LightRed,
	"lightgreen":   LightGreen,
	"lightyellow":  LightYellow,
	"lightblue":    LightBlue,
	"lightmagenta": LightMagenta,
	"lightcyan":    LightCyan,
	"lightgray":    LightGray,
	"bold":         Bold,
	"italic":       Italic,
	"boldwhite":    Bold.Combine(White),
	"boldred":      Bold.Combine(LightRed),
	"boldgreen":    Bold.Combine(LightGreen),
	"boldyellow":   Bold.Combine(LightYellow),
	"boldblue":     Bold.Combine(LightBlue),
	"boldmagenta":  Bold.Combine(LightMagenta),
	"boldcyan":     Bold.Combine(LightCyan),
}

DarkColorMap maps color names to AttributeColor values for dark terminals

View Source 
var EnvNoColor = env.Bool("NO_COLOR") || env.Str("TERM") == "vt100"

EnvNoColor respects the NO_COLOR environment variable

View Source 
var LightColorMap = map[string]AttributeColor{
	"black":        Black,
	"red":          LightRed,
	"green":        LightGreen,
	"yellow":       LightYellow,
	"blue":         LightBlue,
	"magenta":      LightMagenta,
	"cyan":         LightCyan,
	"gray":         LightGray,
	"white":        White,
	"lightwhite":   White,
	"lightred":     LightRed,
	"lightgreen":   LightGreen,
	"lightyellow":  LightYellow,
	"lightblue":    LightBlue,
	"lightmagenta": LightMagenta,
	"lightcyan":    LightCyan,
	"lightgray":    LightGray,
	"darkred":      Red,
	"darkgreen":    Green,
	"darkyellow":   Yellow,
	"darkblue":     Blue,
	"darkmagenta":  Magenta,
	"darkcyan":     Cyan,
	"darkgray":     DarkGray,
	"bold":         Bold,
	"italic":       Italic,
	"boldwhite":    Bold.Combine(White),
	"boldred":      Bold.Combine(LightRed),
	"boldgreen":    Bold.Combine(LightGreen),
	"boldyellow":   Bold.Combine(LightYellow),
	"boldblue":     Bold.Combine(LightBlue),
	"boldmagenta":  Bold.Combine(LightMagenta),
	"boldcyan":     Bold.Combine(LightCyan),
}

LightColorMap maps color names to AttributeColor values for light terminals

View Source 
var X11Colors = map[string]AttributeColor{}/* 140 elements not displayed */

X11Colors maps every canonical X11 color name (no numbered variants) to a TrueColor AttributeColor. The RGB values are taken from the X11 rgb.txt database. A handful of CSS/SVG-only names that are absent from X11 but commonly expected (aqua, fuchsia, indigo, lime, olive, silver, teal) are included for convenience, using their W3C/CSS3 definitions.

Grey aliases (darkgrey, slategrey, …) are included alongside their grey spellings.

Functions

func BeginSyncUpdate added in v1.7.8 

func BeginSyncUpdate()

BeginSyncUpdate sends the terminal's begin synchronized update escape sequence

func Clear 

func Clear()

Clear erases the entire screen

func Close 

func Close()

Close restores the terminal and clears the screen. Use CloseKeepContent to keep the canvas content visible.

func CloseKeepContent added in v1.6.1 

func CloseKeepContent()

CloseKeepContent restores the terminal but leaves the canvas content visible

func Color256ToRGB added in v1.8.0 

func Color256ToRGB(n uint8) (r, g, b uint8)

Color256ToRGB returns the approximate RGB values for an xterm-256color palette index. Indices 0–15 return the standard ANSI colors, 16–231 the 6×6×6 color cube, and 232–255 the 24-step grayscale ramp.

func ColorSplit added in v1.2.1 

func ColorSplit(line, sep string, headColor, sepColor, tailColor AttributeColor, reverse bool) (string, string)

ColorSplit splits on the first sep in line. It returns two parts: left and right. The right part includes the sep itself (so subsequent splits see it). nil color funcs are skipped. reverse=true swaps which side gets the fallback when sep is absent.

func Colorize 

func Colorize(line string) string

Colorize comments in gray. Colorize (){}[] in an alternating way. This provides simple/rudimentary syntax highlighting.

func ContrastRatio added in v1.8.0 

func ContrastRatio(fg, bg AttributeColor) float64

ContrastRatio returns the WCAG 2.1 contrast ratio between fg and bg. The result is in [1.0, 21.0]: 1.0 = no contrast, 21.0 = black on white.

func EchoOff 

func EchoOff()

EchoOff disables terminal echo

func EndSyncUpdate added in v1.7.8 

func EndSyncUpdate()

EndSyncUpdate sends the terminal's end synchronized update escape sequence

func Eprint added in v1.3.0 

func Eprint(msg ...any)

func Eprintf added in v1.3.0 

func Eprintf(format string, msg ...any)

func Eprintln added in v1.3.0 

func Eprintln(msg ...any)

func Fprint added in v1.3.0 

func Fprint(w io.Writer, msg ...any)

func Fprintf added in v1.3.0 

func Fprintf(w io.Writer, format string, msg ...any)

func Fprintln added in v1.3.0 

func Fprintln(w io.Writer, msg ...any)

func GetBackgroundColor 

func GetBackgroundColor(tty *TTY) (float64, float64, float64, error)

GetBackgroundColor queries the terminal for its background color. Returns normalized RGB values in [0.0, 1.0], or an error. The terminal response format is "rgb:RRRR/GGGG/BBBB" where each component is a 16-bit hex value (0000–ffff).

func Has256Colors added in v1.7.15 

func Has256Colors() bool

Has256Colors returns true when the terminal supports 256-color mode (i.e. $TERM contains "256color" or is "xterm-kitty").

func HasAltArrows added in v1.7.15 

func HasAltArrows() bool

HasAltArrows returns true when the terminal is expected to emit alt-arrow key sequences (ESC [1;3A/B/C/D for alt-up/down/right/left). These are only generated by xterm-class emulators.

func HasCtrlArrows added in v1.7.16 

func HasCtrlArrows() bool

HasCtrlArrows returns true when the terminal is expected to emit ctrl-arrow key sequences (ESC [1;5A/B/C/D for ctrl-up/down/right/left). These are only generated by xterm-class emulators.

func HasShiftArrows added in v1.7.16 

func HasShiftArrows() bool

HasShiftArrows returns true when the terminal is expected to emit shift-arrow and shift-home/end key sequences (ESC [1;2A/B/C/D/H/F for shift-up/down/right/left/home/end). These are only generated by xterm-class emulators.

func HasSufficientContrast added in v1.8.0 

func HasSufficientContrast(fg, bg AttributeColor) bool

HasSufficientContrast reports whether fg and bg meet the WCAG 2.1 AA minimum contrast ratio of 4.5 for normal text.

func HasTrueColor added in v1.8.0 

func HasTrueColor() bool

HasTrueColor returns true when the terminal supports 24-bit true color (i.e. $COLORTERM is "truecolor" or "24bit").

func Home 

func Home()

Home moves the cursor to the top-left corner

func Init 

func Init()

Init initializes the terminal for full-screen canvas use

func Is256Color added in v1.8.0 

func Is256Color(ac AttributeColor) bool

Is256Color reports whether ac was created with Color256 or Background256 (i.e. holds an xterm-256color palette index)

func IsTrueColor added in v1.8.0 

func IsTrueColor(ac AttributeColor) bool

IsTrueColor reports whether ac was created with TrueColor or TrueBackground (i.e. holds a 24-bit RGB value)

func Luminance added in v1.8.0 

func Luminance(ac AttributeColor) float64

Luminance returns the WCAG 2.1 relative luminance of ac in [0.0, 1.0]. Returns 0.0 for non-color attributes.

func Multiplexed added in v1.6.1 

func Multiplexed() bool

Multiplexed returns true when running inside a terminal multiplexer

func MustTermSize 

func MustTermSize() (uint, uint)

MustTermSize returns the current terminal width and height

func Print added in v1.2.10 

func Print(msg ...any)

func Printf added in v1.2.10 

func Printf(format string, msg ...any)

func Println added in v1.2.10 

func Println(msg ...any)
Example 
o := NewTextOutput(true, true)
o.Println("hello")

Output:
hello

func RebuildTagReplacers added in v1.7.18 

func RebuildTagReplacers()

RebuildTagReplacers rebuilds the cached tag replacers from the current DarkColorMap and LightColorMap. Call this after adding entries to either map so that the new entries are recognized by DarkTags and LightTags.

func Reset 

func Reset()

Reset sends the terminal reset sequence

func SetLineWrap 

func SetLineWrap(enable bool)

SetLineWrap enables or disables line wrapping

func SetNoColor 

func SetNoColor()

SetNoColor resets all color attributes

func SetXY 

func SetXY(x, y uint)

SetXY moves the cursor to the given position (0,0 is top left)

func SetupResizeHandler added in v1.3.7 

func SetupResizeHandler(sigChan chan os.Signal)

SetupResizeHandler sets up a terminal resize signal handler

func ShowCursor 

func ShowCursor(enable bool)

ShowCursor shows or hides the terminal cursor

func Stop 

func Stop() string

Stop returns the escape sequence for resetting all color attributes, or "" when NO_COLOR is set.

func ToHex added in v1.8.0 

func ToHex(ac AttributeColor) string

ToHex returns the hex color string ("#rrggbb") for any AttributeColor whose RGB can be determined. Returns "#000000" for non-color attributes.

func ToRGB added in v1.8.0 

func ToRGB(ac AttributeColor) (r, g, b uint8, ok bool)

ToRGB extracts the RGB components of any AttributeColor:

  • TrueColor / TrueBackground → exact 24-bit values, ok=true
  • 256-color / background256 → palette-derived values via Color256ToRGB, ok=true
  • Standard ANSI 16 foreground (30–37, 90–97) → approximate values from ansi16Palette, ok=true
  • Anything else (attributes, Default, …) → 0, 0, 0, false

func WaitForKey 

func WaitForKey()

WaitForKey waits for ctrl-c, Return, Esc, Space, or 'q' to be pressed

func XtermLike added in v1.6.3 

func XtermLike() bool

xtermLike returns true when $TERM looks like an xterm-class emulator

Types

type AttributeColor 

type AttributeColor uint32

AttributeColor represents a terminal color/attribute value 

const (
	// Non-color attributes
	ResetAll      AttributeColor = 0
	Bright        AttributeColor = 1
	Bold          AttributeColor = 1
	Dim           AttributeColor = 2
	Italic        AttributeColor = 3
	Underscore    AttributeColor = 4
	Blink         AttributeColor = 5
	Reverse       AttributeColor = 7
	Hidden        AttributeColor = 8
	Strikethrough AttributeColor = 9
	None          AttributeColor = 0

	Black     AttributeColor = 30
	Red       AttributeColor = 31
	Green     AttributeColor = 32
	Yellow    AttributeColor = 33
	Blue      AttributeColor = 34
	Magenta   AttributeColor = 35
	Cyan      AttributeColor = 36
	LightGray AttributeColor = 37

	DarkGray     AttributeColor = 90
	LightRed     AttributeColor = 91
	LightGreen   AttributeColor = 92
	LightYellow  AttributeColor = 93
	LightBlue    AttributeColor = 94
	LightMagenta AttributeColor = 95
	LightCyan    AttributeColor = 96
	White        AttributeColor = 97

	BackgroundBlack     AttributeColor = 40
	BackgroundRed       AttributeColor = 41
	BackgroundGreen     AttributeColor = 42
	BackgroundYellow    AttributeColor = 43
	BackgroundBlue      AttributeColor = 44
	BackgroundMagenta   AttributeColor = 45
	BackgroundCyan      AttributeColor = 46
	BackgroundLightGray AttributeColor = 47

	// Bright background colors (xterm codes 100–107)
	BackgroundBrightBlack   AttributeColor = 100
	BackgroundBrightRed     AttributeColor = 101
	BackgroundBrightGreen   AttributeColor = 102
	BackgroundBrightYellow  AttributeColor = 103
	BackgroundBrightBlue    AttributeColor = 104
	BackgroundBrightMagenta AttributeColor = 105
	BackgroundBrightCyan    AttributeColor = 106
	BackgroundBrightWhite   AttributeColor = 107

	Default           AttributeColor = 39
	DefaultBackground AttributeColor = 49
)

func Background256 added in v1.7.15 

func Background256(n uint8) AttributeColor

Background256 returns an AttributeColor for the given xterm 256-color background index (0–255). Use Has256Colors() to check whether the terminal supports this.

func BackgroundFromHex added in v1.7.17 

func BackgroundFromHex(s string) (AttributeColor, error)

BackgroundFromHex parses a hex color string and returns a true-color background AttributeColor. Accepted formats: "#rrggbb", "#rgb", "rrggbb", "rgb".

func BestBackground added in v1.8.0 

func BestBackground(r, g, b uint8) AttributeColor

BestBackground is the background-color variant of BestColor.

func BestBackgroundFromHex added in v1.8.0 

func BestBackgroundFromHex(s string) AttributeColor

BestBackgroundFromHex is the background-color variant of BestColorFromHex. Returns DefaultBackground on parse error.

func BestColor added in v1.8.0 

func BestColor(r, g, b uint8) AttributeColor

BestColor returns the most faithful foreground AttributeColor for (r, g, b) that the current terminal can display:

  • Default (no color) if NO_COLOR is set
  • 24-bit true color if $COLORTERM is "truecolor" or "24bit"
  • nearest xterm-256color entry if $TERM contains "256color" or is "xterm-kitty"
  • nearest ANSI-16 color otherwise

func BestColorFromHex added in v1.8.0 

func BestColorFromHex(s string) AttributeColor

BestColorFromHex parses a "#rrggbb" (or "#rgb" / "rrggbb" / "rgb") hex string and returns the most faithful foreground AttributeColor the terminal supports, using the same terminal-capability detection as BestColor. Returns Default on parse error.

func Blend added in v1.8.0 

func Blend(a, b AttributeColor, t float64) AttributeColor

Blend linearly interpolates between colors a and b. t=0.0 returns a; t=1.0 returns b. The result is always a TrueColor (or TrueBackground if a is a background color). If neither a nor b has a representable RGB, a is returned unchanged.

func Color256 added in v1.7.15 

func Color256(n uint8) AttributeColor

Color256 returns an AttributeColor for the given xterm 256-color foreground index (0–255). Use Has256Colors() to check whether the terminal supports this.

func ColorCube added in v1.8.0 

func ColorCube(r, g, b uint8) AttributeColor

ColorCube returns a 256-color foreground AttributeColor from the 6×6×6 RGB color cube (palette indices 16–231). Each of r, g, b must be 0–5; values above 5 are clamped.

func ColorFromHex added in v1.7.17 

func ColorFromHex(s string) (AttributeColor, error)

ColorFromHex parses a hex color string and returns a true-color foreground AttributeColor. Accepted formats: "#rrggbb", "#rgb", "rrggbb", "rgb".

func Darken added in v1.8.0 

func Darken(ac AttributeColor, amount float64) AttributeColor

Darken returns a darker version of ac by blending its RGB toward black. amount is in [0.0, 1.0]: 0.0 = unchanged, 1.0 = black. For non-color attributes, ac is returned unchanged.

func Grayscale256 added in v1.8.0 

func Grayscale256(level uint8) AttributeColor

Grayscale256 returns a 256-color foreground AttributeColor from the 24-step grayscale ramp (palette indices 232–255). level 0 is near-black (rgb 8,8,8) and level 23 is near-white (rgb 238,238,238). Values above 23 are clamped.

func Lighten added in v1.8.0 

func Lighten(ac AttributeColor, amount float64) AttributeColor

Lighten returns a lighter version of ac by blending its RGB toward white. amount is in [0.0, 1.0]: 0.0 = unchanged, 1.0 = white. For non-color attributes, ac is returned unchanged.

func NearestColor256 added in v1.8.0 

func NearestColor256(r, g, b uint8) AttributeColor

NearestColor256 returns the AttributeColor for the xterm-256color palette entry whose RGB value is closest to (r, g, b) by squared Euclidean distance.

func TrueBackground added in v1.7.17 

func TrueBackground(r, g, b uint8) AttributeColor

TrueBackground returns a true-color (24-bit) background AttributeColor for the given RGB values.

func TrueColor added in v1.7.17 

func TrueColor(r, g, b uint8) AttributeColor

TrueColor returns a true-color (24-bit) foreground AttributeColor for the given RGB values.

func (AttributeColor) Background 

func (ac AttributeColor) Background() AttributeColor

Background converts a foreground color to the corresponding background attribute

func (AttributeColor) Bold added in v1.8.1 

func (ac AttributeColor) Bold() AttributeColor

Bold returns a new AttributeColor with the Bold attribute combined in

func (AttributeColor) Bright 

func (ac AttributeColor) Bright() AttributeColor

Bright returns a new AttributeColor with the Bright attribute combined in

func (AttributeColor) Combine 

func (ac AttributeColor) Combine(other AttributeColor) AttributeColor

Combine packs two AttributeColor values into one

func (*AttributeColor) Equal 

func (ac *AttributeColor) Equal(other AttributeColor) bool

func (AttributeColor) Error 

func (ac AttributeColor) Error(text string)

Error prints text with this color to stderr, followed by a newline

func (AttributeColor) Get 

func (ac AttributeColor) Get(text string) string

Get is an alias for Wrap

func (AttributeColor) Head 

func (ac AttributeColor) Head() uint32

func (AttributeColor) Ints 

func (ac AttributeColor) Ints() []int

func (AttributeColor) Italic added in v1.8.1 

func (ac AttributeColor) Italic() AttributeColor

Italic returns a new AttributeColor with the Italic attribute combined in

func (AttributeColor) Output 

func (ac AttributeColor) Output(text string)

Output prints text with this color to stdout, followed by a newline

func (AttributeColor) Start 

func (ac AttributeColor) Start(text string) string

Start returns the escape sequence followed by text, without resetting

func (AttributeColor) StartStop 

func (ac AttributeColor) StartStop(text string) string

StartStop is an alias for Wrap

func (AttributeColor) Stop 

func (ac AttributeColor) Stop(text string) string

Stop returns text followed by the reset escape sequence. Returns text unchanged when NO_COLOR is set.

func (AttributeColor) Strike added in v1.8.4 

func (ac AttributeColor) Strike() AttributeColor

Strike returns a new AttributeColor with the Strikethrough attribute combined in

func (AttributeColor) String 

func (ac AttributeColor) String() string

String returns the VT100 escape sequence for this color/attribute. Standard ANSI codes (0–255) are served from a pre-computed array with no allocation. Extended values (true-color, 256-color, combined attributes) are computed once and memoized in extCache. Returns "" when NO_COLOR is set.

func (AttributeColor) Tail 

func (ac AttributeColor) Tail() uint32

func (AttributeColor) Wrap added in v1.6.0 

func (ac AttributeColor) Wrap(text string) string

Wrap returns text wrapped with this color's escape sequence and a trailing reset. Returns text unchanged when NO_COLOR is set.

type Canvas 

type Canvas struct {
	// contains filtered or unexported fields
}

Canvas represents a 2D grid of colored characters

func NewCanvas 

func NewCanvas() *Canvas

NewCanvas creates a canvas sized to the current terminal

func (*Canvas) At 

func (c *Canvas) At(x, y uint) (rune, error)

At returns the rune at the given coordinates, or an error if out of bounds

func (*Canvas) Clear 

func (c *Canvas) Clear()

Clear canvas

func (*Canvas) Copy 

func (c *Canvas) Copy() Canvas

Copy creates a new Canvas struct that is a copy of this one. The mutex is initialized as a new mutex.

func (*Canvas) Draw 

func (c *Canvas) Draw()

Draw the entire canvas

func (*Canvas) DrawAndSetCursor 

func (c *Canvas) DrawAndSetCursor(x, y uint)

DrawAndSetCursor draws the entire canvas and then places the cursor at x,y

func (*Canvas) Fill 

func (c *Canvas) Fill(fg AttributeColor)

Fill changes the foreground color for each character

func (*Canvas) FillBackground 

func (c *Canvas) FillBackground(bg AttributeColor)

FillBackground changes the background color for each character

func (*Canvas) H 

func (c *Canvas) H() uint

H returns the canvas height

func (*Canvas) Height 

func (c *Canvas) Height() uint

Height returns the canvas height

func (*Canvas) HideCursor 

func (c *Canvas) HideCursor()

HideCursor hides the cursor. Redundant calls emit no escape.

func (*Canvas) HideCursorAndDraw 

func (c *Canvas) HideCursorAndDraw()

HideCursorAndDraw hides the cursor and draws the entire canvas

func (*Canvas) HideCursorAndRedraw 

func (c *Canvas) HideCursorAndRedraw()

HideCursorAndRedraw marks all cells dirty, hides the cursor, and re-renders

func (*Canvas) HideCursorAndRedrawFull added in v1.5.11 

func (c *Canvas) HideCursorAndRedrawFull()

HideCursorAndRedrawFull hides the cursor and forces a full-frame redraw

func (*Canvas) Lock 

func (c *Canvas) Lock()

Lock the canvas mutex

func (*Canvas) Plot 

func (c *Canvas) Plot(x, y uint, r rune)

Plot sets the rune at (x, y) and marks the cell as undrawn

func (*Canvas) PlotAll 

func (c *Canvas) PlotAll()

PlotAll tries to plot each individual rune. It's very inefficient and meant to be used as a robust fallback.

func (*Canvas) PlotColor 

func (c *Canvas) PlotColor(x, y uint, fg AttributeColor, r rune)

PlotColor sets the rune and foreground color at (x, y)

func (*Canvas) Redraw 

func (c *Canvas) Redraw()

Redraw marks all cells dirty and re-renders

func (*Canvas) RedrawFull added in v1.5.11 

func (c *Canvas) RedrawFull()

RedrawFull forces a full-frame redraw by discarding the previous frame

func (*Canvas) Resize 

func (c *Canvas) Resize()

Resize adjusts the canvas to the current terminal size, discarding old content

func (*Canvas) Resized 

func (c *Canvas) Resized() *Canvas

Resized checks if the terminal was resized and returns a new Canvas if so. Returns nil if the size has not changed.

func (*Canvas) SetLineWrap 

func (c *Canvas) SetLineWrap(enable bool)

SetLineWrap enables or disables line wrapping

func (*Canvas) SetRunewise 

func (c *Canvas) SetRunewise(b bool)

SetRunewise enables or disables per-rune rendering

func (*Canvas) SetShowCursor 

func (c *Canvas) SetShowCursor(enable bool)

SetShowCursor sets the cursor visibility

func (*Canvas) ShowCursor 

func (c *Canvas) ShowCursor()

ShowCursor shows the cursor. Redundant calls emit no escape.

func (*Canvas) Size 

func (c *Canvas) Size() (uint, uint)

Return the size of the current canvas

func (*Canvas) String 

func (c *Canvas) String() string

String returns only the characters, as a long string with a newline after each row

func (*Canvas) ToImage 

func (c *Canvas) ToImage() (image.Image, error)

func (*Canvas) Unlock 

func (c *Canvas) Unlock()

Unlock the canvas mutex

func (*Canvas) W 

func (c *Canvas) W() uint

W returns the canvas width

func (*Canvas) Width 

func (c *Canvas) Width() uint

Width returns the canvas width

func (*Canvas) Write 

func (c *Canvas) Write(x, y uint, fg, bg AttributeColor, s string)

Write is an alias for WriteString, for backwards compatibility

func (*Canvas) WriteBackground 

func (c *Canvas) WriteBackground(x, y uint, bg AttributeColor)

WriteBackground sets the background color at (x, y)

func (*Canvas) WriteBackgroundAddRuneIfEmpty 

func (c *Canvas) WriteBackgroundAddRuneIfEmpty(x, y uint, bg AttributeColor, r rune)

WriteBackgroundAddRuneIfEmpty sets the background color at (x, y) and writes r if the cell is empty

func (*Canvas) WriteBackgroundNoLock 

func (c *Canvas) WriteBackgroundNoLock(x, y uint, bg AttributeColor)

WriteBackgroundNoLock sets the background color at (x, y) without locking

func (*Canvas) WriteRune 

func (c *Canvas) WriteRune(x, y uint, fg, bg AttributeColor, r rune)

WriteRune will write a colored rune to the canvas

func (*Canvas) WriteRuneB 

func (c *Canvas) WriteRuneB(x, y uint, fg, bgb AttributeColor, r rune)

WriteRuneB will write a colored rune to the canvas. The x and y must be within range (x < c.w and y < c.h).

func (*Canvas) WriteRuneBNoLock 

func (c *Canvas) WriteRuneBNoLock(x, y uint, fg, bgb AttributeColor, r rune)

WriteRuneBNoLock will write a colored rune to the canvas. The x and y must be within range (x < c.w and y < c.h). The canvas mutex is not locked.

func (*Canvas) WriteRunesB 

func (c *Canvas) WriteRunesB(x, y uint, fg, bgb AttributeColor, r rune, count uint)

WriteRunesB fills count cells starting at (x, y) with the given colored rune

func (*Canvas) WriteString 

func (c *Canvas) WriteString(x, y uint, fg, bg AttributeColor, s string)

WriteString will write a string to the canvas

func (*Canvas) WriteTagged added in v1.2.11 

func (c *Canvas) WriteTagged(x, y uint, bgColor AttributeColor, tagged string)

WriteTagged writes a tagged string ("<green>hello</green>") to the canvas

func (*Canvas) WriteWideRuneB added in v1.5.8 

func (c *Canvas) WriteWideRuneB(x, y uint, fg, bgb AttributeColor, r rune)

WriteWideRuneB writes a double-width (CJK) rune to the canvas. The next cell (x+1) is marked as a continuation cell and skipped during drawing. The x and y must be within range (x+1 < c.w and y < c.h).

func (*Canvas) WriteWideRuneBNoLock added in v1.5.8 

func (c *Canvas) WriteWideRuneBNoLock(x, y uint, fg, bgb AttributeColor, r rune)

WriteWideRuneBNoLock writes a double-width (CJK) rune to the canvas without locking. The next cell (x+1) is marked as a continuation cell and skipped during drawing. The x and y must be within range (x+1 < c.w and y < c.h).

type Char 

type Char ColorRune

Char is an alias for ColorRune, for API stability

type CharAttribute 

type CharAttribute struct {
	A AttributeColor
	R rune
}

CharAttribute is a rune and a color attribute

type ColorRune 

type ColorRune struct {
	// contains filtered or unexported fields
}

ColorRune holds a single terminal cell

type TTY 

type TTY struct {
	// contains filtered or unexported fields
}

func NewTTY 

func NewTTY() (*TTY, error)

NewTTY opens /dev/tty in raw+cbreak mode with a read timeout

func (*TTY) ASCII 

func (tty *TTY) ASCII() int

ASCII returns the ASCII code of the key pressed

func (*TTY) Close 

func (tty *TTY) Close()

Close restores the terminal and closes the file descriptor

func (*TTY) Flush 

func (tty *TTY) Flush()

Flush discards pending input/output

func (*TTY) Key 

func (tty *TTY) Key() int

Key reads the keycode or ASCII code and avoids repeated keys

func (*TTY) KeyCode 

func (tty *TTY) KeyCode() int

KeyCode returns the key code of the key pressed

func (*TTY) KeyString added in v1.7.0 

func (tty *TTY) KeyString() string

KeyString reads a keypress and returns it as a string, without flushing pending input

func (*TTY) NoBlock 

func (tty *TTY) NoBlock()

NoBlock sets the terminal to cbreak mode

func (*TTY) Poll added in v1.7.6 

func (tty *TTY) Poll(d time.Duration) (bool, error)

Poll checks if there is data available to read from the TTY within the given timeout. Returns true if data is available, false if the timeout was reached.

func (*TTY) PrintRawBytes 

func (tty *TTY) PrintRawBytes()

PrintRawBytes for debugging raw byte sequences

func (*TTY) RawMode 

func (tty *TTY) RawMode()

RawMode switches the terminal to raw mode

func (*TTY) ReadString 

func (tty *TTY) ReadString() (string, error)

ReadString reads all available data from the TTY

func (*TTY) ReadStringKeepTiming added in v1.5.9 

func (tty *TTY) ReadStringKeepTiming() (string, error)

ReadStringKeepTiming reads all available data from the TTY, preserving the caller's timeout value

func (*TTY) Restore 

func (tty *TTY) Restore()

Restore the terminal to its original state (flushes pending input)

func (*TTY) RestoreNoFlush added in v1.7.1 

func (tty *TTY) RestoreNoFlush()

RestoreNoFlush restores the terminal to its original state without flushing pending input

func (*TTY) Rune 

func (tty *TTY) Rune() rune

Rune reads a rune, handling special sequences for arrows, Home, End, etc.

func (*TTY) SetTimeout 

func (tty *TTY) SetTimeout(d time.Duration) (time.Duration, error)

SetTimeout sets the read timeout. Returns the previous timeout.

func (*TTY) SetTimeoutNoSave added in v1.5.9 

func (tty *TTY) SetTimeoutNoSave(d time.Duration) error

SetTimeoutNoSave sets the read timeout without saving the previous value

func (*TTY) String 

func (tty *TTY) String() string

String reads a string, handling key sequences and printable characters. When multiple key sequences arrive in one read (for example a held-down arrow key during a slow redraw), they are returned one by one on successive calls via a pending byte buffer — this prevents queued arrow escapes from leaking into the document as literal "^[[..." text.

func (*TTY) Timeout added in v1.5.2 

func (tty *TTY) Timeout() time.Duration

Timeout returns the configured read timeout

func (*TTY) WriteString 

func (tty *TTY) WriteString(s string) error

WriteString writes a string to the terminal

type TextOutput 

type TextOutput struct {
	// contains filtered or unexported fields
}

TextOutput keeps state about verbosity and if colors are enabled

func New added in v1.2.5 

func New() *TextOutput

New can initialize a new TextOutput struct, which can have colors turned on or off and where the output can be enabled (verbose) or disabled (silent). If NO_COLOR is set, colors are disabled.

func NewTextOutput 

func NewTextOutput(color, enabled bool) *TextOutput

NewTextOutput can initialize a new TextOutput struct, which can have colors turned on or off and where the output can be enabled (verbose) or disabled (silent). If NO_COLOR is set, colors are disabled, regardless.

func (*TextOutput) DarkTags 

func (o *TextOutput) DarkTags(colors ...string) string

Replace <blue> with starting a light blue color attribute and <off> with using the default attributes. </blue> can also be used for using the default attributes.

func (*TextOutput) Disable added in v1.2.8 

func (o *TextOutput) Disable()

Disable text output

func (*TextOutput) DisableColors added in v1.7.7 

func (o *TextOutput) DisableColors()

DisableColors will disable color output

func (*TextOutput) Enable added in v1.2.8 

func (o *TextOutput) Enable()

Enable text output

func (*TextOutput) EnableColors added in v1.7.7 

func (o *TextOutput) EnableColors()

DisableColors will enable color output

func (*TextOutput) Enabled added in v1.3.0 

func (o *TextOutput) Enabled() bool

Enabled checks if the text output is enabled

func (*TextOutput) Eprint added in v1.3.0 

func (o *TextOutput) Eprint(msg ...any)

Eprint writes a message to stderr if output is enabled

func (*TextOutput) Eprintf added in v1.3.0 

func (o *TextOutput) Eprintf(format string, args ...any)

Eprintf writes a formatted message to stderr if output is enabled

func (*TextOutput) Eprintln added in v1.3.0 

func (o *TextOutput) Eprintln(msg ...any)

Eprintln writes a message to stderr if output is enabled

func (*TextOutput) Err 

func (o *TextOutput) Err(msg string)

Err writes an error message in red to stderr if output is enabled

func (*TextOutput) ErrExit added in v1.2.3 

func (o *TextOutput) ErrExit(msg string)

ErrExit writes an error message to stderr and quit with exit code 1

func (*TextOutput) ExtractToSlice 

func (o *TextOutput) ExtractToSlice(s string, pcc *[]CharAttribute) uint

ExtractToSlice iterates over an ANSI encoded string, parsing out color codes and places it in a slice of CharAttribute. Each CharAttribute in the slice represents a character in the input string and its corresponding color attributes. This function handles escaping sequences and converts ANSI color codes to AttributeColor structs, including 24-bit truecolor sequences of the form ESC[38;2;R;G;Bm (foreground) and ESC[48;2;R;G;Bm (background), 256-color sequences of the form ESC[38;5;Nm (foreground) and ESC[48;5;Nm (background), and standard ANSI codes. The returned uint is the number of stored elements.

func (*TextOutput) Fprint added in v1.3.0 

func (o *TextOutput) Fprint(w io.Writer, msg ...any)

Fprint writes a message to the given io.Writer, if output is enabled

func (*TextOutput) Fprintf added in v1.3.0 

func (o *TextOutput) Fprintf(w io.Writer, format string, args ...any)

Fprintf writes a formatted message to the given io.Writer, if output is enabled

func (*TextOutput) Fprintln added in v1.3.0 

func (o *TextOutput) Fprintln(w io.Writer, msg ...any)

Fprintln writes a message to the given io.Writer, if output is enabled

func (*TextOutput) InterfaceTags 

func (o *TextOutput) InterfaceTags(colors ...any) string

InterfaceTags is the same as LightTags, but with interfaces

func (*TextOutput) LightBlue 

func (o *TextOutput) LightBlue(s string) string

func (*TextOutput) LightTags 

func (o *TextOutput) LightTags(colors ...string) string

Replace <blue> with starting a light blue color attribute and <off> with using the default attributes. </blue> can also be used for using the default attributes.

func (*TextOutput) OutputTags 

func (o *TextOutput) OutputTags(colors ...string)

OutputTags will output text that may have tags like "<blue>", "</blue>" or "<off>" for enabling or disabling color attributes. Respects the color/enabled settings of this TextOutput.

func (*TextOutput) Print 

func (o *TextOutput) Print(msg ...any)

Print writes a message to stdout if output is enabled

func (*TextOutput) Printf added in v1.2.7 

func (o *TextOutput) Printf(format string, args ...any)

Printf writes a formatted message to stdout if output is enabled

func (*TextOutput) Println 

func (o *TextOutput) Println(msg ...any)

Println writes a message to stdout if output is enabled

func (*TextOutput) Tags 

func (o *TextOutput) Tags(colors ...string) string

Same as LightTags

Source Files

View all Source files

Directories

Path Synopsis
cmd
bg command
blink command
canvas command
color command
key command
menu command
move command
ok command
resize command
rune command
shooter command
string command
waitkey command
widget command
writerune command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.