hotty-go

hotty-go is the Go SDK for hotty, HTML over the TTY. With it, a terminal program shows small HTML documents, called surfaces, on rectangles of cells, and hears what the user does in them. A surface can be a card left in the scrollback, a chart that streams, a form that asks, or the panels of a full-screen Bubble Tea program.

It speaks hotty 0.4: a key is named as myelin key names name it (ctrl+a, arrow_left, shift+g; SPEC §10.4), a host's replies and events carry msgpack bodies (SPEC §3.3), and its query lists the version it speaks (a=q:n=1:v=0.4, SPEC §4). A terminal of another hotty version is no host to it, and the program draws in cells. A program written for 0.3 ports as hotty's CHANGES.md says: its data-keys, menu keys and tests move to the new names, a hotty.Platform's Mod is "ctrl" or "super", a key is read with hotty.ParseKey or Platform.ReadKey, and hotty.ModControl and hotty.ModMeta are hotty.ModCtrl and hotty.ModSuper.

The SDK:

• encodes the protocol, and cuts it out of a byte stream, for a program that reads its terminal raw or a relay that reads another's output;
• finds out whether the terminal is a hotty host;
• keeps surfaces on screen while a full-screen frame changes;
• edits a text field in cells as a host edits it on a surface, with the keymap the program gives both (hotty.TerminalKeys, hottyedit);
• converts Markdown, tables and images into documents;
• tests programs against a host that runs inside go test.

Every program has three renditions (SPEC §14): surfaces on a host, cells on any other terminal, and plain data into a pipe. The examples show all three.

t, err := hottyterm.Open("hello") // the terminal, whatever stdout is
if err != nil {
	fmt.Println("Hello.") // no terminal: a pipe, a cron job
	return
}
defer t.Close()
if !t.Detect(ctx) {
	fmt.Println("Hello.") // a terminal that is not a host
	return
}
_ = t.LineStart(ctx)
_, _ = t.Print("hello", `<p>Hello, <b>HTML</b> in the terminal.</p>`, hotty.Placement{Cols: 40, Rows: 1})
_, _ = t.Fence(ctx) // the host's replies, before the shell reads the terminal

Testing it needs no terminal:

h := hottytest.New(t)
run(ctx, hottyterm.New(h, h, "hello", h.TermSize, nil))
h.Surface("hello-hello").Text() // "Hello, HTML in the terminal."

The reference is in docs/api and on pkg.go.dev.

Install

The SDK is a few modules, so that a program takes on only the dependencies of what it imports:

go get github.com/neuroplastio/hotty-go github.com/neuroplastio/hotty-go/hottyterm

Packages

Examples

Each example is a program for one use case. It works in a hotty host, in any other terminal, and into a pipe, and its tests run it in each.

The examples are a module of their own (examples/go.mod), built against the SDK beside them: what they import is never the SDK's dependency. Run one from there:

cd examples
go run ./dashboard https://example.com

Documentation

The API reference in docs/api is written from the code by internal/docgen: the doc comments, the Example functions, and the examples' package comments. make docs writes it again, as does go generate ./.... The tables above are written the same way, between their markers; the rest of this file is not. CI fails when what is checked in is not what make docs would write, and when an exported identifier has no doc comment.

Development

The toolchain is in mise.toml: run mise install first.

• make check is the gate: formatting, tidy modules, vet, staticcheck, the tests with the race detector, coverage, and the documentation being current, in every module.
• The modules build against each other as they are in the repository: each nested go.mod replaces the others with their directories. What a program that uses the SDK gets are the requirements between them, which make pin REV=… sets: before a release to a pushed commit, and for a release to its version (make pin REV=v0.1.0), committed, and then every module tagged at that commit (v0.1.0, hottyterm/v0.1.0, …).
• make cover runs the tests with coverage, prints a table by package, and fails when a public package is under COVER_MIN (85%).
• make docs writes the documentation.
• make vectors copies the conformance vectors from a checkout of neuroplastio/hotty (HOTTY_DIR, by default ../../hotty/main).

Licensed under Apache-2.0.