Packages
This chapter contains an index of all of the Go packages in cy's pkg directory, the READMEs of which are consolidated here for your convenience.
anim
Package anim contains a range of terminal animations. These are used on cy's splash screen and in the background while fuzzy finding.
bind
Package bind is a key binding engine. It checks incoming key events against all registered key bindings to determine whether an action should be fired. bind uses a trie data structure, implemented in the bind/trie package, to describe sequences of keys.
As distinct from a traditional trie, in which nodes have a fixed value, bind's trie also supports regex values. Key events are stringified and then compared against the regex pattern to determine if the state machine should transition to that node.
cy
Package cy contains cy's server and Janet API.
emu
Package emu provides a VT100-compatible terminal emulator. For the most part it attempts to emulate xterm as closely as possible (ie to be used with TERM=xterm-256color.)
emu's basic mode of operation is quite simple: you Write() some bytes and it will correctly calculate the state of the virtual terminal which you can happily capture and send elsewhere (with Terminal.View()).
emu's magic, however, comes from Terminal.Flow(), which is an API for viewing the terminal's scrollback buffer with a viewport of arbitrary size. This is important because cy's core feature is to be able to replay terminal sessions, the lines of which should wrap appropriately to fit your terminal screen.
This package is a fork of github.com/hinshun/vt10x. The original library was rough, incomplete, and had a range of serious bugs that I discovered after integrating it. Because of this, little of the original code remains.
fluid
Package fluid is a viscoelastic fluid simulator ported from kotsoft/particle_based_viscoelastic_fluid. Out of fear of making a mistake, I made no effort to translate the original JavaScript into idiomatic Go.
frames
Package frames contains static backgrounds.
geom
Package geom provides a range of geometric primitives and convenience methods. Notably, it contains:
- Data types for representing static bitmaps of terminal data (
image.Image) and terminal state (tty.State). Vec2, a traditional vector data type but with a terminal flavor: ie it usesRandC(for rows and columns) instead ofXandY
input/fuzzy
Package fuzzy is a fully-featured fuzzy finder a la fzf. In fact, it makes use of fzf's actual agorithm, forked here as the fuzzy/fzf package.
input/fuzzy/fzf
This is a fork of fzf's matching algorithm.
io
Package io is an assortment of packages with a general theme of IO, including the protocol used by clients to interact with the cy server.
janet
Package janet contains a Janet virtual machine for interoperation between Go and Janet code. Users of its API can register callbacks, define symbols in the Janet environment, execute Janet code, and convert between Go and Janet values.
This code is, admittedly, a little terrifying. Suffice it to say that Janet was not designed to be used from Go, and as a result there are a lot of silly tricks this library uses to ensure we only access memory used by the Janet VM in the goroutine where it was initialized.
Updating Janet
To update the janet version, clone the janet-lang/janet repository and run make, then copy build/c/janet.c, src/include/janet.h, and src/conf/janetconf.h to this directory.
mux
Package mux defines Screen and Stream, two of cy's core abstractions for representing interactive windows and streams of terminal data, respectively. It also contains a wide range of useful Screens and Streams used across cy.
params
Package params is a thread-safe map data structure used as a key-value store for all nodes in cy's node tree.
replay
Package replay is an interface for playing, searching, and copying text from recorded terminal sessions.
replay/replayable
Package replayable is a Screen that pipes a Stream into a Terminal, intercepting all events so that it can be replayed.
sessions
Package sessions contains a data type for recorded terminal sessions and a range of utilities for (de)serializing, searching through, and exporting them.
sessions/search
Package search is a high-performance search algorithm to find matches for a regex pattern on the terminal screen over the course of a recorded terminal session. This is more complicated than it seems: it must track the exact byte at which a match first appeared and calculate how long that match remained intact on the screen.
stories
Package stories is an interface for registering and viewing stories. Stories are predefined configurations of cy's UI components that may also describe a sequence of user inputs that are "played" into the story after it is loaded. This is similar to Storybook.
taro
Package taro is a high level framework for defining terminal interfaces that obey cy's Screen interface. It is a fork of charmbracelet/bubbletea and borrows that library's state machine paradigm, originally inspired by the Elm framework.
I wanted bubbletea Programs to be able to write to arbitrary parts of the screen without futzing with strings. I also needed to improve on bubbletea's key/mouse event parsing (which, at any rate, has since been patched).
util/dir
Taken from robertknight/rd. No license specified.