On this page

Scripting

The language

This is the full reference for writing SwiftLua scripts. The language is a deliberate subset of Lua with defined behaviour; it is not "just Lua". Where Lua leaves behaviour unspecified, SwiftLua pins it down, and where a Lua feature would get in the way of safety or repeatable results, SwiftLua limits it or leaves it out. If you know Lua, read Differences from Lua first. New to scripting, or coming from JavaScript or TypeScript? Start with Getting started and come back here for the precise rules.

Scripts run inside CoCoCo, in a sandbox: a script can use exactly the input, ctx functions, libraries and stored Scripts CoCoCo gives it, and nothing else. Every run has limits (on instructions, call depth, memory, table sizes and string sizes) and stops at the same point every time one runs out.

In the examples, --> shows what a line produces, and --> error: … shows that it stops with an error saying so.

Safe navigation (dialect extension)

Use ?.field or ?[key] when a receiver may be nil:

LUA
local response = {data = {me = {user = {email = "a@b"}}}}
response.data?.me.user?.email  --> "a@b"
local optionalList: any = nil
optionalList?[1]              --> nil

Only nil short-circuits. The receiver is evaluated once; if it is nil, the result is nil and the rest of that continuous access chain is skipped, including computed keys, method lookups, calls and their arguments. For a non-nil receiver, ordinary indexing and metatable behaviour apply. false is not treated as nil. Errors from an executed lookup or call still propagate.

Each ? guards its own receiver. With a?.b.c, nil a skips both accesses, but a present a whose b is nil still errors at .c. Use a?.b?.c if both may be absent. Parentheses end the chain: (a?.b).c performs .c even when a?.b returned nil. Binary operators also end the chain; a?.b + 1 still attempts the addition, while a?.b or fallback uses the usual Lua fallback rule (which also replaces false).

The checker checks accesses against the non-nil receiver type and includes nil in the result when the receiver may be absent. Unknown fields and invalid index types remain errors. Safe chains cannot be assignment targets and always produce exactly one value, including when they end with a function call. A chain ending in a call may stand alone as a statement, for example receiver?.notify().

There is no ?() safe-call operator, ?: safe-method operator, or ?? operator. Each continuous chain allows at most 32 safe guards (Swift hosts may set a lower parser nesting limit). This syntax is shared by this dialect's Swift, Go and Rust engines; stock Lua and Luau do not accept it. Optional type annotations such as string? are unchanged.

Key points

If you take four things from this guide, take these:

  1. Reading an undefined global is an error. It doesn't give nil, so typos fail loudly.
  2. There are no iterators, coroutines, redefinable operators, io or os. If you reach for one, this guide lists the alternative, or the thing genuinely can't be done.
  3. Multiple returns follow Lua 5.1. A call in the last position of a list expands to all its values; write (f()) to keep just one (Functions and multiple returns).
  4. Only what The standard library lists exists. The standard library is a closed set: next, string.gmatch and math.random, among others, aren't there. Don't assume a name is present because it's standard elsewhere.