Runtime guide
Advanced capabilities supplied by the official Polonio Reference Distribution.
What “runtime” means
The language defines expressions, control flow, functions, and values. A runtime gives that language a setting in which to work: rendering a template, handling an HTTP request, or saving data. You can learn and use the language without every runtime feature.
| Runtime | Use it when you need | Examples |
|---|---|---|
| Template Runtime | Rendered text or HTML | Interpolation, includes, print |
| Web Runtime | An HTTP request and response | Forms, cookies, sessions, uploads, redirects |
| Data Runtime | Persistent local data | Sandboxed files and SQLite |
The Reference Distribution includes all three. The conformance profiles are for implementers who need exact capability guarantees.
Template Runtime
The Template Runtime turns a template into ordered output. It emits literal text, evaluates <% ... %> blocks, replaces $variable in text, and resolves include paths relative to the current file.
Use it whenever you render a page or text file. attempt / recover may handle only capability and resource failures during rendering; emitted output remains emitted. Recovery cannot alter a response finalized by send_file. Start with the Language guide; the Hello example is the smallest complete template.
Web Runtime
The Web Runtime is available when Polonio runs with an HTTP request and response. It supplies _GET, _POST, _FILES, _COOKIE, and _SERVER, plus helpers for headers, redirects, request bodies, sessions, CSRF, uploads, and file responses.
How requests arrive
The official executable can run as CGI or through polonio serve. CGI is a conventional way for a web server to invoke an application: environment variables describe the request and Polonio writes the response to standard output. The local server is usually the easier way to learn:
./build/polonio serve --root ./examples --port 8080It serves static files and renders .pol templates. Extensionless paths resolve to templates, directories use index.pol then index.html, and a root-local 404.pol can supply a missing-page response.
Working with a request
Query strings populate _GET. URL-encoded and multipart form fields populate _POST; uploaded files appear in _FILES. Use request_json() for a JSON body. Set status, headers, content type, or redirects before output begins.
Sessions and security helpers
Sessions, CSRF tokens, password helpers, and secure tokens are Web Runtime features. Sessions require POLONIO_SESSION_SECRET; the Reference Distribution stores session data in a signed cookie. See the focused forms and session examples before using them.
Data Runtime
The Data Runtime provides sandboxed file storage and SQLite. Set POLONIO_STORAGE_PATH to choose the storage root. File, directory, database, upload, download, and mail-outbox paths are relative to that root, so templates cannot reach arbitrary host files.
Use file_* and dir_* helpers for local files and db_* helpers for SQLite. upload_save, send_file, and send_mail also use this storage model in the Reference Distribution. send_mail writes an .eml file; it does not deliver email.
Find signatures in Built-in functions and see the storage and SQLite examples for complete, small routes.
Development-server limits
polonio serve is a local development tool. It is loopback-only, single-threaded, and sequential. It supports HTTP/1.1 GET and POST, URL-encoded forms, multipart uploads, and JSON request access; it does not provide TLS, keep-alive, streaming, chunked request bodies, concurrent handling, or SMTP delivery. Do not expose it as a public production server.
Return to Examples to apply these capabilities, or consult the language specification for the formal language boundary.