vtTools/README.md

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

## Usage

In the simplest terms, this library allows you to create objects which represent
the DEC terminal, which can be used to write UTF-8 encoded strings to a real
hardware DEC terminal (or an extremely faithful emulator) safely.

It does this by translating UTF-8 Characters to the appropriate codepoints on
the limited character encoding used by DEC terminals, and invoking the
necessary control sequences to remap additional characters to these codepoints
when needed.

#### Create a Terminal

Terminals are attached to an `io.Writer` (usually `os.Stdout`) which will send
the data to the Hardware terminal.

```go
var term = NewVT220(os.Stdout)
```

#### Use the Terminal as a writer.

Terminals implement the `io.Writer` interface themselves (they effectively
wrap the `io.Writer` they were assigned at creation), and can be passed to
programs that need to write safely to the screen.

```go
term := NewVT220(os.Stdout)
logger := zerolog.New(term)
```

#### Use the Terminal instead of `fmt`.

In order to safely print to the screen, you can use the term instead of
the `fmt` package.

```go
import (
	stdFmt "fmt"

	"git.sdf.org/CRThaze/vtTools/vt220"
)

fmt := NewVT220(os.Stdout)

func testPrint() error {
	// Yes, the standard library fmt.Print(f|ln)? functions
	// can also return errors.
	_, err := fmt.Println("Hello World!")
	if err != nil {
		return stdFmt.Errorf("Failed to print: %v", err)
	}
	return nil
}
```

#### Invoke Arbitrary Control Sequences

DEC Terminals support their own proprietary control sequences. Terminal objects
provide some helper functions for easily using some of these, especially
for swapping character sets (some of these are handled automatically when
writing to or printing with the terminal object).

The [DEC VT220 Programmers Reference Manual](https://web.archive.org/web/20230928233241/vt100.net/docs/vt220-rm/chapter4.html)
describes numerous control sequences which can be used to enable various feautres
and functions.

They characters that make them up are indicated in the manual by either a mnemonic or
character from the standard character sets, as well as a Column / Row above these.
It is very easy invoke any combination of control characters using these:

```go
import (
	"git.sdf.org/CRThaze/vtTools/vt220"
)

term := NewVT220(os.Stdout)

func main() {
	cs := vt220.NewControlSequence(
		// The characters from the C0 and C1 ranges can be refrenced by either
		// their coordinates (C00R01) or their mnemonic (as below).
		vt220.ESC,
		vt220.C02R09,
	)
	term.InvokeCtrlSequence(cs)
}
```

## Roadmap

- Optimize the mapping of new character sets to codepoint ranges when
  shifting sets in.
- Build an equivalency table for a wider array of Unicode characters to
  find characters in the terminal's repetoire that are visually similar enough
  to use instead.
- Support loading, and invoking soft (down-line-loadable) Character
  Sets (fonts)
- Support creating arbitrary sixels for use in Soft Character Sets.
- Have write method more intelligently determine when to lock-shift or
  designate character sets into the graphic registers based on what would be
  most efficient for the given string to print.
- Add more helper-functions for standard control sequences.
- Support VT100 and more.
- Support 7-bit mode.