Reference​

The lookup page. The guide teaches the language and the embedding chapters teach the host API; this page is where you come back to when you already know the shape of a thing and need the exact rule, the exact spelling, or the exact error text. The tables point back at the chapters that show each rule running, and the Documents section at the end indexes the specification files themselves.

Two conventions, used everywhere below. A handle is a shared_ptr<T>; a reference is a T&. And the checker means the static checker that runs before any script executes. It is on, in strict mode, unless the host turns it down.

Operators​

From Operators & Arithmetic:

Overflowing + - *, unary -, and INT64_MIN / -1 raise a catchable runtime error in the default build (JAISCRIPT_CHECKED_OVERFLOW). Integer arithmetic is never undefined behavior. Integer and float division by zero raise a catchable error (no IEEE infinity). When you want wraparound on purpose, math::wrap_add / wrap_sub / wrap_mul say so.

char operands promote to int (unsigned, 0..255) under arithmetic, bitwise, and comparison operators: 'a' == 97 is true, 'z' - 'a' is 25, and s[i] > 127 is an unsigned high-bit test (byte 0xC3 is 195, never -61). There is no implicit int→char: type_of('a' + 1) is "int". A char converts only through an explicit cast: cast<char>(n) (range-checked 0..255), cast<int>(c), cast<string>(c), cast<char>("a"), or through the stdlib function form to_char(n), or a \xNN literal.

Overloading on script classes. A class declares C++'s overloadable set less && || , -> new delete and !: binary + - * / % & | ^ << >> < > <= >= == != <=>, unary - + ~ (told apart from the binary form by the parameter count), =, [] and (), each as a method (Vec operator+(Vec o)). An operator runs only when its (left) operand is an instance whose class chain declares it; every other operand keeps the builtin meaning. a op= b is a = a op b through operator op (there is no operator op=); = into an existing object (a slot declared the class, a var) runs operator= when an overload takes the value, else the implicit memberwise copy, and initialization copy-constructs; != without an operator!= negates operator==; relational operators use <=> when the class does not declare the requested operator. Truthiness is bool to_bool(): if (v) calls it and !v negates it, and declaring operator! is the parse error operator! cannot be declared: !v is !to_bool(v); declare bool to_bool(). operator() makes an instance callable (v(1, 2)); the checker still holds a function slot to functions and null, so a callable instance goes in wrapped in a lambda. Chapter: Operators & Arithmetic.

Keywords​

The reserved words. None of them names a variable, a parameter, a program-scope function or a class; a qualifier or a member declaration makes one a name (keyword member names):

Words with a meaning only in one position, and names everywhere else: operator (an operator declared in a class, operator+), using (using ns::name; at the start of a statement), do (do { } while (c); when a { follows), double (a synonym of float where a type is read), utf8_string (the text type, where a type is read), uint8 and int8 (an array's element type only), the attributes [[warn_mode]] and [[strict_mode]], and hot_reload_migrate (reserved for the reload hook at a file's top level). Words from other languages (goto, virtual, delete, constexpr, ...) are not reserved; where one would fail to parse, the error names the JaiScript spelling (the table below).

Type conversions​

An example before the table. Every one of these is the same rule applied to a different slot:

class Meters { float v = 0; Meters(float x) { v = x; } }
class Reading { int raw = 0; Reading(int r) { raw = r; } int to_int() { return raw * 10; } }
Meters m = 3;              // one-step converting constructor
int n = Reading(4);        // to_int() on the way into an int slot
float f = 7;               // widens
int t = 3.99;              // truncates toward zero
bool b = 5;                // truthiness
string s = 42;             // anything -> string
print("{} {} {} {} {} {}", m.v, n, f, t, b, s);
var nul = null;
Meters typed_null = nul;   // null is a typed null in any object slot
print("{}", typed_null == null);

3.0 40 7.0 3 true 42
true

(A float prints as the shortest text that reads back to the same value, keeping .0 on a whole number, with inf, -inf and nan for the values no digits spell (every NaN prints nan, a format spec included, whatever produced it); template strings and {} placeholders take format specs: ${f:.1f}.)

One table. The same conversion rules govern declarations (int x = e), assignment (x = e), by-value parameters, return values, instance and static field stores, and the element boundary of typed arrays and maps. A conversion is always one step: a converting constructor or a to_X() method runs, but never chains (X.to_int() followed by C(int) is not implicit).

When a mismatch is caught. If both sides are visibly typed (int x = "s", a string returned from a function declared -> int, an unrelated class into a typed field), the checker reports it and the load fails before a single statement runs. If the value came through var (or any other slot the checker treats leniently), the same rule runs at run time and raises a catchable error with the texts in Diagnostics. Both cases are the same table; only the moment differs.

Compound assignment. On a typed (or locked-auto) target, a op= b computes like C++ and converts the result back to the target's type (int i = 7; i /= 2 → 3; i += 0.5 → 7; i += "s" is an error). On a var target the stored value is whatever the operation produces. A compound on a missing map key starts from the value type's default (map<string, int> m; m["x"] += 5 stores 5). The value of an assignment expression is what the destination stored (auto r = (i = 3.9) is int 3).

The typed boundary and the escape hatches​

Three spellings let you say, precisely, where you are stepping outside what the checker can see. None of them loosens anything else.

cast<T>(e), cast<T&>(e), cast<shared_ptr<T>>(e)​

class Base { int b = 1; }
class Derived : Base { int t = 0; }
class Holder { Base p = Derived(); }     // a Derived, held through a Base-typed field

print("{} {} {}", cast<int>('a'), cast<char>(97), cast<string>('z'));
char c = cast<char>(65);                 // `char c = 65;` would be a load error

auto h = Holder();
cast<Derived&>(h.p).t = 5;               // alias the same object: the store lands
print("{} {}", c, cast<Derived&>(h.p).t);

shared_ptr<Derived> sp = new Derived();
shared_ptr<Base> sb = cast<shared_ptr<Base>>(sp);   // share it, don't copy it
sb.b = 42;
print("{}", sp.b);

var v = Base();
try { Derived d = cast<Derived>(v); } catch (e) { print("caught: {}", e); }

97 a z
A 5
42
caught: Cannot cast 'Base' to 'Derived'

The operand is never checked against T statically. That is the point of a cast. A class mismatch raises the catchable Cannot cast 'X' to 'T' where X is the object's run-time class; null passes the value and handle forms (you get a typed null) and fails the reference form (Cannot cast 'null' to 'T&'). A T that names no class is a load error. Chapter: The Type Ladder.

extern​

extern declares a name that exists outside the program (a host global bound after load, a function the running instance registers, a value another engine injects) so that the checker counts it as declared instead of reporting use of undeclared identifier. At run time it declares nothing: the name resolves when it is used, and a use while nothing defines it raises 'name' is declared extern but never defined (an 'inline' declaration creates it) (extern function: without the parenthesis). inline T name; is the C++17 inline variable: one variable shared by every unit that declares it, created with its initializer or its type's default by the first to run and adopted by the rest (a later unit's initializer does not run again). Inline and plain declarations of one name never mix: a plain declaration of an inline variable raises 'x' is already defined inline; declare it 'inline int x;' to share it, and an inline declaration of another unit's plain variable raises 'x' is already defined (not inline) in <file>; declare every definition 'inline' to share it. When the checker sees both units it reports the plain declaration at load, with the first text.

using ns::name; (a comma list: using game::spawn, game::cost;) makes the rest of the file read name as ns::name, for any namespace. It is a parse-time rewrite: file-local, not transitive through imports or includes, and the name cannot be declared again in that file. There is no using namespace.

An extern name travels with the program: every unit the root imports sees it. It is also the idiom for a shared leaf that reaches into a module only some programs import. In a program that does import the module, the declaration is inert and the real definition wins.

[[warn_mode]] and [[strict_mode]]​

extern function log_to_host;   // the host registers this later: calls are unchecked
extern int frame;              // typed: reads and stores are checked as an int
extern config;                 // untyped: behaves like var

int total = 0;
try {
    [[warn_mode]] total = "oops";        // this one statement is only warned about...
} catch (e) {
    print("run time: {}", e);            // ...so the mistake surfaces here instead
}
print("{}", total);

run time: Cannot assign string to 'total' (declared int)
0

The two attributes set the checker's mode for a region of one file. They compose and the innermost wins; everywhere else a file is strict. Where the attribute sits decides what it covers:

In a warn region every error is reported as a warning (still collected, still visible through engine->check()) and an undeclared identifier is accepted as unknown; nothing is proven from it. In a strict region errors gate the load, even inside a warn region. The runtime never changes: both backends treat the attribute as nothing, so a warn region's type mistakes raise at run time exactly as they would have without a checker, which is what the example shows. A unit's mode says nothing about the units it imports. warn_mode and strict_mode are the only attribute names; anything else is a parse error.

Language rules in one place​

The contractual one-liners: the things both backends are tested to agree on, byte for byte.

Diagnostics as you read them​

There are two shapes of error, and knowing which one you are looking at tells you when it happened.

The static listing (before anything runs)​

int x = 5;
x = "hello";                  // typed to typed: the load fails, nothing runs
print("never printed");

jaiscript: static check failed:
<script>:2:3: error: cannot assign 'string' to 'x' declared 'int' (declared at 1:5)
    x = "hello";                  // typed to typed: the load fails, nothing runs
      ^

The shape is FILE:LINE:COL: error: MESSAGE, then the source line, then a caret. FILE is the unit's resolved path for a file (the root file, an import, an include) and <script> for source text handed to execute(). Messages are lowercase, except the few that reuse a run-time text and keep its capital (Cannot access private member 'x' of class 'C', Cannot access private constructor of class 'C'); a message about a declared name ends with that declaration's position, (declared at LINE:COL). A failed load hands the host one jai::static_check_error whose what() is the whole listing (sorted by location, deduplicated, capped at 100), and nothing has executed. Warnings (shadowing, a copying cast) use the same shape with warning: and never stop the load. A syntax error reads the same way under parse failed: instead, thrown as jai::parse_error: the parser lists every syntax error it meets in source order (it resumes after each), and no check runs until the source parses. The runner lists them under --warnings, and a host reads them from last_check_diagnostics(). Common messages:

Run-time errors (what catch sees)​

var dynamic = "hello";        // var: the checker cannot see what it holds
try {
    int x = dynamic;          // so this fails at run time, where catch sees it
} catch (e) {
    print("caught: {}", e);
}

caught: Cannot initialize 'x' (declared int) with string

Run-time texts lead with the action that failed, or with the builtin or member that refused it; names are quoted. catch (e) receives the text alone, and an uncaught error's what() on the host side is the same text alone, with no category or location appended (only an error raised without a text of its own reads as its category's name). Every text is byte-identical on both backends. The catalog, by family:

Null receiver​

No such member​

Not a function​

Arity and overloads​

The typed boundary​

Numeric conversion​

Containers​

Handles and references​

Const​

Assignment targets​

Methods as values​

Casts​

Names​

Definitions​

The strict checker reports the class texts below at load, and the method texts with a lowercase first letter.

Arithmetic​

Vectors​

Indexing​

Strings, bytes, time​

Regular expressions​

Random numbers and crypto​

Files​

Archives​

Exceptions​

Coroutines​

Sleep​

Parallel bodies​

Script layers​

Access​

Limits (catchable)​

The engine stays usable afterwards. On the VM a bare self tail call reuses its frame and never accumulates depth, so a runaway tail loop is stopped by the budget instead. A value nests as deep as memory allows: a deep copy, ==, <=> and the orderings, to_json/from_json and to_binary/from_binary walk it on work lists, never on the host thread's stack.

Limits (terminal: script cannot catch them)​

Errors in script the runtime calls. A sort comparator, a filter or remove_if predicate, the other callback helpers, a parallel_for body, a user operator, to_bool() under a condition, to_string() under string +, and an accessor or post_load an archive runs all raise their own errors: the text leaves the builtin or operator unchanged, catchable like any run-time error, and an uncaught one carries the callback's frames in its trace. The builtin makes no further calls after the first failure, and sort leaves the array as it was. An archive load tolerates only a store the member itself refuses (a read-only host property, a value the field's store rejects), which leaves that member at its constructed value.

A caught error's e.stack and the host's format_stack_trace() list the innermost 64 frames, then one line ... N more frames. A host that keeps an error result past 256 newer errors whose text embeds a value reads (the error text is no longer available) in place of that text.

Texts thrown to the host as jai::runtime_error, never seen by a script:

Call-depth configuration​

Privileges​

Callbacks​

Engine entry points​

Suspendable runs​

Host records​

Conversions​

A host reads a value as a C++ type (as<T>(), as_int(), a bound function's parameter, a bound property's store) and the value holds another type. The text names what the value holds as type_of spells it, and the type the host asked for. A script that caused the read catches the same text.

Values and engines​

Archives​

Thrown as jai::serialization_error by the C++ archives (from_json, from_binary and the readers under them) when the data does not match the type being loaded.

Saved programs​

A malformed .jaibite is refused before anything runs, every text prefixed jaibite: .

Parse errors that name the JaiScript spelling. Each word is recognized only where it would otherwise fail to parse, so a script that uses it as a name (var goto = 5;) keeps working:

Other parse errors in the same voice: Enum values take no initializer: 'a' is 0, its position in the enum · 'uint8' is an array element type only (array<uint8>, one byte per element); a single byte is an int · '??=' needs a variable, a member or an element whose index runs no code; store anything else in a local first · A map entry binds two names, the key and the value: for (auto [k, v] : m) · operator! cannot be declared: !v is !to_bool(v); declare bool to_bool() · Nested function 'helper' cannot use enclosing local 'y': a named function captures nothing; use a lambda with a capture ([&], [=] or [y]) or function(...) / => · a class cannot be declared inside a function body (a class is a program-scope type); declare it at program scope or import its file · 'a' names g::a by a using declaration; a variable cannot be declared with that name.

Full API signatures: arguments, defaults, results, effects, and availability for builtins, standard-library functions, and the standalone runner.

Builtin methods​

From Containers & Strings. One registry serves both backends, so the lists below are the same on each.

Arrays (31)​

pop on an empty array raises a catchable error. a.filter(f) keeps the elements f accepts in a itself; remove_if drops the ones its predicate accepts. The copying forms are the array:: functions: array::slice, array::filter, array::map, array::concat, array::append, array::sort and array::reverse return a new array and leave their argument alone. The callback helpers pass the element, or the element and its index to a two-parameter callback; a T& element parameter is the element itself. a.map(f) keeps a's element type (results convert into it); array::map returns an array<T> when its callback declares T; find returns a copy or null, find_index an index or -1; reduce(f) without an initial value raises on an empty array; insert(i, v) takes i from 0 to size(). A typed array (array<int>) checks every store against its element type; array<var>, and a literal with no spelled element type, holds anything.

Maps (14)​

Writing m[key] = v inserts; reading a missing key returns null and does NOT insert. get(key) returns null for a missing key; get(key, default) supplies an explicit fallback. Keys are ordered; any script value can be a key (the total ordering of <=> guarantees it). A declared key type is enforced on stores (map<string,int> m; m[5] = 1 raises); keys never coerce.

Strings (38 core)​

s[i] indexes bytes and returns a char, which promotes to an unsigned int (0..255) in numeric contexts, so s[i] + 0 reads a byte value, s[i] - '0' is the digit-parse shape, and s[i] == 0x1A is a byte test. s.at(i) returns the same char; on a utf8_string, u.at(i) returns character i as text. s[i] = c replaces byte i and s[i] = text replaces it with the whole text (s[i] += text reads, concatenates and writes back); on a utf8_string, u[i] reads and replaces character i. Bytes are minted with cast<char>(n) or to_char(n) (both range-checked 0..255; out += cast<char>(b) is the binary-writer shape) and with \xNN escapes (exactly two hex digits; "\x00" embeds a real NUL). A raw string R"(text)" (or R"delim(text)delim", a delimiter of up to 16 characters, none a space, parenthesis, backslash or quote) holds its text with no escapes, a line ending inside as one \n. find returns -1 when absent; split() with no argument splits on whitespace and drops empty pieces (split(string::whitespace) is the same); split(sep) keeps empties; split("") splits into characters; explode is its synonym.

The mutator camp is the surprise: auto upper = name.to_upper(); also uppercases name itself. This is deliberate: returning the receiver makes chained pipelines like s.trim().to_lower() allocation-free, and value semantics keeps the mutation local to that one variable. Copy first if you need the original, or build new strings with + (which never mutates), or call the string:: function of the same name (string::to_upper(s) returns a new string).

Every engine also has text helpers beyond the core table: lines partition compare code explode byte_size utf8_length utf8_chars is_valid_utf8 is_digit is_alpha is_alnum is_space is_upper is_lower to_utf8 (a utf8_string), and the binary doors to_bytes([offset], [count]) (an array<uint8>) and reader() (a binary::reader). A utf8_string answers the same method names in characters, except to_utf8.

Smart pointers​

Library at a glance​

math::vec3 p = math::vec3(1, 2, 3);
p.x = 10;                                     // a component is an lvalue
array<math::vec3> pts = [p, math::vec3(0, 0, 1)];
print(p * 2.0, " ", math::dot(p, p), " ", math::length(math::vec2(3, 4)), " ", pts[1]);

binary::writer w;
w.uint16(513); w.text("hi");
var r = w.to_string().reader();
print(r.uint16(), " ", r.text(), " ", r.at_end());

utf8_string u = "h\xC3\xA9llo";
print(u.size(), " ", u[1], " ", "h\xC3\xA9llo".size());

array<float> xs = [1.0, 2.0, 3.0];
parallel_for (auto& x : xs) { x *= 2.0; }
print(to_json(xs), " ", type_of(time::utc_now()));
print(to_json({"a": [1, 2]}, 2));

(20.0, 4.0, 6.0) 113.0 5.0 (0.0, 0.0, 1.0)
513 hi true
5 é 6
[2.0,4.0,6.0] time::date
{
  "a": [
    1,
    2
  ]
}

What a bare engine has. jai::engine::make() alone runs the whole language with these builtins: a print that concatenates its arguments, template strings with format specs (format_value), the builtin container and string methods and their array:: forms, math:: (functions, vectors, colors, wrap_*), regex, binary:: readers and writers with string::from_bytes, same_object, extend, thread_count, parallel_transform and parallel_reduce, sleep, and the location builtins (executable_dir, file_data, resolve_path and the rest). jai::stdlib::register_all adds the formatted print, format, to_string, type_of, JSON and binary serialization, the string:: functions, to_char, random, time::, crypto:: and reflect::; web:: and spider:: are separate opt-ins.

include vs import​

From Modules:

#include "x.jai" is accepted (the # is ignored for C++ muscle memory). Persistent state goes in a module you only import and never include, so a reload can't wipe it.

Every file-based load also maintains a jaibite disk cache in a .cache folder beside the source (foo.jai → .cache/foo.jai.jaibite, or below the host's cache directory): a cache recording the exact source text (size + hash) and a matching registration fingerprint loads instead of parsing; any other text reparses and refreshes the cache, whatever its mtime. Parse-level and side-effect-free: it never changes whether a file runs. Silent on write failure; eng->jaibite_cache(false) disables.

Import modes (engine::import_behavior)​

Engine API quick reference​

The embedding surface used across the embedding chapters; each row links to the chapter with the compiled-and-run example.

Engine lifecycle & execution: Quickstart​

Registering the host surface: Quickstart, dynamic_binder​

Safety rails: Safety Rails​

Time source: Quickstart, Time​

Static checking & precompiled scripts: Static Checking, jaibite​

Serialization & coroutines: Serialization, Coroutine Hosting​

Thread pool: Thread Pool for Host Work, Parallel worker count​

Command-line runner​

jaiscript is the reference embedding and the quickest way to run anything on this site. It is built by the jaiscript_runner target (on by default), lands in build/bin/, and always registers the full stdlib, the web:: library, the spider:: HTTP client (WinHTTP on Windows, sockets elsewhere, the network permission granted), file IO (read_file, write_file, file_exists, delete_file, move_file, dir_exists, make_dirs, list_dir, writable_dir, plus Download, zip_entries and zip_extract), a small console-game surface (read_key, key_down, term_cols, term_rows, and sound: load_sound, play_sound, stop_sounds; clocks are the standard library's time::), two socket classes, NetServer and NetChannel, and net_host_name and net_local_addresses. Enough that the example shims and JaiDoom run on it unmodified. Full notes: tools/jaiscript/README.md.

The runner's host API​

The runner registers these on every engine it builds; a host embedding JaiScript has none of them unless it registers its own. The calls that name a file (the file functions, Download.start, load_sound and play_sound) run under the engine's filesystem privilege, so an engine with it disabled raises Insufficient privilege: filesystem. at the call; Download.start reaches the network too and needs the network privilege as well. Signatures and effects are also in the API reference under the standalone runner. Locations (executable_dir(), root_script_dir(), current_script_dir(), resolve_path(name), app_data_dir(name) and the rest) are language builtins on every engine, described in Modules; a script that builds its paths from them runs the same from any working directory.

Every Sound is its own voice: music in one, ambience in another and effects in the rest all play at once, mixed. A Sound loaded once and played again is the way to fire an effect many times, since loading a file costs more than playing it. A loaded Sound closes when the last variable holding it lets go (a copy of a Sound is the same sound). No call waits on the audio device: one audio thread opens and drives the devices, so a frame loop never stalls on a sound. Sound plays on Windows; elsewhere load_sound and play_sound return null, so a script that checks for null, as it does for a missing file, runs unchanged, silent.

var music = load_sound("theme.mid");
var hit = load_sound("hit.wav");
if (music != null) { music.volume(0.6); music.play(true); }   // loops until stopped
if (hit != null) { hit.play(); }                               // again and again, each restarting it
play_sound("door.wav");                                        // fire and forget

A packet is one send's bytes, delivered whole and in order: on the wire each packet is a 4-byte big-endian length, then the bytes. Neither class runs a thread. The sockets do not block, and the signals fire only inside pump(), on the script's own call stack, so a game calls pump() once a frame. A NetChannel fires on_connect(), on_packet(bytes) and on_disconnect(reason); a NetServer fires on_client_connect(id), on_client_packet(id, bytes) and on_client_disconnect(id, reason). A disconnect's reason is "closed by peer", "recv error", "send error", "oversized frame" (a length over 64 MiB) or, for a server's client, "kicked". Packets that arrived ahead of a close are delivered before its disconnect.

NetChannel.connect is asynchronous. It returns false only when the attempt fails at once (the host name does not resolve, the socket cannot be made), with the reason in status(). Otherwise it returns true while the connection is still being made, and the outcome arrives later through pump(): on_connect() when the peer accepts, on_disconnect("connect refused") when it does not. Packets sent before then wait in the queue and go out once the connection is made.

Performance rules of thumb: Backends, Performance​

Every cost claimed above is quantified. One page, one machine, one protocol: Performance.

Documents​

This site is the specification of the language and its embedding API: where a rule is stated here, that statement is the rule, and a disagreement with the code is a bug worth reporting. The repository holds a few documents beside it, about building and running; the links open them on GitHub.