vtTools

README

VT Tools

vtTools is a Go library for providing support for Digital Equipment Corporation Video Terminals to Go programs.

It currently only supports the DEC VT220 in 8-bit Mode.

Why

Go programs are written in UTF-8. This can cause challenges when running the compiled program on DEC Hardware Terminals which use a proprietary 8-bit encoding which (while flexible) is only partially compatible with modern character encoding formats.

This library aims to allow developers to write Go code (in UTF-8) which can be run correctly on DEC Video Terminals.

It also provides some support for manipulating the terminal in additional ways according to its documented spec. (See the section on Control Sequences below)

Installation

go get codeberg.org/CRThaze/vtTools

CLI Usage

The vt command-line tool encodes UTF-8 text to VT220 character encoding.

Basic Usage

# Encode piped input
echo "Hello World" | vt

# Apply character attributes
echo "Important message" | vt --bold
echo "Warning" | vt --bold --underline

# Combine multiple attributes
cat document.txt | vt --bold --negative

Flags

Flag	Default	Description
--equivalence	true	Use equivalence encoding for similar characters
--dynamic	true	Use dynamic graphic set selection with single shifts
--national	false	Use 7-bit national mode instead of 8-bit multinational
--bold	false	Apply bold attribute to output
--underline	false	Apply underline attribute to output
--blink	false	Apply blink attribute to output
--negative	false	Apply negative/reverse video attribute to output

Subcommands

Command	Description
vt demo	Display an interactive demo of character sets and attributes

Library Usage

Basic Encoding

package main

import (
    "os"
    "codeberg.org/CRThaze/vtTools/term"
)

func main() {
    vt := term.New(os.Stdout)
    vt.Print("Hello, VT220!")
    vt.Printf("The answer is %d\n", 42)
}

Configuration Options

vt := term.NewWithConfig(os.Stdout, term.VTConfig{
    Mode:              term.Multinational,  // or term.National for 7-bit NRC
    UseEquivalence:    true,                // map similar Unicode chars
    DynamicGraphicSet: true,                // use SS2/SS3 for extended chars
})

Character Set Designation

The VT220 has four graphic registers (G0-G3) that can hold character sets:

import "codeberg.org/CRThaze/vtTools/term/control"
import "codeberg.org/CRThaze/vtTools/term/repertoire"

// Designate character sets to registers
vt.Designate(control.G0, repertoire.ASCII)
vt.Designate(control.G1, repertoire.Supplemental)
vt.Designate(control.G2, repertoire.SpecialGraphics)

// Lock shift registers into GL/GR
vt.LockShiftGL(control.G0)  // G0 -> GL (7-bit range)
vt.LockShiftGR(control.G1)  // G1 -> GR (8-bit range)

// Single shift for one character from G2 or G3
vt.SingleShiftG2(0x6A)  // Output one char from G2

Character Rendition Attributes (SGR)

Apply text attributes using the fluent Attr() builder:

// Single attributes
vt.Attr().Bold().Print("Bold text")
vt.Attr().Underline().Println("Underlined")
vt.Attr().Blink().Print("Blinking")
vt.Attr().Negative().Print("Reverse video")

// Combined attributes
vt.Attr().Bold().Underline().Printf("Score: %d", score)
vt.Attr().Bold().Blink().Negative().Println("ALERT!")

// For composition, use Bprint variants (return []byte)
header := vt.Attr().Bold().Bprint("Status: ")
value := vt.Attr().Underline().Bprint("OK")
vt.WriteRaw(append(header, value...))

Terminal Control

// Reset terminal to default state
vt.Reset(false)       // Soft reset (DECSTR)
vt.Reset(true)        // Soft reset + clear screen

// Send control sequences directly
vt.SendSequence(control.ClearScreen)
vt.SendSequence(control.CursorHome)

Available Character Sets

Set	Description	DSCS
repertoire.ASCII	US ASCII	B
repertoire.Supplemental	DEC Supplemental Graphics	<
repertoire.SpecialGraphics	DEC Special Graphics (box drawing)	0
repertoire.British	British NRC	A
repertoire.Dutch	Dutch NRC	4
repertoire.Finnish	Finnish NRC	C
repertoire.French	French NRC	R
repertoire.FrenchCanadian	French Canadian NRC	Q
repertoire.German	German NRC	K
repertoire.Italian	Italian NRC	Y
repertoire.NorwegianDanish	Norwegian/Danish NRC	E
repertoire.Spanish	Spanish NRC	Z
repertoire.Swedish	Swedish NRC	H
repertoire.Swiss	Swiss NRC	=

Note: NRC (National Replacement Character) sets require 7-bit national mode and cannot be used in multinational mode.

Packages

vtTools contains the following subpackages:

Package	Description	Status
encoding	An implementation of the golang.org/x/text/encoding interface for the DEC Proprietary encodings used on the DEC VT series of Terminals.	Implemented
equivalence	A mapping of similar Unicode glyphs to the reduced characters supported by the DEC proprietary encodings.	Implemented
sixel	Tools for working with the DEC Sixel format.	NOT Implemented
term	An abstraction for controlling and printing text on a DEC VT Hardware Video Terminal.	Implemented
cmd	CLI Implementation	Implemented

Glossary

Term	Definition
Code Page	A mapping between a Character Set and a Code Space (GL or GR), enabling translation between Unicode runes and DEC byte values.
Code Table	A 16x16 matrix representing all 256 possible byte values (0x00-0xFF), divided into control regions (C0, C1) and graphic regions (GL, GR).
Code Space	A region of the Code Table: C0 (columns 0-1), GL (columns 2-7), C1 (columns 8-9), or GR (columns 10-15).
Character Set	A collection of glyphs mapped to the 94 positions in a graphic code space (GL or GR), plus SP and DEL.
Glyph	A visual representation of a character; in this library, a Unicode rune that corresponds to a position in a Character Set.
Glyph Table	A 16x6 matrix mapping row/column positions to Unicode runes for a single graphic code space.
Encoding	The process of converting UTF-8 text to DEC byte sequences, or vice versa (decoding).
GL	Graphics Left - the 7-bit graphic code space (columns 2-7, bytes 0x20-0x7F) containing printable characters.
GR	Graphics Right - the 8-bit graphic code space (columns 10-15, bytes 0xA0-0xFF) containing supplemental characters.
C0	The control code space for bytes 0x00-0x1F (columns 0-1), containing ASCII control characters.
C1	The control code space for bytes 0x80-0x9F (columns 8-9), containing 8-bit control characters.
DEC MSC	DEC Multinational Character Set - a full 8-bit encoding combining ASCII (GL) with DEC Supplemental Graphics (GR).
DEC NRC	DEC National Replacement Character sets - 7-bit character sets that replace certain ASCII characters with national variants (e.g., British, German, French).
SGR	Select Graphic Rendition - control sequences for character attributes (bold, underline, blink, negative).
SCS	Select Character Set - escape sequences for designating character sets to graphic registers.
DSCS	Designate Character Set Sequence - the final byte(s) that identify a character set in SCS sequences.

References

• VT220 Programmer Reference Manual
• VT220 Programmer Pocket Guide