gh-7: Add extension support.

Author: python-processing-unit

.gitignore

@@ -1 +1,6 @@
-*.exe
+# Ignore binaries (both executables and libraries)
+*.exe
+*.app
+*.dll
+*.so
+*.dylib

build.ps1

@@ -1,74 +1,129 @@
 <#
-build-temp.ps1
-Compile the project inside a temporary directory under $env:TEMP (e.g. C:\Windows\Temp), copy the resulting EXE back into this repo, and remove all temporary artifacts.
-Requires: run from a Developer Command Prompt for Visual Studio where `cl.exe` is on PATH.
+build.ps1
+Compiles the interpreter in a temporary directory and copies the resulting EXE
+back into this repo. Also discovers extension C sources under ext/ and lib/
+and compiles each one into a dynamic library next to its source file.
+
+Requires: run from a Developer Command Prompt for Visual Studio where cl.exe is on PATH.
 Usage (from Prefix-C folder):
-    powershell -ExecutionPolicy Bypass -File .\build-temp.ps1
+    powershell -ExecutionPolicy Bypass -File .\build.ps1
 #>
 
 $script = Split-Path -Parent $MyInvocation.MyCommand.Definition
 $src = Join-Path $script "src"
+$extRoots = @(
+    (Join-Path $script "ext"),
+    (Join-Path $script "lib"),
+    (Join-Path $script "tests")
+)
 
-Write-Host "Preparing temp build directory under`$env:TEMP`..."
+Write-Host "Preparing temp build directory under`$env:TEMP..."
 $stamp = Get-Date -Format "yyyyMMdd-HHmmss"
 $buildDir = Join-Path $env:TEMP ("prefix-build-$stamp")
 New-Item -ItemType Directory -Path $buildDir -Force | Out-Null
-
 Write-Host "Build dir: $buildDir"
 
-# Ensure cl.exe is available
 $cl = Get-Command cl.exe -ErrorAction SilentlyContinue
 if (-not $cl) {
     Write-Error "cl.exe not found. Run this script from a Developer Command Prompt for Visual Studio."
+    Remove-Item -Recurse -Force $buildDir -ErrorAction SilentlyContinue
     exit 1
 }
 
-# Collect .c files
 $cFiles = Get-ChildItem -Path $src -Filter *.c -File -Recurse | ForEach-Object { $_.FullName }
 if ($cFiles.Count -eq 0) {
     Write-Error "No .c files found in '$src'"
     Remove-Item -Recurse -Force $buildDir -ErrorAction SilentlyContinue
     exit 1
 }
 
-Push-Location $buildDir
+$platform = [System.Runtime.InteropServices.RuntimeInformation]
+$extSuffix = ".dll"
+if ($platform::IsOSPlatform([System.Runtime.InteropServices.OSPlatform]::Linux)) {
+    $extSuffix = ".so"
+} elseif ($platform::IsOSPlatform([System.Runtime.InteropServices.OSPlatform]::OSX)) {
+    $extSuffix = ".dylib"
+}
 
+Push-Location $buildDir
 try {
-    # Build in temp dir; cl will place outputs in the current dir
-    $fe = "/Fe:prefix.exe"
-    $args = @("/std:c17", "/Gd", "/O2", "/Gy", "/GF", "/GL", "/W4", "/WX", "/MP", "/nologo", $fe)
-    $args += $cFiles
-
-    Write-Host "Invoking: cl.exe $($args -join ' ')"
-    & cl.exe @args
-    $rc = $LASTEXITCODE
-    if ($rc -ne 0) {
-        throw "cl.exe returned exit code $rc"
+    $exeArgs = @(
+        "/std:c17", "/Gd", "/O2", "/Gy", "/GF", "/GL", "/W4", "/WX", "/MP", "/nologo",
+        "/Fe:prefix.exe"
+    )
+    $exeArgs += $cFiles
+
+    Write-Host "Invoking: cl.exe $($exeArgs -join ' ')"
+    & cl.exe @exeArgs
+    if ($LASTEXITCODE -ne 0) {
+        throw "cl.exe returned exit code $LASTEXITCODE while building interpreter"
     }
 
-    # Copy EXE back to repo (Prefix-C root)
-    $outExe = Join-Path $buildDir 'prefix.exe'
+    $outExe = Join-Path $buildDir "prefix.exe"
     if (-not (Test-Path $outExe)) {
         throw "Expected output EXE not found: $outExe"
     }
-    $dest = Join-Path $script 'prefix.exe'
-    Copy-Item -Path $outExe -Destination $dest -Force
-    Write-Host "Copied EXE to: $dest"
 
+    $exeDest = Join-Path $script "prefix.exe"
+    Copy-Item -Path $outExe -Destination $exeDest -Force
+    Write-Host "Copied EXE to: $exeDest"
+
+    $extSources = @()
+    foreach ($root in $extRoots) {
+        if (Test-Path $root) {
+            $extSources += Get-ChildItem -Path $root -Filter *.c -File -Recurse
+        }
+    }
+
+    if ($extSources.Count -eq 0) {
+        Write-Host "No extension C sources found under ext/ or lib/."
+    } else {
+        Write-Host "Found $($extSources.Count) extension source file(s)."
+    }
+
+    foreach ($extSource in $extSources) {
+        $extSourcePath = $extSource.FullName
+        $extName = [System.IO.Path]::GetFileNameWithoutExtension($extSourcePath)
+        $extOutName = "$extName$extSuffix"
+        $extDest = Join-Path $extSource.DirectoryName $extOutName
+        $extBuildDir = Join-Path $buildDir ("ext-" + [guid]::NewGuid().ToString("N"))
+
+        New-Item -ItemType Directory -Path $extBuildDir -Force | Out-Null
+        Push-Location $extBuildDir
+        try {
+            $extArgs = @(
+                "/std:c17", "/Gd", "/O2", "/W4", "/WX", "/nologo", "/LD",
+                "/I$src",
+                "/Fe:$extOutName",
+                $extSourcePath
+            )
+
+            Write-Host "Invoking: cl.exe $($extArgs -join ' ')"
+            & cl.exe @extArgs
+            if ($LASTEXITCODE -ne 0) {
+                throw "cl.exe returned exit code $LASTEXITCODE while building extension '$extSourcePath'"
+            }
+
+            $extOutPath = Join-Path $extBuildDir $extOutName
+            if (-not (Test-Path $extOutPath)) {
+                throw "Expected output extension not found: $extOutPath"
+            }
+
+            Copy-Item -Path $extOutPath -Destination $extDest -Force
+            Write-Host "Copied extension to: $extDest"
+        } finally {
+            Pop-Location
+            Remove-Item -Recurse -Force $extBuildDir -ErrorAction SilentlyContinue
+        }
+    }
 } catch {
     Write-Error "Build failed: $_"
-    Pop-Location
-    # Cleanup temp build dir on failure as well
-    Write-Host "Cleaning up temp build dir: $buildDir"
-    Remove-Item -Recurse -Force $buildDir -ErrorAction SilentlyContinue
     exit 1
 } finally {
     Pop-Location
+    Write-Host "Cleaning up temp build dir: $buildDir"
+    Remove-Item -Recurse -Force $buildDir -ErrorAction SilentlyContinue
 }
 
-# Cleanup temp build dir
-Write-Host "Cleaning up temp build dir: $buildDir"
-Remove-Item -Recurse -Force $buildDir -ErrorAction SilentlyContinue
-
 Write-Host "Build succeeded and exe copied to: $(Join-Path $script 'prefix.exe')"
 exit 0

docs/SPECIFICATION.html

@@ -416,27 +416,34 @@
 
 - Program argument: the interpreter reads a single *program* argument as its input program. If the `-source` flag is not present, the program argument is interpreted as a path to a source file and the interpreter loads and parses that file. If the `-source` flag is present, the program argument is treated as the source text itself (a string containing the program) and is parsed directly without reading a file.
 
-- Extensions: the interpreter may also accept zero or more *extension* arguments that load Python extension modules before parsing and execution. Extensions may add new operators, new runtime types, and runtime hooks (including custom REPL implementations), but MUST NOT replace or modify existing built-in operators or types.
+- Extensions: the interpreter may also accept zero or more *extension* arguments that load compiled extension modules before parsing and execution. Extensions may add new operators, new runtime types, and runtime hooks (including custom REPL implementations), but MUST NOT replace or modify existing built-in operators or types.
 
-  - A Python extension is a `.py` file that defines `PREFIX_EXTENSION_API_VERSION = 1` (optional; defaults to 1) and a callable `prefix_register(ext)` entrypoint.
+  - A compiled extension is a platform-specific dynamically-linked library (`.dll` on Windows, `.so` on Unix/Linux, `.dylib` on macOS) built from C code. Extensions must define a single public C function with C calling convention: `void prefix_extension_init(struct prefix_ext_context *ctx)` that the interpreter invokes at load time to register operators, types, and hooks.
+  
+  - Extension API: Extensions include the public header `prefix_extension.h` which defines the extension API, including:
+    - `PREFIX_EXTENSION_API_VERSION`: a version constant that the extension must match (currently 1).
+    - Registration function pointers (supplied in `prefix_ext_context`) for registering operators: `register_operator(const char *name, prefix_operator_fn fn, int asmodule)`.
+    - Registration for type constructors and custom type hooks.
+    - Registration for event handlers: `on_event(const char *event_name, prefix_event_fn fn)` for events such as `program_start`, `program_end`, `on_error`, `before_statement`, `after_statement`, `before_call`, and `after_call`.
+    - Utilities for allocating and manipulating Prefix runtime values (`prefix_value_t`).
 
   - A pointer file is a `.prex` text file containing one extension path per line. Lines are trimmed; blank lines are ignored; lines beginning with `!` are comments. Relative paths are resolved relative to the `.prex` file's directory; when a referenced path is not found there the interpreter will also try the current working directory and, as a final fallback, the interpreter's own `ext/` subdirectory.
 
   - If a `.prex` file is supplied as an argument, all of the linked extensions are loaded.
 
   - If no explicit extension arguments are provided, the interpreter will automatically look for a pointer file named `.prex` in the current working directory. When a program path is being executed (not when `-source` is used), the interpreter also checks the program's directory for a `.prex` pointer file and will additionally accept a pointer file that shares the program's basename but ends with `.prex` (for example `program.pre` alongside `program.prex`). If any pointer file is found the extensions listed in that pointer file are loaded as if supplied on the command line.
 
-  - Extensions are loaded before parsing so that extension-defined type names are recognized in typed assignments and function signatures.
+  - Extensions are loaded before parsing so that extension-defined type names are recognized in typed assignments and function signatures. At load time, the interpreter uses platform-specific mechanisms (`LoadLibraryEx` on Windows, `dlopen` on Unix-like systems) to load the extension library, locates the `prefix_extension_init` symbol, invokes it with a context pointer, and records all registered operators and hooks.
 
   - If the only supplied positional inputs are extensions (and no program is supplied), the interpreter runs the REPL with the loaded extensions.
 
-  - Hook surfaces exposed by the reference implementation include:
+  - Hook surfaces and registration: Extensions register operators and hooks by calling registration functions provided in the `prefix_ext_context` structure. Supported operations include:
 
-    - Operators: additional call names dispatched like built-ins. Extensions may opt into module-qualifying all of their operators by defining the module-level flag `PREFIX_EXTENSION_ASMODULE = True`. When an extension sets this flag every operator it registers will be exposed under the extension's name as a dotted prefix (for example, an extension named `mymod` registering `FOO` will expose `mymod.FOO`). This mirrors imported module-qualified bindings and avoids global name collisions.
+    - Operators: Extensions call `register_operator(name, handler_fn, flags)` to add new operators dispatched like built-ins. The `flags` parameter includes `PREFIX_EXTENSION_ASMODULE` to opt into module-qualifying all of an extension's operators with the extension's name as a dotted prefix (for example, an extension named `mymod` registering `FOO` will expose `mymod.FOO`). This mirrors imported module-qualified bindings and avoids global name collisions.
 
-    - Per-N-steps rules: `every_n_steps(N, handler)` runs the handler after state-log step indices where `step_index % N == 0`.
+    - Per-N-steps rules: `register_periodic_hook(N, handler_fn)` registers a handler to run after state-log step indices where `step_index % N == 0`.
 
-    - Event-bound rules: `on_event(name, handler)` for the following event names:
+    - Event-bound rules: `register_event_handler(event_name, handler_fn)` for the following event names:
 
       - `program_start(interpreter, program, env)`
 
@@ -448,7 +455,7 @@
 
       - `before_call(interpreter, name, args, env, location)` / `after_call(interpreter, name, result, env, location)`
 
-    - REPL: extensions may provide a replacement REPL implementation.
+    - REPL: Extensions may register a custom REPL implementation via `register_repl_handler(repl_fn)`.
 
 - Verbose tracebacks: if the `-verbose` flag is supplied on the command line, tracebacks include the environment snapshots described in Section 10.8. In concise traceback mode the `-verbose` flag causes the interpreter to attach an `env_snapshot` entry to each frame shown; in verbose traceback mode the same flag expands the printed `State snapshot: blocks to include the selected local environment and any small set of globals included by policy. The snapshot contents follow the requirements in Section 10.2 and are suitable for deterministic replay.
 
@@ -464,15 +471,15 @@
 
 - Source-string mode: `prefix -source "foo = INPUT\nPRINT(foo)" -verbose`
 
-- With extensions (file mode): `prefix myext.py program.pre`
+- With compiled extension (file mode): `prefix myext.dll program.pre` (Windows) or `prefix myext.so program.pre` (Unix/Linux)
 
 - With pointer file: `prefix extensions.prex program.pre`
 
-- REPL / Interactive mode: `prefix` (no program argument), or `prefix myext.py` (extensions only)
+- REPL / Interactive mode: `prefix` (no program argument), or `prefix myext.dll` (extensions only)
 
 ## 11. REPL (Interactive Mode)
 
-When the interpreter is invoked without a program path or a `-source` string argument it enters an interactive read–eval–print loop (REPL). The REPL is a convenient development and exploration environment that executes Prefix statements using the same parser, runtime, built-ins, and state-logging semantics as file-mode execution. The following rules describe REPL behaviour:
+When the interpreter is invoked without a program path or a `-source` string argument it enters an interactive read-eval-print loop (REPL). The REPL is a convenient development and exploration environment that executes Prefix statements using the same parser, runtime, built-ins, and state-logging semantics as file-mode execution. The following rules describe REPL behaviour:
 
 - Invocation: running `prefix` with no program argument launches the REPL. If one or more extensions are supplied and no program argument is supplied, the interpreter launches a REPL with those extensions loaded; if an extension provides a replacement REPL, that REPL may be used.
 

src/builtins.c

@@ -6875,11 +6875,14 @@ static BuiltinFunction builtins_table[] = {
     {NULL, 0, 0, NULL}
 };
 
-void builtins_init(void) {
-    // Nothing to initialize for now, table is static
-}
+typedef struct DynamicBuiltin {
+    BuiltinFunction fn;
+    struct DynamicBuiltin* next;
+} DynamicBuiltin;
 
-BuiltinFunction* builtin_lookup(const char* name) {
+static DynamicBuiltin* g_dynamic_builtins = NULL;
+
+static BuiltinFunction* builtin_lookup_static(const char* name) {
     for (int i = 0; builtins_table[i].name != NULL; i++) {
         if (strcmp(builtins_table[i].name, name) == 0) {
             return &builtins_table[i];
@@ -6888,6 +6891,95 @@ BuiltinFunction* builtin_lookup(const char* name) {
     return NULL;
 }
 
+static BuiltinFunction* builtin_lookup_dynamic(const char* name) {
+    for (DynamicBuiltin* n = g_dynamic_builtins; n != NULL; n = n->next) {
+        if (n->fn.name && strcmp(n->fn.name, name) == 0) {
+            return &n->fn;
+        }
+    }
+    return NULL;
+}
+
+void builtins_reset_dynamic(void) {
+    DynamicBuiltin* n = g_dynamic_builtins;
+    while (n) {
+        DynamicBuiltin* next = n->next;
+        free((char*)n->fn.name);
+        if (n->fn.param_names) {
+            for (int i = 0; i < n->fn.param_count; i++) {
+                free((char*)n->fn.param_names[i]);
+            }
+            free((void*)n->fn.param_names);
+        }
+        free(n);
+        n = next;
+    }
+    g_dynamic_builtins = NULL;
+}
+
+int builtins_register_operator(const char* name, BuiltinImplFn impl, int min_args, int max_args, const char** param_names, int param_count) {
+    if (!name || name[0] == '\0' || !impl) return -1;
+    if (min_args < 0) return -1;
+    if (max_args >= 0 && max_args < min_args) return -1;
+    if (builtin_lookup_static(name) || builtin_lookup_dynamic(name)) {
+        return -1;
+    }
+
+    DynamicBuiltin* node = calloc(1, sizeof(DynamicBuiltin));
+    if (!node) return -1;
+
+    node->fn.name = strdup(name);
+    node->fn.min_args = min_args;
+    node->fn.max_args = max_args;
+    node->fn.impl = impl;
+    node->fn.param_names = NULL;
+    node->fn.param_count = 0;
+
+    if (!node->fn.name) {
+        free(node);
+        return -1;
+    }
+
+    if (param_names && param_count > 0) {
+        const char** copy_names = calloc((size_t)param_count, sizeof(char*));
+        if (!copy_names) {
+            free((char*)node->fn.name);
+            free(node);
+            return -1;
+        }
+        for (int i = 0; i < param_count; i++) {
+            if (!param_names[i]) {
+                copy_names[i] = strdup("");
+            } else {
+                copy_names[i] = strdup(param_names[i]);
+            }
+            if (!copy_names[i]) {
+                for (int j = 0; j < i; j++) free((char*)copy_names[j]);
+                free((void*)copy_names);
+                free((char*)node->fn.name);
+                free(node);
+                return -1;
+            }
+        }
+        node->fn.param_names = copy_names;
+        node->fn.param_count = param_count;
+    }
+
+    node->next = g_dynamic_builtins;
+    g_dynamic_builtins = node;
+    return 0;
+}
+
+void builtins_init(void) {
+    // Nothing to initialize for now, table is static
+}
+
+BuiltinFunction* builtin_lookup(const char* name) {
+    BuiltinFunction* b = builtin_lookup_static(name);
+    if (b) return b;
+    return builtin_lookup_dynamic(name);
+}
+
 bool is_builtin(const char* name) {
     return builtin_lookup(name) != NULL;
 }

src/builtins.h

@@ -8,11 +8,13 @@
 // Forward declaration
 typedef struct Interpreter Interpreter;
 
+typedef Value (*BuiltinImplFn)(Interpreter* interp, Value* args, int argc, Expr** arg_nodes, Env* env, int line, int col);
+
 typedef struct {
     const char* name;
     int min_args;
     int max_args;  // -1 for variadic
-    Value (*impl)(Interpreter* interp, Value* args, int argc, Expr** arg_nodes, Env* env, int line, int col);
+    BuiltinImplFn impl;
     // Optional: parameter names for keyword argument binding.
     // If NULL/0, the builtin does not accept keyword arguments.
     const char** param_names;
@@ -31,4 +33,11 @@ BuiltinFunction* builtin_lookup(const char* name);
 // Check if a name is a builtin
 bool is_builtin(const char* name);
 
+// Register a runtime builtin operator (used by extensions).
+// Returns 0 on success, -1 on failure (duplicate/invalid input/oom).
+int builtins_register_operator(const char* name, BuiltinImplFn impl, int min_args, int max_args, const char** param_names, int param_count);
+
+// Remove all runtime-registered operators.
+void builtins_reset_dynamic(void);
+
 #endif // BUILTINS_H