Skip to main content

Crate arb

Crate arb 

Source
Expand description

arb — visualize and modify Unix pipelines.

The crate is a lib + bin: the language front-end (lexer/parser/interpreter) lives here so it is unit-testable without a terminal; the arb binary (src/main.rs) wires it to stdin and the ratatui render loop.

M1 scope: the Tcl-flavored reader, the declarative widget/source subset, and rendering text/tail/list widgets fed from stdin. The expression layer, fusevm lowering, query verbs, and the rest of SPEC.md are later milestones — not stubbed here as if present.

Re-exports§

pub use embed::run_program;

Modules§

actor
Actor system — Akka-style message-passing concurrency for arb.
algo
A port of fzf’s matching algorithm — src/algo/algo.go from fzf 0.74.2.
ast
Parsed command tree: a spec is a list of commands, each a verb plus args; an arg may itself be a nested block of commands (e.g. a source { … } body).
banner
The REPL banner (shown only for the interactive arb --repl / bare-TTY launch, never for a piped render or the headless dump path).
cache
rkyv-backed script cache for parsed .arb specs (mirrors the sibling langs zshrs/rubylang/elisprs/vimlrs/awkrs). Versioned from day one so a spec that parsed once never breaks on a later run.
cli
cli submodule: the command line, callable as a library. arb — visualize and modify Unix pipelines.
dap
Debug Adapter (arb --dap): a real, steppable DAP over the same stdio Content-Length framing as the LSP. The debugger model reinterprets arb’s stream world onto DAP concepts — the same per-line predicate scan the TUI already runs against expect /regex/ reactions, run headless and made to block the feed thread on a condvar instead of firing an action:
embed
Running an arb spec from a host program, without a process or a terminal.
err
SpecError — a lex/parse/build error that optionally carries the source span (char offsets) where it occurred, so the LSP can anchor a diagnostic to the real location. It converts freely to/from String (via the From impls below), so every existing caller that used Result<_, String> keeps working: ? widens a String error into a spanless SpecError, and a SpecError narrows back to its message for anything that still wants a String.
expr
Arb’s computational substrate: arithmetic expressions are compiled to a fusevm::Chunk and executed on the fusevm VM (Cranelift JIT for hot chunks). This is what “arb runs on fusevm” means concretely — every computed value in a spec flows through fusevm bytecode, not a bespoke evaluator.
fzf
fzf option compatibility: everything arb --fzf needs to paint the picker the fzf binary would paint for the same environment.
hosted
hosted submodule: running arb inside another process. Running arb inside somebody else’s process.
jq
Native jq-syntax front-end for source { … } bodies. A body command whose first token is a jq literal (starts with ., or is a select(…)/map(…) stage) is handed here verbatim (verb + args, space-joined) and translated to a Vec<QueryOp> over arb’s existing ops. This is a PRACTICAL subset — path, iterate, index, pipe, select, map, and the builtins arb already implements — not Turing-complete jq. Anything outside the subset is a clean error, never a silent mis-translation.
jqlang
jqlang — a complete jq language engine.
jqval
jq VALUE expressions — the bodies of select(…) / map(…) and a bare arithmetic stage such as .a + .b.
jsondocs
in.json’s reading of the line stream: one item per JSON DOCUMENT.
jvparse
jvparse — jq’s JSON text parser, ported from jq 1.8’s src/jv_parse.c.
lexer
Tcl-flavored lexer.
lsp
Language Server (arb --lsp): a std-only, no-async LSP over stdio JSON-RPC for .arb specs. It parses + builds each open document and republishes the parser/interpreter error as a diagnostic, plus documentSymbol, hover, completion, signatureHelp, definition, references, documentHighlight, rename, foldingRange, formatting, and semanticTokens/full. The transport shape is the standard Content-Length framing; the language logic (diagnose/handle + the pure helpers) is unit-testable.
parser
Token stream -> command tree. A command is the run of args between two separators; the first arg is the verb. Block tokens are parsed recursively. Each command records the char offset of its verb (for LSP diagnostics).
pattern
A port of fzf’s query language — src/pattern.go from fzf 0.74.3.
pkg
Package registry client (arb install|search|update|publish|uninstall) — a std-only, no-async, no-TLS client over a git index + GitHub repos model (SPEC §18, like the stryke-* family). All network I/O goes through the git subprocess (the honest std-only transport — std has no TLS client).
pty
spawn -pty CMD support: run a spawn source on a pseudo-terminal so it acts as if interactive, and hand back a writer to its stdin for the Expect send action. Ported from the sibling zwire-host PTY session; cross-platform via portable-pty.
query
Query pipeline. A source { … } body compiles to a sequence of ops applied to the live stream on each evaluation.
repl
Interactive REPL for arb — utop-style line editor backed by reedline, ported from the strykelang REPL onto arb’s spec/query evaluator.
rust_ffi
arb wiring for inline Rust FFI (rust { ... } blocks).
serve
Web target: serve the same Spec as a live browser dashboard. A std-only HTTP server (no async runtime, no framework) binds a local port, serves one page at / built from the vendored zgui-core toolkit, and answers GET /data (and a /ws push) with the current widget values as JSON — so the same spec that drives the ratatui TUI drives a browser, live.
sniff
Zero-config input sniffing (SPEC §1/§19): cmd | arb with no spec peeks the first stream lines and picks the stdlib preset whose source pipeline matches the data shape, instead of the generic tail. Pure and unit-testable; every returned name is guarded against crate::spec::STDLIB_NAMES so a stdlib rename can’t route to a missing module.
spec
Interpreter: command tree -> a Spec. Recognizes the widget verbs, source .x { … } whose body compiles to a query pipeline (see query), and the .x <- in bind shorthand. Unknown widget verbs are ignored so specs stay forward-compatible.
stream
Shared live-stream state. In M1 every stdin-bound widget renders from one shared buffer (per-widget transforms/queries arrive with the query engine).
testrun
In-language test runner for arb --test. A spec’s test "NAME" { given …; run { … }; want … } blocks are evaluated headlessly — each run pipeline is applied to its given lines via the same crate::query::eval the widgets use, and the flattened output is compared to want. Output is TAP-flavored so it drops into any TAP consumer; run returns the pass/fail tally so the CLI can exit 0 (all passed) or 1 (any failed).
theme
Color themes — the 31 storageshower palettes shared by the sibling iftoprs and htoprs HUD apps, ported verbatim, plus a user custom palette.
tiers
Which fusevm execution tier a program’s bytecode actually reaches.
tui
ratatui render loop. Widgets are auto-tiled vertically (explicit pack/grid geometry arrives later). Each widget’s source pipeline is evaluated against the shared stream every frame; text/tail/list render the resulting lines and gauge renders a scalar against -max. Widget kinds without a renderer yet show an honest placeholder rather than faking output.
web
Static HTML export: render a Spec into a single self-contained dashboard page. No external resources, no CDNs — one inline <style> block and the widget panels laid out on a CSS grid. Used to snapshot a pipeline TUI as a shareable HTML file.
xpath
Native XPath front-end for source { … } / out { … } bodies. A body command whose first token starts with /, //, or @ is an XPath literal.
xpath_eval
The XPath 1.0 data model and evaluator.
xpath_syntax
XPath 1.0 lexer, AST and parser.
yaml
YAML -> the jq value model, composed from the parser’s EVENT stream, with every node’s metadata kept beside its value.
ynode
The YAML node model — the metadata a YAML node carries that a JSON value has no place for, plus the writer that puts it back on the page.
yqfmt
The encoders, decoders and clock yq exposes as operators.