API

This is a complete listing of all of the API functions that cy provides in the top-level Janet environment (ie you do not need to import or use anything.)

Janet code executed with cy can also access everything from Janet's standard library except for anything in spork. In addition, Janet's ev family of functions probably will not work; I have never tested them.

Concepts

Binding

Several API functions related to binding keys return a Binding. A Binding table represents a single key sequence and its associated function. Each table has the following properties:

:node: the NodeID where the binding is defined.
:sequence: a list of strings representing the key sequence that will execute this action. If the original call to key/bind used a regex, it will be returned as a string with a re: prefix.
:function: the Janet function that will be called when this sequence is executed.

For example:

{
  :node 1
  :sequence ["ctrl+a" "t"]
  :function <some function>
}

NodeID

Many API functions have a parameter of type NodeID, which can be one of two values:

:root which is a short way of referring to cy's top-level group.
An integer that refers to a node in cy's node tree. You cannot infer these yourself, but they are returned from API functions like pane/current and group/children.

Symbols

action/choose-frame action/command-palette action/jump-command action/jump-pane action/jump-pane-command action/jump-project action/jump-screen-lines action/jump-shell action/kill-current-pane action/margins-160 action/margins-80 action/margins-bigger action/margins-smaller action/new-project action/new-shell action/next-pane action/open-log action/random-frame action/reload-config action/toggle-margins cmd/commands cmd/new cmd/path cy/detach cy/env cy/get cy/kill-server cy/log cy/paste cy/reload-config cy/replay cy/set cy/toast exec/file group/children group/leaves group/new input/find key/action key/bind key/bind-many key/bind-many-tag key/current key/get key/remap key/unbind pane/attach pane/current pane/screen path/abs path/base path/glob path/join replay/beginning replay/command-backward replay/command-forward replay/copy replay/cursor-down replay/cursor-left replay/cursor-right replay/cursor-up replay/end replay/end-of-line replay/end-of-screen-line replay/first-non-blank replay/first-non-blank-screen replay/half-page-down replay/half-page-up replay/jump-again replay/jump-backward replay/jump-forward replay/jump-reverse replay/jump-to-backward replay/jump-to-forward replay/last-non-blank replay/last-non-blank-screen replay/middle-of-line replay/middle-of-screen-line replay/open replay/quit replay/scroll-down replay/scroll-up replay/search-again replay/search-backward replay/search-forward replay/search-reverse replay/select replay/start-of-line replay/start-of-screen-line replay/swap-screen replay/time-play replay/time-playback-rate replay/time-step-back replay/time-step-forward shell/attach shell/new tree/group? tree/kill tree/name tree/pane? tree/parent tree/path tree/root tree/set-name viewport/get-frames viewport/set-frame viewport/set-size viewport/size

action/choose-frame

function

(action/choose-frame)

Choose a frame.

source

action/command-palette

function

(action/command-palette)

Open the command palette.

source

action/jump-command

function

(action/jump-command)

Jump to the output of a command.

source

action/jump-pane

function

(action/jump-pane)

Jump to a pane.

source

action/jump-pane-command

function

(action/jump-pane-command)

Jump to a pane based on a command.

source

action/jump-project

function

(action/jump-project)

Jump to a project.

source

action/jump-screen-lines

function

(action/jump-screen-lines)

Jump to a pane based on screen lines.

source

action/jump-shell

function

(action/jump-shell)

Jump to a shell.

source

action/kill-current-pane

function

(action/kill-current-pane)

Kill the current pane.

source

action/margins-160

function

(action/margins-160)

Set size to 160 columns.

source

action/margins-80

function

(action/margins-80)

Set size to 80 columns.

source

action/margins-bigger

function

(action/margins-bigger)

Increase margins by 5 columns.

source

action/margins-smaller

function

(action/margins-smaller)

Decrease margins by 5 columns.

source

action/new-project

function

(action/new-project)

Create a new project.

source

action/new-shell

function

(action/new-shell)

Create a new shell.

source

action/next-pane

function

(action/next-pane)

Move to the next pane.

source

action/open-log

function

(action/open-log)

Open a .borg file.

source

action/random-frame

function

(action/random-frame)

Switch to a random frame.

source

action/reload-config

function

(action/reload-config)

Reload the cy configuration.

source

action/toggle-margins

function

(action/toggle-margins)

Toggle the screen's margins.

source

cmd/commands

function

(cmd/commands arg0)

cmd/new

function

(cmd/new parent &named path command args name)

Run command with args and working directory path in a new pane as a child of the group specified by parent. You may also provide the name of the new pane. If command is not specified, (cmd/new) defaults to the current user's shell. parent is a NodeID.

When the command exits, it will be rerun. This is not currently configurable. If the command exits with a non-zero exit code more than three times in a second, it will not be run again.

Some examples:

# Create a new shell in the root group
(cmd/new :root)

# `args` is a list of strings
(cmd/new :root :command "less" :args @["README.md"])

cmd/path

function

(cmd/path target)

Get the working directory of the program running in the pane pane specified by target. target is a NodeID.

cy/detach

function

(cy/detach)

Detach from the cy server.

cy/env

function

(cy/env)

cy/get

function

(cy/get key)

Get the value of the parameter with key key.

cy/kill-server

function

(cy/kill-server)

Kill the cy server, disconnecting all clients.

cy/log

function

(cy/log level message)

Log message to the /logs pane. level must be one of :info, :warn, :error.

cy/paste

function

(cy/paste)

Paste the text in the copy buffer to the current pane.

cy/reload-config

function

(cy/reload-config)

Detect and (re)evaluate cy's configuration. This uses the same configuration detection scheme described in the Configuration chapter.

cy/replay

function

(cy/replay &named main copy location)

Enter replay mode for the current pane.

cy/set

function

(cy/set key value)

Set the value of the parameter with key key to value value. For the time being, parameter values can only be strings, booleans, and integers. This is expected to change in the future.

cy/toast

function

(cy/toast level message)

Send a toast with message to all attached clients. level must be one of :info, :warn, :error.

exec/file

function

(exec/file path)

Execute the Janet file found at path. Throws any errors that occur during execution.

group/children

function

(group/children group)

Get the NodeIDs for all of group's child nodes.

group/leaves

function

(group/leaves group)

Get the NodeIDs for all of the leaf nodes reachable from group. In other words, this is a list of all of the NodeIDs for all panes that are descendants of group.

group/new

function

(group/new parent &named name)

Create a new group with parent and (optionally) name.

parent is a NodeID.

input/find

function

(input/find inputs &named prompt full reverse animated headers)

(input/find) is a general-purpose fuzzy finder that is similar to fzf. When invoked, it prompts the user to choose from one of the items provided in inputs. (input/find) does not return until the user makes a choice; if they choose nothing (such as by hitting ctrl+c), it returns nil.

inputs is an array with elements that can take different forms depending on the desired behavior. See more on the page about fuzzy finding.

This function supports a range of named parameters that adjust its functionality:

:full (boolean): If true, occupy the entire screen.
:prompt (string): The text that will be shown beneath the search window.
:reverse (boolean): Display from the top of the screen (rather than the bottom.)
:animated (boolean): Enable and disable background animation.
:headers ([]string): Provide a title for each column. This mostly used for filtering tabular data.

key/action

macro

(key/action name docstring & body)

An action is just a Janet function that is registered to the cy server with a short human-readable string description. It provides a convenient method for making some functionality you use often more discoverable.

In a similar way to other modern applications, cy has a command palette (invoked by default with ctrl+a ctrl+p, see (action/command-palette) ) in which all registered actions will appear.

source

key/bind

function

(key/bind target sequence callback)

Bind the key sequence sequence to callback for node target, which is a NodeID, :time (for time mode), or :copy (for copy mode). target can refer to any group or pane.

sequence is a key sequence, which consists of a tuple with string elements that are either key literals ("h"), preset key specifiers ("ctrl+a"), or regex patterns ([:re "^[a-z]$"]).

Read more about binding keys in the dedicated chapter.

key/bind-many

macro

(key/bind-many scope & body)

Bind many bindings at once in the same scope.

For example:

(key/bind-many :root
               [prefix "j"] action/new-shell
               [prefix "n"] action/new-project)

source

key/bind-many-tag

macro

(key/bind-many-tag scope tag & body)

Bind many bindings at once in the same scope, adding the provided tag.

source

key/current

function

(key/current)

Get all of the bindings accessible to the current client as an array of Bindings. It contains all of the bindings defined by the node to which the client is attached and its ancestors. In other words, this is equivalent to the list of bindings against which the client's key presses are compared.

key/get

function

(key/get target)

Get all of target's bindings. target is a NodeID, :time, or :copy. Returns an array of Bindings. Note that this does not return bindings defined in an ancestor node, only those defined on the node itself.

key/remap

function

(key/remap target from to)

Remap all bindings that begin with sequence from to sequence to for node target, which is a NodeID, :time, or :copy. Empty sequences ([]) are not currently supported for from and to.

For example, to remap all of the default bindings that begin with ctrl+a to ctrl+v:

(key/remap :root ["ctrl+a"] ["ctrl+v"])

key/unbind

function

(key/unbind target sequence)

Clear all bindings that begin with sequence for node target, which is a NodeID, :time, or :copy. Note that the empty sequence [] will unbind all keys in the scope.

sequence is a key sequence, which consists of a tuple with string elements that are either key literals ("h"), preset key specifiers ("ctrl+a"), or regex patterns ([:re "^[a-z]$"]).

The following code snippet will unbind all of cy's default keybindings that begin with ctrl+a:

(key/unbind :root ["ctrl+a"])

pane/attach

function

(pane/attach pane)

Attach to pane, which is a NodeID that must correspond to a pane. This is similar to tmux's attach command.

pane/current

function

(pane/current)

Get the NodeID of the current pane.

pane/screen

function

(pane/screen pane)

Get the visible screen lines of the pane referred to by NodeID. Returns an array of strings.

path/abs

function

(path/abs path)

Return the full absolute path for path. Calls Go's path/filepath.Abs.

path/base

function

(path/base path)

Return the last element of path. Calls Go's path/filepath.Base.

path/glob

function

(path/glob pattern)

Return an array of all files matching pattern. Calls Go's path/filepath.Glob.

path/join

function

(path/join paths)

Join the elements of the string array paths with the OS's file path separator. Calls Go's path/filepath.Join.

replay/beginning

function

(replay/beginning)

Go to the beginning of the time range (in time mode) or the first line of the screen (in copy mode).

replay/command-backward

function

(replay/command-backward)

In time mode, jump to the moment in time just before the last command was executed. In copy mode, move the cursor to the first character of the last command that was executed.

replay/command-forward

function

(replay/command-forward)

In time mode, jump to the moment in time just before the next command was executed. In copy mode, move the cursor to the first character of the next command.

replay/copy

function

(replay/copy)

Yank the selection into the copy buffer.

replay/cursor-down

function

(replay/cursor-down)

Move cursor down one cell.

replay/cursor-left

function

(replay/cursor-left)

Move cursor left one cell.

replay/cursor-right

function

(replay/cursor-right)

Move cursor right one cell.

replay/cursor-up

function

(replay/cursor-up)

Move cursor up one cell.

replay/end

function

(replay/end)

Go to the end of the time range (in time mode) or the last line of the screen (in copy mode).

replay/end-of-line

function

(replay/end-of-line)

Move to the last character of the physical line. Equivalent to vim's $.

replay/end-of-screen-line

function

(replay/end-of-screen-line)

Move to the end of the screen line. Equivalent to vim's g$.

replay/first-non-blank

function

(replay/first-non-blank)

Move to the first non-blank character of the physical line. Equivalent to vim's ^.

replay/first-non-blank-screen

function

(replay/first-non-blank-screen)

Move to the first non-blank character of the screen line. Equivalent to vim's g^.

replay/half-page-down

function

(replay/half-page-down)

Scroll the viewport half a page (half the viewport height) down.

replay/half-page-up

function

(replay/half-page-up)

Scroll the viewport half a page (half the viewport height) up.

replay/jump-again

function

(replay/jump-again)

Repeat the last character jump.

replay/jump-backward

function

(replay/jump-backward char)

Jump to the previous instance of char on the current line.

replay/jump-forward

function

(replay/jump-forward char)

Jump to the next instance of char on the current line.

replay/jump-reverse

function

(replay/jump-reverse)

Repeat the inverse of the last character jump.

replay/jump-to-backward

function

(replay/jump-to-backward char)

Jump to the cell before char after the cursor on the current line.

replay/jump-to-forward

function

(replay/jump-to-forward char)

Jump to the cell before char after the cursor on the current line.

replay/last-non-blank

function

(replay/last-non-blank)

Move to the last non-blank character of the physical line. Equivalent to vim's g_.

replay/last-non-blank-screen

function

(replay/last-non-blank-screen)

Move to the last non-blank character of the screen line. Equivalent to vim's g<end>.

replay/middle-of-line

function

(replay/middle-of-line)

Move to the middle of the physical line. Equivalent to vim's gM.

replay/middle-of-screen-line

function

(replay/middle-of-screen-line)

Move to the middle of the screen line. Equivalent to vim's gm.

replay/open

function

(replay/open group path)

Open the .borg file found at path in a new replay window in group.

For example:

(replay/open (tree/root) "some_borg.borg")

replay/quit

function

(replay/quit)

Quit replay mode.

replay/scroll-down

function

(replay/scroll-down)

Scroll the viewport one line down.

replay/scroll-up

function

(replay/scroll-up)

Scroll the viewport one line up.

replay/search-again

function

(replay/search-again)

Go to the next match in the direction of the last search.

replay/search-backward

function

(replay/search-backward)

Search for a string backwards in time (in time mode) or in the scrollback buffer (in copy mode).

replay/search-forward

function

(replay/search-forward)

Search for a string forwards in time (in time mode) or in the scrollback buffer (in copy mode).

replay/search-reverse

function

(replay/search-reverse)

Go to the previous match in the direction of the last search.

replay/select

function

(replay/select)

Enter visual select mode.

replay/start-of-line

function

(replay/start-of-line)

Move to the first character of the physical line. Equivalent to vim's 0.

replay/start-of-screen-line

function

(replay/start-of-screen-line)

Move to the first character of the screen line. Equivalent to vim's g0.

replay/swap-screen

function

(replay/swap-screen)

Swap between the alt screen and the main screen. This allows you to return to the pane's scrollback without quitting a program that is using the alternate screen, such as vim or htop.

replay/time-play

function

(replay/time-play)

Toggle playback.

replay/time-playback-rate

function

(replay/time-playback-rate rate)

Set the playback rate to rate. Positive numbers indicate a multiplier of real time moving forwards, negative numbers, backwards. For example, a rate of 2 means that time will advance at twice the normal speed; -2 means that time will go backwards at -2x.

rate is clamped to the range [10, 10].