vt100

package module
v1.16.11 Latest Latest
Warning

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

 Go to latest Published: Nov 5, 2024 License: BSD-3-Clause Imports: 19 Imported by: 16

README

VT100

Build Status GoDoc License Go Report Card

  • Supports colors and attributes.
  • Supports platforms with VT100 support and a /dev/tty device.
  • Can detect the terminal size.
  • Can get key-presses, including arrow keys (252, 253, 254, 255) and pgup/pgdn (251, 250).
  • Has a Canvas struct, for drawing only the updated lines to the terminal.
  • Uses the a reference document directly, but memoizes the commands sent to the terminal, for performance.
  • Could be used for making an alternative to the dialog or whiptail utilities.
Editor

For an editor that uses this module, take a look at orbiton.

Images

shooter example

Screen recording of the shooter example, where you can control a small character with the arrow keys and shoot with space.

menu example

Screen recording of the menu example, which uses VT100 terminal codes and demonstrates a working menu.

VT100 terminal

A physical VT100 terminal. Photo by Jason Scott, CC BY 2.0

Requirements
  • Go 1.17 or later.
Features and limitations
  • Can detect letters, arrow keys and space. F12 and similar keys are not supported (they are supported by VT220 but not VT100).
  • Resizing the terminal when using the Canvas struct may cause artifacts, for a brief moment.
  • Holding down a key may trigger key repetition which may speed up the main loop.
  • As an exception, pgup and pgdown are supported.
Simple use

Output "hi" in blue:

vt100.Blue.Output("hi")

Erase the current line:

vt100.Do("Erase Line")

Move the cursor 3 steps up (it's a bit verbose, but it is memoized for better performance):

vt100.Set("Cursor Up", map[string]string{"{COUNT}": "3"})

The full overview of possible commands are at the top of vt100.go.

Another example

See cmd/move for a more advanced example, where a character can be moved around with the arrow keys.

A small editor using vt100

The Orbiton editor that uses vt100 can be used for editing Go, Bash or for example C++ code.

Quick installation:

go install github.com/xyproto/o/v2@latest
General info

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// Non-color attributes
	ResetAll   = NewAttributeColor("Reset all attributes")
	Bright     = NewAttributeColor("Bright")
	Dim        = NewAttributeColor("Dim")
	Underscore = NewAttributeColor("Underscore")
	Blink      = NewAttributeColor("Blink")
	Reverse    = NewAttributeColor("Reverse")
	Hidden     = NewAttributeColor("Hidden")

	None AttributeColor

	// Dark foreground colors (+ light gray)
	Black     = NewAttributeColor("Black")
	Red       = NewAttributeColor("Red")
	Green     = NewAttributeColor("Green")
	Yellow    = NewAttributeColor("Yellow")
	Blue      = NewAttributeColor("Blue")
	Magenta   = NewAttributeColor("Magenta")
	Cyan      = NewAttributeColor("Cyan")
	LightGray = NewAttributeColor("White")

	// Light foreground colors (+ dark gray)
	DarkGray     = NewAttributeColor("90")
	LightRed     = NewAttributeColor("91")
	LightGreen   = NewAttributeColor("92")
	LightYellow  = NewAttributeColor("93")
	LightBlue    = NewAttributeColor("94")
	LightMagenta = NewAttributeColor("95")
	LightCyan    = NewAttributeColor("96")
	White        = NewAttributeColor("97")

	// Aliases
	Pink = LightMagenta
	Gray = DarkGray

	// Dark background colors (+ light gray)
	BackgroundBlack     = NewAttributeColor("40")
	BackgroundRed       = NewAttributeColor("41")
	BackgroundGreen     = NewAttributeColor("42")
	BackgroundYellow    = NewAttributeColor("43")
	BackgroundBlue      = NewAttributeColor("44")
	BackgroundMagenta   = NewAttributeColor("45")
	BackgroundCyan      = NewAttributeColor("46")
	BackgroundLightGray = NewAttributeColor("47")

	// Aliases
	BackgroundWhite = BackgroundLightGray
	BackgroundGray  = BackgroundLightGray

	// Default colors (usually gray)
	Default           = NewAttributeColor("39")
	DefaultBackground = NewAttributeColor("49")
	BackgroundDefault = NewAttributeColor("49")

	DarkColorMap = map[string]AttributeColor{
		"black":        Black,
		"Black":        Black,
		"red":          Red,
		"Red":          Red,
		"green":        Green,
		"Green":        Green,
		"yellow":       Yellow,
		"Yellow":       Yellow,
		"blue":         Blue,
		"Blue":         Blue,
		"magenta":      Magenta,
		"Magenta":      Magenta,
		"cyan":         Cyan,
		"Cyan":         Cyan,
		"gray":         DarkGray,
		"Gray":         DarkGray,
		"white":        LightGray,
		"White":        LightGray,
		"lightwhite":   White,
		"LightWhite":   White,
		"darkred":      Red,
		"DarkRed":      Red,
		"darkgreen":    Green,
		"DarkGreen":    Green,
		"darkyellow":   Yellow,
		"DarkYellow":   Yellow,
		"darkblue":     Blue,
		"DarkBlue":     Blue,
		"darkmagenta":  Magenta,
		"DarkMagenta":  Magenta,
		"darkcyan":     Cyan,
		"DarkCyan":     Cyan,
		"darkgray":     DarkGray,
		"DarkGray":     DarkGray,
		"lightred":     LightRed,
		"LightRed":     LightRed,
		"lightgreen":   LightGreen,
		"LightGreen":   LightGreen,
		"lightyellow":  LightYellow,
		"LightYellow":  LightYellow,
		"lightblue":    LightBlue,
		"LightBlue":    LightBlue,
		"lightmagenta": LightMagenta,
		"LightMagenta": LightMagenta,
		"lightcyan":    LightCyan,
		"LightCyan":    LightCyan,
		"lightgray":    LightGray,
		"LightGray":    LightGray,
	}

	LightColorMap = map[string]AttributeColor{
		"black":        Black,
		"Black":        Black,
		"red":          LightRed,
		"Red":          LightRed,
		"green":        LightGreen,
		"Green":        LightGreen,
		"yellow":       LightYellow,
		"Yellow":       LightYellow,
		"blue":         LightBlue,
		"Blue":         LightBlue,
		"magenta":      LightMagenta,
		"Magenta":      LightMagenta,
		"cyan":         LightCyan,
		"Cyan":         LightCyan,
		"gray":         LightGray,
		"Gray":         LightGray,
		"white":        White,
		"White":        White,
		"lightwhite":   White,
		"LightWhite":   White,
		"lightred":     LightRed,
		"LightRed":     LightRed,
		"lightgreen":   LightGreen,
		"LightGreen":   LightGreen,
		"lightyellow":  LightYellow,
		"LightYellow":  LightYellow,
		"lightblue":    LightBlue,
		"LightBlue":    LightBlue,
		"lightmagenta": LightMagenta,
		"LightMagenta": LightMagenta,
		"lightcyan":    LightCyan,
		"LightCyan":    LightCyan,
		"lightgray":    LightGray,
		"LightGray":    LightGray,
		"darkred":      Red,
		"DarkRed":      Red,
		"darkgreen":    Green,
		"DarkGreen":    Green,
		"darkyellow":   Yellow,
		"DarkYellow":   Yellow,
		"darkblue":     Blue,
		"DarkBlue":     Blue,
		"darkmagenta":  Magenta,
		"DarkMagenta":  Magenta,
		"darkcyan":     Cyan,
		"DarkCyan":     Cyan,
		"darkgray":     DarkGray,
		"DarkGray":     DarkGray,
	}
)

Functions

func ASCIIOnce added in v0.2.1 

func ASCIIOnce() int

ASCIIOnce returns the ASCII code of a single key press

func AttributeAndColor 

func AttributeAndColor(attr, name string) string

Get the terminal command for setting a terminal attribute and a color

func AttributeNumber added in v0.5.0 

func AttributeNumber(name string) string

Returns the number (as a string) for a given attribute name. Returns the given string if the attribute was not found in the spec.

func AttributeOrColor 

func AttributeOrColor(name string) string

Execute the terminal command for setting a given display attribute name, like "Bright" or "Blink"

func BrightColor 

func BrightColor(text, color string) string

Return text with a bright color applied

func Clear 

func Clear()

Clear screen

func Close added in v0.7.0 

func Close()

func ColorNum 

func ColorNum(colorNum int) string

Get the terminal command for setting a given color number

func ColorString added in v1.2.0 

func ColorString(line, colors string) string

ColorString takes a string with words to be colored and another string with colors with which to color the words. Example strings: "hello there" and "red blue".

func Colors 

func Colors() []string

Return all available colors

func Commands 

func Commands() []string

Return all available commands

func DarkColor added in v0.3.0 

func DarkColor(text, color string) string

Return text with a dark color applied

func Do 

func Do(command string)

Do the given command, with no parameters

func Down 

func Down(n uint)

Move the cursor down

func EchoOff added in v0.9.0 

func EchoOff()

func Get 

func Get(command string, replacemap map[string]string) string

Return the terminal command, given a map to replace the values mentioned in the spec.

func GetBackgroundColor added in v1.10.0 

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

GetBackgroundColor prints a code to the terminal emulator, reads the results and tries to interpret it as the RGB background color. Returns three float64 values, and possibly an error value.

func Home 

func Home()

func Init added in v0.7.0 

func Init()

func KeyCodeOnce added in v0.2.1 

func KeyCodeOnce() int

KeyCodeOnce returns the key code of a single key press

func Left 

func Left(n uint)

Move the cursor to the left

func MustTermSize added in v1.16.5 

func MustTermSize() (uint, uint)

Convenience function

func NoColor 

func NoColor() string

Get the terminal command for setting no colors or other display attributes

func Reset 

func Reset()
func Right(n uint)

Move the cursor to the right

func ScreenHeight added in v0.6.0 

func ScreenHeight() int

Convenience function

func ScreenSize added in v1.16.4 

func ScreenSize() (int, int)

Convenience function

func ScreenWidth added in v0.6.0 

func ScreenWidth() int

Convenience function

func Set 

func Set(command string, replacemap map[string]string)

Do the terminal command, given a map to replace the values mentioned in the spec.

func SetAttribute 

func SetAttribute(name string)

Execute the terminal command for setting a given display attribute name, like "Bright" or "Blink"

func SetAttributeAndColor 

func SetAttributeAndColor(attr, name string)

Execute the terminal command for setting a terminal attribute and a color

func SetColorNum 

func SetColorNum(colorNum int)

Execute the terminal command for setting a given color number

func SetLineWrap 

func SetLineWrap(enable bool)

func SetNoColor 

func SetNoColor()

Execute the terminal command for setting no colors or other display attributes

func SetXY 

func SetXY(x, y uint)

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

func ShowCursor 

func ShowCursor(enable bool)

func Stop added in v0.6.0 

func Stop() string

Return a string for resetting the attributes

func TermHeight added in v1.16.4 

func TermHeight() uint

func TermSize 

func TermSize() (uint, uint, error)

func TermWidth added in v1.16.4 

func TermWidth() uint

func TrueColor added in v0.4.0 

func TrueColor(fg color.Color, text string) string

This is not part of the VT100 spec, but an easteregg for displaying 24-bit "true color" on some terminals. Example use: fmt.Println(vt100.TrueColor(color.RGBA{0xa0, 0xe0, 0xff, 0xff}, "TrueColor"))

func Up 

func Up(n uint)

Move the cursor up

func WaitForKey added in v0.6.0 

func WaitForKey()

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

func Words added in v0.7.0 

func Words(line string, colors ...string) string

Words takes a string with words and several color-strings, like "blue". Color the words with the corresponding colors and return the string.

func Write added in v0.6.0 

func Write(x, y int, text string, fg, bg AttributeColor)

Output a string at x, y with the given colors

func WriteRune added in v0.6.0 

func WriteRune(x, y int, r rune, fg, bg AttributeColor)

Output a rune at x, y with the given colors

Types

type AttributeColor added in v0.3.0 

type AttributeColor []byte

func NewAttributeColor added in v0.5.0 

func NewAttributeColor(attributes ...string) AttributeColor

func (AttributeColor) Background added in v0.7.0 

func (ac AttributeColor) Background() AttributeColor

Modify color attributes so that they become background color attributes instead

func (AttributeColor) Bright added in v0.6.0 

func (ac AttributeColor) Bright() AttributeColor

Return a new AttributeColor that has "Bright" added to the list of attributes

func (AttributeColor) Combine added in v0.5.0 

func (ac AttributeColor) Combine(other AttributeColor) AttributeColor

Combine the unique bytes from ac and other

func (*AttributeColor) Equal added in v1.4.0 

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

Equal checks if two colors have the same attributes, in the same order. The values that are being compared must have at least 1 byte in them.

func (AttributeColor) Error added in v1.0.1 

func (ac AttributeColor) Error(text string)

Same as output, but outputs to stderr instead of stdout

func (AttributeColor) Get added in v0.3.0 

func (ac AttributeColor) Get(text string) string

An alias for StartStop

func (AttributeColor) Head added in v0.6.0 

func (ac AttributeColor) Head() byte

func (AttributeColor) Ints added in v0.7.0 

func (ac AttributeColor) Ints() []int

func (AttributeColor) Output added in v0.3.0 

func (ac AttributeColor) Output(text string)

Use this color to output the given text. Will reset the attributes at the end of the string. Outputs a newline.

func (AttributeColor) Start added in v0.6.0 

func (ac AttributeColor) Start(text string) string

Get the full string needed for outputting colored text, with the text, but don't reset the attributes at the end of the string

func (AttributeColor) StartStop added in v0.6.0 

func (ac AttributeColor) StartStop(text string) string

Get the full string needed for outputting colored texti, with the text and stopping the color attribute

func (AttributeColor) Stop added in v0.6.0 

func (ac AttributeColor) Stop(text string) string

Get the text and the terminal codes for resetting the attributes

func (AttributeColor) String added in v0.6.0 

func (ac AttributeColor) String() string

Return the VT100 terminal codes for setting this combination of attributes and color attributes

func (AttributeColor) Tail added in v0.6.0 

func (ac AttributeColor) Tail() []byte

type Canvas 

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

func NewCanvas 

func NewCanvas() *Canvas

func (*Canvas) At added in v0.2.1 

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 added in v1.5.1 

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 added in v1.15.6 

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

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

func (*Canvas) Fill added in v0.6.0 

func (c *Canvas) Fill(fg AttributeColor)

Change the foreground color for each character

func (*Canvas) FillBackground added in v0.6.0 

func (c *Canvas) FillBackground(bg AttributeColor)

Change the background color for each character

func (*Canvas) H 

func (c *Canvas) H() uint

func (*Canvas) Height added in v1.5.0 

func (c *Canvas) Height() uint

func (*Canvas) HideCursor added in v1.5.1 

func (c *Canvas) HideCursor()

func (*Canvas) HideCursorAndDraw added in v1.16.0 

func (c *Canvas) HideCursorAndDraw()

HideCursorAndDraw will hide the cursor and then draw the entire canvas

func (*Canvas) HideCursorAndRedraw added in v1.16.1 

func (c *Canvas) HideCursorAndRedraw()

func (*Canvas) Lock added in v1.12.3 

func (c *Canvas) Lock()

func (*Canvas) Plot 

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

func (*Canvas) PlotAll added in v1.8.7 

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 added in v1.3.0 

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

func (*Canvas) Redraw 

func (c *Canvas) Redraw()

func (*Canvas) Resize 

func (c *Canvas) Resize()

func (*Canvas) Resized 

func (c *Canvas) Resized() *Canvas

Check if the canvas was resized, and adjust values accordingly. Returns a new canvas, or nil.

func (*Canvas) SetLineWrap added in v1.9.2 

func (c *Canvas) SetLineWrap(enable bool)

func (*Canvas) SetRunewise added in v1.8.7 

func (c *Canvas) SetRunewise(b bool)

func (*Canvas) SetShowCursor added in v1.9.2 

func (c *Canvas) SetShowCursor(enable bool)

func (*Canvas) ShowCursor added in v1.5.1 

func (c *Canvas) ShowCursor()

func (*Canvas) Size 

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

Return the size of the current canvas

func (*Canvas) String added in v0.2.1 

func (c *Canvas) String() string

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

func (*Canvas) ToImage added in v1.13.0 

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

func (*Canvas) Unlock added in v1.12.3 

func (c *Canvas) Unlock()

func (*Canvas) W 

func (c *Canvas) W() uint

func (*Canvas) Width added in v1.5.0 

func (c *Canvas) Width() uint

func (*Canvas) Write added in v0.8.0 

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

func (*Canvas) WriteBackground added in v1.12.8 

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

WriteBackground will write a background color to the canvas The x and y must be within range (x < c.w and y < c.h)

func (*Canvas) WriteBackgroundAddRuneIfEmpty added in v1.12.9 

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

WriteBackgroundAddRuneIfEmpty will write a background color to the canvas The x and y must be within range (x < c.w and y < c.h)

func (*Canvas) WriteBackgroundNoLock added in v1.12.8 

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

WriteBackgroundNoLock will write a background color 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) WriteRune added in v0.9.0 

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

WriteRune will write a colored rune to the canvas

func (*Canvas) WriteRuneB added in v1.8.6 

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 added in v1.12.3 

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 added in v1.11.0 

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

WriteRunesB will write repeated colored runes to the canvas. This is the same as WriteRuneB, but bg.Background() has already been called on the background attribute. The x and y must be within range (x < c.w and y < c.h). x + count must be within range too.

func (*Canvas) WriteString added in v1.5.0 

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

WriteString will write a string to the canvas.

type Char 

type Char ColorRune

for API stability

type ColorRune added in v1.8.6 

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

type TTY added in v0.2.1 

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

func NewTTY added in v0.2.1 

func NewTTY() (*TTY, error)

NewTTY opens /dev/tty in raw and cbreak mode as a term.Term

func (*TTY) ASCII added in v0.2.1 

func (tty *TTY) ASCII() int

ASCII returns the ASCII code of the key pressed

func (*TTY) Close added in v0.2.1 

func (tty *TTY) Close()

Close will restore and close the raw terminal

func (*TTY) Flush added in v1.15.4 

func (tty *TTY) Flush()

Flush flushes the terminal output

func (*TTY) Key added in v0.2.1 

func (tty *TTY) Key() int

Key reads the keycode or ASCII code and avoids repeated keys

func (*TTY) KeyCode added in v0.2.1 

func (tty *TTY) KeyCode() int

KeyCode returns the key code of the key pressed

func (*TTY) NoBlock added in v0.2.1 

func (tty *TTY) NoBlock()

NoBlock sets the terminal to cbreak mode (non-blocking)

func (*TTY) PrintRawBytes added in v1.15.4 

func (tty *TTY) PrintRawBytes()

PrintRawBytes for debugging raw byte sequences

func (*TTY) RawMode added in v0.2.1 

func (tty *TTY) RawMode()

RawMode switches the terminal to raw mode

func (*TTY) ReadString added in v1.10.0 

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

ReadString reads a string from the TTY

func (*TTY) Restore added in v0.2.1 

func (tty *TTY) Restore()

Restore the terminal to its original state

func (*TTY) Rune added in v1.8.0 

func (tty *TTY) Rune() rune

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

func (*TTY) SetTimeout added in v0.2.1 

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

SetTimeout sets a timeout for reading a key

func (*TTY) String added in v1.8.0 

func (tty *TTY) String() string

String reads a string, handling key sequences and printable characters

func (*TTY) Term added in v0.2.1 

func (tty *TTY) Term() *term.Term

Term will return the underlying term.Term

func (*TTY) WriteString added in v1.10.0 

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

WriteString writes a string to the terminal

Source Files

View all Source files

Directories

Path Synopsis
cmd
bg
bgc
blink
box
canvas
color
icegame
info
key
menu
move
ok
raw
resize
rune
shooter
string
waitkey
widget
writerune

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.