Shorten image and type tooling; improve portability and docs

Add runtime TYPE builtin to return a value's type name (INT/FLT/STR/TNS), preserving extension types.
Add OS-aware cleanup in tests: use del on Windows and rm on other platforms.
Improve image extension:
Ensure JPEG save unwraps interpreter Value objects safely with _expect_int before writing bytes.
Expand supported image extension files list (image.py, win32.py) and library bindings.
Add SHOW helper to stdlib lib/image.asmln to open saved images on Windows.
Tidy README code block formatting for PowerShell install steps.
Update SPECIFICATION wording for identifier character ranges and tensor literal types.

Author: python-processing-unit

README.md

@@ -1,6 +1,8 @@
 ## Installation
-`Invoke-WebRequest -Uri "https://github.com/python-processing-unit/ASM-Lang/archive/refs/heads/main.zip" -OutFile "path\to\download\ASM-Lang.zip"`<br>
-`Expand-Archive -Path "path\to\download\ASM-Lang.zip" -DestinationPath "path\to\extract\ASM-Lang"`<br>
-`$old = [Environment]::GetEnvironmentVariable('Path','User')`<br>
-`if(-not $old.Split(';') -contains 'path\to\extract\ASM-Lang'){ [Environment]::SetEnvironmentVariable('Path',$old + ';path\to\extract\ASM-Lang','User') }`<br>
-`Remove-Item -Path "path\to\download\ASM-Lang.zip"`<br>
+<code>
+Invoke-WebRequest -Uri "https://github.com/python-processing-unit/ASM-Lang/archive/refs/heads/main.zip" -OutFile "path\to\download\ASM-Lang.zip"<br>
+Expand-Archive -Path "path\to\download\ASM-Lang.zip" -DestinationPath "path\to\extract\ASM-Lang"<br>
+$old = [Environment]::GetEnvironmentVariable('Path','User')<br>
+if(-not $old.Split(';') -contains 'path\to\extract\ASM-Lang'){ [Environment]::SetEnvironmentVariable('Path',$old + ';path\to\extract\ASM-Lang','User') }<br>
+Remove-Item -Path "path\to\download\ASM-Lang.zip"
+</code>

SPECIFICATION.html

@@ -72,17 +72,17 @@
 
 - The first character MUST NOT be `0` or `1`. Any other non-ASCII character is disallowed, but otherwise the lexer permits a broad set of ASCII punctuation and symbol characters in addition to letters and digits. In particular, the following characters are valid as the first character of an identifier:
 
-  - Lowercase letters `a`–`z`
-  - Uppercase letters `A`–`Z`
-  - Decimal digits `2`–`9`
+  - Lowercase letters `a`-`z`
+  - Uppercase letters `A`-`Z`
+  - Decimal digits `2`-`9`
   - The punctuation and symbol characters
     `; / ! @ $ % & ~ _ + | < > ?`
 
 - Subsequent characters in an identifier may be any of the following:
 
-  - Lowercase letters `a`–`z`
-  - Uppercase letters `A`–`Z`
-  - Decimal digits `0`–`9`
+  - Lowercase letters `a`-`z`
+  - Uppercase letters `A`-`Z`
+  - Decimal digits `0`-`9`
   - The punctuation and symbol characters
     `; / ! @ $ % & ~ _ + | < > ?`
 
@@ -113,7 +113,7 @@
 - `[[0,1,10],[0,10,100]]` has shape `[10,11]`.
 - `[[[0,1,10],[1,10,100]]]` has shape `[1,10,11]`.
 
-Expressions inside a tensor literal may themselves evaluate to `INT`, `STR`, or `TNS`. If an element expression evaluates to a tensor value, it occupies a single position and does not contribute additional dimensions; only the explicit bracket structure determines the shape. A tensor literal that mixes sub-brackets of differing lengths is invalid (for example, `[[0,0,0],[1,1]]`).
+Expressions inside a tensor literal may themselves evaluate to `INT`, `FLT`, `STR`, or `TNS`. If an element expression evaluates to a tensor value, it occupies a single position and does not contribute additional dimensions; only the explicit bracket structure determines the shape. A tensor literal that mixes sub-brackets of differing lengths is invalid (for example, `[[0,0,0],[1,1]]`).
 
 Tensor values carry a fixed shape (dimension count and length per dimension). Each location in a tensor is statically typed by the value it first receives; attempting to write a different type to that location is a runtime error. Tensors are indexed with one-based indices. Negative indices address from the end of the corresponding dimension (for example, index -1 is the last element of that dimension); index 0 is invalid. Tensors may be re-assigned in two ways: binding a new tensor to the variable name, or writing through an index such as `tensor[dim1,...,dimN] = expr`. The latter mutates the existing tensor value in place at the indexed location and does not construct a new tensor object.
 
@@ -344,6 +344,7 @@
 - `ISINT(SYMBOL: x):INT` ; returns `1` if the identifier `x` exists and is of type `INT`, otherwise returns `0`. The argument must be an identifier; supplying any other expression is a runtime error.
 - `ISSTR(SYMBOL: x):INT` ; returns `1` if the identifier `x` exists and is of type `STR`, otherwise returns `0`. The argument must be an identifier; supplying any other expression is a runtime error.
 - `ISTNS(SYMBOL: x):INT` ; returns `1` if the identifier `x` exists and is of type `TNS`, otherwise returns `0`. The argument must be an identifier; supplying any other expression is a runtime error.
+- `TYPE(ANY: obj):STR` ; returns the runtime type name of `obj` as a `STR` — one of `INT`, `FLT`, `STR`, or `TNS` (extension-defined type names are returned unchanged when extensions are enabled).
 - `SLEN(STR: s):INT` returns the length of the supplied `STR` in characters as an `INT`. The argument must be a `STR`; passing an `INT` raises a runtime error.
 - `ILEN(INT: n):INT` returns the length in binary digits of the absolute value of the supplied `INT`. `ILEN(0)` returns 1. The argument must be an `INT`; passing a `STR` raises a runtime error.
 

asm-lang.exe

@@ -974,14 +974,16 @@ def _op_save_jpeg(interpreter, args, _arg_nodes, _env, location):
     # Try GDI+
     if _load_with_gdiplus is not None:
         try:
-            # _save_with_gdiplus expects RGBA list
+            # _save_with_gdiplus expects an RGBA list of plain ints. Use the
+            # interpreter helper to unwrap `Value` objects to ints rather than
+            # calling `int()` on them directly.
             rgba = []
             for y in range(h):
                 for x in range(w):
-                    rgba.append(int(arr[y, x, 0]) & 0xFF)
-                    rgba.append(int(arr[y, x, 1]) & 0xFF)
-                    rgba.append(int(arr[y, x, 2]) & 0xFF)
-                    rgba.append(int(arr[y, x, 3]) & 0xFF)
+                    rgba.append(interpreter._expect_int(arr[y, x, 0], "SAVE_JPEG", location) & 0xFF)
+                    rgba.append(interpreter._expect_int(arr[y, x, 1], "SAVE_JPEG", location) & 0xFF)
+                    rgba.append(interpreter._expect_int(arr[y, x, 2], "SAVE_JPEG", location) & 0xFF)
+                    rgba.append(interpreter._expect_int(arr[y, x, 3], "SAVE_JPEG", location) & 0xFF)
             _save_with_gdiplus(path, w, h, rgba, "JPEG", quality=int(quality))
             return Value(TYPE_STR, "OK")
         except Exception as exc:

ext/image.py

@@ -386,6 +386,7 @@ def __init__(self) -> None:
         self._register_custom("ISFLT", 1, 1, self._isflt)
         self._register_custom("ISSTR", 1, 1, self._isstr)
         self._register_custom("ISTNS", 1, 1, self._istns)
+        self._register_custom("TYPE", 1, 1, self._type)
         self._register_custom("ROUND", 1, 3, self._round)
         self._register_custom("READFILE", 1, 2, self._readfile)
         self._register_custom("BYTES", 1, 1, self._bytes)
@@ -1748,6 +1749,21 @@ def _istns(
             raise
         return Value(TYPE_INT, 1 if val.type == TYPE_TNS else 0)
 
+    def _type(
+        self,
+        interpreter: "Interpreter",
+        args: List[Value],
+        arg_nodes: List[Expression],
+        env: Environment,
+        location: SourceLocation,
+    ) -> Value:
+        # TYPE(ANY: obj):STR -> return the runtime type name of the value as STR
+        if len(args) != 1:
+            raise ASMRuntimeError("TYPE expects one argument", location=location, rewrite_rule="TYPE")
+        val = args[0]
+        # Return the type string as STR; preserve extension type names if present
+        return Value(TYPE_STR, val.type)
+
     def _frozen(
         self,
         interpreter: "Interpreter",

interpreter.py

@@ -25,6 +25,7 @@
 # BLIT(TNS: src, TNS: dest, INT: x, INT: y, INT: mixalpha = 1):TNS
 # GRAYSCALE(TNS: img):TNS  # three-channel grayscale (rgb=luminance, alpha preserved)
 # BLUR(TNS: img, INT: radius):TNS  # gaussian blur with integer radius
+# SHOW(TNS: img, STR: window):INT  # saves to temp file and opens with default viewer (Windows only)
 #
 # The returned tensor layout is [row][column][channel] with 1-based indexing
 # in user code. Channels are ordered r,g,b,a and values are 0..255.
@@ -95,4 +96,14 @@ FUNC INVERT(TNS: img):TNS{
     DEL(b)
     DEL(a)
     POP(out)
+}
+ 
+FUNC SHOW(TNS: img, STR: window):INT{
+    # Save the image to the provided path and open it with the system default
+    # viewer on Windows. `window` is treated as the target file path.
+    SAVE_PNG(img, window, 0)
+    # ShellExecuteW(hwnd, operation, file, params, dir, showcmd)
+    # Use NULL hwnd (0), operation "open", empty params and dir, showcmd=1
+    win32.WIN_CALL("shell32", "ShellExecuteW", "PSSSSI", "P", 0, "open", window, "", "", 1)
+    RETURN(0)
 }

lib/image.asmln

@@ -1 +1,2 @@
-image.py
+image.py
+win32.py

lib/image.asmxt

@@ -7,7 +7,7 @@ IMPORT(image)
 IMPORT(waveforms)
 IMPORT(stats)
 
-FUNC RUN_TESTS():INT{
+FUNC STDLIB_TESTS():INT{
     PRINT("Running library tests...")
 
     # PRNG reproducibility (LCG)
@@ -247,22 +247,34 @@ FUNC RUN_TESTS():INT{
     # SAVE/LOAD roundtrip (BMP/PNG/JPEG)
     ASSERT(EQ(image.SAVE_BMP(bmp, out_bmp), "OK"))
     TNS: bmp_rt = image.LOAD_BMP(out_bmp)
-    CL(JOIN('del "', REPLACE(out_bmp,'/','\'), '"'))
+    IF(EQ(OS(),"win")){
+        CL(JOIN('del "', REPLACE(out_bmp,'/','\'), '"'))
+    } ELSE {
+        CL(JOIN('rm "', out_bmp, '"'))
+    }
     DEL(out_bmp)
     ASSERT(EQ(bmp_rt, bmp))
     DEL(bmp_rt)
 
     ASSERT(EQ(image.SAVE_PNG(bmp, out_png, 1010), "OK"))
     TNS: png_rt = image.LOAD_PNG(out_png)
-    CL(JOIN('del "', REPLACE(out_png,'/','\'), '"'))
+    IF(EQ(OS(),"win")){
+        CL(JOIN('del "', REPLACE(out_png,'/','\'), '"'))
+    } ELSE {
+        CL(JOIN('rm "', out_png, '"'))
+    }
     DEL(out_png)
     ASSERT(EQ(png_rt, bmp))
     DEL(png_rt)
     # Use a high JPEG quality (95 -> binary 1011111). JPEG is lossy so
     # require dimensions match and per-channel values be close.
     ASSERT(EQ(image.SAVE_JPEG(bmp, out_jpeg, 1011111), "OK"))
     TNS: jpeg_rt2 = image.LOAD_JPEG(out_jpeg)
-    CL(JOIN('del "', REPLACE(out_jpeg,'/','\'), '"'))
+    IF(EQ(OS(),"win")){
+        CL(JOIN('del "', REPLACE(out_jpeg,'/','\'), '"'))
+    } ELSE {
+        CL(JOIN('rm "', out_jpeg, '"'))
+    }
     DEL(out_jpeg)
     ASSERT(EQ(image.WIDTH(jpeg_rt2), image.WIDTH(bmp)))
     ASSERT(EQ(image.HEIGHT(jpeg_rt2), image.HEIGHT(bmp)))
@@ -304,9 +316,11 @@ FUNC RUN_TESTS():INT{
     DEL(blit_out)
 
     PRINT("image library tests passed.")
-
-    # Extension tests (requires interpreter to be started with these extensions loaded)
     PRINT()
+    RETURN(0)
+}
+
+FUNC STDEXT_TESTS():INT{
 
     PRINT("Running extension tests...")
 
@@ -332,9 +346,13 @@ FUNC RUN_TESTS():INT{
     ASSERT(LTE(volpct, 1100100))  # dec 100
     PRINT("wasapi extension tests passed.")
 
-    # If we reach here all tests passed; print success code and return
     PRINT()
-    
+    RETURN(0)
+}
+
+FUNC RUN_TESTS():INT{
+    STDLIB_TESTS()
+    STDEXT_TESTS()
     PRINT("All tests passed.")
     RETURN(0)
 }