Host Integration

Expr is a language runtime embedded in the host application.

The core language defines parsing, expressions, values, variables, functions, classes, objects, control flow, errors, and evaluation behavior. The host decides where Expr is used, which session is attached, which output stream receives text, which built-in objects are available, and which compatibility options are enabled for a specific context.

Most user scripts should use normal Expr syntax. Host integration features are for specific application contexts such as G-code expression evaluation, custom dialogs, probing scripts, ATC scripts, file import helpers, and interactive MDI use.

Expr is responsible for language semantics:

• tokenizing and parsing Expr source
• evaluating expressions and statements
• applying scope and assignment rules
• storing session variables, user functions, and user classes
• reporting parse and runtime errors
• calling built-in functions, object methods, and callbacks

The host application is responsible for application policy:

• where a script can be executed
• which session name is used
• which output sink is attached
• which built-in objects and host services are exposed
• which include paths are allowed
• which compatibility options are enabled
• whether a script is trusted enough to access files, settings, Python, serial ports, dialogs, or machine-related services

Expr should not be treated as a standalone sandbox. If a host exposes side-effect operations, scripts can use those operations.

Expr can be used in several different host contexts.

The available objects and the persistence of variables depend on the context selected by the host.

Compatibility options are selected by the host for a specific evaluation context. They are not recommended for normal Expr source files unless that context requires them.

Wrapper markers are host or G-code embedding syntax, not core Expr syntax.

A host context may allow Expr text to be embedded inside wrapper markers such as {! ... !}. The host extracts or marks the Expr portion before evaluation.

Do not use wrapper markers in ordinary Expr include files or standalone Expr scripts.

Hash variables are a G-code compatibility option.

When Expr is called from G-code expression evaluation, the host can enable hash-variable syntax so Expr variables and G-code parameters refer to the same values in that context.

Examples of compatibility forms include:

#1
#name
#<name>

Use normal Expr identifiers in normal scripts:

speed = 1200;
depth = -1.5;

See Lexical basics.

The host can enable named operator compatibility for older or embedded contexts.

Examples include `AND`, `OR`, `XOR`, `NOT`, `DIV`, `MOD`, `EQ`, `NE`, `GE`, `LE`, `GT`, and `LT`.

Normal Expr scripts should use the standard symbolic operators described in Operators.

//= is a host-editable comment form when modifiable-comment compatibility is enabled.

It is not ordinary comment syntax for normal Expr scripts. Use // and /* ... */ for normal comments.

See Lexical basics.

Included files are parsed with default Expr parsing options.

They do not inherit caller compatibility options such as G-code hash variables, named operators, wrapper markers, or modifiable comments.

This keeps shared include files predictable and portable between host contexts.

See Include system.

Each evaluation runs in an Expr session. The host chooses the session name, or it can evaluate without relying on persistent session state.

A host can:

• reuse a named session for interactive workflows
• create an isolated session for a job or background task
• use a temporary session for one-shot evaluation
• clear or delete sessions when state is no longer needed

Root variables, user-defined functions, and user-defined classes persist only when the same named session is reused.

// first evaluation in a persistent host session
part_count = 1;
 
// later evaluation in the same host session
part_count += 1;
print(part_count);

The global `session` object exposes session inspection and management for contexts where the host allows it.

See Execution model and sessions and session.

Functions such as `print()` and `printf()` write to the output sink selected by the host.

Depending on context, output may appear in a console, message/log panel, debug output, script result view, or another host-defined destination.

`enable_print(false)` can suppress print output for the current evaluation context when available:

enable_print(false);
print('hidden');
enable_print(true);
print('visible');

See Output, Formatting, Clipboard, and Errors.

Path handling is host-defined.

The `path()` function returns the profile path. `path(relativePath)` resolves profile-relative paths that start with `.` and source-relative paths that do not.

profile = path();
script = path('./scripts/probe.expr');

Other objects that load or save files also depend on host path policy and platform behavior. Examples include file dialogs, image data, image streams, byte buffers, Python files, and crypto file operations.

Use `path(…)` or host file dialogs when scripts should be portable between machines.

See Platform and Paths, Include system, and Dialogs.

Some built-in functions and objects are pure language helpers. Others are bridges to host services.

Important host-facing groups include:

A host build or context can expose additional application-specific globals. Scripts that depend on such globals are host-specific.

When Expr is used from G-code, the host can evaluate Expr expressions as part of G-code parsing or script execution.

In this mode, the host may:

• enable hash-variable compatibility
• map Expr variables to G-code parameters
• enable wrapper marker handling in G-code text
• provide G-code or machine-related objects
• choose a session strategy for the current program or command

This does not change normal Expr file syntax. Shared Expr include files should use strict Expr syntax and normal variable names.

Some host objects store callable Expr references and invoke them later.

Examples include:

• `timer(callback)`
• serial monitor callbacks
• GUI event callbacks
• asynchronous Python task handling, where supported by the host object

A callback runs in a new evaluation context connected to the relevant session selected by the object or host.

If callback state must survive after the original evaluation ends, keep it in the object instance or in a named session.

class Counter()
{
    Count = 0;
 
    function OnTimer(n)
    {
        Count += 1;
        print('timer call ', Count);
    }
}
 
counter = Counter();
t = timer(counter.OnTimer);
t.start(1000, 3);

Callback errors are reported through the object or host error path. A host object may stop the operation after a callback error.

See Execution model and sessions, timer, and serial.

Expr is not a security sandbox.

A script can only do what the host exposes, but exposed objects may allow side effects such as:

• reading or writing files
• modifying application settings
• running Python code
• opening dialogs or windows
• accessing serial ports
• using clipboard data
• starting timers or background work

Host-side recommendations:

• Treat Expr scripts as trusted configuration or trusted automation code.
• Restrict include roots to trusted folders.
• Avoid exposing sensitive host objects to untrusted script text.
• Log script source, context, and errors when traceability matters.
• Prefer strict Expr syntax for shared script libraries.

For scripts intended to be reused in different contexts:

• Use normal Expr identifiers instead of hash variables.
• Use symbolic operators instead of named operator compatibility.
• Put reusable code in include files that use strict Expr syntax.
• Avoid hard-coded absolute paths.
• Use `path(…)` or file dialogs for host-resolved paths.
• Keep host-specific code near the script entry point.
• Document required host objects such as `settings`, `python`, `serial`, or GUI objects.

Previous: Execution model and sessions

Next: Limits and performance