gh-5: Add type THR.

Add build.ps1

Author: python-processing-unit

asm-lang.exe

@@ -5,6 +5,7 @@
 import sys
 import os
 from typing import List, Optional
+import threading
 
 from extensions import ASMExtensionError, ReplContext, load_runtime_services
 from interpreter import ASMRuntimeError, Environment, ExitSignal, Interpreter, TracebackFormatter
@@ -62,11 +63,30 @@ def run_repl(*, verbose: bool, services) -> int:
     had_output = False
     # Tracks whether any PRINT has occurred since the last REPL input.
     first_print_since_input = True
+    main_thread_id = threading.get_ident()
 
     def _output_sink(text: str) -> None:
         nonlocal had_output, first_print_since_input
         # If this is not the first PRINT since the last REPL input,
         # emit a leading newline so outputs appear on separate lines.
+        if threading.get_ident() != main_thread_id:
+            # Background-thread output: ensure it appears on its own line
+            # to avoid being glued to the prompt. Use a normal print so a
+            # trailing newline is emitted.
+            try:
+                # If not first print since input, keep the separation.
+                if not first_print_since_input:
+                    print()
+                first_print_since_input = False
+                had_output = True
+                print(text)
+            except Exception:
+                # Best-effort: swallow to avoid crashing the REPL.
+                pass
+            return
+
+        # Main-thread REPL output: keep original inline behaviour so the
+        # REPL can control newlines and prompt placement.
         if not first_print_since_input:
             print()
         first_print_since_input = False

asm-lang.py

@@ -0,0 +1,22 @@
+$ErrorActionPreference = "Stop"
+
+$ROOTDIR = Split-Path -Parent $MyInvocation.MyCommand.Definition
+Set-Location $ROOTDIR
+Write-Host "Building executable from $ROOTDIR..."
+pyinstaller --onefile --icon `
+    "$ROOTDIR\docs\icon.png" `
+    --add-data "$ROOTDIR\lexer.py;." `
+    --add-data "$ROOTDIR\parser.py;." `
+    --add-data "$ROOTDIR\interpreter.py;." `
+    --add-data "$ROOTDIR\extensions.py;." `
+    "$ROOTDIR\asm-lang.py"
+Write-Host "Build complete."
+Write-Host "Cleaning up build artifacts..."
+if (Test-Path "$ROOTDIR\asm-lang.exe") {
+    Remove-Item "$ROOTDIR\asm-lang.exe"
+}
+Remove-Item "$ROOTDIR\build" -Recurse -Force
+Move-Item "$ROOTDIR\dist\asm-lang.exe" "$ROOTDIR\"
+Remove-Item "$ROOTDIR\dist" -Recurse -Force
+Remove-Item "$ROOTDIR\asm-lang.spec"
+Write-Host "Cleanup complete. Executable is located at $ROOTDIR\asm-lang.exe"

build.ps1

@@ -45,7 +45,7 @@
 
 ## 1. Overview
 
-The language is a familiar statement-based, imperative language. Programs consist of variable declarations via assignment, expressions, and control-flow constructs such as `IF`, `ELSEIF`, `ELSE`, `WHILE`, and `FOR`. ASM-Lang has five runtime data types: binary integers (`INT`), binary floating-point numbers (`FLT`, IEEE754), strings (`STR`), non-scalar tensors (`TNS`), and first-class user-defined functions (`FUNC`). Identifiers, function parameters, and return values are statically typed; the type of every symbol must be declared when it is first introduced. Computation proceeds by evaluating expressions and executing statements in sequence, with explicit constructs for branching and looping. Input and output are modeled through built-in operators, in particular `INPUT` and `PRINT`.
+The language is a familiar statement-based, imperative language. Programs consist of variable declarations via assignment, expressions, and control-flow constructs such as `IF`, `ELSEIF`, `ELSE`, `WHILE`, and `FOR`. ASM-Lang has seven runtime data types: binary integers (`INT`), binary floating-point numbers (`FLT`, IEEE754), strings (`STR`), non-scalar tensors (`TNS`), first-class user-defined functions (`FUNC`), associative maps (`MAP`), and thread handles (`THR`). Identifiers, function parameters, and return values are statically typed; the type of every symbol must be declared when it is first introduced. Computation proceeds by evaluating expressions and executing statements in sequence, with explicit constructs for branching and looping. Input and output are modeled through built-in operators, in particular `INPUT` and `PRINT`.
 
 The interpreter compiles source code into a single initial configuration (the seed state), which includes the program code, an empty variable environment, and an initial I/O history. It then advances execution by repeatedly applying a single, fixed small-step transition function that is independent of the particular program. A disassembler and log view expose all intermediate states so that every step and every control-flow decision is inspectable and replay-able.
 
@@ -99,7 +99,7 @@
 
 ## 3. Data Model
 
-ASM-Lang supports five runtime data types: binary integers, binary floating-point numbers, strings, non-scalar tensors, and first-class functions.
+ASM-Lang supports seven runtime data types: binary integers, binary floating-point numbers, strings, non-scalar tensors, first-class functions, associative maps, and thread handles.
 
 Binary integer literal: an unsigned non-empty sequence of `{0,1}` (for example, `0`, `1`, `1011`), or a signed literal formed by a leading `-` (the dash is part of the literal, not an operator) followed by optional spaces, tabs, or carriage returns and then a non-empty sequence of `{0,1}`. A `-` that does not immediately introduce a literal is a syntax error.
 
@@ -161,7 +161,13 @@
 
 Blocks group one or more statements and are enclosed in curly brackets: `{ statement1 ... statementN }`. Curly braces must match (that is, `{` closes with `}`). Blocks serve as the bodies of control-flow constructs and functions.
 
-ASYNC blocks: The `ASYNC` statement introduces a background task whose body is a regular block: `ASYNC{ ... }`. The statements inside the block execute synchronously with respect to each other but asynchronously relative to the rest of the program: the interpreter begins executing the block in a background task and immediately continues with the next statement in the current thread. The block shares the main program namespace (it executes with the same lexical environment), so assignments and mutations performed inside an `ASYNC` block are visible to the rest of the program immediately. Runtime errors raised inside an `ASYNC` block are reported via the interpreter's error hooks and recorded in the state log; they do not synchronously abort the main thread. Note that language invariants still apply inside the `ASYNC` block (for example, `RETURN` outside a function is a runtime error).
+ASYNC blocks: The `ASYNC` statement introduces a background task whose body is a regular block: `ASYNC{ ... }`. The statements inside the block execute synchronously with respect to each other but asynchronously relative to the rest of the program. The block shares the main program namespace (it executes with the same lexical environment), so assignments and mutations performed inside an `ASYNC` block are visible to the rest of the program immediately. Runtime errors raised inside an `ASYNC` block are reported via the interpreter's error hooks and recorded in the state log; they do not synchronously abort the main thread. When `ASYNC{ ... }` appears as a top-level statement the interpreter begins executing the block immediately in a background task and continues with the next statement. When `ASYNC{ ... }` is evaluated in expression position and is used as an argument to a surrounding call expression, the interpreter returns a `THR` handle but defers starting the worker thread until the immediately-enclosing call expression completes; this allows operators that receive the `THR` (for example `PAUSE` or `STOP`) to act on the thread before it begins execution. Note that language invariants still apply inside the `ASYNC` block (for example, `RETURN` outside a function is a runtime error).
+
+Thread values (`THR`): a `THR` value is a handle to a background task. In Boolean contexts, a finished `THR` (including one that has been stopped) is `0`, otherwise it is `1`.
+
+`THR(symbol){ block }`: the `THR` statement starts executing `block` in a background task and binds the identifier `symbol` (static type `THR`) in the current environment to the newly-created thread handle. The spawned task shares the main program namespace (it executes with the same lexical environment) similarly to `ASYNC`.
+
+`ASYNC{ block }` as an expression: `ASYNC{ ... }` may also appear in expression position, where it evaluates to a `THR` handle. In statement position, `ASYNC{ ... }` remains valid and its resulting `THR` value is ignored.
 
 Assignments have the syntax `TYPE : identifier = expression` on first use, where TYPE is `INT`, `FLT`, `STR`, `TNS`, or `FUNC`. Spaces around the colon and equals sign are optional. Subsequent assignments to an existing identifier may omit the type but must preserve the original type. Variables are deallocated only when `DEL(identifier)` is executed.
 
@@ -448,7 +454,7 @@
 - `OR(ANY: a1, ..., ANY: aN):INT` ; Boolean OR
 - `XOR(ANY: a1, ..., ANY: aN):INT` ; Boolean XOR
 - `NOT(ANY: a):INT` ; Boolean NOT
-- `BOOL(ANY: item):INT` ; returns the truthiness of `item` as `INT` (`INT`: non-zero -> `1`, `STR`: non-empty -> `1`, `TNS`: true if any element is true), otherwise `0`
+- `BOOL(ANY: item):INT` ; returns the truthiness of `item` as `INT` (`INT`: non-zero -> `1`, `STR`: non-empty -> `1`, `TNS`: true if any element is true), otherwise `0`, `THR` is true if it is not stopped, `MAP` is true if it has any entries.
 
 ### 12.4 Comparisons
 - `EQ(ANY: a, ANY: b):INT` ; 1 if a == b else 0
@@ -504,8 +510,14 @@
 ### 12.8 Concurrency
 
 - `PARALLEL(TNS: functions):INT` — Execute each element of `functions` in parallel. Each element must evaluate to a `FUNC` value; the interpreter invokes each function with no arguments (in separate worker threads) and waits for all workers to complete. Returns `INT` 0 on success. If any element is not a `FUNC` or any worker raises an error, `PARALLEL` raises a runtime error (rewrite: `PARALLEL`) and the failing worker's error is propagated.
-
 - `PARALLEL(FUNC: f1, FUNC: f2, ...):INT` — Variadic form: accept one or more `FUNC` values as direct arguments. Behaviour is equivalent to the tensor form: each supplied function is invoked in parallel with no arguments and the call waits for completion; returns `INT` 0 on success or raises on error.
+- `ASYNC{ block }:THR` — Expression form: start executing `block` asynchronously in a separate thread (while sharing the same namespace) and return a `THR` handle. In statement position, `ASYNC{ block }` is permitted and the returned handle is ignored.
+- `STOP(THR: thread):THR` — Cooperatively stop a running thread and mark it finished.
+- `AWAIT(THR: thread):THR` — Block until the thread is finished.
+- `PAUSE(THR: thread, FLT: seconds=-1):THR` — Pause execution while preserving the current location. If `seconds` is provided and is $\ge 0$, the thread is automatically resumed after that duration. Pausing an already-paused thread is a runtime error.
+- `RESUME(THR: thread):THR` — Resume a paused thread. Resuming a thread that is not paused is a runtime error.
+- `PAUSED(THR: thread):INT` — Returns `INT` 1 if `thread` is paused, otherwise `INT` 0.
+- `RESTART(THR: thread):THR` — Reinitialize and start executing the thread again.
 
 ### 12.9 Logarithms
 - `LOG(INT: a):INT` ; floor(log2(a)) for a > 0
@@ -586,7 +598,8 @@
 - `CONTINUE()` ; skip remaining statements in the innermost loop iteration and proceed to the next iteration; if used in the last iteration it acts like `BREAK(1)`. Using `CONTINUE()` outside of a loop is a runtime error.
 - `GOTOPOINT(INT|STR: n)` ; register a gotopoint with identifier `n` at this statement's location (identifier may be `INT` or `STR`) (n evaluated at runtime). Gotopoints are visible across the containing function or top-level scope rather than being restricted to a single lexical block.
 - `GOTO(INT|STR: n)` ; jump to a previously-registered gotopoint with identifier `n` (`INT` or `STR`) within the same function or top-level scope; runtime error if not registered in that scope
-- `ASYNC{ block }` ; execute `block` asynchronously in a separate thread (while sharing the same namespace); the caller continues executing immediately without waiting for the async block to complete. Any uncaught errors in the async block are logged to the interpreter's error log but do not affect the caller.
+- `ASYNC{ block }` ; execute `block` asynchronously in a separate thread (while sharing the same namespace); the caller continues executing immediately without waiting for the async block to complete. Any uncaught errors in the async block are logged to the interpreter's error log but do not affect the caller. When used in expression position, `ASYNC{ block }` evaluates to a `THR` handle. If the expression is used as an argument to a surrounding call expression, the worker thread's start is deferred until that enclosing call completes so that the callee may operate on the `THR` (for example, `PAUSE` or `STOP`) before the worker runs; in statement position the worker starts immediately and the returned handle is ignored.
+- `THR(SYMBOL: symbol){ block }` ; execute `block` asynchronously in a separate thread and bind the identifier `symbol` (static type `THR`) to the thread handle.
 - `TRY{ block }CATCH{ block }` ; execute `block` in the `TRY` and, if an interpreter-level runtime error occurs during the `TRY` block, stop the `TRY` and execute the directly-following `CATCH` block. If no error occurs, the `CATCH` block is skipped.
 - `TRY{ block }CATCH(SYMBOL: name){ block }` ; like the previous form but bind a temporary `STR` symbol `name` visible inside the `CATCH` block containing the error message. The temporary symbol shadows any existing binding for `name` and is restored or removed after the `CATCH` block completes.