Execution Model and Sessions

Expr evaluation runs a script in an evaluation context connected to an Expr session.

The evaluation context is temporary. The session can persist data across evaluations when the host uses the same session name.

Each evaluation has two main phases:

1. Parse the source text into an internal program tree.
2. Execute that program tree in an evaluation context.

Parse errors stop before any script code runs.

Runtime errors stop during execution.

a = 10;
b = 20;
a + b;

The final value produced by the script is the evaluation result. In this example, the result is `30`.

A script result is the last produced value unless control flow changes it.

a = 10;
a + 5;

The result is `15`.

Assignments also produce values:

a = 10;       // produces 10
b = 20;       // produces 20

If the last statement is a declaration or another statement that produces no useful value, the result can be `none()`.

function Add(a, b)
{
    return a + b;
}

Use an explicit final expression when the caller needs a specific result.

Output functions write to the active output sink. They are separate from the evaluation result.

print('Running');
42;

This writes `Running` to output and returns `42` as the script result.

Common output functions include:

• `print(…)`
• `printf(…)`
• `sprint(…)`
• `sprintf(…)`
• `enable_print(…)`

See Output, Formatting, Clipboard, and Errors.

A session stores state for Expr evaluations.

A session contains:

• root/session variables
• user-defined functions
• user-defined classes
• built-in global objects such as `settings`, `controller`, `session`, and `python`
• the last evaluation result

Named sessions allow state to persist across evaluations that use the same session name.

// first evaluation in session 'job1'
count = 1;

// later evaluation in session 'job1'
count += 1;
count;

The second evaluation can read and update `count` because it uses the same named session.

Different named sessions are isolated from each other.

Host code decides which session name is used for an evaluation.

Common host patterns are:

• use a named session for interactive or stateful workflows
• use a temporary or cleared session for one-shot evaluation
• use a generated session name for isolated tasks

When a script has no persistent host session, root variables, functions, and classes should not be relied on after the evaluation ends.

The global `session` object can switch the active context to the fallback empty-name session with session.join(''). This is mainly useful for host-controlled or interactive workflows. Prefer named sessions when persistence matters.

The global `session` object exposes session inspection and management.

print(session.current);
print(session.list_variables());

Common methods include:

See session.

Built-in global objects are restored when a session is prepared for evaluation.

Current global objects include:

• `settings`
• `controller`
• `session`
• `python`

These names are protected. Do not assign over them.

settings = 1;     // error
controller = 1;   // error
session = 1;      // error
python = 1;       // error

See Global objects.

Normal top-level assignment creates or updates a root variable in the current session.

feed = 1200;

Root variables are visible to later statements and can be visible to later evaluations when the same named session is reused.

Assigning `none()` removes or clears the variable so that later reads behave as missing.

feed = none();
feed;             // none()

See Variables and assignment.

User-defined functions and classes are stored in the active session.

function Add(a, b)
{
    return a + b;
}
 
class Box(value)
{
    Value = value;
}

If the same named session is reused, later evaluations can call the function or construct the class.

Re-defining the same function or class name in a session replaces the previous definition.

During evaluation, Expr uses local scopes for blocks, functions, and methods.

Local variables are created with `set`.

function AddOne(value)
{
    set temp = value + 1;
    return temp;
}

Local variables disappear when their scope ends.

Variable lookup checks local scopes before root/session variables. Inside object methods, object fields also participate in name lookup and assignment rules.

See Variables and assignment and Classes and user-defined objects.

Control-flow statements set internal evaluation state while the current program is running.

• `return` exits the current function or method.
• `break` exits the current loop.
• `continue` skips to the next loop iteration.

These effects do not persist in the session after evaluation ends.

See Control flow.

The evaluation context tracks the source path and profile path used for file resolution.

The profile path is the machine configuration folder. `path()` returns this folder.

The source path is the folder of the current source script used by the host. `path(“”)` returns this folder.

Paths that start with `.` are profile-relative. Paths that do not start with `.` are source-relative.

profile_file = path("./lib/Loader.expr");
source_file = path("job_data.csv");

See How relative paths work and Include system.

Some host objects call Expr callbacks after the original statement has returned.

Examples include:

• GUI event callbacks
• dialog result callbacks
• `timer` callbacks
• serial monitor callbacks
• Python task callbacks

Callbacks run in a new evaluation context connected to the relevant session when the object invokes them.

Because callbacks can run later, keep callback state in the object instance or in a named session when it must survive beyond the original evaluation.

class Demo()
{
    Count = 0;
 
    function OnTimer(count)
    {
        Count += 1;
    }
}
 
demo = Demo();
t = timer(demo.OnTimer);
t.start(1000, 3);

Object lifetime rules are object-specific. See the relevant object page for details.

Expr session registries and session containers are protected internally.

Each evaluation should use its own evaluation context.

Practical rules:

• Prefer separate sessions for independent background tasks.
• Avoid many concurrent writer-heavy scripts sharing the same mutable session.
• Use named sessions deliberately when state must persist.
• Clear or delete sessions when long-lived state is no longer needed.

Thread-safety prevents data-structure corruption. It does not make conflicting script logic automatically correct.

Use a named session for interactive workflows:

count += 1;
count;

Use a temporary evaluation for isolated calculations:

set a = 10;
set b = 20;
a + b;

Use classes for persistent object state inside a session:

class Average()
{
    Count = 0;
    Total = 0;
 
    function Add(value)
    {
        Count += 1;
        Total += value;
        return Total / Count;
    }
}

Previous: Error model

Next: Host integration