Parses Markdown source into a structured DValue document tree.

The parser targets a practical GitHub-flavored subset by default:

• ATX headings with #

• setext headings

• paragraphs

• blockquotes

• ordered and unordered lists

• task list items

• fenced code blocks

• tables

• horizontal rules

• emphasis, strong, and strikethrough

• links, images, autolinks, and code spans

• ::: directive blocks for component-based extensions

The returned AST uses type plus node-specific fields such as level, text, lang, href, src, name, argument, attrs, and children.

Top-level documents use:

Common block nodes:

• heading

• paragraph

• blockquote

• list

• list_item

• code_block

• table

• directive

• hr

Common inline nodes:

• text

• code

• strong

• em

• strike

• link

• image

• raw_html

Example:

Options:

• options["gfm"] enables GitHub-style extras such as tables, task lists, strikethrough, and bare-URL autolinks. Defaults to true.

• options["allow_html"] allows raw HTML passthrough nodes to be captured and rendered. Defaults to false.

• options["components"] provides the component hook map later used by markdown_to_html(). The parser preserves directive data needed by those hooks.

Renders Markdown source into HTML and returns the generated markup as a String.

markdown_to_html() does not write to the output stream directly. This keeps it aligned with the UCE naming convention where render_* names are reserved for direct-output helpers.

Because the return value is HTML markup, embed it with <?: markdown_to_html(...) ?>, print(markdown_to_html(...)), or pass it through a component.

By default the function aims at a practical GitHub-flavored Markdown target, including tables, task lists, fenced code blocks, autolinks, and strikethrough.

Example:

Supported syntax:

• headings with # or setext underlines

• paragraphs

• ordered and unordered lists

• task lists

• blockquotes

• fenced code blocks

• horizontal rules

• tables

• inline emphasis, strong, strikethrough, and code spans

• links, images, and bare http:// / https:// URLs

• :::name ... ::: directive blocks

Options:

• options["gfm"] defaults to true and turns on GitHub-style extras such as tables, task lists, autolinks, and strikethrough.

• options["allow_html"] defaults to false. When true, raw HTML blocks and inline tags may pass through as raw_html nodes instead of being escaped as plain text.

• options["components"] declares renderer extension points using normal UCE components.

Directive hook example:

Generic node hook examples:

If both an exact directive hook and a generic node.directive hook exist, the exact directive hook wins.

When a markdown hook component is called, its props arrive in context.props.

Useful fields include:

• context.props["hook"] for the matched hook key such as :::warning or node.code_block

• context.props["target"] for the resolved component target name

• context.props["default_html"] for the renderer output without the hook

• context.props["children_html"] for already-rendered child HTML

• context.props["node"] for the full AST node

• context.props["type"] for the node type

• context.props["name"] for the directive name when applicable

• context.props["argument"] for directive remainder after the name

• context.props["text"] for source text used by nodes such as code_block

• context.props["lang"] for fenced code language

• context.props["href"], context.props["src"], and context.props["title"]

• context.props["options"] for the full markdown options tree

Directive blocks use this form:

The parser stores:

That makes directive components a good fit for alerts, callouts, cards, embeds, and richer page-level Markdown extensions.

Parses a simple XML document into a structured DValue.

xml_decode() parses a compact XML subset. It does not validate schemas, DTDs, namespaces, or document types. It parses the first root element and returns the same structural element shape accepted by xml_encode().

Try the live example in the XML demo.

Return shape:

Example:

CDATA and numeric entities are folded into text:

Supported parser features:

• elements

• attributes with quoted values

• self-closing tags

• text nodes

• XML entities such as &, <, >, ", and '

• decimal and hexadecimal numeric entities

• comments, processing instructions, and CDATA sections

Whitespace-only text between child elements is ignored. Mixed non-empty text is concatenated into node["text"].

Malformed XML raises a request-visible runtime error.

Serializes a DValue into a simple XML string.

xml_encode() does not validate against a schema, DTD, or namespace rules. It is a structural converter for application data, similar in spirit to json_encode().

Try the live example in the XML demo.

The native element shape is:

Example:

The result is:

For simple map/list/scalar trees, xml_encode() creates ordinary child elements:

Result:

Notes:

• Element and attribute names are normalized to XML-name-safe strings when needed.

• Text and attribute values are escaped.

• List values use repeated <item> children.

• Empty elements serialize as self-closing tags.

• Map child order follows DValue map iteration order.

Parses a practical YAML subset into a DValue.

yaml_decode() is designed for concise UCE config files. It supports a practical YAML subset and does not implement anchors, aliases, tags, directives, or complex inline collection syntax.

Try the live example in the YAML demo.

Example:

Supported syntax:

• indentation-based maps

• indentation-based lists

• key: value map entries

• list entries with - value

• quoted strings with single or double quotes

• booleans true and false

• empty/null-ish values as empty strings

• comments beginning with # outside quoted strings

• literal block strings with |

• folded block strings with >

• optional --- and ... document markers

Numeric-looking values are stored as strings, matching json_decode()'s current behavior. Use to_s64(), to_u64(), or to_f64() when reading numeric config values.

Malformed input raises a request-visible yaml_decode(): ... runtime error.

Serializes a DValue into a compact YAML string for configuration files.

yaml_encode() focuses on the ordinary data shapes UCE apps use for config: nested maps, lists, strings, booleans, and numeric f64 values. It does not emit YAML tags, anchors, aliases, or custom schema features.

Try the live example in the YAML demo.

Example:

Typical result:

Notes:

• Map keys are emitted in DValue map iteration order.

• Strings are left plain when safe and quoted when needed.

• Multiline strings are emitted as literal block scalars with |.

• Empty strings are emitted as "" so they are not confused with YAML null.

• Decoded numeric-looking config values are strings unless the original DValue value was explicitly numeric.

Executes a raw command on an open Memcache connection and returns the server response as a string.

This is the low-level escape hatch for Memcache operations that are not covered by the dedicated helpers.

Connects to a Memcache server instance.

If the connection fails, the function returns -1.

Deletes the entry identified by key.

The return value is true when the operation succeeds.

Retrieves a value from an existing Memcache connection.

If the key is missing, default_value is returned instead.

Retrieves multiple entries in one call.

The result is returned as a StringMap keyed by the requested Memcache keys.

Stores value under key on the Memcache server.

expires_in controls the expiration timeout and defaults to one hour.

Normalizes whitespace in a memcache key to underscores before it is placed into a text protocol command.

Applies memcache_escape_key() to each key in a list.

Establishes a connection to a MySQL server and returns a pointer to the connection struct.

This connection handle is then used with helpers such as mysql_query(), mysql_error(), and mysql_disconnect().

Closes an existing connection to a MySQL server.

Call this when you are done using a MySQL* connection handle.

Returns the last error message associated with the given MySQL connection.

If there is no current error, the result is an empty string.

Escapes a string so it can be used safely as a value inside an SQL expression.

If quote_char is provided, the escaped result is wrapped with that quote character. Pass NULL when you only want escaping without wrapping.

Returns the last automatically assigned row ID used by the current MySQL connection.

This is typically used after an INSERT into a table with an AUTO_INCREMENT primary key.

Executes a MySQL query and returns the resulting data, if any.

params provides the query parameter values used by the statement. Use named :name placeholders only; positional ? placeholders are rejected.

The result is returned as a DValue, which makes it easy to iterate through rows and read fields with the usual DValue accessors.

Works like generate_float(), but uses context.random_index for the index value and context.random_seed for the seed.

After each call, context.random_index is increased by one. At the start of every request, context.random_seed is automatically populated with a new seed value.

Works like generate_int(), but uses context.random_index for the index value and context.random_seed for the seed.

After each call, context.random_index is increased by one. At the start of every request, context.random_seed is automatically populated with a new seed value.

Generates a deterministic noise value in the range from 0 to 1 for the given index and seed.

Generates a deterministic 32-bit noise value for the given index and seed.

Generates a deterministic 64-bit-indexed noise value for the given index and seed.

Generates a deterministic noise value between from and to for the given index and seed.

Generates a deterministic noise value between from and to for the given index and seed.

Returns the SHA-1 hash of s.

When as_binary is false, the hash is returned as hexadecimal text. When it is true, the raw binary hash bytes are returned.

Returns the SHA-256 digest of data as raw bytes. Prefer sha256_hex() when you need printable text; use the raw form when feeding the digest into other binary operations.

Returns the SHA-256 digest of data as hex text. Use it for checksums, cache keys, and content fingerprints where you want a printable digest. For the raw 32-byte digest use sha256().

Computes an HMAC-SHA256 and returns it as raw bytes. Prefer hmac_sha256_hex() for printable signatures; use the raw form for binary protocols.

Computes an HMAC-SHA256 message authentication code and returns it as hex. Use it to sign tokens, cookies, and webhook payloads, then verify with crypto_equal() to avoid timing leaks.

Returns n cryptographically secure random bytes, suitable for session IDs, tokens, and salts. The bytes are binary; wrap them with base64_encode() or sha256_hex() when you need printable text.

Compares two byte strings in constant time, so the comparison takes the same time whether they differ in the first byte or the last. Always use it to check secrets such as HMACs, tokens, and password hashes — == can leak how much of a secret matched via timing.

Defines the main HTTP render handler for the current .uce page.

When a page is requested over HTTP, the runtime loads the target file and calls its RENDER(Request& context) function.

Entry Point Behavior

The default page entrypoint is always the plain RENDER(Request& context) handler.

Reusable component handlers live on COMPONENT(Request& context) and COMPONENT:NAME(Request& context). The component helpers call those handlers, not RENDER().

The request environment is passed explicitly through context, including params, cookies, post data, session state, headers, uploaded files, and the current context.props tree.

If the file defines ONCE(Request& context), the runtime calls that hook once per request before the first RENDER() or COMPONENT... entrypoint from that unit runs.

If the file defines INIT(Request& context), the runtime calls that hook once when the worker loads the compiled unit into memory.

For a normal direct page request, context.props starts empty.

If the page is invoked from another UCE file via unit_render(file_name, context), the callee receives that same context.

Pages that serve WebSocket traffic may expose both RENDER(Request& context) and WS(Request& context). Files may also define COMPONENT() handlers when one unit needs both page and component behavior.

In that case:

• RENDER(Request& context) serves the direct HTTP response

• WS(Request& context) handles later WebSocket messages

• COMPONENT() remains available only through the component helpers

Defines a local command-line entrypoint for a UCE unit.

CLI(Request& context) is invoked only through the local UCE CLI Unix socket, not through ordinary public HTTP requests. This lets web apps keep test runners, migrations, maintenance tasks, and admin tooling beside the rest of their UCE units while still separating those commands from browser-facing RENDER() routes.

The default CLI socket path is /run/uce/cli.sock and is configured with CLI_SOCKET_PATH.

Example convenience script usage:

Equivalent curl probe:

For structured commands, prefer JSON POST bodies. The scripts/uce-cli helper sends key=value parameters as JSON POST by default, while still allowing --get for simple query-string probes.

Inside the handler, the usual Request& context fields are available:

• context.get for command query parameters

• context.post and context.in for POST bodies

• context.params["UCE_CLI"] == "1" for CLI socket dispatch

• context.params["SCRIPT_FILENAME"] for the invoked unit file

CLI responses default to text/plain; charset=utf-8, but the handler may set headers and status explicitly.

Use cli_input(context) to merge query parameters, form parameters, and JSON POST fields into one DValue.

ONCE(Request& context) runs before CLI() in the same way it runs before render and component entrypoints. INIT(Request& context) runs when the unit is loaded into a worker.

Returns a structured parameter tree for a CLI(Request& context) invocation.

cli_input() merges simple command inputs into one DValue:

1. query parameters from context.get

2. form parameters from context.post

3. JSON object fields from an application/json or *+json request body

Later sources override earlier ones, so a JSON body can override a query or form key with the same name.

If the JSON body is a scalar or array instead of an object, the decoded value is stored under input["_"].

Convenience script usage:

Reads one value from the merged cli_input(context) parameter tree.

If the key is missing, or the resolved value is empty, default_value is returned.

For commands that need multiple values or typed reads, prefer calling cli_input(context) once and reading the returned DValue directly.

Calls an exported function inside another UCE file.

Use unit_call() when you need structured data exchange between units rather than rendered HTML output.

The callee must expose an EXPORT function whose name matches function_name. Arguments are passed through call_param, and the return value is a DValue* owned by the callee.

unit_call() also understands the request-bound UCE entrypoint names:

• RENDER

• RENDER:NAME

• COMPONENT

• COMPONENT:NAME

• ONCE

• INIT

When function_name matches one of those macro-style entrypoints, unit_call() does not look for a plain EXPORT DValue* ... function. Instead, it translates the name to the generated C++ symbol, uses the current Request context, and passes call_param into context.props, matching the normal component invocation model.

For RENDER... and COMPONENT..., the unit's ONCE(Request& context) hook is still honored automatically before the selected handler runs.

Example:

Calling a named component handler through unit_call():

Calling a page render handler through unit_call():

Renders another .uce file as a component and returns the captured output as a String.

component() resolves the target file relative to the current page and also tries the components/ prefix automatically, mirroring the shorthand used by the starter example project.

Component props are passed in context.props.

Because <?= ... ?> HTML-escapes its value, embed component markup with <?: component(...) ?>, print(component(...)), or use component_render(...) for direct output.

Named Components

When name contains a colon, such as components/card:BODY, the part after the colon selects a named component handler exported from the component file through COMPONENT:BODY(Request& context).

The default handler is COMPONENT(Request& context).

When name starts with a colon, such as :BODY, the target resolves against the current .uce file so component files can call their own named handlers without repeating the file name.

When a component unit defines ONCE(Request& context), the runtime calls that hook once per request, per resolved component file, before the first COMPONENT() or COMPONENT:NAME() handler from that file runs.

Resolution Order

• exact file name

• exact file name with .uce

• the same two forms under components/

Common Patterns

Default component handler:

Named component handler:

Self-targeted named handler from inside the same file:

Preparing props in C++ before rendering:

Embedding returned component markup inside a literal block:

Because <?= ... ?> escapes HTML, use <?: ... ?> when inserting the returned markup from component().

Lifecycle Notes

• INIT(Request& context) runs once when the worker loads that unit into memory.

• ONCE(Request& context) runs once per request before the first component or render entrypoint from that file.

• component() then calls either COMPONENT(Request& context) or the selected COMPONENT:NAME(Request& context) handler.

Checks whether a component file can be resolved from the current page context.

Resolution uses the same host resolver as component_resolve(): candidate bases include absolute targets, the entry unit directory, the current unit directory, and the site root; each base tries exact, .uce, components/name, and components/name.uce forms.

If name contains a colon, only the file portion is used for existence checks.

This is useful when a page wants to render an optional component if it is present without hard-failing when it is missing.

Resolves a component name to the concrete .uce file path that will be loaded.

Resolution searches host-side candidate bases in order: absolute target when supplied, entry unit directory, current unit directory, and site root. Within each base it tries the exact file name, the same name with .uce appended, and the same two forms under the components/ prefix.

If name contains a colon, only the file portion is used for resolution.

This is primarily a debugging helper so you can see which concrete file a shorthand component name maps to.

Includes another UCE file.

Use #load when you want the current file to pull in declarations or reusable content from another UCE source file.

Discards the current output buffer and its contents, switching back to the previous buffer on the stack. Use it when you captured output only to throw it away (e.g. rendering for a side effect).

Returns the current output buffer's contents WITHOUT discarding the buffer, so more output can still be appended. Use ob_get_close() when you also want to pop the buffer.

Returns the current output buffer's contents and discards the buffer, switching back to the previous one on the stack. This is the usual way to capture rendered output for post-processing.

Starts a new output buffer. Subsequent print() output is captured into it instead of the response until you collect it with ob_get_close() (or discard it with ob_close()). Buffers nest: each ob_start() pushes another buffer onto the stack. Use it to render a fragment, post-process it, then emit the result.

Appends data to the current request output stream.

Use print() when you want to emit response content directly from UCE code.

Renders another .uce file as a component and writes the result directly to the current output buffer.

This is the direct-output counterpart to component().

Component props are passed through context.props, and name:COMPONENTFUNC may be used to select a named handler exported by COMPONENT:COMPONENTFUNC(Request& context).

When name starts with :, the runtime resolves that named handler against the current .uce file.

If the target file defines ONCE(Request& context), that hook runs once per request before the file's first component or render entrypoint.

Use component_render() when you want to write component output directly from C++ code instead of capturing it as a String.

Example

native-only internal API. unit_load() returns a process-local SharedUnit*, which is not a valid value across the wasm membrane and is not exposed to wasm units.

Use unit-facing APIs such as unit_info(), unit_compile(), unit_call(), unit_render(), or component helpers instead.

Calls another UCE file and executes its RENDER(Request& context) function.

If context is omitted, the current active request context is used.

Examples:

Tests whether subject matches pattern from start to end.

This is a full-string match, not a substring search. Use regex_search() when you want to find the first occurrence anywhere in a string.

Examples:

Supported flags:

• i enables case-insensitive matching.

• m enables multiline ^ and $.

• s lets . match newlines.

• x enables extended / whitespace-insensitive pattern syntax.

• u explicitly enables UTF-8 and Unicode character properties.

• a disables UTF-8 / Unicode property mode for ASCII-oriented matching.

UCE uses PCRE2 in UTF-8 + Unicode-property mode by default, so patterns such as \\p{L}+ work naturally on Unicode text.

Invalid patterns or invalid flags raise a request-visible runtime error with the PCRE2 diagnostic message.

Searches subject for the first occurrence of pattern and returns structured match data.

Example:

Return shape:

• matched is a boolean.

• pattern stores the original pattern.

• flags stores the supplied flags, or default.

• match is the full matched text when a match exists.

• start and end are byte offsets into the original string.

• captures is a list of capture objects, with capture 0 representing the full match.

• named maps named capture groups to their captured text.

• named_offsets maps named capture groups to index, start, and end metadata.

Capture entries contain:

If no match is found, matched is false and match-specific fields are omitted.

Finds every non-overlapping match of pattern in subject.

Example:

Return shape:

• matched is true when at least one match exists.

• count is the number of matches.

• matches is a list of entries with the same shape returned by regex_search().

• pattern and flags mirror the call inputs.

Zero-length matches are handled safely; the scanner advances after each zero-length match to avoid infinite loops.

Replaces every match of pattern in subject and returns the transformed string.

Example:

Replacement strings use PCRE2 substitution syntax, including numbered capture references such as $1 and named references such as ${name}.

For simple literal search-and-replace, use replace(). Use regex_replace() when the match condition needs a pattern, captures, character classes, anchors, or flags.

Invalid patterns, invalid flags, or invalid substitution syntax raise a request-visible runtime error.

Splits subject wherever pattern matches.

Example:

This is the pattern-aware companion to split().

Behavior notes:

• Separators are removed from the returned list.

• Empty fields are preserved.

• If the pattern does not match, the result contains the original subject as a single item.

• Zero-length separators are handled safely to avoid infinite loops.

Formats a captured native backtrace frame array.

Most page code should use backtrace_capture() instead. Use this helper when you already have raw frame pointers from lower-level diagnostic code.

Captures and formats a native backtrace for the current call stack.

This helper is for diagnostics. It is used by runtime error reporting paths and can also be useful in local debugging pages.

Example:

Three optional keys in /etc/uce/settings.cfg route error conditions to developer-defined UCE pages. Each key names a .uce file, either absolute or relative to the server's working directory. When a key is unset, or the named file does not exist, or the error page itself fails, the runtime's built-in plain-text behavior stands.

All three pages receive the error context in context.call["error"]:

• type — compiling, compiler_error, or runtime_error

• source — the requested .uce file

• compiler_error adds: compiler_output (raw clang output), generated_cpp, status, details

• runtime_error adds: title, details, request_uri, signal, signal_name, trace, generated_cpp

A sensible status code is set before the page renders (503 for compiling, 500 for errors); the page may override it with set_status() and set its own headers.

page_compiling

Without this key, a request that hits an uncompiled or changed page blocks until the synchronous build finishes. With it, the runtime responds immediately with your page, hands the build to the proactive compiler, and the page can poll until the build lands:

The compiling page is only used while PROACTIVE_COMPILE_ENABLED is on (the default) — otherwise nothing would finish the build asynchronously, and the runtime waits for the on-request wasm compile.

pagecompilererror

Triggered when the entry page fails to build (components that fail mid-page keep the inline behavior, since the page is already half-rendered). context.call["error"]["compiler_output"] carries the full raw compiler output — show it on development hosts, hide it in production.

pageruntimeerror

Triggered after the worker recovers from a fatal signal or an uncaught exception. The worker has just recovered from a fault, so keep this page simple: static markup and the error fields, no database connections or heavy components.

Recursion safety

While an error page renders, error-page handling is disabled: a compiling, broken, or crashing error page falls back to the built-in behavior instead of looping.

Ready-made examples

site/errors/compiling.uce, site/errors/compiler-error.uce, and site/errors/runtime-error.uce in this repository are working examples — point the config keys at them or copy them into your site.

Returns a readable name for a POSIX signal number.

Example:

This is mostly useful in diagnostics and error reporting code.

Returns runtime metadata for a UCE compilation unit.

The returned tree is supplied by the host runtime and may include normalized source/artifact paths, compile/runtime status, ABI/wasm availability, timing counters, mtimes, and exported API declarations. Treat absent fields as unavailable rather than as false.

If path is relative, it is resolved by the same host unit resolver used for unit calls/components.

Because unit metadata lives in worker process memory, request and timing counters reflect the current runtime process, not an aggregate across every worker process.

Returns the normalized paths of all known .uce units.

This includes the shared known-unit registry plus any units already loaded in the current runtime process.

Triggers a manual recompile of a UCE compilation unit through the host membrane.

If path is relative, it is resolved by the host unit resolver. The function returns whether compilation succeeded; it does not return or expose a native SharedUnit* to wasm units.

sig : one or more real C++ signatures, exactly as declared

params : name : description rows plus return value : description

content : usage-first prose in 2-5 tight sentences

example : runnable UCE code whose real output is captured by the renderer

see : an area reference (>area) followed by closest sibling page slugs

Doc pages use a small structured text format so the index, detail view, search, and tests can all reason about the same source. Put usage first: describe what the API does and when to reach for it before lower-level implementation notes. Every page should include at least one deterministic :example; the renderer materializes each example as a temporary UCE unit, compiles it, renders it, and shows both the source and captured output. Keep cross-membrane, lock, and PHP/JS equivalence notes short and trailing when they are useful.

Creates and returns a new session ID.

This helper is useful when you need to generate a session token directly rather than starting a full session flow with session_start().

Deletes the cookie specified by session_name and clears the data stored under the current session ID.

This also empties context.session_id and context.session.

Starts a session or reconnects to an existing one.

If the cookie named by session_name does not exist, UCE creates it and fills it with a new unique session ID. The function then loads the session data for that ID.

After session_start() completes, the following context fields are populated:

• context.session_id contains the current session ID.

• context.session_name contains the current session cookie name.

• context.session contains the current session data. The session data is automatically saved after the request completes.

Closes an existing socket connection.

Use this when you are done with a socket opened through socket_connect().

Opens a socket connection to the given host and port.

The returned socket handle is then used with socket_read(), socket_write(), and socket_close().

Reads data from a socket connection.

max_length limits how much data is read, and timeout controls how long the operation is allowed to wait.

Writes data to the given socket.

The function returns true when the write succeeds.

Opens an SQLite database file and returns a connection handle.

UCE opens SQLite with serialized/full-mutex connection mode, sets a busy timeout, enables foreign keys, and applies WAL-oriented defaults:

PRAGMA busy_timeout = 5000;
PRAGMA foreign_keys = ON;
PRAGMA journal_mode = WAL;
PRAGMA synchronous = NORMAL;

SQLite itself handles file locking and one-writer/many-reader concurrency. UCE does not add a separate app-level database lock.

Connections are registered for request cleanup, but explicit sqlite_disconnect() is still preferred when you are done with the handle.

Closes an SQLite connection and deletes the UCE connection wrapper.

UCE also cleans up SQLite connections that remain open at request end, but explicit disconnects keep resource lifetime local and clear.

Returns the latest SQLite connector status or error message.

Successful calls usually set the message to ok or connected. Failed prepare, bind, step, pragma, or open operations include connector context plus SQLite's own error text.

Executes one SQLite statement and returns result rows as a DValue array. Multi-statement SQL strings are rejected so migrations cannot silently run only their first statement.

Use named parameters with :name placeholders only. Positional ? placeholders and SQLite's other named marker forms (@name, $name) are rejected so UCE SQLite queries use the same placeholder style as the MySQL helper. UCE binds parameters with SQLite prepared statements; it does not substitute values into the SQL string.

Result rows are objects keyed by column name. SQLite integer, float, text, blob, and null values are converted to DValue values. Blob values are returned as byte strings.

For statements that do not return rows, inspect sqlite_affected_rows() or sqlite_insert_id() after the call.

Returns SQLite's last inserted rowid for the connection after an insert statement.

Returns the number of rows changed by the most recent insert, update, or delete statement on the connection.

Like safe_name(), but also restricts the result to ASCII, transliterating or dropping non-ASCII characters. Use it when the consumer (a legacy filesystem, header, or protocol) requires plain ASCII.

Decodes Base64 text back to bytes. Pairs with base64_encode() for round-tripping binary data through text channels.

Encodes bytes as Base64 text. UCE strings are binary-safe, so raw may contain NUL and other non-text bytes — handy for embedding random_bytes() or a sha256() digest in headers, cookies, or JSON.

Returns whether haystack contains needle.

An empty needle always returns true.

Returns a new list containing the members of items for which f returned true.

Returns the first non-empty string from the provided arguments.

Leading and trailing whitespace are ignored when checking emptiness, so a string containing only whitespace counts as empty.

Joins all strings in l into a single String.

The delimiter is inserted between items. If delim is omitted, the default separator is a newline character.

Advances i past JSON whitespace in s.

This helper is mainly useful when writing a parser that follows UCE's JSON parsing rules. Most page code should call json_decode() instead.

Example:

Serializes either a String or a DValue into JSON notation.

When passed a String, json_encode() returns a quoted and escaped JSON string literal.

When passed a DValue, scalar values are serialized directly and nested map values are emitted as JSON objects.

Returns a new list by calling f for each item in items.

Use filter() when you want to keep only matching items, and map() when you want to transform each item.

Returns the part of haystack before the first occurrence of delim.

As a side effect, the consumed portion is removed from haystack, including the delimiter itself.

If delim does not occur in haystack, the entire string is returned and haystack is set to an empty string.

Appends data to the current request output stream.

Use print() when you want to emit response content directly from UCE code.

Finds the first occurrence of needle inside haystack.

This is the closest UCE equivalent to PHP strpos(), but it returns -1 instead of false when no match is found.

If needle is an empty string, strpos() returns the normalized start offset.

Checks whether haystack ends with needle.

Checks whether haystack starts with needle.

Extracts part of a string using PHP-style start and length semantics.

Use the two-argument form to return everything from start_pos to the end of the string.

If start_pos is negative, counting starts from the end of the string.

If length is negative, the returned range stops that many bytes before the end of the string.

Splits str into multiple strings using delim as the separator.

Every exact occurrence of delim creates a new entry in the returned StringList.

Parses HTTP request/header text into a StringMap.

For a request line, the returned map includes fields such as REQUEST_METHOD, REQUEST_URI, SCRIPT_NAME, QUERY_STRING, and SERVER_PROTOCOL. Header names are normalized to uppercase CGI-style keys, for example Host becomes HTTP_HOST.

Example:

Most page code should read context.params instead. Use this helper when parsing raw HTTP text in tests or protocol helpers.

Parses simple line-based key/value text into a StringMap.

Each non-empty line is split on the first separator. Lines without the separator are kept with an empty value.

Example:

This is useful for small config files, metadata blocks, and tests that need predictable key/value parsing.

Splits str on runs of whitespace.

Multiple adjacent whitespace characters are treated as a single separator, so repeated spaces, tabs, or line breaks do not create empty entries.

Splits str into its constituent Unicode code points.

If compound_characters is true, split_utf8() also applies a small amount of grouping so some multi-code-point glyphs stay together. The current rules are:

• combine characters joined by a Zero-Width Joiner (ZWJ)

• combine two Regional Indicator Symbol Letter characters

• append Variation Selectors to the previous character

• otherwise leave characters as separate entries

This is useful when simple byte-wise or ASCII splitting would break Unicode text incorrectly.

Replaces every occurrence of search in s with replace_with.

The returned string contains the fully replaced result.

Tests whether subject matches pattern from start to end.

This is a full-string match, not a substring search. Use regex_search() when you want to find the first occurrence anywhere in a string.

Examples:

Supported flags:

• i enables case-insensitive matching.

• m enables multiline ^ and $.

• s lets . match newlines.

• x enables extended / whitespace-insensitive pattern syntax.

• u explicitly enables UTF-8 and Unicode character properties.

• a disables UTF-8 / Unicode property mode for ASCII-oriented matching.

UCE uses PCRE2 in UTF-8 + Unicode-property mode by default, so patterns such as \\p{L}+ work naturally on Unicode text.

Invalid patterns or invalid flags raise a request-visible runtime error with the PCRE2 diagnostic message.

Searches subject for the first occurrence of pattern and returns structured match data.

Example:

Return shape:

• matched is a boolean.

• pattern stores the original pattern.

• flags stores the supplied flags, or default.

• match is the full matched text when a match exists.

• start and end are byte offsets into the original string.

• captures is a list of capture objects, with capture 0 representing the full match.

• named maps named capture groups to their captured text.

• named_offsets maps named capture groups to index, start, and end metadata.

Capture entries contain:

If no match is found, matched is false and match-specific fields are omitted.

Finds every non-overlapping match of pattern in subject.

Example:

Return shape:

• matched is true when at least one match exists.

• count is the number of matches.

• matches is a list of entries with the same shape returned by regex_search().

• pattern and flags mirror the call inputs.

Zero-length matches are handled safely; the scanner advances after each zero-length match to avoid infinite loops.

Replaces every match of pattern in subject and returns the transformed string.

Example:

Replacement strings use PCRE2 substitution syntax, including numbered capture references such as $1 and named references such as ${name}.

For simple literal search-and-replace, use replace(). Use regex_replace() when the match condition needs a pattern, captures, character classes, anchors, or flags.

Invalid patterns, invalid flags, or invalid substitution syntax raise a request-visible runtime error.

Splits subject wherever pattern matches.

Example:

This is the pattern-aware companion to split().

Behavior notes:

• Separators are removed from the returned list.

• Empty fields are preserved.

• If the pattern does not match, the result contains the original subject as a single item.

• Zero-length separators are handled safely to avoid infinite loops.

Returns a lower-case version of s.

This function is not yet Unicode-aware.

Returns an upper-case version of s.

This function is not yet Unicode-aware.

Returns raw with leading and trailing whitespace removed.

Extracts a floating point number from a String.

If no usable number can be identified, the result is 0.

Extracts an integer value from s.

The base argument controls which number system is used while parsing. If no usable number can be identified, the function returns 0.

Returns a version of the input string where special HTML characters are replaced by entities:

• & becomes &

• < becomes <

• > becomes >

• " becomes "

Sanitizes a string into a safe name by normalizing or stripping characters that are unsafe in file names and identifiers (whitespace, separators, control characters). Use it before turning user input into a file name or cache key.

Returns a string representation of t intended for debugging.

Deserializes s into a DValue structure.

The returned structure is usually consumed through DValue accessors such as:

• tree["key"].to_string()

• tree["count"].to_u64()

• tree["enabled"].to_bool()

Current runtime behavior:

• JSON objects and arrays become map-shaped DValue values.

• JSON booleans become native bool DValue values.

• JSON strings become native String DValue values.

• JSON numbers currently deserialize as string-valued DValue nodes, so typed conversions such as to_f64() and to_u64() are the normal way to read numeric content.

Returns the last component of a path — the file or directory name without its leading directories.

Returns everything in a path except the final component — i.e. the containing directory.

Expands a path: a relative path is resolved against relative_to_path (or the current unit's directory when that is empty), producing a normalized path you can hand to the file APIs.

Appends one or more values to a file, creating it if needed. Each call takes an exclusive lock for the append, so concurrent appends are serialized and readers wait for them; you never manage locks yourself.

Reports whether a regular file exists. Use it to guard reads or to confirm a write or delete took effect. It is file-oriented and returns false for directories — use file_stat() and check is_dir to test for a directory.

Reads an entire file and returns it as a String. The read takes a shared lock for its duration, so it waits for any in-progress file_put_contents() / file_append() write to finish; you never manage locks yourself. For large files or random access, use file_open() + file_read().

Returns a file's last-modified time as a Unix timestamp. Compare two files' mtimes for cache-freshness checks, or test for > 0 to confirm a file exists with a real timestamp.

Writes content to a file, replacing whatever was there. The write takes an exclusive lock for the truncate-and-write, so concurrent writers are serialized and readers wait for it; you never manage locks yourself.

Returns the current working directory.

Returns the names of the entries in a directory as a StringList. For names only this is simpler than dir_list(), which returns full metadata per entry.

Creates a single directory and returns whether it succeeded. The parent directory must already exist, so build nested paths one level at a time.

Joins two path fragments with exactly one separator, regardless of whether base ends in a slash or child begins with one. Use it instead of string concatenation to build paths safely.

Sets the host worker process current directory. In wasm this is a hostcall, so restore the previous directory when using it inside request code.

Escapes a parameter so it can be used more safely with shell_exec().

This is the helper to reach for when building shell command lines from dynamic input.

Executes a Linux shell command and returns the generated output.

When command text includes user-controlled input, escape that input first with shell_escape().

Deletes a file. Deleting a path that does not exist is a no-op, so it is safe to call before recreating a file.

Creates a ZIP archive at zip_file_name.

entries can be a simple map where each key is the archive member name and each value is the file content:

For list-shaped input or when the map key should not be the member name, each child can provide explicit fields:

An entry may also provide file instead of content; UCE reads that source file and stores its contents under name.

Entry names are normalized to forward slashes and rejected when they are absolute paths, drive-qualified paths, empty names, or contain .. path segments.

Reads the central directory from zip_file_name and returns structured metadata.

The returned tree contains:

• file : archive path

• count : number of entries

• entries : list of entry metadata

Each entry contains:

• name

• index

• size

• compressed_size

• is_directory

• method

Example:

Reads one file member from a ZIP archive and returns its uncompressed bytes as a String.

entry_name is normalized to forward slashes and rejected when it is empty, absolute, drive-qualified, or contains a .. path segment.

Use zip_list() when you need to discover entry names before reading them.

Extracts every member in a ZIP archive into destination_directory.

UCE creates the destination directory and any needed child directories when they do not already exist.

For safety, every member name is normalized and checked before extraction. Absolute paths, drive-qualified paths, empty names, and .. path segments are rejected so archives cannot write outside the destination directory.

Compresses src and returns a gzip-format byte string.

The result is binary data. Store it in a file, send it with an appropriate content type/encoding, or pass it directly to gz_uncompress().

UCE writes a standard gzip wrapper around a deflate stream, including CRC32 and uncompressed-size footer fields.

Uncompresses a gzip-format byte string and returns the original content.

gz_uncompress() validates the gzip header, CRC32 footer, and uncompressed-size footer. It throws a runtime error when the input is not a supported gzip stream or fails validation.

Starts or updates a custom HTTP listener backed by a UCE handler file.

The server key is runtime-wide. Calling server_start_http() again with the same key and the same bind target updates the mapped UCE file/function without restarting the listener. If the bind target changes, UCE stops the old listener and starts a replacement.

socket_fn_or_port may be a numeric TCP port such as "19091" or a Unix socket path.

Handler files use SERVE_HTTP:

SERVE_HTTP(Request* req)
{
    req->header["Content-Type"] = "text/plain; charset=utf-8";
    print("hello from custom HTTP\n");
}

SERVE_HTTP:admin(Request* req)
{
    print("named handler\n");
}

The custom server dispatcher uses the same nonblocking HTTP listener machinery as the built-in HTTP/WebSocket path, and hands request/response data through the normal Request object. Handler code may block in the first implementation; future worker dispatch can be added without changing this API.

Stops a custom server listener by key and removes its registry config.

server_stop() currently targets custom servers started through server_start_http(). The same key model is intended to extend to future server_start_tcp() and server_start_udp() helpers.

Opens a file for streaming, handle-based I/O and returns an opaque handle for file_read(), file_write(), file_seek(), and file_close(). Locks are automatic and scoped to the handle: read opens take a shared lock, write/append/read-write opens take an exclusive lock, and file_close() releases it. Lock waits are bounded by UCE_FILE_LOCK_TIMEOUT_MS (default 2000ms), so a contended open returns 0 instead of blocking forever. For whole-file access prefer file_get_contents() / file_put_contents().

Reads up to len bytes starting at the handle's current offset and advances the offset. Returns fewer bytes (or "") at end of file. Use file_seek() to move the offset, or file_pread() to read at an absolute offset without moving it.

Reads len bytes from an absolute offset without moving the handle's current offset. Useful for random access reads that interleave with sequential ones.

Writes data at the handle's current offset and advances the offset. The handle must come from file_open() with a writable mode ("w", "a", or "r+"). Binary-safe: data may contain NUL and other non-text bytes.

Writes data at an absolute offset without moving the handle's current offset. The handle must be opened with a writable mode ("r+" for in-place edits).

Moves a handle's read/write offset for random access. Combine with file_read() / file_write() to jump around a file; file_tell() reports the current offset.

Returns a handle's current read/write offset, as moved by file_read(), file_write(), and file_seek().

Closes a file handle and releases the lock that file_open() took. Always close handles you open: locks are scoped to the handle's lifetime, so a leaked handle holds its lock until the worker recycles.

Returns metadata about a path as a DValue map. Read fields with the usual accessors, e.g. st["size"].to_u64() and st["is_file"].to_bool(). When the path does not exist, exists is false.

Lists a directory's entries as a DValue list. Each entry is a map with name, type ("file", "dir", "symlink", or "other"), size, and mtime. Iterate with .each() and read fields with item.key("name")->to_string().

Renames or moves a file. After a successful rename the source path no longer exists. Use it for atomic publish patterns: write a temp file, then rename it into place.

Copies a file's contents to a new path, overwriting the destination if present.

Truncates (or extends) a file to exactly size bytes. Shrinking discards trailing bytes; growing pads with zero bytes.

Removes a directory. By default it must be empty; pass recursive = true to delete the directory and all of its contents.

Creates a new, uniquely named empty file using prefix as the leading path and returns its full path. Use it for scratch files and the write-then-rename publish pattern.

Sets a path's permission bits, like the shell chmod. Pass the mode as an octal literal such as 0600.

Creates a symbolic link at linkpath pointing to target. Reading through the link reads the target; use path_real() to resolve a link to its canonical destination.

Flushes a handle's buffered writes to disk, so the data survives a crash or power loss. Call it before file_close() when durability matters (e.g. after writing a checkpoint).

Reports whether path lies inside root. It resolves both paths to their canonical form (like path_real()), so they must exist and .. traversal is collapsed first. Use it to reject path-traversal attempts before opening user-supplied paths.

Resolves a path to its canonical absolute form, following symlinks and collapsing . and .. segments. The path must exist. Combine with path_is_within() to validate that user-supplied paths stay inside an allowed root.

Returns the directory captured when the native process started. It remains stable even if cwd_set() changes the current working directory.

Returns a DValue with timing and process metadata such as worker pid, parent pid, request count, request start times, and workspace birth timing when available.

Trims a runtime key and converts it to a stable SHA-1 identifier suitable for task/runtime file names.

Starts exec_func in a new process and returns that process ID.

If a process with the same key is already running anywhere in the runtime instance, task() does not start a second copy. Instead it returns the PID of the already-running task. Coordination is through a shared task status file under BIN_DIRECTORY, so the key applies across workers, not just the current worker process.

Task keys may contain ordinary user-facing text. UCE hashes the key before using it as an internal lock/status filename so slashes and other path-like characters cannot escape the task state directory.

timeout is enforced in the child process with an alarm. The default is ten minutes. Pass 0 only for tasks that have their own shutdown path.

Starts a repeating background worker process.

exec_func runs in a loop, and the worker sleeps for interval seconds between executions. interval must be greater than zero.

If a process with the same key is already running anywhere in the runtime instance, task_repeat() does not start a second worker and instead returns the PID of the existing one. Coordination is through the same shared task state used by task().

timeout bounds the lifetime of the repeating worker. The default is ten minutes. Pass 0 only for workers that have another shutdown path.

Checks whether a process with the given key is running anywhere in the runtime instance and returns its PID if it is.

Returns 0 when no matching task is active or task state cannot be read safely. Stale task status files are removed when the recorded PID is no longer alive.

New task status records include the Linux process start tick from /proc/<pid>/stat, so task_pid() can reject a stale status file if the PID has exited and the numeric PID has since been reused by another process.

Wraps the standard POSIX kill() function for positive process IDs.

task_kill() rejects pid <= 0 and returns -1, so callers cannot accidentally use POSIX process-group or broadcast semantics through this helper.

sig may be any supported POSIX signal, including values such as SIGTERM, SIGKILL, SIGINT, SIGUSR1, SIGUSR2, SIGCHLD, SIGCONT, and related process-control signals.

Passing 0 as the signal performs an existence and permission check without actually delivering a signal.

Pauses the current request or task for a number of microseconds.

Use this for short waits in local tests, polling loops, or background tasks. Avoid long sleeps in normal HTTP render paths because they hold a worker process for the duration.

Example:

For whole-second waits, use sleep().

Returns the current Unix timestamp as a 64-bit float with millisecond accuracy or better.

Returns the current Unix timestamp as a 64-bit integer with second precision.

Formats a timestamp in the server's local timezone.

This formatter is based on the Linux date command and supports the same core formatting tokens plus UCE's relative-time delta tokens.

Supported format sequences:

Padding and case flags may follow %:

Formats a timestamp relative to the current time using the same formatting engine as time_format_local() and time_format_utc().

The formatter chooses one of three output formats:

• if now - timestamp is less than medium_recency_seconds, use format_very_recent

• else if it is less than not_recent_seconds, use format_medium_recent

• otherwise use format_not_recent

The relative-time tokens available in all time formatters are:

Default behavior examples:

Formats a timestamp in the GMT/UTC timezone.

This formatter is based on the Linux date command and supports the same core formatting tokens plus UCE's relative-time delta tokens.

Supported format sequences:

Padding and case flags may follow %:

Attempts to parse time_string into a Unix timestamp.

Request& context is the request-local state object passed into every UCE handler:

It is the main bridge between the runtime and page code. It contains incoming request data, response state, output buffers, per-request scratch trees, session/cookie state, WebSocket metadata, and runtime diagnostics.

Handler Lifetime

A fresh Request is created for each HTTP/CLI/custom-server request. Component and unit calls normally share that same object, so state placed on context.call, context.header, context.session, or context.cfg is visible to later components in the same request.

For WebSockets, each incoming message is delivered as its own Request, but context.connection points at broker-owned per-socket state that persists for the lifetime of that WebSocket connection.

ONCE(Request& context) hooks run once per request, per resolved unit file, before the first RENDER, COMPONENT, CLI, or matching entrypoint from that unit.

Incoming Request Maps

context.params — server/runtime parameters

Type: StringMap

This is the low-level parameter map from FastCGI/direct HTTP plus UCE-populated convenience fields. It is closest to PHP $_SERVER.

Common CGI/FastCGI-style keys include:

• REQUEST_METHOD: GET, POST, etc.

• REQUEST_URI: raw request URI where available

• DOCUMENT_URI: normalized request path where available

• SCRIPT_NAME: script path where available

• SCRIPT_FILENAME: resolved filesystem path of the active UCE unit

• QUERY_STRING: raw query string

• DOCUMENT_ROOT: web root used by the frontend/backend

• CONTENT_TYPE: request body content type

• CONTENT_LENGTH: request body length

• HTTP_COOKIE: raw cookie header

• HTTP_HOST, HTTP_USER_AGENT, HTTP_ACCEPT, and other HTTP_... headers supplied by the frontend

UCE also populates convenience route/link fields before handlers run:

• SCRIPT_URL: canonical script URL; /index.uce is collapsed to the containing directory URL

• BASE_URL: canonical directory URL for the script

• ROUTE_PATH: sanitized first keyless query-string segment, defaulting to index when no route was supplied; empty when unsafe input was rejected

• ROUTE_PAGE: first segment of ROUTE_PATH

• ROUTE_PATH_RAW: normalized but untrusted route input, for diagnostics only

• ROUTE_VALID: 1 when route input is safe, 0 when the supplied route was rejected

See request_context_params, request_script_url, request_base_url, request_query_path, request_query_route, and route_path_sanitize.

context.get

Type: StringMap

Parsed query-string key/value parameters. This is populated from context.params["QUERY_STRING"] with parse_query().

For front-controller route URLs such as /?dashboard&theme=dark, the keyless dashboard segment is represented by sanitized ROUTE_PATH; named parameters such as theme=dark are available in context.get.

context.post

Type: StringMap

Parsed request body parameters for ordinary POST requests. URL-encoded bodies are parsed with parse_query(). Multipart form data is parsed with parse_multipart() and uploaded files are listed in context.uploaded_files.

context.cookies

Type: StringMap

Cookies sent by the client, parsed from HTTP_COOKIE. set_cookie() also updates this map after queuing a response cookie, so later code in the same request can observe the new value.

context.in

Type: String

Raw request body. For WebSocket handlers, this is the current message payload.

Use this for JSON APIs:

context.uploaded_files

Type: std::vector<UploadedFile>

Each UploadedFile contains:

• file_name: original submitted filename

• tmp_name: temporary server-side upload path

• size: uploaded byte count

Use this with multipart form posts.

Session State

context.session

Type: StringMap

Session data loaded by session_start(). UCE does not load sessions automatically for every request; call session_start() before reading/writing session data.

At the end of a successful request, modified session data is saved automatically if a session is active.

context.session_id and context.session_name

The active session ID and cookie name after session_start().

Related helpers:

• session_start()

• session_destroy()

• session_id_create()

• set_cookie()

Per-request Structured Trees

context.call

Type: DValue

General request-local scratch/configuration tree. It is shared by the page, components, and unit calls participating in the current request. Use it for app-level request state, fragments, router results, page type, page title, and other values that need to be read by later components.

Examples from front-controller style apps:

Prefer clear top-level names when state is app-wide (route, fragments) and nested app names only when the state is truly owned by that app (app/page_title, app/page_type).

context.cfg

Type: DValue

Request-local structured configuration. The runtime does not fill this with application config by default; application code may assign it during boot/setup:

This is separate from context.server->config, which is the runtime/server string config from /etc/uce/settings.cfg.

Use get_by_path() for non-mutating deep reads:

context.props

Type: DValue

Invocation-local props for component(), component_render(), and macro-style unit_call() entrypoints. During a component call, the runtime temporarily replaces context.props with the props passed to that component and restores the previous value after the call returns.

context.connection

Type: DValue

WebSocket connection-local state. Mutations persist across WS(Request& context) calls for the same socket.

Only meaningful for WebSocket handlers.

Response State

context.response_code

Type: String

The raw status line. Usually use context.set_status(...) instead of writing this directly.

context.header

Type: StringMap

Response headers to emit. Header names are case-sensitive as written.

context.set_cookies

Type: StringList

Queued Set-Cookie header lines. Prefer set_cookie() instead of editing this directly.

context.set_status(code[, reason])

Sets the HTTP response status and context.flags.status.

Related helpers:

• redirect(url[, code])

• set_cookie(...)

Output Buffers

context.ob_stack and context.ob

Internal output-buffer stack. Most code should use helpers instead of touching these directly:

• print(...)

• out(...)

• ob_start()

• ob_get()

• ob_get_close()

• ob_close()

Common capture pattern:

context.out and context.err

Runtime output/error artifacts used by some transports and failure paths. Normal page rendering should use print() / output buffers.

Request Flags

context.flags contains runtime booleans and the numeric status:

• log_request: whether the request should be logged

• is_finished: internal completion marker

• status: numeric HTTP status set by set_status()

• output_closed: internal transport state

• params_closed: internal transport state

• input_closed: internal transport state

Most page code only reads flags.status, if anything.

Request Stats

context.stats contains counters/timing for the request:

• bytes_written

• time_init

• time_start

• time_end

• mem_high

• mem_alloc

• invoke_count

These are useful for diagnostics, demos, and runtime instrumentation.

Random / Noise State

• random_seed

• random_index

Used by UCE noise/random helpers to provide request-local deterministic progression.

Related helpers include functions in the noise/hash area such as gen_int, gen_float, gen_noise64, and gen_sha1.

WebSocket Fields

In WS(Request& context), the runtime mirrors WebSocket metadata into context.params and context.resources.

Convenience context.params keys include:

• WS_MESSAGE

• WS_CONNECTION_ID

• WS_SCOPE

• WS_CONNECTION_COUNT

• WS_OPCODE

• WS_MESSAGE_TYPE

• WS_DOCUMENT_URI

Prefer WebSocket helper functions where possible:

• ws_message()

• ws_connection_id()

• ws_scope()

• ws_opcode()

• ws_is_binary()

• ws_connections()

• ws_connection_count()

• ws_send()

• ws_send_to()

• ws_close()

Use context.connection for per-socket structured state.

Runtime / Resource Fields

context.server

Pointer to server state. Useful mainly for low-level/runtime code. Runtime config lives at:

This is a StringMap, separate from app-owned context.cfg.

context.resources

Internal runtime resources and transport state. Includes sockets, MySQL handles, WebSocket state, current unit file, and parser buffers. Application code should normally use public helpers instead of editing this directly.

Notable fields:

• is_websocket

• is_cli

• websocket_connection_id

• websocket_scope

• websocket_scope_connection_ids

• current_unit_file

Common Patterns

Minimal page

JSON endpoint

Redirect

Component props

Front-controller route

Or use runtime-populated params directly:

Merges two maps or trees using PHP-like merge behavior.

For StringMap, keys from b overwrite keys from a.

For DValue, string keys from b overwrite keys from a. Numeric keys are appended and reindexed when either side behaves like a list.

This helper is the closest UCE equivalent to PHP array_merge() for common request, config, and JSON-shaped data.

DValue is UCE's general-purpose structured value type. It is the runtime's default container for nested data such as configuration trees, call payloads, decoded JSON, connection state, and metadata returned by runtime helpers.

Value Kinds

DValue can hold:

• String

• f64

• bool

• pointer values

• nested child DValue values in a map-shaped container

Map-shaped DValue values can also represent list-like data when their keys are numeric strings in sequence.

Where It Appears

You will encounter DValue throughout the runtime, especially in:

• context.cfg

• context.props

• context.connection

• json_decode() results

• unit_call() return values

• unit_info()

Reading Values

• ["key"] accesses or creates a child node.

• .has("key") checks whether a child exists without creating it.

• .key("key") returns a child pointer when it already exists.

• .get_or_create("key") returns a child pointer and creates it when missing.

• .get_by_path("a/b/c") traverses nested children without creating missing keys.

• .to_string(default) reads scalar content as text.

• .to_s64(default), .to_u64(default), and .to_f64(default) perform best-effort numeric conversion.

• .to_bool(default) performs best-effort boolean conversion.

• .to_stringmap() converts a map-shaped tree into StringMap.

All read accessors are const and never modify the tree; they work directly on const DValue& values such as each() callback parameters. Every to_* conversion takes an optional default that is returned when the value is missing or cannot be converted — see the individual pages (2_DValue_to_string, 2_DValue_to_s64, 2_DValue_to_u64, 2_DValue_to_f64, 2_DValue_to_bool) for the exact rules:

operator[] creates missing entries, just like std::map. .has() and .key() are the non-mutating lookup helpers, and .get_by_path() is the non-creating traversal helper.

json_decode() currently stores JSON numbers as string-valued DValue nodes, so typed numeric conversion is the normal way to consume those values.

References are dereferenced automatically in most normal reads.

Conversion Rules

• Scalar-looking strings are trimmed before numeric and boolean parsing.

• .to_bool() understands common textual forms such as true, false, yes, no, 1, and 0.

• bool values convert numerically to 1 and 0.

• Pointer values convert numerically when read as numbers.

• Single-value maps can act as scalar wrappers for numeric and boolean conversion.

• Missing values and invalid numeric input fall back to the accessor's default_value argument (0, "", or false when not given).

• .to_stringmap() converts map children key-by-key using each child's to_string().

Writing Values

Common mutating helpers include:

• .set(String)

• .set(f64)

• .set_bool(bool)

• .set(StringMap)

• .set_array()

• .push(...)

• .pop()

• .remove(key)

• .clear()

Use .set_array() when you want list-style behavior with push() and pop().

Inspection Helpers

Useful inspection helpers include:

• .has(key)

• .key(key)

• .get_or_create(key)

• .get_type_name()

• .is_array()

• .is_list()

• .to_json()

each()

each(std::function<void (const DValue& t, String key)> f) iterates over the current tree value (see 2_DValue_each for details).

For map-shaped DValue values, the callback runs once per child entry and receives:

• t as the child value, by const reference (no copy)

• key as the child key

For non-map values, each() still invokes the callback once:

• t is the current value

• key is an empty string

Examples

filter(keys) copies existing children with the named keys into a new map-shaped DValue.

filter(f) calls the predicate for each item from each(). Kept children from list-shaped input are pushed into a new list and re-indexed from zero; kept children from map-shaped input keep their original keys. Scalar input is passed to the predicate once and, if accepted, is pushed into a list.

Returns the keys produced by each(). Scalar values have no child key, so the result is empty. List-shaped values return their numeric keys as strings.

Builds a new DValue by replacing each iterated child with the mapper's returned value. List-shaped input stays list-shaped and is re-indexed by push(). Map-shaped input preserves keys. Scalar input is mapped once and pushed into a list.

Copies the values produced by each() into a new list-shaped DValue.

Iterates a DValue without modifying it. References are dereferenced before iteration.

For map-shaped values, the callback receives each child and its key. List-shaped maps iterate in numeric index order (0, 1, 2, ...); ordinary maps iterate in std::map string-key order. Scalar values invoke the callback once with the current value and an empty key.

Traverses nested map/list children without creating missing nodes. Empty path segments are ignored. If any segment is missing or an intermediate value is not map-shaped, the method returns an empty DValue.

Checks for a child key without creating it. Returns false for scalars and missing keys.

Returns true when the value's current type is M, the map/list container type. It does not require contiguous numeric keys; use is_list() for that.

Returns true for map-shaped values that represent a list. An empty map is a list only if it was explicitly put in list mode with set_array() or by list operations. Non-empty lists must have canonical numeric string keys from 0 through size - 1.

Sets the request status line and mirrors the numeric status into context.flags.status. When reason is omitted, common HTTP status codes get their standard phrase. FastCGI-style requests use a Status: prefix; other requests use HTTP/1.1.

Primary string type used throughout UCE.

String is an alias for std::string.

It is used for request data, headers, cookie values, file contents, query strings, JSON text, and WebSocket payloads.

Because it is backed by std::string, it is binary-safe and may also contain raw bytes.

For UTF-8-aware splitting, use helpers such as split_utf8() instead of assuming one byte equals one character.

StringList is an ordered container of String values. It inherits normal std::vector<String> behavior and adds list helpers for filtering, mapping, indexes, iteration, deduplication, sorting, and predicate checks.

Returns a new StringList containing the original items for which the predicate returns true. Order is preserved.

Returns a new StringList containing the mapper result for each item, in the same order. Use it for simple string transformations while keeping list shape.

Returns the list indexes as strings from 0 through size() - 1. Use it when code expects string keys for a list-shaped value.

Calls the callback once for each string in order. Use it when you want side effects such as building output or accumulating a separate value.

Returns a copy of the list with duplicate strings removed. The first occurrence of each string is kept, so the result preserves first-seen order.

Returns a sorted copy of the list without changing the original. Use it for deterministic output, menus, manifests, and test comparisons.

Tests whether any string in the list satisfies the predicate. Use it for concise presence checks when the condition is more specific than direct equality.

Tests whether all strings in the list satisfy the predicate. Use it for validation checks where a list is acceptable only if every member passes the same rule.

Returns the first string in the list that satisfies the predicate. Use it when you need the matching value itself, not just a yes/no answer, and when a clear fallback is better than a separate missing-value branch.

Associative container mapping String keys to String values.

StringMap is an alias for std::map<String, String>.

Common Uses

StringMap commonly appears in:

• context.params

• context.get

• context.post

• context.cookies

• context.session

• context.header

Because it uses std::map, map["key"] will create an empty entry when that key does not already exist.

Helpers such as parse_query() and encode_query() convert between query strings and StringMap values.

Converts strings, numbers, bools, pointers, and maps to bool. Text such as true, yes, on, 1, false, no, off, 0, and null is recognized; non-empty unparseable strings are truthy; empty strings use the default. Multi-child maps are true when non-empty.

Converts strings, f64, bool, pointer, and single-value maps to a finite double. Invalid or empty strings return the default.

Returns the JSON scalar representation used by this low-level method: strings are escaped and quoted, numbers are emitted with std::to_string, bools as true/false, maps as "(array)", pointers as "(pointer)", and references as "(reference)". For full structured encoding, use the runtime JSON helpers.

Converts strings, f64, bool, pointer, and single-value maps to a signed integer. Invalid or empty strings return the default. Values outside the signed range are clamped.

Returns the stored string, converts f64/bool/pointer values to text, and returns the default for empty strings, maps, unresolved references, or unknown types. Bool text is (true) or (false).

Converts a DValue to StringMap. Map children become entries converted with to_string(). Non-empty strings become value=<string>. f64, bool, and pointer values become value=<to_string()>. References that cannot be resolved produce an empty map.

Converts strings, f64, bool, pointer, and single-value maps to an unsigned integer. Invalid or empty strings return the default. Negative values clamp to zero and oversized values clamp to u64 max.

Parses a trimmed, case-insensitive boolean string.

Truthy tokens are "1", "true", "yes", and "on". Falsey tokens are "0", "false", "no", and "off". Empty or unrecognized strings return the fallback.

Parses a trimmed string as a floating-point number.

Unlike float_val(), the whole trimmed string must be consumed by the parser. Empty strings and partially parsed values such as "3.5ms" return the fallback.

Parses a trimmed string as a base-10 signed integer.

The whole trimmed string must be consumed by the parser. Empty strings and partially parsed values such as "-12px" return the fallback.

Parses a trimmed string as a base-10 unsigned integer.

Unlike int_val(), the whole trimmed string must be consumed by the parser. Empty strings and partially parsed values such as "42px" return the fallback.

Serializes a DValue to UCEB1, UCE's binary DValue wire format for the WASM membrane and future cross-instance calls.

UCEB1 is length-prefixed and binary-safe. It preserves nested maps, list-shaped maps, empty lists, and scalar bytes, including embedded NUL bytes. Use JSON/YAML/XML serializers for human-facing formats; use UCEB1 when UCE code needs the native DValue protocol.

Decodes UCEB1 bytes produced by ucb_encode() back into a DValue.

The one-argument form returns an empty DValue on invalid input. The three-argument form reports whether decoding succeeded and can return a human-readable error string.

Encodes a StringMap of URL parameters into a single query-string String.

Sets the Location response header and updates the current HTTP status code.

Use this helper instead of manually assigning context.header["Location"] and context.set_status(...) when you want to redirect the current response.

UCE populates several convenience request parameters before invoking page, component, CLI, custom HTTP, or WebSocket handlers:

• context.params["SCRIPT_URL"]: canonical script URL, with /index.uce collapsed to the containing directory URL

• context.params["BASE_URL"]: canonical directory URL for the script

• context.params["ROUTE_PATH"]: sanitized first keyless query-string segment, defaulting to index when no route was supplied

• context.params["ROUTE_PAGE"]: first segment of ROUTE_PATH

• context.params["ROUTE_PATH_RAW"]: normalized but not trusted route input, for diagnostics only

• context.params["ROUTE_VALID"]: 1 when the supplied/defaulted route is safe, 0 when the supplied route was rejected

• context.params["UCE_BIN_DIRECTORY"]: writable runtime cache directory from BIN_DIRECTORY, useful for generated helper units or other request-local artifacts that must not be written into the source tree

ROUTE_PATH is safe to compose under an application-controlled route root. Unsafe route input such as .., ., empty interior segments, backslashes, dots in filenames, or other non route-segment characters is rejected by the runtime and yields an empty ROUTE_PATH with ROUTE_VALID=0.

These are useful for front-controller apps that use URLs like /?dashboard or /?workspace/projects while still accepting ordinary named query parameters.

Returns the canonical directory base URL for the current script. This is useful for front-controller apps that generate links to sibling assets or query-routed pages.

Returns the first keyless query-string segment as a sanitized route path.

For a request such as /?workspace/projects&theme=dark, this returns workspace/projects.

When no keyless route is supplied, the result is default_path. When unsafe route input is supplied, the result is an empty string. Unsafe route input includes . or .. segments, empty interior segments, backslashes, dots in filenames, or any character outside ASCII letters, digits, _, and -.

The runtime-populated context.params["ROUTE_PATH"] uses the same sanitizer.

Builds a small route tree from the first keyless query-string segment.

Fields:

• raw_path: normalized but untrusted route input, for diagnostics only

• l_path: sanitized full route path, or empty string when input was rejected

• page: first path segment of l_path, or empty string when input was rejected

• valid: boolean; true when l_path is safe

This supports front-controller apps that use URLs such as /?dashboard or /?workspace/projects while still allowing ordinary named query parameters alongside the route. The returned l_path is already sanitized for composing under an application-controlled route root.

Returns the request script URL from DOCUMENT_URI / SCRIPT_NAME, canonicalizing a front-controller URL ending in /index.uce to the containing directory URL.

Returns whether a normalized route path is safe to use as a route-derived file path segment.

A safe route path contains only non-empty segments made from ASCII letters, digits, _, and -. The segments . and .. are rejected.

Most request code should use runtime-populated context.params["ROUTE_PATH"] or request_query_route() instead of calling this directly.

Trims whitespace and removes leading/trailing / from a route path without deciding whether the path is safe.

For route data that may be used to compose file paths, prefer route_path_sanitize() or runtime-populated context.params["ROUTE_PATH"].

Normalizes and validates a route path for file-backed routing.

Rules:

• leading and trailing / are removed

• an empty path becomes default_path

• every path segment must be non-empty

• . and .. segments are rejected

• only ASCII letters, digits, _, and - are accepted inside a segment

• unsafe input returns an empty string

Use this instead of manually checking app routes before composing file paths.

request_query_path(), request_query_route(), and the runtime-populated ROUTE_PATH params already use this sanitizer.

Creates and returns a new session ID.

This helper is useful when you need to generate a session token directly rather than starting a full session flow with session_start().

Decodes a query-string fragment such as a=b&c=d into a StringMap.

Parsing rules:

• pairs are separated on &

• each pair is split on the first raw = only

• both key and value are URL-decoded

• keyless flags such as preview are present with an empty string value

• empty pairs, including a trailing &, are ignored

• repeated keys use the last value seen

Examples:

This is useful when you need to work with URL parameter data outside the normal request parsing flow.

Parses a URI into its component maps.

return.parts contains the parsed URI fields. return.query contains query parameters decoded with the same rules as parse_query().

Example:

Use parse_uri() when you need to inspect a full URL. Use parse_query() when you only have the query string.

Decodes a URI-encoded string.

URI-encodes a string.

Normalizes and validates a raw route path. The returned DValue includes route fields used by request context population, including sanitized path and validity metadata.

Queues a WebSocket close frame and closes the targeted connection.

If connection_id is omitted, the current connection handled by WS(Request& context) is closed.

Returns the number of currently connected WebSocket clients for the given scope.

If scope is omitted, the current page scope is used.

Returns the runtime-generated connection ID of the client whose message is currently being handled.

This ID can be passed to ws_send_to() or ws_close() to target a single connected client.

Returns the currently connected WebSocket client IDs for the given scope.

If scope is omitted, the current page scope is used.

Returns whether the message currently being handled by WS(Request& context) arrived as a binary frame.

If this returns false, the current message was delivered as a text frame.

Returns the payload of the current WebSocket message being handled by WS(Request& context).

For text frames this is the decoded text payload. For binary frames this String contains the raw message bytes.

Use ws_is_binary() or ws_opcode() to choose how to parse the payload.

Returns the opcode of the message currently being handled by WS(Request& context).

Common values are:

• 0x1 for text messages

• 0x2 for binary messages

Returns the runtime's scope identifier for the current WebSocket endpoint.

This is the same default scope used by ws_send(), ws_connections(), and ws_connection_count() when no explicit scope is supplied.

In the current runtime implementation this scope is the page's internal endpoint identifier, typically the absolute SCRIPT_FILENAME of the .uce file that accepted the WebSocket upgrade.

Queues a WebSocket message for every client connected to the given scope.

If scope is omitted, the current page scope is used.

Queues a WebSocket message for one specific connected client.

Defines the default component entrypoint for the current .uce file.

component() and component_render() call COMPONENT(Request& context) by default. Named component entrypoints use COMPONENT:NAME(Request& context).

If the same file defines ONCE(Request& context), that hook runs once per request before the first COMPONENT() or COMPONENT:NAME() call for that unit.

If the file defines INIT(Request& context), that hook runs once when the worker loads the compiled unit into memory.

Why It Exists

This keeps page rendering and component rendering separate:

• direct HTTP requests call RENDER(Request& context)

• WebSocket messages call WS(Request& context)

• component helpers call COMPONENT(Request& context) or COMPONENT:NAME(Request& context)

A file intended only for component reuse can define COMPONENT() without defining RENDER().

Inside component handlers, props arrive through context.props.

When you call component(":NAME", props, context) or component_render(":NAME", props, context), the runtime resolves :NAME against the current .uce file instead of requiring the file name again.

Example

Defines a worker-load hook for the current .uce unit.

When a worker instantiates the unit's compiled wasm module, the runtime checks whether the unit exposes INIT(Request& context). If it does, the hook runs once for that instance before the unit begins serving requests from that worker-local copy.

Because UCE usually loads units on demand during a request, INIT() still receives a valid Request& context. Use it for worker-local initialization, not for request-local state that should reset each request.

Typical Uses

• warm caches or parse static lookup data into globals

• initialize worker-local helper state for expensive component trees

• perform one-time registration work for that unit's in-memory copy

Example

Defines a request-local one-time hook for the current .uce unit.

When a request first enters a given file through RENDER(Request& context), COMPONENT(Request& context), or any COMPONENT:NAME(Request& context) handler, the runtime checks whether that unit exposes ONCE(Request& context). If it does, the hook runs before the selected render or component handler.

ONCE() is tracked per request and per resolved unit file, so repeated component calls to the same file inside one request do not rerun it.

Typical Uses

• prepare request-local derived state on context.call

• load request-scoped config or data needed by multiple named component handlers

• normalize shared props before the unit's first render/component call

Example

Defines the WebSocket message handler for the current .uce page.

Any .uce unit may expose both RENDER(Request& context) and WS(Request& context). RENDER(Request& context) serves the initial HTTP response, while WS(Request& context) is called whenever a complete WebSocket message arrives for that page. Configure nginx/Apache to route WebSocket upgrade requests for .uce paths to the runtime's HTTP/WebSocket listener.

UCE reassembles fragmented messages before calling WS(Request& context). Text and binary frames are both delivered. The current payload is available directly on context.in, message metadata is mirrored into context.params["WS_..."], and connection-local state lives on context.connection.

Connection State

context.connection is a broker-owned DValue for the current socket. It starts empty for a new client and persists across later WS(Request& context) calls on that same connection.

Message Data

The current message payload is available as:

• context.in: current WebSocket payload

• context.params["WS_MESSAGE"]: same payload mirrored into the parameter map

The current message metadata is available as:

• context.params["WS_CONNECTION_ID"]: sender connection ID

• context.params["WS_SCOPE"]: current endpoint scope

• context.params["WS_CONNECTION_COUNT"]: number of currently connected clients in that scope

• context.params["WS_OPCODE"]: WebSocket opcode of the current message

• context.params["WS_MESSAGE_TYPE"]: TEXT or BINARY

• context.params["WS_DOCUMENT_URI"]: request URI of the current endpoint

Helper wrappers such as ws_message(), ws_connection_id(), ws_scope(), ws_connection_count(), ws_opcode(), and ws_is_binary() are still available when that reads better for the handler.

Assignment overloads forward to the matching set(...) overloads. They are the normal concise way to write string, number, pointer, DValue, and StringMap values. Boolean values should use set_bool() to avoid overload ambiguity.

Clears the value into an empty map-shaped value and resets its array index. Unlike set_array(), this does not set list mode.

Returns the value after following internal reference links. Most public accessors call this for you, so direct use is rare in unit code.

Ensures the value is map-shaped and returns the named child. If the key does not exist, an empty child is created. Creating a non-numeric key on a list-shaped value clears list mode.

Returns a human-readable name for the dereferenced value's type tag.

Reports whether the current node's direct type tag is the internal reference tag. Most read methods dereference automatically; this helper is mainly useful when handling reference-aware runtime state.

Looks up one child without creating it. The non-const overload forwards through references; both overloads return 0 for scalars or missing keys.

Returns a mutable reference to a child, creating the child when it does not already exist. If this value is an internal reference, the operation is forwarded to the target. This has the same creation behavior as get_or_create(), so use has(), key(), or get_by_path() for non-mutating reads.

Ensures the value is map-shaped, removes the last entry according to std::map reverse key order, and returns it. For list-mode values, the next array index is reset to the new size.

Appends a child under the next numeric key. Empty values become list-shaped. Existing contiguous lists continue at their size; non-list maps use the next unused numeric key and remain non-list.

If this node is an internal reference, follows reference links up to the runtime safety limit and returns the final non-reference target. Returns 0 for non-references, null/self references, or chains that still resolve to a reference.

Ensures the value is map-shaped and erases the named child. Removing the last child resets the next array index to zero.

Assigns a new value, forwarding through references when possible. String, pointer, and f64 overloads set scalar nodes. set(DValue) copies the source's current type and payload. set(StringMap) creates a map-shaped value with each string entry as a child.

Clears the value and makes it an empty list-shaped map. Subsequent push() calls append numeric keys starting at 0.

Stores a boolean value, forwarding through references when possible.

Stores an internal reference to another DValue. Most unit code should not need to create references directly; normal reads and writes generally follow existing references automatically.

Changes the node's internal type tag, forwarding through references when possible. Switching to map type clears children, resets list state, and resets the array index.

Prefer the typed setters (set, set_bool, set_array) in normal unit code.

Starts a new output buffer for the request and makes it the active context.ob. Most unit code should prefer the higher-level output-buffer helpers (ob_start(), ob_get(), ob_get_close(), ob_close()) rather than calling the method directly.

UCE units reach the operating system only through a fixed set of uce_host_* membrane hostcalls (see the runtime architecture). A server operator can disable individual hostcalls so a deployment exposes only the capabilities it wants — for example turning off shell_exec or http_request on a hardened host. A unit that calls a disabled function fails at request time with the configurable error page, stating exactly which function was blocked and why.

Configuration

Set UCE_HOSTCALL_BLOCKLIST in /etc/uce/settings.cfg to a comma-separated list of hostcall names. Names may be given bare (shell_exec) or fully qualified (uce_host_shell_exec); whitespace is ignored. Empty (the default) blocks nothing.

Changes take effect on restart (systemctl restart uce). There is no hot reload — the list is parsed once per worker process into a fast lookup, so an empty list has zero runtime cost and a non-empty list costs only a single check per hostcall at workspace birth (never per call).

Behaviour when a blocked function is called

The blocked hostcall resolves to a trap stub instead of its real implementation. When a unit invokes it, the request fails into the runtime error page with:

• error type policy_blocked (so a custom error page template can special-case it),

• a title function disabled by server policy,

• a message naming the exact function, e.g. "this unit called ucehostshellexec, which is disabled on this server by configuration (UCEHOSTCALL_BLOCKLIST)".

The worker is unharmed (it is a clean guest trap, like any other), and only the offending request fails. A unit cannot catch this — blocking is enforcement, not a soft signal.

What can and cannot be blocked

Any uce_host_* capability hostcall can be listed — file I/O, shell_exec / shell_spawn, http_request, mysql, sockets, memcache, crypto, the job registry, etc. (the full set is the membrane list in the runtime architecture doc and src/wasm/core_hostcalls.syms).

A small core set the runtime itself needs is exempt and ignored even if listed, so a deployment cannot be bricked by an over-broad blocklist: component_resolve (used for component() / unit rendering).

Notes

• No recompilation is required (neither the wasm core nor the native binary) — this is pure runtime configuration; blocked hostcalls still exist as imports, they simply resolve to a trap.

• Pure-compute library functions that are NOT hostcalls (string ops, DValue methods, hashing helpers like gen_noise, etc.) are not OS capabilities and cannot be blocked this way — only uce_host_* membrane calls are gateable.

UCE runs a small custom source-to-source preprocessor before Clang sees a .uce or .ws.uce file.

The template rewriting implementation lives in src/lib/compiler-parser.cpp, with orchestration in src/lib/compiler.cpp. It does not try to parse all of C++. Instead, it performs a narrow character-wise rewrite that understands literal output, inline code islands, #load, and EXPORT harvesting, then writes a generated .cpp file and compiles that file into a WebAssembly side module.

Syntax

• <> ... </> enters literal-output mode.

• ?> ... <? also enters literal-output mode.

• The open and close pairs are interchangeable, so <> ... <?, ?> ... </>, and the traditional matched forms all work.

• Inside literal output, <? ... ?> emits raw C++.

• Inside a literal block, <?= expression ?> emits print(html_escape(expression));.

• Inside a literal block, <?: expression ?> emits print(expression); without HTML escaping.

• #load "other.uce" injects another UCE unit at compile time.

• RENDER(Request& context), COMPONENT(Request& context), CLI(Request& context), ONCE(Request& context), INIT(Request& context), and WS(Request& context) are normal C++ macros from src/lib/compiler.h.

• ONCE, RENDER, and COMPONENT may be followed by a preprocessor attribute line such as @fragment head before the opening {. The handler's output is then captured and appended to context.call["fragments"]["head"] instead of being emitted at the call site. ONCE defaults to @fragment once when no fragment is specified.

• COMPONENT:NAME(Request& context) is rewritten by the custom pass into an exported named component handler.

• EXPORT is also a normal C++ macro, but the custom pass additionally records exported declarations for metadata.

Pipeline

• The generated file starts by including the logical runtime header uce_lib.h; the wasm unit compile script provides the include path.

• It then inlines the configured setup template from SETUP_TEMPLATE (by default scripts/setup.h.template), which defines the internal hook __uce_set_current_request(Request*).

• It inserts #line 1 before page code so compiler diagnostics point back to the original .uce file.

• Each literal region is rewritten into one or more print(R"...( ... )..."); calls using a safe raw-string delimiter selected for that literal content.

• <> and ?> both switch from code mode into literal output.

• </> and <? both switch from literal output back into code mode.

• <? ... ?> temporarily breaks out of literal printing, emits the enclosed C++ unchanged, then resumes literal output.

• <?= ... ?> becomes print(html_escape(...));.

• <?: ... ?> becomes print(...); and is intended for trusted markup or already-escaped content.

• #load "file.uce" is replaced with a generated C++ #include that points at the loaded unit's preprocessed .cpp file under BIN_DIRECTORY.

• Lines beginning with EXPORT are scanned so their declarations can be written to a sibling .exports.txt file.

• @fragment slot-name lines immediately following ONCE, RENDER, or COMPONENT are removed and replaced with an output-capture guard at the start of the handler body.

• Lines beginning with RENDER:NAME(...) are rewritten into exported __uce_render_NAME(...) functions.

• Lines beginning with COMPONENT:NAME(...) are rewritten into exported __uce_component_NAME(...) functions for the component helpers.

• The final generated source is written to BIN_DIRECTORY + src_path + "/" + source_file + ".cpp".

• scripts/compile_wasm_unit then compiles that generated .cpp into source_file + ".wasm" as a PIC WebAssembly side module.

• When a worker instantiates the compiled unit, the runtime checks for INIT(Request& context) and calls it once for that worker-side instance.

• On each request, the first time a given unit is entered through RENDER(), CLI(), or any COMPONENT... handler, the runtime checks for ONCE(Request& context) and calls it before the selected handler.

Generated Files

For a source file like /some/path/page.uce, the preprocessor produces:

• generated C++: BIN_DIRECTORY/some/path/page.uce.cpp

• wasm side module: BIN_DIRECTORY/some/path/page.uce.wasm

• export list: BIN_DIRECTORY/some/path/page.uce.exports.txt

Examples

Literal output with escaped data:

The same thing can also be written with PHP-style literal delimiters:

Roughly becomes:

Literal output with trusted unescaped markup:

Roughly becomes:

Compile-time composition:

The loaded file is resolved relative to the current source file unless the path is already absolute.

One-time worker initialization plus request-local setup:

One-time page assets captured for a template-controlled slot:

The page template can then render context.call["fragments"]["head"] inside <head>.

Rules

• Literal mode can start on either <> or ?>.

• Literal mode can end on either </> or <?.

• Literal delimiters are interchangeable; the parser treats them as one shared code-vs-literal state machine rather than as separate nested block types.

• #load is recognized only when the current line starts with #load at column 1.

• EXPORT harvesting only triggers when the current line starts with EXPORT at column 1 and is followed by whitespace.

• Relative #load paths are expanded against the including unit's source directory.

• unit_render() and unit_call() are runtime APIs. #load is a compile-time composition feature.

• INIT() runs when the wasm unit is instantiated by a worker during a request-triggered load, so it still receives a valid Request& context.

• ONCE() is tracked per request and per resolved unit file. A file entered multiple times in one request only runs ONCE() once.

Limitations

• This pass is character-wise, not a full parser.

• Outside literal blocks it tracks C++ quotes and comments while deciding whether <> or ?> should open literal mode.

• It does not understand comments, raw string literals, templates, or general C++ token structure.

• Inside literal blocks it tracks quotes and comments while scanning <? ... ?>, <?= ... ?>, and <?: ... ?> islands so quoted ?> text does not close those islands early.

• Literal output is emitted through C++ string literals generated by the preprocessor. The preprocessor chooses a raw-string delimiter that does not occur in the literal content, so literal text may safely contain the ordinary raw-string terminator sequence )".

• #load depends on the target unit's generated .cpp existing and being compilable. If the target cannot be preprocessed or compiled correctly, the including file will fail to compile as well.

Debugging

• Inspect the generated file under BIN_DIRECTORY first. That file shows the exact C++ produced by the UCE preprocessor.

• Compiler errors usually point back to the .uce source because the preprocessor inserts #line 1, but the generated .cpp is still the best place to inspect expansion problems.

• Compile failures are reported with the source path, generated C++ path, compile-output artifact path, an excerpt when UCE can identify a line, and the raw compiler output from the configured compile script.

• Runtime request failures include the request/script path, generated C++ path, a hint about inspecting template delimiters and recent component/unit calls, and a native trace when available.

• If a #load include looks wrong, check the current file's directory, the configured BIN_DIRECTORY, and whether the loaded page already produced its own generated .cpp.

UCE is server-first C++ with a small template preprocessor. It does not try to be React, but several concepts map cleanly.

Concept Map

• RENDER(Request& context) is the page/server-render entrypoint.

• COMPONENT(Request& context) and COMPONENT:NAME(Request& context) are server-rendered components.

• context.props is the component invocation payload, similar to props.

• context.call is request-local scratch state shared across units during one request.

• context.cfg is structured app/config data.

• ONCE(Request& context) is per-request setup for a unit before its first render/component entry.

• INIT(Request& context) is worker-local setup when a unit is loaded.

• <?= expression ?> is escaped interpolation; prefer it for user-visible text.

• <?: expression ?> writes trusted raw markup, similar to dangerouslySetInnerHTML in React.

• unit_render() renders another page unit; component() returns component HTML as a string.

Routes and Layouts

UCE does not require a framework-level router. A front controller can keep routing explicit and app-local. The starter example demonstrates this in site/examples/uce-starter/index.uce: it resolves a request path by checking:

1. views/<path>.uce

2. views/<path>/index.uce

3. parent index handlers such as views/workspace/index.uce with the last segment as a route parameter

That keeps file-based and hierarchical routing in normal UCE code instead of hiding it in the runtime.

Data Shaping Near Render Code

The function library includes small collection helpers for common route/menu/card transformations:

Use these when a short transformation is clearer than a loop. Prefer explicit loops for side effects or multi-step validation.

Assets and Islands

UCE core does not provide a global asset or island registry. The starter emits CSS and JavaScript from the owning unit's ONCE(Request& context) hook, with a few shared sibling asset components when multiple components need the same files. The starter's COMPONENT:island helper in components/theme/web_affordances.uce covers small progressive-enhancement modules while keeping app policy in the app.

Debugging

When a unit fails to compile, UCE reports the source path, generated C++ path, compile-output artifact, a source/generated excerpt when it can identify a line, and the raw compiler output. The generated C++ under BIN_DIRECTORY is the source of truth for what the configured compiler actually saw.

What Not To Expect

• No client-side virtual DOM is built into UCE.

• No global file-router is imposed by the runtime.

• No JSX-like component tags are required for this workflow.

• Component children/slot syntax is not part of UCE yet; use explicit props and component calls for now.