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:
local response = {data = {me = {user = {email = "a@b"}}}}
response.data?.me.user?.email --> "a@b"
local optionalList: any = nil
optionalList?[1] --> nilOnly 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:
- Reading an undefined global is an error. It doesn't give
nil, so typos fail loudly. - There are no iterators, coroutines, redefinable operators,
iooros. If you reach for one, this guide lists the alternative, or the thing genuinely can't be done. - 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). - Only what The standard library lists exists. The standard library is a closed set:
next,string.gmatchandmath.random, among others, aren't there. Don't assume a name is present because it's standard elsewhere.