Documentation
Build with Rat
Rat is a small dialect for writing web apps where a single .rat file declares its state, its markup, and its behaviour. Every page below pairs a description, the canonical snippet, and a live preview of what the snippet renders.
New here? Start with Setup and read straight through — each page assumes the previous one.
Basics
Install the binary, write your first page, and learn the dialect from the ground up. Every page assumes the previous one — read it linearly.
- SetupInstall the binary, scaffold a project, run the dev server.
- Hello worldThe smallest possible page and the file layout that backs it.
- Interpolation[expr] reads, expression syntax, and attribute interpolation.
- HTML attributesBracket-attr syntax, the snake_case to kebab-case rule, boolean flags, and interpolated values.
- ReactivityWrites with <<, derived fields with >>, event handlers in the page.
- Pups (components)Turn any .rat file in pups/ into a reusable tag with props and a children slot.
- ServicesSingletons with state and methods, callable as auth.login(...) from anywhere.
- State tiersServer, page, session, local — what lives where and how long it survives.
- FunctionsTop-level > name[params] declarations, one-liners, and returning via <<.
- Guards and loops(cond) action first-match chains, plus [item] in coll iteration.
Pages
How filesystem layout under pages/ becomes routes, and how main.rat wraps every page in a shared shell.
Styling
Inline > [selector] blocks for component-local CSS and files under styles/ for globals — both share the same [bracket] variable rewrite.
Builtins
Top-level callables — logging, inspection, strings, math, conversion, collections, encoding, HTTP — that work identically on server tier and inside browser handlers.
- Logginglog / debug / error route to console (browser) or stdout (server) with identical call shape.
- Inspectionlen, type, keys, values, has — ask any value about its size, kind, and contents.
- StringsCase folding, trim, split/join, replace, prefix/suffix checks, padding, and positional format.
- Mathfloor, ceil, round, round_to, abs, min/max, clamp, lerp — the numeric basics on top of operators.
- Conversionstr / num / bool to coerce values at boundaries — form input, query params, foreign payloads.
- Collectionsrange, sort, filter, map, reduce, group_by, unique, chunk, zip — array helpers with lambda support.
- Encodingbase64, URL, hex — three encode/decode pairs for safely moving binary and text across boundaries.
- HTTPhttp.get / post / put / delete / request — uniform response object, auto-JSON, shared pool.
Namespaces
Dotted stdlib surfaces — json, date, regex — with the same location-transparent dispatch as builtins.
Data
Declare models under data/, register databases, and call queries through the unified namespace dispatch.
API
JSON endpoints from .rat files under api/ — plain function calls over HTTP with explicit opt-in for what crosses the network.
Forms and uploads
Two-way input bindings, handler-driven submission, and the multipart upload surface.
Realtime
Server-side broadcast over SSE — pages subscribe with one tag and get live patches.
Dev workflow
The CLI, the settings file, and the hot-reload loop that makes editing feel instant.
- CLIrat new, start, build, install, i, db — what each subcommand does.
- Script mode (rat run)Run a .rat file with a top-level > main[args] — same engine, no HTTP.
- Settingssettings.rat fields and the dev / prod build-mode toggles.
- Parser errorsDid-you-mean hints for the documented dialect gotchas, surfaced inline at parse time.
- Hot reloadFile watcher → SSE bump → browser refresh, no full reload.
Advanced
Cross-runtime dispatch (Python, JS) and middleware services with route patterns and lifecycle hooks.
- Tail (Python)Call Python modules from any page — same dispatch shape as services and DBs.
- Inverse Tail (JS)Call JS libraries (Chart.js, Monaco, Three.js) from page-tier Rat.
- MiddlewareServices with route patterns and before / after / on_start / on_shutdown hooks.
- Location transparencyPure calls (math, json, date, regex) compile for both tiers, so the same call runs wherever it sits.