Compiler · syntax workshop
Make room for your notation
A full guide to Nelua's file-local syntax extensions.
Start with the opt-in library, compose a project pack, then build your own grammar rules. Every form becomes ordinary Nelua before type checking.
Extend the language one file at a time. Load a ready-made syntax module, combine a pack, or write grammar rules that turn your own notation into ordinary Nelua. The type checker, ownership checks and C generator continue to do their usual work. There is no extension interpreter in the resulting program.
Start here
Use the complete pack for exploration, or load only the modules your file uses:
#syntax 'syntax.all'
require 'string'
local double = fn(x: integer) => x * 2
local n = 1_000
times 3 do n += 1 end
print($"{n |> double}: {choose n > 1_000 then 'grown' else 'same' end}")
-- 2006: grown
assert(n == 1003)
#syntax runs during parsing and affects the rest of its source file. Put it
between top-level statements. A required file enables its own syntax; enabling a
module in a library does not enable it for that library's callers. Nothing is
enabled implicitly in ordinary upstream-compatible source files.
Run the complete tour with ./nelua examples/syntax_tour.nelua from the compiler
checkout. Its source is in
examples/syntax_tour.nelua.
Choose your modules
| Module | Adds | Lowers to |
|---|---|---|
syntax.compound |
x += 1, a[i] *= 2 |
Assignments, with a temporary pointer for complex targets |
syntax.pipe |
`x | > f(a) |
syntax.interp |
$"hello {name}, {n:%04d}" |
String literals, concatenation, tostring, string.format |
syntax.control |
unless, until … do, guard, loop, times |
if, while, numeric for |
syntax.choose |
choose test then a else b end |
A do expression containing if and in |
syntax.lambda |
fn(x) => expr, fn(x) do … end |
An anonymous function |
syntax.let |
let {x, y = other} = value, let [a, _, c] = value |
One source temporary and local declarations |
syntax.using |
using name = value do … end |
A scoped local with <close> |
syntax.collect |
collect(T; i = lo, hi when test => value) |
A vector(T), a loop, an optional if, and push |
syntax.literals |
1_000, b"1010_0101", hex"de ad be ef" |
Number and string literals |
syntax.operators |
**, !=, &&, ` |
syntax.all loads all the modules above. Loading a module again is a no-op in
that file, including when two packs share it. It does not add require 'string'
or require 'vector': runtime dependencies remain explicit.
Compound assignment
#syntax 'syntax.compound'
local n = 10
n += 2
n *= 3
n //= 4
assert(n == 9)
local data: [2]integer = {5, 6}
local calls = 0
local function index() calls = calls + 1 return 0 end
data[index()] += 7
assert(data[0] == 12 and calls == 1)
Supported spellings are += -= *= /= //= %= ^= ..= |= &= <<= >>=. Here ^=
means power, as ^ does in Nelua. ~= keeps its existing meaning, not-equal.
There is no xor-assignment spelling. The operator module does not add **=.
A complex target such as data[index()] is addressed once through a temporary
pointer, before the assignment. Simple names, fields, and constant or plain-name
indexes use the ordinary target = target op value rewrite. They therefore keep
the native assignment rules, including ownership restrictions and any changes
to an index variable caused by the right-hand side.
Pipe calls
#syntax 'syntax.pipe'
local function add(a: integer, b: integer) return a + b end
local function twice(a: integer) return a * 2 end
local result = 3 |> add(4) |> twice
assert(result == 14)
x |> f becomes f(x). x |> f(a, b) becomes f(x, a, b), and
x |> object:method(a) becomes object:method(x, a). The right side must be a
function name, field, or call. The left expression appears once in the result.
It is not a placeholder-based pipeline, and it does not implicitly move an owned
variable.
Pipes group left at the bitwise-or level: arithmetic binds more tightly, comparisons less tightly. Write parentheses around a larger boolean or comparison that you want to pipe. Generated calls follow native argument evaluation rules; use separate local declarations to sequence side effects in multiple arguments.
Interpolated strings
#syntax 'syntax.interp'
#syntax 'syntax.pipe'
require 'string'
local name, n = 'world', 3
local function twice(x: integer) return x * 2 end
local greeting = $"hello {name}, {n + 1} times"
local formatted = $"{{count}} {n:%04d}, doubled {n |> twice}"
assert(greeting == 'hello world, 4 times')
assert(formatted == '{count} 0003, doubled 6')
{expression} calls tostring; {expression:%format} calls string.format.
Only a top-level colon followed by % starts a format, so method calls such as
{name:upper()} work. {{ and }} produce literal braces. Ordinary string
escapes, quoted strings inside expressions, nested braces and nested interpolated
strings are supported. Embedded expressions use the grammar active at the string's
position, including pipes and your own extensions.
$" must be adjacent. $ pointer remains dereference. Interpolation can allocate
strings, just as its generated concatenation and formatting calls can. Separate
side effects into statements when their order matters. Empty expressions,
unclosed expressions and an unmatched single } produce compile errors.
Control flow
#syntax 'syntax.control'
local total = 0
times 4 as i: integer do
if i == 2 then continue end
total = total + i
end
assert(total == 8)
until total >= 10 do total = total + 1 end
unless total > 10 then total = 20 else total = 30 end
loop do
total = total + 1
if total == 22 then break end
end
local function positive(n: integer): boolean
guard n > 0 else return false end
return true
end
assert(total == 22 and positive(total) and not positive(0))
repeat total = total - 1 until total == 20
assert(total == 20)
unless condition then … [else …] end tests the negated condition.
until condition do … end is a pre-test loop equivalent to while not condition;
ordinary repeat … until condition still works and remains a post-test loop.
loop do … end is while true.
guard condition else … end runs its block when the condition is false. It does
not insert a return or require the block to exit; write return, break, or
continue when that is your intent.
times count [as index] do … end is a numeric for from one through count.
The count is evaluated once on entry. Zero and negative integer counts run no
iterations. An explicit index accepts the normal declaration type and annotations;
an omitted index gets a generated name. Count and index types follow native
numeric-for rules. break and continue target this loop as usual.
The new words are contextual. You can still declare variables named guard,
times, unless, or loop, and call functions with those names.
Conditional expressions
#syntax 'syntax.choose'
local calls = 0
local function expensive(): integer calls = calls + 1 return 99 end
local condition = true
local n = choose condition then 42 else expensive() end
local flag = choose condition then false else true end
local nested = choose condition then choose false then 1 else 7 end else 0 end
assert(n == 42 and flag == false and nested == 7 and calls == 0)
Only the selected branch runs, and the condition runs once. A selected false,
nil, or nilptr is preserved; this is not an and/or fallback idiom. Both
branches are still analyzed and must satisfy the normal type rules for a do
expression. It is an expression form: use if when you need statements in a branch.
Concise functions and closures
#syntax 'syntax.lambda'
local function make_adder(offset: integer)
return fn(x: integer): integer => x + offset
end
local add = make_adder(10)
local half = fn(x: integer) do
local result = x // 2
return result
end
assert(add(2) == 12 and half(8) == 4)
do
local total = 0
local bump = fn(x: integer) <byref> => (do total = total + x in total end)
local first = bump(3)
local second = bump(4)
assert(first == 3 and second == 7 and total == 7)
end
The parameter list, optional : returntype, and optional function annotations
are the same as for function. => expression becomes return expression;
do … end uses its statements as the function body. Use a block for multiple
returns or early exits. Parenthesize the whole concise function if you need to
call it immediately: (fn(x: integer) => x + 1)(2).
Captures are the fork's existing closure records. By-value captures copy their
values; <byref> captures pointers and must not outlive the captured frame. Native
closure restrictions, including which scopes accept <byref>, still apply.
Destructuring locals
#syntax 'syntax.let'
local Point = @record{x: integer, y: integer}
local calls = 0
local function make_point(): Point calls = calls + 1 return {20, 22} end
let {x, y = height: integer,} = make_point()
let [first, _, third] = (@[3]integer){10, 20, 30}
assert(x + height == 42 and first + third == 40 and calls == 1)
Record patterns bind fields by name; field = localname renames a binding and
accepts a typed local declaration. Record patterns allow a trailing comma. Array
patterns start at index zero, accept typed declarations, and use _ to skip a
position. A record alias of _ skips that field. Duplicate bound names are an
extension error. Missing fields and out-of-bounds constant indexes receive the
normal compiler diagnostics.
The source is evaluated once into a temporary; bindings are separate local
declarations visible after the statement. They are values, not references, and
do not track later source changes. Pointers to records can be destructured using
normal field access. Copying an owned lvalue is still rejected; use native
references and explicit move where ownership is involved. Keep resource-owning
sources in a using block and destructure a borrowed pointer; the hidden source
temporary does not schedule cleanup. Nested patterns and assignment into existing
locals are not part of this form.
Scoped resources
#syntax 'syntax.using'
local Resource = @record{closed: *integer}
function Resource:__close() $self.closed = $self.closed + 1 end
local closed = 0
local function use_resource(): integer
using resource: Resource = Resource{&closed} do
return 42
end
return 0
end
local answer = use_resource()
assert(answer == 42 and closed == 1)
using name = expression do … end creates a do scope with a local <close>
binding. The initializer runs once and cleanup follows normal Nelua rules on
fallthrough, return, break, and continue. The binding is visible only inside
the block. Type annotations and existing declaration annotations work; an
explicit <close> is not duplicated. Nest blocks for multiple resources; cleanup
runs in the usual reverse scope order. This is deterministic scope cleanup and
does not add exception handling or cleanup after process termination.
Vector comprehensions
## pragmas.nogc = true
#syntax 'syntax.collect'
require 'vector'
local squares <close> = collect(integer; i = 1, 8 when i % 2 == 0 => i * i)
local descending <close> = collect(integer; i = 5, 1, -2 => i)
local exclusive <close> = collect(integer; i = 0, < 3 => i)
local input: [4]integer = {10, 20, 30, 40}
local selected <close> = collect(integer; i, value in ipairs(input) when i % 2 == 0 => value + 1)
assert(#squares == 4 and squares[3] == 64)
assert(#descending == 3 and descending[2] == 1)
assert(#exclusive == 3 and exclusive[2] == 2)
assert(#selected == 2 and selected[0] == 11 and selected[1] == 31)
Write collect(ElementType; iterator => expression) with an optional
when condition before =>. The iterator can be a numeric loop, including a
step or comparison bound, or a generic iterator such as i, value in ipairs(a).
The semicolon distinguishes this notation from an ordinary collect(value) call.
Its initialization follows the corresponding native for rules. The filter runs
once per visited iteration; the mapped expression runs once per accepted one.
Elements are pushed in iteration order into a zero-based vector(ElementType).
An empty range or a filter that never matches produces an empty vector.
The element type is explicit and vector must be in scope. This form allocates
and grows a vector using the normal default allocator. It works under nogc with
<close>, using, or explicit destruction. It is not a lazy iterator, a fixed
array constructor, or a freestanding heap substitute. Element insertion and
returning the result retain the vector library's normal ownership rules.
Literal notation
#syntax 'syntax.literals'
require 'string'
local size = 1_024
local wide: uint64 = 18_446_744_073_709_551_615_u64
local decimal = 1_234.5_625e-1
local flags = b"10 1010"
local bytes = hex"00 41_ff"
assert(size == 1024 and wide == 0xffffffffffffffff_u64)
assert(decimal == 123.45625 and flags == 42)
assert(#bytes == 3 and bytes:byte(1) == 0 and bytes:byte(3) == 255)
Grouped decimal literals require a separator in their integer part. Groups must
contain digits; fractional and exponent groups may also use _. Existing suffixes
such as _u64 are passed to the native literal machinery. Ungrouped decimals,
hexadecimal numbers and native binary numbers retain their existing syntax.
The decimal digits are passed as text, so wide integers are not rounded through
Lua's floating-point type.
b"…" is a binary integer with optional spaces or underscores. It needs at least
one digit and permits only 0 and 1 after separators are removed. hex"…" is a
byte string; each byte needs two hexadecimal digits. Spaces and underscores are
ignored, upper and lower case both work, and an empty byte string is allowed.
Embedded zero bytes are preserved. These forms do not interpret string escapes.
Overflow and supported integer widths remain the native compiler's responsibility.
Alternative operators and precedence
#syntax 'syntax.operators'
local calls = 0
local function tick(): boolean calls = calls + 1 return true end
local a = false && tick()
local b = true || tick()
assert(not a and b and calls == 0)
assert(4 != 5 && 2 ** 3 ** 2 == 512)
assert(1 + 2 ** 3 * 2 == 17)
!= is ~=, && is and, || is or, and ** is ^. Both boolean operators
short-circuit exactly as their native equivalents do. Power groups to the right
and follows Nelua's native numeric promotion rules, so an integer-looking power
can produce a floating-point value. Built-in spellings remain available.
syntax.binary(level, token, builder) attaches an operator at an existing level.
The table runs from weakest to strongest; these are the actual API level names.
| Level | Native examples | Shipped additions |
|---|---|---|
or |
or |
` |
and |
and |
&& |
cmp |
== ~= < <= > >= |
!= |
orelse |
orelse |
— |
bor |
bitwise | |
|> |
bxor |
~ |
— |
band |
& |
— |
bshift |
<< >> >>> |
— |
concat |
.. |
— |
arit |
+ - |
— |
fact |
* / // /// % %%% |
— |
pow |
^ |
** |
The power level's right operand is a unary expression, which can contain another
power; this gives power its right grouping. Prefix unary operators sit between
multiplication and power, as in the base grammar. Other added binary operators
fold left at their level, including added operators at concat. Native ..
retains its own right-recursive operand rule. Use parentheses to make mixed
operator intent clear; the API does not create arbitrary new precedence levels.
Embed Bend2
Load syntax.bend2 to write Bend2 definitions inline and call them as typed
Nelua functions. This module is enabled separately from syntax.all.
#syntax 'syntax.bend2'
bend2 (twice(uint32): uint32) [=[
import Base
def twice(x: U32) -> U32:
(x * 2 : U32)
]=]
local value: uint32 = 21
assert(twice(value) == 42)
On Linux, install Clang and Bend 2.0.40, then run the example from the compiler checkout:
./nelua --cc clang --release examples/bend2/scalars.nelua
Use NELUA_BEND to select the Bend executable when it is outside your
PATH. A block can list several export signatures. Bend checks each wrapper
against its definition, and Nelua links the generated C into the executable.
The Bend CLI is a build-time dependency. Include import Base in each block.
Values across the boundary
| Signature type | Nelua value | Bend type |
|---|---|---|
uint32 |
uint32 |
U32 |
float32 |
float32 |
F32 |
string |
UTF-8 string |
String |
bytes |
Binary string |
List<&2, U32> with elements from 0 to 255 |
u32s |
vector(uint32) |
List<&2, U32> |
Scalars pass by value. Text, bytes and vectors cross by copying. Text decodes
invalid UTF-8 as replacement characters. Use bytes for arbitrary octets or
u32s for full-width integers. Returned buffers use Nelua's default allocator,
so they follow the standard string and vector lifetime rules. General records,
tuples and Bend handles stay on the Bend side of the interface.
IO and local imports
Write io before the result type to export an IO(T) action. A Nelua call runs
the action synchronously and returns its result. Use io void for IO(Unit).
#syntax 'syntax.bend2'
bend2 (report(string): io void) [=[
import Base
def report(text: String) -> IO(Unit):
IO.print(text)
]=]
report('Hello from Bend2')
The embedded event loop waits for spawned actions to finish before returning.
IO calls into the same block are serialized. Bend's IO.exit and IO.die exit
the host process. Pass arguments explicitly to the export because IO.args
does not receive the host command line.
A top-level import such as import ./helper.bend as Helper resolves from the
directory containing the Nelua file. Imports inside a Bend module resolve from
that module's directory. Relative foreign effects such as
import "./effect.c" follow the same rule. Base and BendHub imports still
resolve through Bend. Run the combined example on Linux:
./nelua --cc clang examples/bend2/interop.nelua
Write Nelua and run it through Bend2
Use bend2 nelua to keep the function body in Nelua. The compiler derives
the export signature, checks the supported subset, lowers the body to Bend,
and links the result into the same executable. Call the export like any other
local Nelua function.
#syntax 'syntax.bend2'
bend2 nelua (sum_squares gpu_at(1, 4096)) do
local function sum_squares(count: uint32): uint32
local total: uint32 = 0
for i: uint32 = 0, < count do
total = total + (i * i)
end
return total
end
end
assert(sum_squares(4) == 14)
The reduction loop becomes a balanced tree of Bend tasks. Its uint32 sum
wraps as it would in Nelua. A gpu_at cutoff generates the Bend offload marker
automatically. Without a cutoff, the function still runs through the Bend
backend on the CPU. Choose the cutoff for your workload. This example uses an
illustrative cutoff of 4096 elements.
The current subset accepts pure local functions with explicit uint32
parameters and one uint32 result. It supports typed locals, addition,
subtraction, multiplication, calls to earlier helpers in the block, and
returning if branches with unsigned comparisons. Use decimal literals
and add _u32 to literals used in arithmetic or comparisons. Loops must
have a zero start, an exclusive upper bound, and one assignment of the form
total = total + value, where value is independent of total.
Unsupported operations raise an error at the source location. General Nelua
programs, IO, and arbitrary mutation require ordinary Nelua or a handwritten
Bend block.
Run the comparison against a normal Nelua implementation on the same inputs:
./nelua --cc clang examples/bend2/nelua.nelua
Automatic CPU and GPU dispatch
Use bend2 auto and give an eligible pure export a cutoff. Both devices use
the same Bend implementation and the same Nelua call. Mark the compute entry
with Bend's !; ordinary Nelua calls need no device selection.
#syntax 'syntax.bend2'
bend2 auto (checksum(uint32): uint32 gpu_at(1, 12)) [=[
import Base
def sum_tips(+depth: Nat, +seed: U32) -> U32:
match depth:
case 0n:
seed
case 1n+smaller:
a b = sum_tips(smaller, seed) sum_tips(smaller, (seed + 1 : U32))
(a + b : U32)
def checksum(depth: U32) -> U32:
sum_tips!(U32.to_nat(depth), 1)
]=]
assert(checksum(3) == 20)
assert(checksum(12) == 28672)
gpu_at(1, 12) sets the minimum for the first argument. A uint32 is measured
by value, u32s by element count, and string or bytes by byte count. The
cutoff is inclusive. Measure it with the workload and hardware you expect to
use. Exports without a cutoff and IO exports in an automatic block run on the
CPU.
With the CUDA 12 or 13 headers present at build time, Clang 19 or newer can
build both paths. Set CUDA_HOME if needed. The executable loads the CUDA driver
and matching NVRTC major version only when a call qualifies. If either library
or a compatible device is missing, automatic mode runs that call on the CPU.
Builds without the headers include the CPU path. CUDA execution failures after
a device is selected are reported as errors.
./nelua --cc clang --release -o bend2-auto examples/bend2/auto.nelua
./bend2-auto
NELUA_BEND_DEVICE=cpu ./bend2-auto
NELUA_BEND_DEVICE=gpu ./bend2-auto
NELUA_BEND_DEVICE is read at the first cutoff-enabled call in each block.
cpu bypasses CUDA. gpu ignores the cutoffs on eligible exports and reports
an error when CUDA is unavailable. The default, auto, uses the cutoffs.
Use the overrides to compare steady-state workloads on the two devices.
CUDA execution
Use bend2 gpu (...) on Linux to run reachable Bend ! calls on NVIDIA CUDA.
Set CUDA_HOME to the toolkit if needed, and make its NVRTC library available
to the dynamic loader. Build with Clang 19 or later.
./nelua --cc clang --release examples/bend2/cuda.nelua
Ordinary calls in that block can still run on the CPU. Each GPU block compiles
its embedded kernel with NVRTC on first use and reuses the runtime and the
kernel for later calls. It restores the calling thread's CUDA context on return.
The GPU runtime defaults to a 1 GiB managed-memory allocation per block. Set
NELUA_BEND_GPU_MIB to adjust that allocation for the application and device.
Write an inline extension
The following adds a contextual check condition else message statement:
#syntax [[
syntax.statement("'check' WORDSKIP expr `else` @expr", function(condition, message)
return syntax.stat('assert(c, message)', {c=condition, message=message})
end)
]]
local answer = 42
check answer == 42 else 'unexpected answer'
The pattern uses LPegRex and can reference
base grammar rules from lualib/nelua/syntaxdefs.lua: expr, exprs, Block,
name, iddecl, iddecls, typeexpr, funcargs, and more. Captures become
builder arguments in order. name captures text; expr captures an AST node;
iddecls captures a list. @expr commits to an expression and reports an error
if it is missing. Delay committed matches until the extension's opening is
unambiguous, so normal calls and assignments can backtrack into the base grammar.
Backticks use Nelua's token machinery, including whitespace and comments. A new
word in backticks becomes reserved for the remainder of the file. For contextual
words use 'word' WORDSKIP, which also checks the identifier boundary. A raw
quoted punctuation literal does not skip whitespace; add SKIP explicitly when
that is required.
Builder API reference
| Call | Contract |
|---|---|
syntax.statement(peg, builder, options) |
Add a statement before built-in alternatives. Return one AST node or a Block to splice into its enclosing block. Optional {fallback=true} tries the rule after specific statements, before native assignments and calls. |
syntax.expression(peg, builder) |
Add a primary expression before the built-in simple expressions. Return one expression AST. |
syntax.prefixexpr(peg, builder) |
Match an expression before built-in prefix operators; useful for claiming $" before $. |
syntax.unary(token, builder) |
Add a prefix operator. The builder receives its operand. |
syntax.binary(level, token, builder) |
Add an infix operator at a listed precedence. The builder receives left and right operands. |
syntax.rules(text) |
Add named LPegRex helper rules. Existing rule names cannot be shadowed; use a module-specific prefix. |
syntax.error(label, message) |
Give a PEG error label a readable diagnostic. Use @rule or ^Label to throw it. |
syntax.def(name, value) |
Expose an LPegRex definition, for example a ->name capture transform. |
syntax.use(module) |
Load another extension into the same file's state. Shared dependencies are applied once; cycles are errors. |
syntax.gensym(prefix) |
Get a compiler-unique identifier for a temporary. Reserve the __sx_ namespace for generated code. |
syntax.expr(text, substitutions) |
Parse a template containing exactly one expression. |
syntax.stat(text, substitutions) |
Parse statements; return a single node or a spliced block. |
syntax.block(text, substitutions) |
Parse statements and always return a block. |
syntax.raise(message, ...) |
Raise a formatted compile error at the syntax use being expanded. |
syntax.aster |
Access ordinary AST constructors, such as BinaryOp, Function, and VarDecl. |
syntax.levels |
Inspect the level-to-right-operand-rule mapping used by binary. |
Builders execute bottom-up after parsing. Child extensions have already become
ordinary AST before a parent builder sees them. A builder must return an AST
node, not a Lua number, string, or plain list. Use syntax.aster.Number{'42'},
syntax.aster.String{'text'}, or a template to create literal expressions.
An expression builder cannot return a block of statements; wrap statements in
a native (do … in value end) expression instead.
syntax.filename() returns the name of the file being parsed.
Call registration methods and syntax.use while the module loads or inside an
inline #syntax directive. Builders run after the source has been parsed; their
job is to construct the replacement AST, rather than change the accepted grammar.
Templates, substitution and generated names
#syntax [[
syntax.statement("'twice' WORDSKIP expr `do` Block @`end`", function(value, body)
local name = syntax.gensym('repeat')
return syntax.stat('for index = 1, count do body() end', {
index=name, count=value, body=body,
})
end)
]]
local n = 0
twice 2 do n = n + 3 end
assert(n == 6)
Substitution is structural. An identifier whose name is a substitution key is
replaced by an AST clone, a numeric or boolean literal, or an identifier when the
value is a Lua string. A string substitution is an identifier, not a string
literal: use syntax.aster.String{value} for a literal. String substitutions
also rename declarations, field names, labels and other named AST slots.
An empty statement call such as body() splices a captured Block or list of
statements. A placeholder in an argument or expression list can splice a list
of expressions. Lists cannot replace a single expression. Cloning substitutions
lets a builder reuse a captured tree without sharing mutable AST nodes.
Templates use the grammar active where the extension is used, so they can contain
other enabled extensions. That grammar is recorded per syntax use, rather than
taken from the end of the file. A template cannot contain #syntax. Expansion
inside a template happens before its placeholders are substituted: placeholder
names should stand on their own, rather than depend on a type known only after
substitution. Generated trees receive the original syntax use's source location,
so analyzer errors refer to the source construct.
gensym prevents accidental reuse between builders. It does not make arbitrary
captured user code hygienic: avoid fixed helper names, and keep generated locals
in the narrowest appropriate scope. A returned statement Block is spliced and
does not add scope; return a Do statement when bindings must remain private.
Package and compose extensions
Save a Lua module next to your source file, for example project_syntax.lua:
return function(syntax)
syntax.use('syntax.control')
syntax.use('syntax.compound')
syntax.statement("'bump' WORDSKIP name", function(name)
return syntax.stat('target += 1', {target=name})
end)
end
Then use #syntax 'project_syntax' in your source file. Dots in module names map
to directories as in Lua. A top-level directive searches beside the source file,
then the Nelua library path and the Lua package path. A nested syntax.use first
searches beside the module doing the loading. The module must return a function
taking the syntax API; it should keep file-specific state inside that function,
because the compiler caches the loaded Lua module across parsed files.
Helpers should use module-specific rule and definition names. Two different modules defining the same helper rule are an error; two modules claiming the same surface spelling may compete by PEG registration order. The first matching alternative wins. Use a single project pack to make registration order explicit, and test it with every extension you plan to combine.
Broad statement rules that start with var, such as compound assignment, should
use {fallback=true}. A committed index error while probing var can otherwise
consume a contextual opening such as let [a, b] before its own rule gets tried.
Diagnostics and practical limits
Read the compiler's named error and its highlighted source construct. A missing
module names the module and searched paths; circular syntax.use dependencies
are rejected. Invalid PEG rules are reported at the directive, and
syntax.raise reports at the construct the builder is expanding. A bad template
adds an in syntax template diagnostic. Once expansion succeeds, normal Nelua
diagnostics handle types, declarations, ownership and unsupported target features.
Extension Lua has the compiler process's host access, like preprocessor Lua;
load modules you trust. It is distinct from the bounded comptime evaluator.
Do not use host-dependent builder decisions when cross-target output needs to
be reproducible. The extensions add no runtime framework, but their generated
code has the same costs and platform requirements as hand-written equivalents.
In particular, interpolation may allocate, comprehensions allocate a vector,
closures retain their lifetime rules, and freestanding mode continues to reject
heap-dependent code. Loading syntax.all alone requires none of those runtime
libraries. Static editor grammars cannot infer arbitrary file-local PEG rules;
custom forms may need your editor's grammar updated, even when the compiler
accepts them. Both code generators receive standard AST, and their existing
feature restrictions still apply.
To validate an extension, compare its expansion to ordinary Nelua, run it with
side-effecting operands, try its malformed forms, and check that unrelated source
still parses. The regression coverage is in spec/syntaxext_spec.lua and
spec/syntaxlib_spec.lua; the complete guide examples are executable checks.