A lot.

Get a diff of spec.txt.
That should tell you evetything you need to know.
HINT: It involves a REPL

Author: python-processing-unit

asmln.exe

@@ -3,6 +3,7 @@
 import argparse
 import json
 import math
+import os
 import sys
 from dataclasses import dataclass
 from typing import Any, Callable, Dict, Iterable, List, Optional
@@ -83,8 +84,11 @@ def tokenize(self) -> List[Token]:
                 tokens.append(Token(SYMBOLS[ch],ch,self.line,self.column))
                 self._advance()
                 continue
+            if(ch == "-"):
+                tokens.append(self._consume_signed_number())
+                continue
             if(ch in "01"):
-                tokens.append(self._consume_number())
+                tokens.append(self._consume_unsigned_number())
                 continue
             if(self._is_identifier_start(ch)):
                 tokens.append(self._consume_identifier())
@@ -95,13 +99,27 @@ def tokenize(self) -> List[Token]:
     def _consume_comment(self) -> None:
         while(not self._eof and self._peek() != "\n"):
             self._advance()
-    def _consume_number(self) -> Token:
+    def _consume_unsigned_number(self) -> Token:
+        line, col = self.line, self.column
+        digits = self._consume_binary_digits()
+        return(Token("NUMBER",digits,line,col))
+
+    def _consume_signed_number(self) -> Token:
         line, col = self.line, self.column
+        self._advance()  # consume '-'
+        while(not self._eof and self._peek() in " \t\r"):
+            self._advance()
+        if(self._eof or self._peek() not in "01"):
+            raise ASMParseError(f"Expected binary digits after '-' at {self.filename}:{line}:{col}")
+        digits = self._consume_binary_digits()
+        return(Token("NUMBER","-" + digits,line,col))
+
+    def _consume_binary_digits(self) -> str:
         digits: List[str] = []
         while(not self._eof and self._peek() in "01"):
             digits.append(self._peek())
             self._advance()
-        return(Token("NUMBER","".join(digits),line,col))
+        return "".join(digits)
     def _consume_identifier(self) -> Token:
         line, col = self.line, self.column
         chars: List[str] = []
@@ -480,6 +498,8 @@ def __init__(self) -> None:
         self._register_variadic("LEN", 0, lambda vals: len(vals))
         self._register_fixed("LOG", 1, self._safe_log)
         self._register_fixed("CLOG", 1, self._safe_clog)
+        self._register_custom("MAIN", 0, 0, self._main)
+        self._register_custom("IMPORT", 1, 1, self._import)
         self._register_custom("INPUT", 0, 0, self._input)
         self._register_custom("PRINT", 0, None, self._print)
         self._register_custom("ASSERT", 1, 1, self._assert)
@@ -557,6 +577,49 @@ def _safe_clog(self, value: int) -> int:
             return value.bit_length() - 1
         return value.bit_length()
 
+    def _main(
+        self,
+        interpreter: "Interpreter",
+        _: List[int],
+        __: List[Expression],
+        ___: Environment,
+        location: SourceLocation,
+    ) -> int:
+        # Return 1 when the call originates from the primary program file, else 0.
+        root = interpreter.entry_filename
+        if root == "<string>":
+            return 1 if location.file == "<string>" else 0
+        return 1 if os.path.abspath(location.file) == root else 0
+
+    def _import(
+        self,
+        interpreter: "Interpreter",
+        _: List[int],
+        arg_nodes: List[Expression],
+        env: Environment,
+        location: SourceLocation,
+    ) -> int:
+        if len(arg_nodes) != 1 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
+        base_dir = os.getcwd() if location.file == "<string>" else os.path.dirname(os.path.abspath(location.file))
+        module_path = os.path.join(base_dir, f"{module_name}.asmln")
+
+        try:
+            with open(module_path, "r", encoding="utf-8") as handle:
+                source_text = handle.read()
+        except OSError as exc:
+            raise ASMRuntimeError(f"Failed to import '{module_name}': {exc}", location=location, rewrite_rule="IMPORT")
+
+        lexer = Lexer(source_text, module_path)
+        tokens = lexer.tokenize()
+        parser = Parser(tokens, module_path, source_text.splitlines())
+        program = parser.parse()
+
+        interpreter._execute_block(program.statements, env)
+        return 0
+
     def _slice(self, a: int, hi: int, lo: int) -> int:
         if hi < lo:
             raise ASMRuntimeError("SLICE: hi must be >= lo", rewrite_rule="SLICE")
@@ -645,7 +708,9 @@ def __init__(
         output_sink: Optional[Callable[[str], None]] = None,
     ) -> None:
         self.source = source
-        self.filename = filename
+        normalized_filename = filename if filename == "<string>" else os.path.abspath(filename)
+        self.filename = normalized_filename
+        self.entry_filename = normalized_filename
         self.verbose = verbose
         self.input_provider = input_provider or (lambda: input(">>> "))
         self.output_sink = output_sink or (lambda text: print(text))
@@ -742,6 +807,17 @@ def _evaluate_expression(self, expression: Expression, env: Environment) -> int:
                     return(result)
                 raise
         if(isinstance(expression,CallExpression)):
+            if(expression.name == "IMPORT"):
+                module_label = expression.args[0].name if (expression.args and isinstance(expression.args[0], Identifier)) else None
+                dummy_args:List[int] = [0] * len(expression.args)
+                try:
+                    result:int = self.builtins.invoke(self,expression.name,dummy_args,expression.args,env,expression.location)
+                except ASMRuntimeError:
+                    self._log_step(rule="IMPORT",location=expression.location,extra={"module": module_label,"status": "error"})
+                    raise
+                self._log_step(rule="IMPORT",location=expression.location,extra={"module": module_label,"result": result})
+                return(result)
+
             args:List[int] = []
             for arg in expression.args:
                 args.append(self._evaluate_expression(arg,env))
@@ -873,12 +949,92 @@ def to_json(self, error: ASMRuntimeError) -> str:
         }
         return json.dumps(data, indent=2)
 def run_cli(argv: Optional[List[str]] = None) -> int:
+    def _parse_statements_from_source(text: str, filename: str) -> List[Statement]:
+        lexer = Lexer(text, filename)
+        tokens = lexer.tokenize()
+        parser = Parser(tokens, filename, text.splitlines())
+        program = parser.parse()
+        return program.statements
+
+    def run_repl(verbose: bool) -> int:
+        print("ASM-Lang REPL. Enter statements, blank line to run buffer.")
+        interpreter = Interpreter(source="", filename="<repl>", verbose=verbose)
+        global_env = Environment()
+        global_frame = interpreter._new_frame("<repl>", global_env, None)
+        interpreter.call_stack.append(global_frame)
+        buffer: List[str] = []
+
+        while True:
+            prompt = ">>> " if not buffer else "..> "
+            try:
+                line = input(prompt)
+            except EOFError:
+                print()
+                break
+
+            stripped = line.strip()
+
+            # If buffer is empty, try to execute single-line statements immediately
+            # (so EXIT() exits without needing a blank line). Buffer multi-line
+            # constructs that start blocks (FUNC, IF, WHILE, FOR) or explicit
+            # bracket starts.
+            is_block_start = False
+            if not buffer:
+                uc = stripped.upper()
+                if uc.startswith("FUNC") or uc.startswith("IF") or uc.startswith("WHILE") or uc.startswith("FOR"):
+                    is_block_start = True
+                if stripped.endswith("[") or stripped.endswith("{"):
+                    is_block_start = True
+
+            if not buffer and stripped != "" and not is_block_start:
+                # try execute this single line immediately
+                try:
+                    statements = _parse_statements_from_source(line, "<repl>")
+                    try:
+                        interpreter._execute_block(statements, global_env)
+                    except ExitSignal as sig:
+                        return sig.code
+                except ASMParseError as error:
+                    # If parse error, fall back to buffering the line to allow
+                    # multi-line input (user may be starting a block).
+                    buffer.append(line)
+                continue
+
+            if stripped == "" and buffer:
+                source_text = "\n".join(buffer)
+                buffer.clear()
+                try:
+                    statements = _parse_statements_from_source(source_text, "<repl>")
+                    interpreter._execute_block(statements, global_env)
+                except ExitSignal as sig:
+                    return sig.code
+                except ASMParseError as error:
+                    print(f"ParseError: {error}", file=sys.stderr)
+                except ASMRuntimeError as error:
+                    if interpreter.logger.entries:
+                        error.step_index = interpreter.logger.entries[-1].step_index
+                    formatter = TracebackFormatter(interpreter)
+                    print(formatter.format_text(error, verbose=interpreter.verbose), file=sys.stderr)
+                    interpreter.call_stack = [global_frame]
+                continue
+
+            buffer.append(line)
+
+        return 0
+
     parser = argparse.ArgumentParser(description="ASM-Lang reference interpreter")
-    parser.add_argument("program", help="Source file path or literal source with -source")
+    parser.add_argument("program", nargs="?", help="Source file path or literal source with -source")
     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")
     args = parser.parse_args(argv)
+
+    if args.program is None:
+        if args.source_mode:
+            print("-source requires a program string", file=sys.stderr)
+            return 1
+        return run_repl(verbose=args.verbose)
+
     if args.source_mode:
         source_text = args.program
         filename = "<string>"
@@ -906,4 +1062,4 @@ def run_cli(argv: Optional[List[str]] = None) -> int:
         return 1
     return 0
 if __name__ == "__main__":
-    raise SystemExit(run_cli())
+    raise SystemExit(run_cli())

asmln.py

@@ -10,12 +10,6 @@ state-transition (rewrite) function. All intermediate states are
 exactly, including I/O and nondeterministic choices, which are modeled
 explicitly for deterministic replay.
 
-Note: Builds should not refer to this language by any proper name,
-as none has been specified yet. If a name is needed
-(e.g. for a filename), use ASM-Lang (Abstract State Machine Language) as a
-placeholder.
-
-
 1. Overview
 -----------
 
@@ -58,6 +52,12 @@ function names (Section 2.5); keywords and built-ins (control-flow
 keywords, built-in operators and functions; see Sections 4 and 5); and
 delimiters, namely '(', ')', '[', ']', '{', '}', ',', and '='.
 
+The character '-' is not an operator token. It is permitted only as the
+leading sign of a binary integer literal (Section 3.1). If '-' appears
+anywhere else, the lexer must raise a syntax error. When '-' starts a
+literal, any spaces, horizontal tabs, or carriage returns between the '-'
+and the first digit are ignored and the literal is treated as negative.
+
 Identifiers denote variables and user-defined functions. They must be
 non-empty and case-sensitive. An identifier must not contain non-ASCII
 characters, nor any of the following characters: '{', '}', '[', ']', '(',
@@ -71,10 +71,13 @@ with the name of any built-in operator or function (see Section 4.1).
 -------------
 
 The sole literal data type is the binary integer. A binary integer literal is
-a non-empty sequence of characters drawn from the set '{0,1}' (for example,
-'0', '1', '1011', '100110'). There is no syntactic sign ('+' or '-') for
-literals; sign, if modeled, is an implementation detail (such as two’s
-complement) and does not affect the syntax.
+either (1) an unsigned non-empty sequence of characters drawn from the set
+'{0,1}' (for example, '0', '1', '1011', '100110'), or (2) a signed literal
+formed by a leading '-' followed by optional whitespace (spaces, horizontal
+tabs, or carriage returns) and then a non-empty sequence of '{0,1}'. The '-'
+is part of the literal spelling and is not an operator; it may only appear in
+this leading position. A '-' that is not immediately introducing a literal is
+a syntax error.
 
 Every runtime value is a mathematical integer. The language does not support
 fractional or real-valued numbers. All operations that would otherwise
@@ -174,6 +177,17 @@ position, and any return value is discarded. The effect on the external
 world is recorded in the execution log, ensuring that replay remains
 deterministic.
 
+'IMPORT(name)' loads and executes another source file inside the caller's
+namespace. The argument must be an identifier naming a module; the
+interpreter looks for a file named '<name>.asmln' in the same directory as
+the current source file. When the current source is provided via the
+'-source' string literal mode, the search directory is the process's current
+working directory. The imported file is parsed and run as if its top-level
+statements appeared inline at the call site: assignments affect the caller's
+environment, and any functions defined in the imported module become
+available to the caller. Each 'IMPORT' call executes the target module anew;
+there is no automatic caching or cycle detection.
+
 'INPUT()' (or simply 'INPUT' in expression position) reads a value from the
 console or input stream. If the incoming text is empty, the result is '0'.
 If the text consists solely of the characters '0' and '1', it is interpreted
@@ -185,6 +199,12 @@ log for deterministic replay.
 non-zero, execution proceeds normally; if 'a' is '0', the program crashes
 with an assertion failure.
 
+'MAIN()' returns '1' when the call site belongs to the primary program file
+(the file passed as the interpreter's first argument, or '<string>' when
+'-source' is used). It returns '0' when executed from code that came from an
+'IMPORT' (including nested imports). The result is determined solely by the
+source file that contains the call expression, not by the caller's call stack.
+
 Program termination is exposed via 'EXIT'. 'EXIT()' or 'EXIT(code)' requests
 immediate termination of the interpreter. If an integer 'code' is supplied,
 it is used as the interpreter's process exit code; otherwise '0' is used.
@@ -550,6 +570,54 @@ full `rewrite_record` describing the DIV operation that failed.
   - File mode: `interpreter program.asm`
   - Source-string mode: `interpreter -source "foo = INPUT\nPRINT(foo)" -verbose`
 
+  - REPL / Interactive mode: `interpreter` (no program argument)
+
+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 ASM-Lang
+statements using the same parser, runtime, built-ins, and state-logging
+semantics as file-mode execution. The following rules describe REPL
+behaviour:
+
+- Invocation: running `interpreter` with no positional `program` argument
+  launches the REPL. The `-verbose` and `--traceback-json` flags keep the
+  same meanings in the REPL as in batch mode.
+- Prompting and input: the REPL presents a primary prompt for new top-level
+  input and a continuation prompt while the user is entering a multi-line
+  block (for example, the body of `FUNC`, `IF`, `WHILE`, or `FOR`).
+- Single-line execution: when the user enters a single complete top-level
+  statement (for example `x = 1010` or `PRINT(x)`), the REPL parses and
+  executes that statement immediately and prints any side-effect output.
+  This means `EXIT()` typed as a single-line statement will terminate the
+  REPL immediately and return the supplied exit code (or `0` if omitted),
+  identical to the behaviour when `EXIT()` is executed in a file.
+- Multi-line buffering: if a statement begins a block (for example a `FUNC`
+  definition or an `IF(...)[` that spans multiple lines), the REPL buffers
+  lines until the block is complete (a blank line may be used to indicate
+  end-of-entry when appropriate). When the buffer is complete the REPL
+  parses and executes the collected statements as a unit.
+- Environment persistence: variables, function definitions, and the state
+  logger persist for the duration of the REPL session (that is, top-level
+  bindings remain available across successive inputs until explicitly
+  deleted with `DEL(name)`). This lets the user incrementally build up a
+  program interactively.
+- Deterministic logging and tracebacks: all REPL-executed statements are
+  recorded in the same state log format used for file-mode execution. Errors
+  produce tracebacks in the same concise and verbose modes; the `-verbose`
+  flag causes the REPL to attach `env_snapshot` entries in tracebacks when
+  available.
+
+Notes and examples:
+- Start REPL: `interpreter`
+- Exit via meta-command: type `.exit` or press Ctrl-D (EOF)
+- Exit programmatically: `EXIT()` — this immediately terminates the
+  interpreter and returns the specified exit code to the shell, just like in
+  batch execution.
+
+
 APIREF — Quick Reference
 ------------------------
 
@@ -561,8 +629,11 @@ Function / Operator Signatures (expression position)
 - 'INPUT()' or 'INPUT' : returns integer from input stream (0 for empty)
 - 'PRINT(a1, a2, ..., aN)' : prints arguments (side-effect), return value discarded
 - 'ASSERT(a)' : crashes if 'a' is 0
+- 'MAIN()' : 1 if executing in the primary program file, else 0 when in imported code
 - 'DEL(x)' : delete variable 'x' from environment
 - 'EXIT()' or 'EXIT(code)' : terminate program immediately with optional exit code (default 0)
+- 'IMPORT(name)' : load and execute '<name>.asmln' beside the caller, sharing the caller's namespace
+- Binary literal: optional leading '-' (spaces/tabs/CR allowed after the dash) then '{0,1}+'
 
 Arithmetic
 - 'ADD(a, b)' : a + b