Enhance IMPORT functionality to support optional aliasing and improve extension loading mechanism

Author: python-processing-unit

SPECIFICATION.html

@@ -247,6 +247,7 @@
   - 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.
   - 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 and, when a program path is being executed (not when `-source` is used), in the program's directory; if 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:
@@ -392,13 +393,13 @@
 - `CLOG(INT: a):INT` ; ceil(log2(a)) for a > 0
 
 ### Module operations:
-- `IMPORT(MODULE: name)` — Loads another source file and provides it as a distinct module namespace.
+- `IMPORT(MODULE: name)` or `IMPORT(MODULE: name, SYMBOL: alias)` — Loads another source file and exposes it as a distinct module namespace. When an optional alias identifier is supplied, the imported module's bindings are exposed under the `alias` prefix rather than the module's own name (for example, `IMPORT(mod, ali)` makes `ali.F()` valid while `mod.F()` is not).
 
-  The argument must be an identifier naming a module; the interpreter first looks for a file named `<name>.asmln` in the same directory as the referring source file. When the referring source is provided via the `-source` string literal mode, the primary search directory is the process's current working directory. If the module file is not found there, the interpreter will additionally attempt to load the file from a `lib` subdirectory located alongside the interpreter implementation (that is, `<interpreter_dir>/lib/<name>.asmln`, where `<interpreter_dir>` is the directory containing the interpreter script or executable).
+  The first argument must be an identifier naming a module; the interpreter first looks for a file named `<name>.asmln` in the same directory as the referring source file. When the referring source is provided via the `-source` string literal mode, the primary search directory is the process's current working directory. If the module file is not found there, the interpreter will additionally attempt to load the file from a `lib` subdirectory located alongside the interpreter implementation (that is, `<interpreter_dir>/lib/<name>.asmln`, where `<interpreter_dir>` is the directory containing the interpreter script or executable).
 
   The imported file is parsed and executed in its own isolated top-level environment on the first import during a given interpreter invocation: top-level assignments and function definitions in the imported module do not directly mutate the caller's environment during execution. During that execution unqualified identifiers (for example, `x` or `helper`) refer to names in the module's own top-level namespace. Qualified identifiers (for example, `other.FOO`) refer only to the dotted names that the module itself has created or imported; those qualified bindings are scoped to the module's namespace.
 
-  After the module finishes executing the first time, the interpreter caches the module's top-level environment and the module-qualified function objects. Subsequent `IMPORT` calls for the same module identifier within the same interpreter process reuse that cached namespace/instance and do not re-execute the module source. Callers importing the same module later will observe the same shared module environment (that is, the same binding objects and the same function objects) exposed under the dotted names (`module.FOO`, `module.bar`, etc.). If the module imported other modules during its execution, those nested qualified bindings are preserved in the cached namespace and remain accessible via the same dotted paths (for example, `module.other.SYM`).
+  After the module finishes executing the first time, the interpreter caches the module's top-level environment and the module-qualified function objects. Subsequent `IMPORT` calls for the same module identifier within the same interpreter process reuse that cached namespace/instance and do not re-execute the module source. Callers importing the same module later will observe the same shared module environment (that is, the same binding objects and the same function objects). By default bindings are exposed under the module's own dotted prefix (`module.FOO`, `module.bar`, etc.); however, if the importer supplied an alias the bindings are instead exposed under the alias prefix (`alias.FOO`, `alias.bar`). Multiple different aliases for the same module identifier will each get their own dotted view into the same cached module instance. If the module imported other modules during its execution, those nested qualified bindings are preserved in the cached namespace and remain accessible via the same dotted paths (for example, `module.other.SYM` or `alias.other.SYM` or `module.alias.SYM`).
 
   This caching behavior ensures that importing a module multiple times produces the same shared module namespace instance for all importers. The interpreter does not automatically perform cycle detection beyond using the cached instance once execution has completed; careful module design should avoid import cycles where possible.
 - `EXPORT(SYMBOL: symbol, MODULE: module):INT` — Adds the caller's binding for the identifier `symbol` into the namespace of the imported module named by the identifier `module`. The first argument must be an identifier (not a string literal); its current value in the caller's environment is copied into the imported module's namespace and becomes available as the qualified name `module.symbol` in the caller's environment. The second argument must be an identifier naming a previously-imported module; if the module has not been imported yet, the interpreter raises a runtime error (rewrite: EXPORT). `EXPORT` returns `INT` 0 on success.

asm-lang.exe

@@ -3,6 +3,7 @@
 from __future__ import annotations
 import argparse
 import sys
+import os
 from typing import List, Optional
 
 from extensions import ASMExtensionError, ReplContext, load_runtime_services
@@ -138,6 +139,26 @@ def run_cli(argv: Optional[List[str]] = None) -> int:
         else:
             remaining.append(item)
 
+    # Initialize `program` early so subsequent checks can reference it safely.
+    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
+    # 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")
+        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.
+            if program and not args.source_mode:
+                program_dir = os.path.dirname(os.path.abspath(program))
+                program_asmx = os.path.join(program_dir, ".asmx")
+                if os.path.exists(program_asmx):
+                    ext_paths.append(program_asmx)
+
     try:
         services = load_runtime_services(ext_paths) if ext_paths else load_runtime_services([])
     except ASMExtensionError as exc:

asm-lang.py

@@ -365,7 +365,7 @@ def __init__(self) -> None:
         self._register_custom("REPLACE", 3, 3, self._replace)
         self._register_custom("MAIN", 0, 0, self._main)
         self._register_custom("OS", 0, 0, self._os)
-        self._register_custom("IMPORT", 1, 1, self._import)
+        self._register_custom("IMPORT", 1, 2, self._import)
         self._register_custom("RUN", 1, 1, self._run)
         self._register_custom("INPUT", 0, 1, self._input)
         self._register_custom("PRINT", 0, None, self._print)
@@ -900,10 +900,17 @@ def _import(
         env: Environment,
         location: SourceLocation,
     ) -> Value:
-        if len(arg_nodes) != 1 or not isinstance(arg_nodes[0], Identifier):
+        # Accept either IMPORT(module) or IMPORT(module, alias)
+        if len(arg_nodes) not in (1, 2) or not isinstance(arg_nodes[0], Identifier):
             raise ASMRuntimeError("IMPORT expects module name identifier", location=location, rewrite_rule="IMPORT")
 
         module_name = arg_nodes[0].name
+        if len(arg_nodes) == 2:
+            if not isinstance(arg_nodes[1], Identifier):
+                raise ASMRuntimeError("IMPORT alias must be an identifier", location=location, rewrite_rule="IMPORT")
+            export_prefix = arg_nodes[1].name
+        else:
+            export_prefix = module_name
         # If module was already imported earlier in this interpreter instance,
         # reuse the same Environment and function objects so all importers
         # observe the same namespace/instance.
@@ -913,9 +920,25 @@ def _import(
             for fn in interpreter.module_functions.get(module_name, []):
                 if fn.name not in interpreter.functions:
                     interpreter.functions[fn.name] = fn
+                # Also register alias-qualified function names when an alias was requested
+                if export_prefix != module_name:
+                    # fn.name is module_name.func; produce alias.func
+                    parts = fn.name.split(".", 1)
+                    if len(parts) == 2:
+                        _, unqualified = parts
+                        alias_name = f"{export_prefix}.{unqualified}"
+                        if alias_name not in interpreter.functions:
+                            created = Function(
+                                name=alias_name,
+                                params=fn.params,
+                                return_type=fn.return_type,
+                                body=fn.body,
+                                closure=cached_env,
+                            )
+                            interpreter.functions[alias_name] = created
 
             for k, v in cached_env.values.items():
-                dotted = f"{module_name}.{k}"
+                dotted = f"{export_prefix}.{k}"
                 env.set(dotted, v, declared_type=v.type)
             return Value(TYPE_INT, 0)
 
@@ -981,6 +1004,25 @@ def _import(
                 interpreter.functions[dotted_name] = created
                 registered_functions.append(created)
 
+        # If the caller requested an alias different from the module name,
+        # also register alias-qualified function entries pointing to the
+        # same function bodies so callers can invoke e.g. ALIAS.F().
+        if export_prefix != module_name:
+            for fn in registered_functions:
+                parts = fn.name.split(".", 1)
+                if len(parts) == 2:
+                    _, unqualified = parts
+                    alias_name = f"{export_prefix}.{unqualified}"
+                    if alias_name not in interpreter.functions:
+                        alias_fn = Function(
+                            name=alias_name,
+                            params=fn.params,
+                            return_type=fn.return_type,
+                            body=fn.body,
+                            closure=module_env,
+                        )
+                        interpreter.functions[alias_name] = alias_fn
+
         # Store module env and functions into the interpreter cache for reuse
         interpreter.module_cache[module_name] = module_env
         interpreter.module_functions[module_name] = registered_functions