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

source

Package anim contains a range of terminal animations. These are used on cy's splash screen and in the background while fuzzy finding.

anim/fluid

source

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.

bind

source

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

source

Package cy contains cy's server and Janet API.

emu

source

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.

frames

source

Package frames contains static backgrounds.

geom

source

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 uses R and C (for rows and columns) instead of X and Y

input/fuzzy

source

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

source

This is a fork of fzf's matching algorithm.

io

source

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

source

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

source

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

source

Package params is a thread-safe map data structure used as a key-value store for all nodes in cy's node tree.

replay

source

Package replay is an interface for playing, searching, and copying text from recorded terminal sessions.

replay/replayable

source

Package replayable is a Screen that pipes a Stream into a Terminal, intercepting all events so that it can be replayed.

sessions

source

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

source

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

source

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.

style/colormaps

source

Package colormaps contains color schemes imported from tinted-theming/schemes.

style/colormaps/schemes

source

Have a look at the Gallery to preview these colorschemes.

Imported Scheme Repositories

These are the original locations all schemes were imported from.

FAQ

Where did these all come from?

These schemes were originally imported from the original schemes source repo on May 25th, 2022 around 11pm UTC.

They were migrated from our old base16-schemes repo on Dec 15th, 2023 around 8pm UTC.

taro

source

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

source

Taken from robertknight/rd. No license specified.