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.gofrom 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
.arbspecs (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
clisubmodule: 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 stdioContent-Lengthframing as the LSP. The debugger model reinterprets arb’s stream world onto DAP concepts — the same per-line predicate scan the TUI already runs againstexpect /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/fromString(via theFromimpls below), so every existing caller that usedResult<_, String>keeps working:?widens aStringerror into a spanlessSpecError, and aSpecErrornarrows back to its message for anything that still wants aString.- expr
- Arb’s computational substrate: arithmetic expressions are compiled to a
fusevm::Chunkand 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 --fzfneeds to paint the picker thefzfbinary would paint for the same environment. - hosted
hostedsubmodule: 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 aselect(…)/map(…)stage) is handed here verbatim (verb + args, space-joined) and translated to aVec<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’ssrc/jv_parse.c.- lexer
- Tcl-flavored lexer.
- lsp
- Language Server (
arb --lsp): a std-only, no-async LSP over stdio JSON-RPC for.arbspecs. It parses + builds each open document and republishes the parser/interpreter error as a diagnostic, plusdocumentSymbol,hover,completion,signatureHelp,definition,references,documentHighlight,rename,foldingRange,formatting, andsemanticTokens/full. The transport shape is the standardContent-Lengthframing; 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.gofrom 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 thestryke-*family). All network I/O goes through thegitsubprocess (the honest std-only transport —stdhas no TLS client). - pty
spawn -pty CMDsupport: run a spawn source on a pseudo-terminal so it acts as if interactive, and hand back a writer to its stdin for the Expectsendaction. Ported from the siblingzwire-hostPTY session; cross-platform viaportable-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 byreedline, 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
Specas 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 vendoredzgui-coretoolkit, and answersGET /data(and a/wspush) 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 | arbwith no spec peeks the first stream lines and picks the stdlib preset whosesourcepipeline matches the data shape, instead of the generic tail. Pure and unit-testable; every returned name is guarded againstcrate::spec::STDLIB_NAMESso 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 (seequery), and the.x <- inbind 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’stest "NAME" { given …; run { … }; want … }blocks are evaluated headlessly — eachrunpipeline is applied to itsgivenlines via the samecrate::query::evalthe widgets use, and the flattened output is compared towant. Output is TAP-flavored so it drops into any TAP consumer;runreturns 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
iftoprsandhtoprsHUD apps, ported verbatim, plus a usercustompalette. - tiers
- Which fusevm execution tier a program’s bytecode actually reaches.
- tui
- ratatui render loop. Widgets are auto-tiled vertically (explicit
pack/gridgeometry arrives later). Each widget’ssourcepipeline is evaluated against the shared stream every frame;text/tail/listrender the resulting lines andgaugerenders a scalar against-max. Widget kinds without a renderer yet show an honest placeholder rather than faking output. - web
- Static HTML export: render a
Specinto 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
yqexposes as operators.