Rhai API reference¶

This page lists the API available to cub Rhai scripts. Use Node methods for ordinary outline work. The lower-level GNX methods are useful when an operation specifically requires a node id.

Opening and saving¶

Nodes¶

Search patterns use the same regular-expression syntax as cub inspect --search and fail when the expression is invalid.

Nodes, clones, and positions¶

A GNX identifies shared node content. A position identifies one occurrence of that node in the outline.

doc.node(gnx), find_h(), and find_b() produce GNX-based handles. When a node has clones, structural operations on such a handle use its first occurrence. Nodes returned by node_at(), parent(), parents(), children(), and subtree() retain the exact occurrence in node.position.

This distinction is most important for removal:

let exact = doc.node_at("0/1");
exact.remove();                 // removes occurrence 0/1

let by_id = doc.node(exact.gnx);
by_id.remove();                 // removes the first remaining occurrence

Prefer a positioned Node when traversing or destructively editing cloned content. Headline and body edits affect every occurrence because clones share the same content.

Document operations¶

doc.apply() accepts the same operation batches as cub apply. See Automation and AI tools for their JSON formats.

GNX equivalents¶

These methods expose the operations underlying Node, using GNX strings directly:

Assertions and output¶

Rhai extensions¶

Functions cub adds to the base Rhai engine, available anywhere -- not tied to a Doc or Node.

All regex_* functions fail (throw) if pattern isn't a valid regular expression -- the same syntax cub inspect --search and doc.find_h/doc.find_b use.

Rhai string literals apply their own escaping before the pattern ever reaches the regex engine, so a backslash meant for the regex needs a second one to survive the string literal: match a literal digit with regex_is_match("\\d+", text), not "\d+" -- the latter is a syntax error ("Invalid escape sequence"), since Rhai doesn't recognize \d as a string escape.

cub:: conventions¶

Unlike the extensions above (generic engine additions with no opinion about outline shape) and the Doc/Node API (generic outline primitives with no opinion about content), cub:: holds functions for cub's own outline conventions -- built on that API, but opinionated about what particular nodes mean.

cub::variable walks target and its ancestors, nearest first, returning the first definition of name it finds among any @variables child along the way -- so different subtrees in the same outline can each set their own value for the same name without clobbering each other. Falls back to a top-level root itself headlined @variables if nothing turned up walking ancestors, for an outline that keeps one outline-wide settings block rather than scoping it to a subtree.

A setting can be written either way: a child headlined name = value, or a child headlined plain name with value in its body (get_variables's shape, from before @variables could be scoped -- both still work, and can be mixed within the same @variables node).

Subprocesses and files¶

Subprocesses¶

Each sh form returns #{ stdout, stderr, code }. A command's non-zero status is returned in code rather than thrown. A process terminated by a signal uses -1.

Paths and directories¶

Files¶

Paths passed as strings are relative to cub's current working directory. Use doc.dir() + "/name" for a path beside the open outline.

TUI script contexts¶

An @action body receives:

An @import command must have the signature fn name(doc, target), where target is a positioned Node. Only functions the top-level COMMANDS map names appear in the action palette -- COMMANDS is #{ fn_name: "one-line description", ... }; the description shows next to the command in the palette.

A script may also define fn available_commands(doc, target) -> map, same shape, for commands whose palette availability depends on the current selection rather than being always offered. Called with the live selection each time the palette opens (or the query changes), the returned map is unioned into COMMANDS's -- a name in both takes available_commands's description, letting it override as well as add. It's meant to be a pure query; nothing stops it from also calling a mutating Doc method, but any such mutation is discarded rather than applied, since it runs against a throwaway copy of the outline, not the one actually open in the TUI. Simply not defining available_commands is the normal, silent case -- most scripts don't need it, and the static COMMANDS set still shows.

An @imported script that fails to read, doesn't parse, throws while its top level runs, or (for available_commands specifically) throws or doesn't return a map, contributes no entries -- and its error message shows in place of the usual per-entry description line below the palette list, so a broken script doesn't just look like one with nothing to offer.

Gotchas¶

Rhai's string case/whitespace/substitution methods -- trim(), trim_start(), trim_end(), to_upper(), to_lower(), replace(), and similar -- mutate their target in place and return nothing. Chaining one onto a temporary throws the result away:

print(result.stdout.trim());   // prints nothing; the trimmed copy is discarded

Call it as a statement on a variable instead, then use that variable:

let hash = result.stdout;
hash.trim();
print(hash);                   // prints the trimmed value

Rhai caps expression nesting depth to guard against pathological input -- 64 levels at a script's top level, 32 (raised here to 64, matching the top-level limit) inside a fn. A long +-chained string build or a few levels of if/for around a compound condition can reach that inside one function faster than it looks; if a script fails to parse with "Expression exceeds maximum complexity", split the expression across a few let/+= statements or an extra helper function rather than one large one.