>_EXECUTIVE SUMMARY
vim-arb is the Vim / Neovim editor support for arb — a Tcl/Tk-flavored declarative language for visualizing and modifying Unix pipelines, on the fusevm bytecode VM + Cranelift JIT. It ships as a standard Vim runtime tree (ftdetect/, syntax/, indent/, ftplugin/, compiler/, plugin/, doc/), so pathogen / vim-plug / native packages add it to runtimepath with no special handling.
Design principle: the syntax file is a standalone arb grammar covering the widget, query-verb, input-source, and directive surface — not a wrapper around another language's syntax. The token surface is built from arb's own LSP corpus so it tracks the binary; scripts/gen_syntax.sh stamps the file with the arb version it was verified against.
~RUNTIME LAYOUT
Standard Vim runtime directories. Each file is loaded automatically when the plugin is on runtimepath; no entry point or sourcing call is required.
| File | Responsibility |
|---|---|
ftdetect/arb.vim | Sets filetype=arb for *.arb files and for any file whose first line is an arb shebang (e.g. #!/usr/bin/env arb). |
syntax/arb.vim | Standalone arb grammar — comments / shebang, numbers / durations / sizes, widget paths, single/double strings, /regex/ literals, widgets, query verbs, input sources, directives, control flow, declarations, flags, and operators, linked to standard highlight groups. |
indent/arb.vim | Standalone indentexpr (GetArbIndent()) — indents after a line opening a block / paren / bracket, dedents lines starting with a closing delimiter. |
ftplugin/arb.vim | Buffer-local options: commentstring=# %s, comments=:#, comment-continuation formatoptions, :compiler arb, the :ArbRun command and its <LocalLeader>r mapping, with a matching b:undo_ftplugin. |
compiler/arb.vim | Defines the arb compiler: makeprg=arb --check % with an errorformat for arb diagnostics, so :make routes them to the quickfix list. |
plugin/arb.vim | Global wiring: ALE linter definition, vim-lsp server registration, coc + nvim-dap snippets (commented), and the g:vim_arb_no_ale / g:vim_arb_no_lsp opt-outs, behind a load guard. |
doc/arb.txt | Vim help (:help vim-arb) with tagged sections for install, detection, syntax, running, linting, LSP, DAP, and options. |
$SYNTAX COVERAGE
Token categories taken from arb's language definition — the widget / query-verb / input-source / directive corpus the arb binary ships. Dotted widget paths (.codes, .errors) and the |> / <- / => operators are first-class arb constructs and are highlighted.
| Group | Tokens (sample) | Highlight link |
|---|---|---|
| Widgets | text tail table list gauge spark bars histo chart select input tabs block frame grid | Function |
| Input sources | in in.json in.csv in.tsv in.xml in.html in.yaml in.toml in.logfmt | Special |
| Directives | source bind configure grid import out search timeout expect | PreProc |
| Control flow | if elif else while for match case when break continue return | Statement |
| Declarations | fn var let import save as | Keyword |
| Query verbs | field fields find attr where pick map tally count sum sort_by group_by uniq percentile sma ewma | Function |
| Actions | alert beep exec flash quit | Statement |
| Literals & vars | widget paths (.codes/.errors), strings, /regex/, durations/sizes, flags (-max/-cols) | Identifier / String / Number |
#TOOLING INTEGRATION
All integrations degrade gracefully: each is guarded so the plugin loads cleanly whether or not ALE / vim-lsp / coc / nvim-dap is installed. --check parses + statically checks the spec (no run), --lsp starts the language server, and --dap the debug adapter. Each of --lsp / --dap is the sole flag (no appended --stdio), mirroring stryke --lsp; the vim-lsp / nvim-dap clients add no transport args.
| Integration | Mechanism |
|---|---|
| :make (compiler) | The arb compiler sets makeprg=arb --check % with an errorformat matching arb diagnostics, routing them to the quickfix list. |
| :ArbRun | Buffer-local command running arb % on the current spec, mapped to <LocalLeader>r (skipped if g:vim_arb_no_maps is set). |
| ALE | Registers a linter via ale#linter#Define running arb --check %t; the handler parses <file>:<line>: <message> into error items. Skipped if ALE is absent or g:vim_arb_no_ale is set. |
| vim-lsp | Registers a server (lsp#register_server) running arb --lsp, allowlisted for the arb filetype. Skipped if vim-lsp is absent or g:vim_arb_no_lsp is set. |
| coc.nvim | A ready-to-paste languageserver block for coc-settings.json using arb --lsp, documented in the plugin source and README. |
| nvim-dap | A ready-to-paste adapter / configuration block using arb --dap, documented in the plugin source and README. |
@COMPATIBILITY
| Target | Status |
|---|---|
| Vim 8+ | Filetype, syntax, indent, ftplugin, compiler, doc |
| Neovim | Same runtime files (no Lua required for the core) |
| pathogen / vim-plug / native packages | Standard runtime layout — no plugin-manager-specific handling |
| ALE | arb --check linter |
| vim-lsp | arb --lsp language server wired |
| coc.nvim | languageserver config provided |
| nvim-dap | arb --dap adapter config provided |