vt

package module
v1.7.2 Latest Latest
Warning

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

 Go to latest Published: Feb 25, 2026 License: BSD-3-Clause Imports: 20 Imported by: 11

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.7.2

Documentation

Index

Examples

Constants

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,
}

DarkColorMap maps color names to AttributeColor values for dark terminals

View Source 
var EnvNoColor = env.Bool("NO_COLOR")

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,
}

LightColorMap maps color names to AttributeColor values for light terminals

Functions

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 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 EchoOff 

func EchoOff()

EchoOff disables terminal echo

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.

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

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
	Dim        AttributeColor = 2
	Underscore AttributeColor = 4
	Blink      AttributeColor = 5
	Reverse    AttributeColor = 7
	Hidden     AttributeColor = 8
	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

	Default           AttributeColor = 39
	DefaultBackground AttributeColor = 49
)

func (AttributeColor) Background 

func (ac AttributeColor) Background() AttributeColor

Background converts a foreground color to the corresponding background attribute

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) 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

func (AttributeColor) String 

func (ac AttributeColor) String() string

String returns the VT100 escape sequence for this color/attribute

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

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) 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

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) Enable added in v1.2.8 

func (o *TextOutput) Enable()

Enable text 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. 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.