Script language

May 16, 2026 · View on GitHub

Syntax reference for scripts passed to Interpreter::cmd or parseScript. Behavior is covered by src/test.cpp (especially readmeExamplesTest).

Statements and expressions

Scripts are a sequence of statements.
Statements end with ;.
Whitespace outside strings is ignored. Line comments start with // (to end of line).
The value of the last expression in a script is the result of cmd / runScript.
Parentheses () group expressions and raise precedence inside them.

Variables

Names start with $:

$a = 5;
$b = "hello";

Initializer syntax:

$a{12};    // same idea as $a = 12 with parse-time init

Non-$ names are ordinary identifiers (containers, struct fields, labels). Names like trueVar are not the boolean literals — only the exact tokens true and false count.

Boolean literals

The keywords true and false are boolean literals (no $ prefix):

$x = true;
$y = false;
if (false) { $a = 1; }
while (true) { break; }

Stored as bool in Value.
cmdResultToString prints them as 1 and 0 (same as numeric truthiness).
Usable anywhere an expression is expected, including if / while conditions and comparisons ($a == true).
Reserved: you cannot addFunction("true", …) or addOperator("false", …); registration fails.

Arithmetic and comparisons

Require ArithmeticOperations and ComparisonOperations:

$a = 5; $b = 2;
$c = $a * (2 + $b);
$d = $a == $b;

Host functions

Registered in C++ with addFunction. Called from script:

$c = summ($a, $b, summ(5, 3));

Arguments are expressions; the host receives evaluated Value values.

Script functions

Define with function and a braced body:

$a = 1; $b = 2;
function myFunc { $a += $b; };
myFunc();

Parameters are positional: $0, $1, …

function add { \$0 += \$1; };
add(2, 3);

Nested functions are allowed. Recursion works if the host function is visible inside the script function body.

Host operators

Registered in C++ with addOperator(name, callback, priority). Base library registers =, ., [, :, etc.

$c = 5;
$c += 5;

Control flow

Construct	Meaning
`if (condition) { body }`	Run body if condition is truthy
`elseif (condition) { body }`	Else branch chain
`else { body }`	Final else
`while (condition) { body }`	Loop while truthy
`break;`	Exit innermost loop
`continue;`	Next loop iteration

Conditions use truthy rules (non-zero numbers, non-empty strings, true, …).

Container iteration

while ($v : a) print($v);

$v receives each element (Vector) or key/value pair context (Map) depending on container type.

Macros

Declare in script

#macro myMac { $c = 5; $d = $c + 5; };
$c = 1; #myMac;

Invoke

#myMac;

With parameters ($0, $1, …)

#macro myMacr { $a = $a + \$0 + \$0 + \$1; };
$a = 5; #myMacr(3, 4);

From C++

ir.setMacro("inc", "$a = $a + 1;");
// script: #inc   (name with or without #)

Macros are expanded before parse. Bodies are cleaned the same way as normal scripts.

Goto

Labels must start with l_ and end with ::

if ($a == 3) {
  goto l_done;
}
l_done: $a = 0;

Containers

Requires Container. See Base library for method tables.

Vector

a = Vector;
a.push_back(1);
a.push_back(2);
a[2];

a = Vector{ 1 + 2, 2 + 3, 3 + 4 };

Map

b = Map;
b.insert(myKey, myValue);
b["myKey"];

$b = 12;
c = Map{ one : $b + 5, two : 2 };
c["one"];

Literals

Comma-separated elements in { … }. Map entries use key : value segments.

Struct

Requires Structure:

e = Struct{ one : 5, two : 2 };
e.one = summ(e.one, e.two);
e.three = 22;

Filesystem

Requires Filesystem:

file1 = File{"main.cpp"};
if (file1.exist()) {
  $data = file1.read();
}

Types

Requires Types:

a: int = 123;
b: str = "abc";
type(a);

Attributes

Optional metadata on entities (advanced). Register names with addAttribute in C++.

print is not built in; the host defines it (see example/main.cpp). Scripts that only call print in a loop often return 0 from cmd because the last value is from the loop, not the printed text. Output goes to the host’s printf (or similar). See Limitations.