Errors and Diagnostics​

Diagnostics as you read them​

An error has one of two shapes, and the shape says when it happened: a static listing before anything runs, or a run-time text that catch sees.

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.

Checked at load, by site​

Each row is an error whenever the types involved are declared or inferred (auto holds the type it inferred). Chapter: Strict Checking.

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 an error that reads as the text alone. 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.

Error kinds​

A caught error's e.kind is one of the error_kind:: names (each is a string holding its own name), decided by the error's code, so a script tells errors apart without reading their text:

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​

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

Arithmetic​

Vectors​

Indexing​

Strings, bytes, time​

Regular expressions​

Random numbers and crypto​

Templates​

Errors marked at load fail the script that calls template before it runs, as a parse failure listing the template file and line. A scoped template's rules about its text fail at load for a literal text or path, at the first render otherwise (HTML Templates). A template file read with the filesystem privilege off raises Insufficient privilege: filesystem. where the call renders.

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 adds no depth; the budget stops a runaway tail loop. A value nests as deep as memory allows: deep copy, ==, <=> and the orderings, to_json/from_json and to_binary/from_binary walk work lists, not the host thread's stack.

Limits (terminal: script cannot catch them)​

Errors in script the runtime calls. Each raises its own errors: 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 +, an accessor or post_load an archive runs.

• The text leaves the builtin or operator unchanged and catchable; uncaught, its trace carries the callback's frames.
• The builtin makes no further calls after the first failure; 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); that member keeps 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 keeping an error result past 256 newer errors whose text embeds a value reads (the error text is no longer available) in its place.

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 it holds another type. The text names the held type as type_of spells it, then the type 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 data does not match the loaded type.

Saved programs​

A malformed .jaibite is refused before anything runs; every text starts jaibite: .

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

Other parse errors in the same voice:

• enum value 'b' names 'c', which is not an earlier value of 'F' (an enumerator's initializer is a constant integer)
• array<T>(...) takes a size and an optional value, not 3 arguments
• '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