candela scripting reference¶

Every builtin the candela script host registers, with its signature, parameters, and behaviour. candela is Lumen's default script language; for the task-oriented introduction see Scripting. The candela language itself is documented separately at /candela/; this page covers only the Lumen surface.

The same surface in the other hosts, under the same names: rhai, lua. One structural difference shapes those names: a candela host function is keyed by name alone and cannot be overloaded on arity, so a call with two forms gets two names on every host: page(path) and page_current(), computed_style(prop) and computed_style_all().

Selecting the host¶

Each script file picks its host from its own extension: .cdl runs under candela, .lua under Lua, .rhai under Rhai. Files of one language combine into a single program; an app that ships two languages runs both hosts, sharing signals but not functions.

An inline <script> block has no extension. It joins the app's one external language when there is exactly one, and candela otherwise.

lumen.toml overrides all of it and puts every script on one engine:

[script]
engine = "candela"   # "candela" (default) | "rhai" | "lua"

Reaching the builtins¶

candela resolves host functions through a typed host "lumen" { ... } block. One import line declares the whole Lumen surface:

import "lumen.cdl";

fn on_start() {
    lumen::signal_set("greeting", "hi");
}

fn main() {}

The import is replaced with the declarations before compilation, so no lumen.cdl file is read from disk. Without the import (or a hand-written host block), the source still compiles, and calling a builtin fails at run time:

lumen::signal_set: the `lumen` builtins are not declared here; add `import "lumen.cdl";`

A call to a name the namespace does not have reads differently. The import is in place; the function is not on the surface, and where the same name lives in a namespace the app can reach, the message names it:

the `lumen` namespace has no `read_file` (called as `lumen::read_file`)
the `lumen` namespace has no `data_dir` (called as `lumen::data_dir`); `files::data_dir` exists

Both surface at load for any function candela can type from that function's own declaration, which is every handler whose parameters are annotated and every function that takes none. A handler with a bare parameter is compiled by the first call that reaches it, and reports there instead.

Write the import in every .cdl file that uses the surface. An app's candela files join into one program and the declarations land once for the whole program, so a repeated import costs nothing.

The prelude also declares the window, document, and history namespaces and defines the Node, Event, Signal<T>, and ArraySignal method wrappers described below, plus the Color record a color signal reads back as.

Types in signatures are candela types: int, float, bool, string, arrays (int[]), and maps ({string: float}). A builtin with no return type returns null.

Dynamically-shaped builtins¶

A few builtins carry a value with no single concrete type: an array signal's records, an http request, a parse_json result. Those are declared with a ... argument list and, where they return a value, the any return type. The tables below give what each one takes and returns; the prelude declares them, so an app calls them like any other builtin.

Read an any result with candela's as_map, as_list, as_str, as_int, as_float, and as_bool downcasts, and test it with is_map, is_list, is_null, and their siblings.

A downcast collection keeps its entries typed any, which is what a parsed document needs: as_map and as_list hand back a collection that takes an insert or a push of any type, in any order, with no wrapper function in between. The same goes the other way, so an entry read back out is an any and needs its own downcast before you use it.

Writing arguments¶

Two candela rules shape how you write a call. Each has the same remedy: bind the value to a variable first.

• A map literal holds one value type. {"id": "a", "n": 1} is rejected; write {"id": "a", "n": "1"}, or build the value from parse_json.
• A builtin call nested inside another builtin's argument list mislays its arguments.

let rows = signal_array("rows");
let row = {"id": "a", "title": "First"};
rows.push(row);
lumen::signal_array_push("rows", {"id": "b"});   // literal straight to a builtin

let n = lumen::signal_array_len("rows");         // not nested in the next call
signal<int>("row_count").set(n);

The candela standard library¶

The toolchain carries candela's own standard library, so a script imports a module by name and gets the functions the candela documentation describes:

import "std/time";

fn on_start() {
    lumen::signal_set("started", str(now()));
}

fn main() {}

The array methods (arr.map(f), arr.sum(), and the rest) come from std/list, which the compiler loads whether or not a program imports anything.

The modules are read from disk when the program compiles, out of a libs/ directory beside the running executable. lumenc package copies that directory into the folder it writes, so a shipped app resolves the same imports. A web build compiles ahead of time, so the text modules travel into the browser inside the compiled image; std/math, std/random, and std/time bind a C library the browser cannot open, and an image naming one is refused whole.

Lifecycle hooks¶

Define these as free functions. Each is optional; a missing hook is a no-op.

Across a hot reload the signal values, the on(...) routing table, and live event bindings are preserved; the recompiled program picks them up.

Event handlers¶

Each event dispatches to a global handler function named below. Handlers are optional.

Annotate a handler's parameters with the types the table gives:

fn on_toggle(id: string, checked: bool) { }

Running from source works either way, because the compiler takes a bare parameter's type from the first call. A compiled app has no compiler to do that, so it records a call trampoline for each handler at build time and only records one for a handler in the app's own script file whose parameters are all annotated. A handler left bare compiles, ships, and is then never called, and so is one an imported script library declares, whatever it annotates: write the handlers in the app's own file.

Annotation is also what puts the handler's body in front of lumenc check. Nothing in the script calls a handler, so the declared types are the only ones its body can be compiled at ahead of the event: check and build compile the body of every handler that annotates its parameters and report a mistake in it the way they report one in main. A bare parameter defers that to the first event, which is where the error then appears, as a runtime failure of the handler.

Per-element routing¶

lumen::on(event: string, id: string, handler: string)

Routes one (event, id) pair to the script function named handler, bypassing the global handler for that pair only. event is the name without the on_ prefix ("click", "toggle", "timer", "file_picked", ...). A handler registered for save also matches template-instance ids ending in :save.

The routed function takes what the global handler takes, so a click route is fn handle_save(id: string) and a toggle route is fn handle_flag(id: string, checked: bool). Annotate it the same way.

lumen::local_id(source: string, suffix: string) -> string

Returns the id of the sibling suffix inside the same template instance as source: local_id("user-card:save", "status") is "user-card:status". A source with no instance prefix returns suffix unchanged. Use it inside a handler to reach the other elements of the instance that fired it.

Signals¶

Signals are the named reactive cells markup binds to with bind-text and friends.

The four typed setters are the marshalling layer the signal handle below calls; reach for the handle instead, which carries the type once instead of in every call name.

A getter converts across the scalar types: an integer cell read through signal_get_float yields the same number as a float, and a string cell parses.

A color signal is a typed cell, not a string: CSS reads it as a color, so writing "#ff8800" to accent recolors everything bound to accent.

The signal handle¶

signal<T>(name) is the spelling to reach for. The type argument says what the cell holds, and that is what makes one get / set pair enough: get returns that type and set takes it.

import "lumen.cdl";

fn on_start() {
    signal<int>("clicks").set(0);
}

fn bump(ev: int) {
    let clicks = signal<int>("clicks");
    clicks.set(clicks.get() + 1);
}

fn main() {}

The handle holds only the name and calls the builtins above, so it reaches the same cells they do. There is no default value: seed a cell by writing it once.

Write the type argument wherever the cell's type is known: it is what makes get hand back that type and set take it. A bare signal("clicks") pins nothing, and a type parameter nothing pins is any, so it is the same handle as signal<any>("clicks"): reads come back as any and writes go through the string sink. That is the form for a cell whose type is not fixed.

Array signals¶

An array signal is the reactive list <for each="name"> renders, one element per record. A record is a string-keyed map whose fields <for> binds by name; an item that is not a map is carried as a one-field value record.

signal_array(name) wraps the name so the same calls read as methods:

import "lumen.cdl";

fn on_start() {
    let rows = signal_array("rows");
    let first = {"id": "a", "title": "Alpha"};
    rows.push(first);
    let back = as_map(rows.get(0));
}

fn main() {}

Methods: set, push, get, all, len, remove, clear.

Field values are stringified on the way into the rendered row, so a record built from a map literal carries strings. A record from parse_json, a response body, or the host side keeps every field's own type when you read it back with signal_array_get.

Validation state¶

lumen::is_valid(id: string) -> bool

Whether the element with that id currently passes validation. The runtime writes the backing valid:<id> signal each tick from the element's validation rules; an element that carries none reads as valid.

Derived signals¶

lumen::derive(name: string, deps: string[], f: string)

Registers a computed signal name, recomputed by the script function named f whenever any signal in deps changes. f receives the dependency values in deps order and returns the new value. A host function takes only the values that marshal across the boundary, and a candela function is not one of them, so the recompute body is referenced by name rather than passed.

Declare each parameter as the type the cell holds, or as any. A cell written through signal<int> arrives as an int, signal<float> as a float, signal<bool> as a bool, and signal<string> as a string; the conversions a getter performs do not apply here, so fn f(n: float) on an int cell is a type error. any takes whatever the cell holds and is the safe choice when a signal's type is not fixed:

fn calc_label(n: any) {
    return "clicks: " + str(n);
}

A derivation runs once after registration, then on every change to a dependency. Derived-of-derived chains settle within the same tick. A derivation that errors, including an internal engine crash mid-evaluation, is contained the same way a failed call is: the app keeps running, that one recompute is skipped, and the derivation is retried on the next tick, so a parameter type that never matches fails and logs on every tick for the life of the app.

Timers¶

Timer names are unique: setting a timer with an existing name replaces it. Negative delays clamp to zero. Cancelling from inside the timer's own handler takes effect before the next fire.

Frame callbacks¶

One request buys one callback. A handler that wants to keep animating asks again from inside itself, and an animation that is finished simply stops asking, which parks the app. dt is the seconds since the previous callback, capped so a stalled tick slows an animation instead of teleporting it, and zero on the frame that starts a loop because no interval has passed yet.

fn on_ready() {
    lumen::request_frame();
}

fn on_frame(dt: float) {
    let angle = signal<float>("angle");
    angle.set(angle.get() + dt * 2.0);
    lumen::request_frame();
}

Use this rather than a repeating timer for anything visual: a timer fires on a wall-clock schedule that has nothing to do with when the app draws.

Query and traverse the element tree¶

Node handles are int ids; 0 means "no node". Reads resolve against the snapshot rebuilt each tick, so a handle to a removed element reads as invalid.

Mutate the element tree¶

Mutations queue a command applied later in the same tick.

Markup blocks¶

An lmn!( ... ) block is markup a candela function returns. It compiles to a fragment when the app is built, and the call instantiates that fragment, so a running app parses no markup. For what goes inside a block and how components compose, see composition.

The block itself is the surface to write against:

fn Home(name: string) {
    return lmn!(<label class="home" text="home for $name"/>);
}

fn on_ready() {
    lumen::mount(Home("bob"));
}

fn main() {}

A block obeys three rules the compiler enforces:

• One root element. A call returns one node.
• Arguments are static. $name substitutes once, when the instance is built. Something that changes while the app runs is a bind-* attribute inside the block.
• A handle is valid for the tick it was minted in. Attach what a component returns before the tick ends, the same as a node_spawn handle.

A component element inside a block is a use site, not a call: the build resolves it against the component it names. Where that component returns its block and nothing else, and reads only its own parameters, the block is put in the tree at build time. Where it works a value out or picks between blocks, the build leaves a marker and the runtime fills it by calling the function on the first tick, before the tree is drawn. A .lmn file writes the same element and means the same thing; see composition.

lumenc check and lumenc build both read every block in the app's scripts, so a malformed one fails ahead of the run.

Read element state¶

Introspection¶

The introspectable components are LayoutBox, Visuals, Opacity, ZIndex, Visible, TextContent, LumenClasses, LumenAttributes, InlineStyle, and Style.

Element events¶

Bind a handler to one element and one event type. Binding returns a token; pass it to event_off to unbind.

The handler takes one parameter, the event id, for every event type: fn handle_click(ev: int). Annotate it the same way, and read the event through the accessors below:

Event types¶

click, dblclick, pointerdown, pointerup, pointermove, pointerenter, pointerleave, wheel, keydown, keyup, input, change, focus, blur, submit, scroll.

Dispatch runs capture (root down to the target), then the target, then bubble (target up to the root). focus, blur, pointerenter, pointerleave, and scroll do not bubble.

input fires per keystroke: every edit that changes the text raises one, carrying the buffer as it stands after that edit. A caret move raises nothing. change and submit come from the commit signal instead, so they fire when the field is committed with Enter. Only click has a default action (link navigation); prevent_default on a click skips it.

Method sugar¶

The prelude wraps a raw handle in a Node or Event struct so calls read as methods. The free functions above keep working on raw handles.

import "lumen.cdl";

fn on_ready() {
    let list = get_by_id("list");
    let row = create("row");
    row.add_class("item");
    row.set_text("hello");
    list.append(row);
    row.on("click", "handle_row");
}

fn handle_row(ev: int) {
    let e = event(ev);
    e.prevent_default();
}

fn main() {}

Constructors: node(handle), event(handle), wrap_nodes(handles), create(tag), get_by_id(id), document_node(), query(selector).

Node methods mirror the node_* builtins with the prefix dropped, except for the class calls and the whole-map style read, which carry the DOM-style names every host uses: exists, valid, parent, first_child, last_child, next, prev, children, closest, clone_deep, set_attr, remove_attr, set_id, set_text, set_inner_markup, add_class, remove_class, toggle_class, set_class, set_style, style_remove, remove, append, insert_before, set_parent, move_to, replace_with, get_attr, text, id, has_class, style_get, computed_style, computed_style_all, is_visible, z_index, classes, components, outer_markup, inner_markup, on, on_capture. exists() tests the handle against 0; valid() tests it against the current snapshot.

ArraySignal methods mirror the signal_array_* builtins with the prefix dropped: set, push, get, all, len, remove, clear. Construct one with signal_array(name).

Signal<T> has one pair, get and set, and the type argument picks which builtin each reaches. Construct one with signal<int>(name) and its siblings; the table under Signals lists what each type argument reads and writes.

Event methods: target, current_target, event_type, key, value, button, x, y, client_x, client_y, delta_x, delta_y, shift, ctrl, alt, super_key, prevent_default, stop_propagation, stop_immediate_propagation, off.

One more helper builds a list row in a single call:

lm_append(parent, tag, cls, text) -> int

It creates a tag element, applies cls and text when they are non-empty, appends the result under parent, and returns the new handle.

window, document, history¶

Each is its own host namespace, declared by the same prelude import.

Page navigation¶

See Pages for the file layout these paths resolve against.

Dialogs¶

Each opens a native dialog and delivers the result to the matching handler, keyed by tag. A cancelled dialog still fires once, with an empty path.

OS integration¶

See OS integration for the markup these pair with.

Styling and theming¶

lumen::set_class takes an element id and Node.set_class takes none because it already has the element. They share a name and do the same thing through different routes: reach for the free function when all you have is an id, and the method when you are holding a handle.

Audio¶

These functions come from the lumen-audio runtime module and exist only when the app declares it under [dependencies] in lumen.toml; see OS integration.

The module writes the audio_position, audio_duration, and audio_playing signals each tick, so markup binds to them directly.

Networking¶

lumen::fetch(url: string, tag: string)

Issues an HTTP GET without holding up a tick. A 2xx reply fires on_fetch(tag, body); a transport failure or non-2xx fires on_fetch_error(tag, message). The reply is delivered on the tick thread, so a handler may touch signals and the element tree freely.

lumen::http(request: any)

Issues any HTTP request. The request is a map; only url and tag are required. method defaults to GET, and body and timeout_ms are optional. Each header rides on a header:<Name> key, because a candela map literal holds one value type:

lumen::http({
    "method": "POST",
    "url": "https://example.test/items",
    "header:Content-Type": "application/json",
    "body": "{\"title\":\"First\"}",
    "timeout_ms": "2500",
    "tag": "create"
});

A request built from parse_json or handed in from the host may instead carry a nested headers map and an integer timeout_ms; both forms are accepted.

Every completed request fires on_http(tag, response), including a 4xx or 5xx. The response is a map:

fn on_http(tag: string, response: any) {
    let r = as_map(response);
    if as_bool(r.get("ok")) {
        lumen::signal_set("status", as_str(r.get("body")));
    }
}

Request and response¶

The readers give back what arrived with the request the document is being rendered for, and an empty string when there is none to read; a desktop app has none. The three writers queue an answer that only a server render applies.

Parsing¶

parse_json returns candela values, not text, so numbers stay numbers and nesting survives:

let root = as_map(lumen::parse_json(body));
let geo = as_map(root.get("geo"));
let city = as_str(geo.get("city_name"));

candela's own json_parse builtin parses JSON too. Prefer lumen::parse_json: it interns the keys it produces, so a key longer than six characters is still reachable with map.get(...).

A parse_markdown block record carries id, kind, level, text, and lang. kind is h, p, code, li, or hr; level is the heading depth and 0 elsewhere; lang is the code fence's language and empty elsewhere. Feed the list straight to an array signal to render a document with <for>. Inline emphasis keeps its markdown delimiters in text, since a label renders plain text.

Translation¶

See Translation and formatting for the catalogue format.

Formatting¶

A trailing zone on a timestamp (Z, +02:00) is read and dropped; nothing is converted between time zones. A value the call cannot read comes back as it was given, the way t returns an untranslated key.

See Translation and formatting for the markup attribute that formats an element's text.

Canvas¶

These functions come from the lumen-canvas runtime module and exist only when the app declares it under [dependencies] in lumen.toml, along with the tag it brings:

[dependencies]
lumen-canvas = { bundled = true, tags = ["canvas"] }

They live in their own canvas namespace, so no import line reaches them: the host declares the namespace from what the module registered.

Every call names a canvas by the id on its <canvas> element. Colours are components in 0..1, angles are radians, and coordinates are canvas units, which are scaled onto the element's box whenever layout gives it one the declaration did not ask for.

A path is stored in canvas units and placed by the transform at the moment it is filled or stroked, so changing the transform between building a path and filling it moves the result. The HTML canvas bakes the transform into each segment as it is added; this is the one place the two differ.

Pixel buffers¶

A canvas is write-only: what it holds is a list of drawing calls bound for the GPU, not an image, so there is nothing to read a pixel back from. Buffers are the read-write half - plain CPU pixels a script creates, edits, loads from a PNG, saves to one, and draws onto a canvas. A pixel is one packed 0xRRGGBBAA integer with straight (not premultiplied) alpha, so what a script writes is what it reads back.

Three settings bound what one call may ask for, from the module's config table: region_cap (pixels in one region call), buffer_pixel_cap (pixels in one buffer), and buffer_count_cap (buffers at once). A call over a cap answers empty or 0 and says why on stderr.

Refusals never raise. An unknown canvas id keeps the drawing, in case the element has not been mounted yet, and reports once if no element ever matches; an unknown buffer handle reads as an empty buffer. See <canvas> for the element, its sizing, and what is not implemented yet.

Filesystem¶

These functions come from the lumen-fs runtime module and exist only when the app declares it under [dependencies] in lumen.toml:

[dependencies]
lumen-fs = { bundled = true }

They live in their own files namespace, so no import line reaches them: the host declares the namespace from what the module registered.

candela ships a filesystem library of its own under fs, which is a different surface: it resolves a path against the process working directory and raises on failure. The module's files functions resolve against the app and report instead.

A relative path names a file the app ships, so it reads the same wherever the app was started from; an absolute path is left alone. Saved state goes under files::data_dir() instead, because the app directory is read-only once the app is installed:

files::write(files::data_dir() + "/session.json", state);

data_dir() follows the platform convention for user data ($XDG_DATA_HOME, else ~/.local/share, on Linux; ~/Library/Application Support on macOS; %APPDATA% on Windows) and names one directory per app from [app] id, so two apps on a machine keep their saves apart.

A call that cannot do what it was asked answers false or an empty value and prints one lumen-fs: line on stderr, so a script branches on the value it got back. Two cases stay silent, because probing for state that has not been saved yet is ordinary: reading a file that is not there, and removing one.

files::read_bytes reads up to 8 MiB by default. Raise or lower it with the module's read_bytes_cap setting, in bytes, between 1 KiB and 256 MiB:

[dependencies]
lumen-fs = { bundled = true, config = { read_bytes_cap = 33554432 } }

On Windows nothing loads a module beside the executable, so this surface exists only in a lumenc package --static build, which compiles the declared modules in.

Archives¶

These functions come from the lumen-archive runtime module and exist only when the app declares it under [dependencies] in lumen.toml:

[dependencies]
lumen-archive = { bundled = true }

They live in their own archive namespace, so no import line reaches them: the host declares the namespace from what the module registered.

Both paths resolve against the app directory, and the extraction runs off the tick loop, so the call answers before any bytes are read. The outcome arrives as an event keyed by tag:

lumen::on("archive_done", tag, fn_name) registers a handler for one job and wins over the fallback, the same as any other event.

fn on_start() {
    archive::extract("themes.zip", "themes", "themes");
}

fn on_archive_done(tag: string, dest: string, count: int) {
    signal<int>("files").set(count);
}

fn on_archive_error(tag: string, message: string) {
    lumen::signal_set("status", message);
}

zip, tar, and gzip-compressed tar are read. The container is taken from the file's leading bytes, so an archive saved under a name that disagrees with its contents still unpacks; the extension decides only when the bytes say nothing.

What an archive may write is settled before anything is written. An entry naming an absolute path, climbing out with .., carrying a Windows drive or UNC prefix, or resolving outside dest ends the whole extraction with an archive_error naming it, rather than being passed over. Entries written before the refused one stay on disk, so a destination that took a failed extraction is one to discard rather than keep using. Symbolic and hard links are skipped, because a link inside the destination can point outside it once extraction is over; count is the files written, so it leaves them out. Existing files are overwritten and missing parent directories are created.

Four extractions run at once by default; a fifth is refused until one finishes, as is a second job under a tag already running. Change the limit with the module's max_concurrent setting:

[dependencies]
lumen-archive = { bundled = true, config = { max_concurrent = 2 } }

Selecting part of an archive, stripping leading path components, per-entry progress, listing an archive without unpacking it, and writing an archive are not part of this surface.

On Windows nothing loads a module beside the executable, so this surface exists only in a lumenc package --static build, which compiles the declared modules in.

Downloads¶

This function comes from the lumen-download runtime module and exists only when the app declares it under [dependencies] in lumen.toml:

[dependencies]
lumen-download = { bundled = true }

It lives in its own download namespace, so no import line reaches it: the host declares the namespace from what the module registered.

Every argument is required, which is what keeps the call typed; there is no shorter form that omits the checksum. checksum is sha256: followed by 64 hex digits, sha1: followed by 40, a bare hex string of either length, or an empty string to check nothing; neither the prefix nor the digits are case sensitive. Any other spelling fails the call. sha1 is accepted because it is what most package and artifact registries publish, and the digest here checks a file against a corrupt transfer rather than standing in for a signature.

The call answers as soon as the transfer starts, and the transfer reports through three handlers keyed by the tag it was given:

A per-tag on("download_done", tag, handler) registration wins over the fallback, the same routing every event gets.

Every refusal arrives as download_error under the tag the call named, and the call itself answers false.

fn on_start() {
    download::to_file("https://example.com/pack.zip", "cache/pack.zip", "pack", "");
}

fn on_download_progress(tag: string, received: int, total: int) {
    if total > 0 {
        signal<int>("pack_progress").set(received * 100 / total);
    }
}

fn on_download_done(tag: string, path: string) {
    lumen::signal_set("pack_path", path);
}

fn on_download_error(tag: string, message: string) {
    lumen::print("pack failed: " + message);
}

A relative path names a file beside the app and an absolute one is left alone, the way every app path resolves; directories that do not exist yet are created on the way. The bytes land in a sibling temp file and are renamed into place only once the body has finished and the checksum has verified, so the destination never holds a half file and a failed transfer never replaces what was already there.

Progress is reported at most ten times a second per tag, so a handler that writes a signal cannot become the transfer's bottleneck, and once more with the final count just before the done handler runs.

A reply that is not 2xx fails the download, which is where this parts company with lumen::fetch: fetch hands a script whatever came back so it can branch on the status, and a download that did not get the file has nothing to write.

Redirects are followed, up to ten in a chain, and an https URL is verified against the bundled web-PKI roots.

Three settings, all optional:

[dependencies]
lumen-download = { bundled = true, config = { timeout_ms = 15000, max_concurrent = 2 } }

One tag means one download: a call naming a tag that is already downloading is refused rather than replacing the transfer under way, because both would report under the same key. A call with no tag has nowhere to report, so it answers false and prints one lumen-download: line on stderr.

On Windows nothing loads a module beside the executable, so this surface exists only in a lumenc package --static build, which compiles the declared modules in.

Processes¶

These functions come from the lumen-process runtime module and exist only when the app declares it under [dependencies] in lumen.toml:

[dependencies]
lumen-process = { bundled = true }

They live in their own process namespace, so no import line reaches them: the host declares the namespace from what the module registered.

A cmd with a path separator in it names a program the app ships and resolves against the app directory; a bare cmd is looked up on PATH. The child runs in the app directory, reads end of file from its input, and has both its output streams captured.

The call answers as soon as the program is running. Everything after that arrives as an event carrying the tag, so one handler serves several children:

A per-child lumen::on("process_exit", tag, handler) registration wins over the fallback, like every other event.

process_exit is always the last event for a tag. Its code is the program's own exit code, 128 plus the signal that killed it on Unix, or -1 for an ending the system does not describe.

A line is what the program wrote before a newline; the newline is not part of it, and the last stretch before the program ends is a line even without one. Bytes that are not utf-8 are replaced, and a line longer than 64 KiB arrives in pieces. There is one handler call per line, so a chatty program calls the handler a lot.

A program that cannot start answers false and prints one lumen-process: line on stderr. It fires no event at all, because the tag never named a running program, so branch on the value the call gave back rather than waiting for an exit that never comes.

There is no way to write to a child's input, no way to end a child from a script, and no per-child environment or working directory. A child is not ended when the app exits: a program still running outlives the app that started it.

On Windows nothing loads a module beside the executable, so this surface exists only in a lumenc package --static build, which compiles the declared modules in.

Diagnostics¶

lumen::print(args: any)

Stringifies its arguments, joins them with a space, and emits the line through the script command stream, where lumenc run prints it prefixed with [script]. candela's own print writes to process stdout instead and bypasses that stream.

Embedder commands¶

Two builtins emit a command with no built-in effect under lumenc run. They exist for embedders that read the script command stream directly.

Two more write directly to the element tree by id, without a node handle:

Native functions from the embedder¶

An embedder exposes its own functions to the app's script: over the C ABI with lumen_app_expose (see C ABI), from Rust with the SDK, or from a Rust plugin. Call them by namespace:

fn on_start() {
    let t = native::now_ms();
    print(as_int(t));
}

Functions the C ABI and the SDK expose land in the native namespace. A plugin can choose a name of its own instead, and the script calls it there (gpio::level(21)).

You do not declare them. candela resolves a host call through a host "<ns>" { .. } block, and the host writes one for every namespace it bound from the signatures it was given. A script that spells the block itself keeps it: the host leaves a namespace the source already declares alone, so an app written against an earlier release compiles unchanged.

A function described with parameter and return types is declared with them, whatever those types are, and the result is typed as declared, so it composes with operators the way a value of that type does. A call passing the wrong types or the wrong number of arguments is refused when it runs, naming the parameter.

A function with an untyped parameter, a variadic argument list, or an optional trailing argument has no such spelling: it is declared any name(...), takes any arguments, and returns any. Read that result with the as_int / as_str / as_map downcasts, the same way a parse_json result is read.

The name is the plugin's to choose, including one candela's own library uses: a namespaced call takes its type from the block that declares it.

A native function may fail. It raises where it was called, under the kind host_fn_error and naming the function, so a script handles one the way it handles any other runtime error:

fn level(pin: int) {
    try {
        return gpio::read(pin);
    } catch "host_fn_error" {
        return -1;
    }
}

A plugin can also ship candela source of its own, compiled ahead of the app, to offer method syntax over its functions. What that looks like is the plugin's choice; pin(21).level() in place of gpio::level(21) is the shape to expect.

Two things follow from where the declarations come from. An app calling a function nothing registered fails the compile, naming it, so lumenc check and lumenc run reject a call meant for an embedder they do not carry. And a .cdlb build gets the same synthesized declarations a live compile gets, from whatever was registered on the host before it compiled; lumenc build does not register a plugin or a runtime module before it compiles your script's .cdlb, so write the host block by hand in a script you will build to an artifact, exactly as you would for an embedder lumenc does not carry.

At the artifact's own load, a declaration with no closure behind it fails the load and names the function, rather than the call silently doing nothing. That is what happens when the app was built against a plugin or module that is not installed where it runs.

Rhai and Lua receive the same functions as plain globals (now_ms()), or as a module or table for a named namespace, because neither needs a declaration to resolve a call.