Lua scripting reference¶

Every builtin the Lua script host registers, with its signature, parameters, and behaviour. The host runs Lua 5.4. For the task-oriented introduction see Scripting.

The same surface in the other hosts, under the same names: candela, rhai. 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 = "lua"   # "candela" (default) | "rhai" | "lua"

Reaching the builtins¶

Builtins are Lua globals; there is no import or require step.

function on_start()
    local count = signal("count", 0)
    count:set(1)
end

Handles (Signal, ArraySignal, Node, NodeQuery, Event) are userdata with methods, called with the colon form. The chained signals accessor works with either form, because the value is always the last argument: signals.count.set(5) and signals.count:set(5) both write 5.

Arrays follow Lua convention where the host builds them: ArraySignal:get(i), the numeric signals.users[i] subscript, and every returned sequence table are 1-indexed.

print(...) is captured into the script command stream instead of writing to stdout; arguments are joined with a tab.

Lifecycle hooks¶

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

Top-level statements run once when the script loads, so that is where handler functions and on(...) registrations are defined. A top-level local survives as an upvalue of any function that closes over it. Across a hot reload the signal values, the on(...) routing table, and live event bindings are preserved.

Event handlers¶

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

Per-element routing¶

on(event, id, handler)

Routes one (event, id) pair to the script function named handler (a string), 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.

Signals¶

Handles¶

signal(name, default)   -- -> Signal
signal_array(name)      -- -> ArraySignal

signal returns a handle to the named scalar signal, seeding it with default the first time that name is seen. A value pushed in before the script loaded wins over the default. signal_array returns a handle to the named reactive array that drives <for each="name">.

Rows are string-keyed tables; their fields become the values a <for> block binds to.

Chained access¶

signals is a pre-bound global. Each .name or [index] step extends the property path, and a terminal method commits:

signals.count.set(5)
signals.user.name.set("Alice")
signals.users[1].name.set("Bo")
signals.bg.set_color("#ff8800")
local n = signals.count.get()

The Lua type of the argument picks the stored type: an integer stores an integer, a number a float, a string a string, a boolean a boolean. Hex colours need the explicit set_color method. Index subscripts render as [N] in the property key, so signals.users[1].name is the key users[1].name.

Typed accessors¶

These predate the chained form and remain available.

Derived signals¶

derive(name, deps, f)   -- -> Signal

Registers a computed signal recomputed whenever any dependency changes. deps is a sequence of Signal handles or signal-name strings; f receives the dependency values in deps order and returns the new value:

local a = signal("a", 1)
local b = signal("b", 2)
local sum = derive("sum", { a, b }, function(a, b) return a + b end)

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 is retried on the next tick.

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.

function on_ready()
  request_frame()
end

function on_frame(dt)
  signals.angle = signals.angle + dt * 2.0
  request_frame()
end

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 is a cheap handle. Reads resolve against the snapshot rebuilt each tick, so a handle to a removed element stops resolving.

Mutate the element tree¶

Every mutator returns the receiver, so calls chain; read-backs end the chain. Mutations queue a command applied later in the same tick.

Read element state¶

Introspection¶

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

Element events¶

Bind a function to one element and one event type. Binding returns a function that unbinds when called.

local off = get_by_id("save"):on("click", function(e)
    e:prevent_default()
    print(e:event_type())
end)
-- later
off()

The handler receives an Event:

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.

window, document, history¶

Pre-bound global tables.

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¶

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 global 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¶

request is a table: url and tag are required; method defaults to "GET"; headers is a table of header name to value; body is a string; timeout_ms is a positive number.

response is a table of ok (true for a 2xx status), status (0 on a transport failure), headers (names lowercased), body, and error (empty on success).

Requests run off the UI thread; the reply is delivered on the tick thread, so a handler may touch signals and the element tree freely.

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.

Data helpers¶

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"] }

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 }

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 }

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:

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

function on_start()
  archive.extract("themes.zip", "themes", "themes")
end

function on_archive_done(tag, dest, count)
  signal("status", ""):set(count .. " files")
end

function on_archive_error(tag, message)
  signal("status", ""):set(message)
end

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 }

Every argument is required. 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.

function on_start()
  download.to_file("https://example.com/pack.zip", "cache/pack.zip", "pack", "")
end

function on_download_progress(tag, received, total)
  if total > 0 then
    signal("pack_progress", "0"):set(received * 100 // total)
  end
end

function on_download_done(tag, path) signal("pack_path", ""):set(path) end
function on_download_error(tag, message) print("pack failed: " .. message) end

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 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 }

args is a list of strings. 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 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.

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¶

Functions an embedder or a plugin registers appear as bare globals here, and one registered under a namespace of its own appears as a global table: gpio.level(21). A function registered with declared parameter types raises on a call whose arguments do not match; an untyped one takes whatever it is passed. See FFI and SDKs.

Reserved global¶

__lumen_event_handlers is the table the host keeps bound event handlers in, keyed by token. Do not write to it.