Script semantics (what actually runs)

This is the interpreter you are targeting, not an abstract language spec. Match examples to this behavior.

Tokenization

1. Skip spaces/tabs (and newlines unless indentation is marked significant).
2. Skip line comments (markers) and block comments (pairs).
3. Longest match among operators, terminators, (), [], block delimiters, argument/member separators, decorator prefixes.
4. Numbers: optional -, digits, optional fractional part if floats enabled.
5. Strings: each literals.string.forms delimiter, default ". Escapes: n t r 0 and “unknown escape is the next char.”
6. Words: [A-Za-z_][A-Za-z0-9_]*. If the word is in any keyword list (including custom kinds and true/false/null), it is a keyword token.

Unicode identifiers are not fully implemented even if the JSON says they are.

Statements

Processed in order. Decorators may precede a statement.

• Function / custom function kind: name, (params), block. Registered on load and again on run.
• Type-first function: ReturnType Name(Type param, ...) { ... } when the language JSON enables c_type_first. void returns no value.
• Variable / declaration keyword: name, optional = expr. On run, stored in engine globals.
• Typed declaration: Type name [= expr] at file scope, in blocks, and in class bodies when type-first declarations are enabled.
• Bare assignment name = expr when the name is new (typical when declaration_required is false).
• Custom type: keyword Name { field = expr; ... } → global map (fields only).
• Class / actor: keyword Name [: Base] { fields and methods }. One instance per declaration; methods are callable with engine.call("methodName") after run. Inside methods, names resolve to instance fields, then methods, then globals/host.
• import spec [;]: spec is ident, a.b.c (imports.module_separator), or a string. Host add_library / add_library_file first, then a script file (importer dir, ., imports.search_directories, add_search_path). Script modules run in their own environment; binding follows imports.bind_as (namespace → last segment is a map; globals → flatten).
• if expr block [else if …] [else block]. Parentheses around expr are optional. Braces around the body are optional.
• while expr block

• for name [=] [in

  of] expr block

  • If expr is an array, iterate elements.
  • If expr is a number N, iterate 0 .. N-1.
  • Otherwise the body does not run.
• return [expr]. If statement terminators are optional, return does not steal the next declaration (return then Type name = … on the following line is a bare return).
• break / continue
• Otherwise: expression statement

Blocks: { ... } using configured delimiters, or a single statement if { is missing.

Statement terminators (often ;) are optional between many statements but recommended in generated examples.

Expressions (Pratt parser)

Prefix: unary -, !, not; parenthesized expr; [a, b] arrays; numbers; strings; true/false/null words; identifiers.

Infix / postfix:

• Call: f(a, b)
• Index: a[i] — arrays, maps (key to_string), strings (one character)
• Member: a.name — maps only
• Assignment operators (right-assoc, low precedence), including compound += -= *= /= when configured
• Binary operators from the language + defaults

&& / and and || / or short-circuit.

+ concatenates if either side is a string (to_string on the other).

Division by zero throws RuntimeError.

Assignment target must be an identifier (x = 1, not a[0] = 1 yet).

Scope

• Top-level run writes globals. Later call and other scripts see those names.
• Function parameters are a child environment. Method calls use the instance environment as parent (fields, then methods, then globals). Closures do not capture locals from an outer fn unless those names were global.
• Block { } is a child environment for let inside the block. Those names die at end of block.

Functions

Arity must match. Extra/missing args throw. Recursion is allowed. Nested fn is parsed if it appears as a statement inside a block; the inner function is still registered on globals by name (last one wins).

Load vs run vs unload

Action	Functions	Top-level let / exprs / types / classes / imports
load	Registered (free functions on entry scripts). Imported script files are parsed as isolated modules	Not executed
run	Re-registered; class methods bound on the instance	Executed; class instances created; imports bind host packages or script exports
unload	Names removed	Names removed

eval does all three.

Truthiness

Used by if / while: null, false, 0, "", empty array → false. Everything else → true.