INCLUDE & SIDELOAD

INCLUDE loads and executes an external .oql file in the current scope — identical to PHP include. SIDELOAD executes a string of OcaltQL code in the current scope — identical to PHP eval. Both share scope fully. Both support RETURN to pass a value back to the caller.

INCLUDE

INCLUDE loads an external .oql file and executes it as if its contents were written inline at that point in the script. Variables set inside the included file are available in the outer script. RETURN inside the included file terminates it and passes the value to SET on the INCLUDE statement. If the file does not exist or produces an error, the result is an INFINITE error state — the script breaks.

Basic Include
INCLUDE "/root/utils.oql"
Include from URL
INCLUDE "https://raw.githubusercontent.com/ocalt/oql-lib/main/utils.oql"
Include from Variable Path
STRING "/root/utils.oql" SET ?path
AFTER INCLUDE ?path
Sequential Includes
INCLUDE "/root/setup.oql"
AFTER INCLUDE "/root/main.oql"
Parallel Includes
INCLUDE "/root/lib1.oql" AND INCLUDE "/root/lib2.oql"
If the file does not exist or produces an error, the result is INFINITE. The script breaks at that point. There is no soft failure — a missing or broken include is unrecoverable.
Include with RETURN Capture — The Included File

Illustrative only — this is the content of /root/utils.oql, referenced by the runnable example below.

STRING "hello" SET ?msg
AFTER RETURN "done"
Include with RETURN Capture — The Main Script
INCLUDE "/root/utils.oql" SET ?result
AFTER EMIT ?result
AFTER EMIT ?msg
(* ?result = "done" — RETURN value from utils.oql captured *)
(* ?msg is also in scope — shared scope means everything utils.oql set is visible here too *)

SIDELOAD

SIDELOAD executes a string of OcaltQL code in the current scope — identical to PHP eval. The string can be a literal or a variable. Variables set inside the sideloaded code are immediately available in the outer script. RETURN inside the sideloaded string terminates it and passes the value to SET on the SIDELOAD statement.

Basic SIDELOAD
SIDELOAD "CALCULATE 1 + 1 SET ?r"
AFTER EMIT ?r
(* Output: 2 — ?r is in scope *)
SIDELOAD with RETURN Capture
SIDELOAD "STRING 'hello' SET ?msg AFTER RETURN 'done'" SET ?result
(* ?result = "done" — RETURN value captured *)
(* ?msg also in scope *)
AFTER EMIT ?result
AFTER EMIT ?msg
SIDELOAD from Variable
STRING "CALCULATE 10 + 5 SET ?r" SET ?code
AFTER SIDELOAD ?code
AFTER EMIT ?r
(* Output: 15 *)
Fetch then SIDELOAD
FETCH "https://example.com/script.oql" SET ?script
AFTER SIDELOAD ?script
INCLUDE = PHP include. Loads a file. Shares scope. RETURN terminates file and passes value to SET. Missing file = INFINITE error.

SIDELOAD = PHP eval. Executes a string. Shares scope. RETURN terminates string and passes value to SET. No INFINITE on error — follows normal error handling.
FETCH & PROMISE →