Update extension handling to support new .asmxt pointer files and module-qualified operators

Author: python-processing-unit

SPECIFICATION.html

@@ -245,13 +245,20 @@
 
 - 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.
   - A Python extension is a `.py` file that defines `ASM_LANG_EXTENSION_API_VERSION = 1` (optional; defaults to 1) and a callable `asm_lang_register(ext)` entrypoint.
-  - A pointer file is a `.asmx` 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 `.asmx` 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 `.asmx` 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 `.asmx` 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 `.asmx` pointer file and will additionally accept a pointer file that shares the program's basename but ends with `.asmx` (for example `program.asmln` alongside `program.asmx`). If any pointer file is found the extensions listed in that pointer file are loaded as if supplied on the command line.
+  - A pointer file is a `.asmxt` 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 `.asmxt` 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 `.asmxt` 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 `.asmxt` 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 `.asmxt` pointer file and will additionally accept a pointer file that shares the program's basename but ends with `.asmxt` (for example `program.asmln` alongside `program.asmxt`). 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.
   - 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:
     - Operators: additional call names dispatched like built-ins.
+      Extensions may opt into module-qualifying all of their operators by
+      defining the module-level flag `ASM_LANG_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.
     - Per-N-steps rules: `every_n_steps(N, handler)` runs the handler after state-log step indices where `step_index % N == 0`.
     - Event-bound rules: `on_event(name, handler)` for the following event names:
       - `program_start(interpreter, program, env)`
@@ -270,7 +277,7 @@
 - File mode: `asm-lang program.asmln`
 - Source-string mode: `asm-lang -source "foo = INPUT\nPRINT(foo)" -verbose`
 - With extensions (file mode): `asm-lang myext.py program.asmln`
-- With pointer file: `asm-lang extensions.asmx program.asmln`
+- With pointer file: `asm-lang extensions.asmxt program.asmln`
 
 - REPL / Interactive mode: `asm-lang` (no program argument), or `asm-lang myext.py` (extensions only)
 

asm-lang.exe

@@ -122,8 +122,8 @@ def _output_sink(text: str) -> None:
 
 def run_cli(argv: Optional[List[str]] = None) -> int:
     parser = argparse.ArgumentParser(description="ASM-Lang reference interpreter")
-    parser.add_argument("inputs", nargs="*", help="Program path/source and/or extension files (.py/.asmx)")
-    parser.add_argument("--ext", action="append", default=[], help="Extension path (.py) or pointer file (.asmx)")
+    parser.add_argument("inputs", nargs="*", help="Program path/source and/or extension files (.py/.asmxt)")
+    parser.add_argument("--ext", action="append", default=[], help="Extension path (.py) or pointer file (.asmxt)")
     parser.add_argument("-source", "--source", dest="source_mode", action="store_true", help="Treat program argument as literal source text")
     parser.add_argument("-verbose", "--verbose", dest="verbose", action="store_true", help="Emit env snapshots in tracebacks")
     parser.add_argument("--traceback-json", action="store_true", help="Also emit JSON traceback")
@@ -134,7 +134,7 @@ def run_cli(argv: Optional[List[str]] = None) -> int:
     remaining: List[str] = []
     for item in inputs:
         lower = item.lower()
-        if lower.endswith(".py") or lower.endswith(".asmx"):
+        if lower.endswith(".py") or lower.endswith(".asmxt"):
             ext_paths.append(item)
         else:
             remaining.append(item)
@@ -143,26 +143,26 @@ def run_cli(argv: Optional[List[str]] = None) -> int:
     program: Optional[str] = remaining[0] if remaining else None
 
     # If the caller didn't specify any extensions, look for a pointer file named
-    # ".asmx" in the current working directory or (when a program file was
+    # ".asmxt" in the current working directory or (when a program file was
     # provided) in the program's directory. If found, use it as the extension
     # pointer file so the interpreter loads the extensions it points to.
     if not ext_paths:
-        cwd_asmx = os.path.abspath(".asmx")
+        cwd_asmx = os.path.abspath(".asmxt")
         if os.path.exists(cwd_asmx):
             ext_paths.append(cwd_asmx)
         else:
             # If a program path was given (and isn't literal source text),
-            # also check the program's directory for a .asmx pointer file.
+            # also check the program's directory for a .asmxt pointer file.
             if program and not args.source_mode:
                 program_dir = os.path.dirname(os.path.abspath(program))
-                program_asmx = os.path.join(program_dir, ".asmx")
+                program_asmx = os.path.join(program_dir, ".asmxt")
                 if os.path.exists(program_asmx):
                     ext_paths.append(program_asmx)
                 else:
                     # Also accept a pointer file that shares the program's
-                    # basename but uses the .asmx extension instead of the
-                    # program extension (e.g. program.asmln -> program.asmx).
-                    program_alt_asmx = os.path.splitext(os.path.abspath(program))[0] + ".asmx"
+                    # basename but uses the .asmxt extension instead of the
+                    # program extension (e.g. program.asmln -> program.asmxt).
+                    program_alt_asmx = os.path.splitext(os.path.abspath(program))[0] + ".asmxt"
                     if os.path.exists(program_alt_asmx):
                         ext_paths.append(program_alt_asmx)
 

asm-lang.py

@@ -18,6 +18,7 @@
 
 ASM_LANG_EXTENSION_NAME = "gc"
 ASM_LANG_EXTENSION_API_VERSION = 1
+ASM_LANG_EXTENSION_ASMODULE = False
 
 
 # ---- Interpreter monkeypatching ----

ext/gc.py

@@ -37,6 +37,7 @@
 
 ASM_LANG_EXTENSION_NAME = "networking"
 ASM_LANG_EXTENSION_API_VERSION = 1
+ASM_LANG_EXTENSION_ASMODULE = True
 
 
 # ---- Value helpers (import lazily inside operators to avoid cycles) ----

ext/networking.py

@@ -24,6 +24,7 @@
 
 ASM_LANG_EXTENSION_API_VERSION = 1
 ASM_LANG_EXTENSION_NAME = "wasapi"
+ASM_LANG_EXTENSION_ASMODULE = True
 
 
 if sys.platform != "win32":

ext/wasapi.py

@@ -27,6 +27,7 @@
 
 ASM_LANG_EXTENSION_NAME = "win32"
 ASM_LANG_EXTENSION_API_VERSION = 1
+ASM_LANG_EXTENSION_ASMODULE = True
 
 
 def _ensure_windows() -> None:

ext/win32.py

@@ -0,0 +1,2 @@
+win32.py
+wasapi.py

ext/windows.asmxt

@@ -153,9 +153,10 @@ class RuntimeServices:
 
 
 class ExtensionAPI:
-    def __init__(self, *, services: RuntimeServices, ext_name: str) -> None:
+    def __init__(self, *, services: RuntimeServices, ext_name: str, asmodule: bool = False) -> None:
         self._services = services
         self._ext_name = ext_name
+        self._asmodule = bool(asmodule)
 
     # ---- metadata ----
     def metadata(self, *, name: str, version: str = "0.0.0", requires_api: int = EXTENSION_API_VERSION) -> None:
@@ -173,7 +174,12 @@ def register_operator(
     ) -> None:
         if not name:
             raise ASMExtensionError("Operator name must be non-empty")
-        self._services.operators.append((name, int(min_args), None if max_args is None else int(max_args), impl, doc))
+        qualified = name
+        if self._asmodule:
+            prefix = str(self._ext_name)
+            if not qualified.startswith(prefix + "."):
+                qualified = f"{prefix}.{qualified}"
+        self._services.operators.append((qualified, int(min_args), None if max_args is None else int(max_args), impl, doc))
 
     def operator(self, name: str, min_args: int, max_args: Optional[int] = None, *, doc: str = ""):
         def deco(fn: Callable[..., Any]) -> Callable[..., Any]:
@@ -287,7 +293,7 @@ def load_extension_module(path: str) -> Any:
 
 def read_asmx(pointer_file: str) -> List[str]:
     if not os.path.exists(pointer_file):
-        raise ASMExtensionError(f".asmx file not found: {pointer_file}")
+        raise ASMExtensionError(f".asmxt file not found: {pointer_file}")
     base_dir = os.path.dirname(os.path.abspath(pointer_file))
     out: List[str] = []
     with open(pointer_file, "r", encoding="utf-8") as handle:
@@ -328,7 +334,7 @@ def read_asmx(pointer_file: str) -> List[str]:
 def gather_extension_paths(paths: Sequence[str]) -> List[str]:
     expanded: List[str] = []
     for p in paths:
-        if p.lower().endswith(".asmx"):
+        if p.lower().endswith(".asmxt"):
             # Resolve pointer file path (absolute if possible) and expand it.
             pointer = p
             if not os.path.isabs(pointer):
@@ -372,6 +378,7 @@ def load_runtime_services(paths: Sequence[str]) -> RuntimeServices:
         if register is None or not callable(register):
             raise ASMExtensionError(f"Extension {path} must define callable asm_lang_register(ext)")
         ext_name = getattr(module, "ASM_LANG_EXTENSION_NAME", os.path.splitext(os.path.basename(path))[0])
-        ext = ExtensionAPI(services=services, ext_name=str(ext_name))
+        ext_asmodule = bool(getattr(module, "ASM_LANG_EXTENSION_ASMODULE", False))
+        ext = ExtensionAPI(services=services, ext_name=str(ext_name), asmodule=ext_asmodule)
         register(ext)
     return services