gh-14: Replace code note char.

Author: python-processing-unit

docs/SPECIFICATION.html

@@ -74,19 +74,19 @@
 
 Whitespace consists of the space character (`U+0020`), horizontal tab, carriage return, and line feed. It may appear freely between tokens and is otherwise ignored, except that newlines delimit top-level statements (see Section 5.1).
 
-A comment begins with the `#` character and continues to the end of the current line. Comments have no effect on execution.
+A comment begins with the `!` character and continues to the end of the current line. Comments have no effect on execution.
 
 Line separator alias: The semicolon character (`;`) is treated by the lexer as a newline-token alias. Whenever a `;` appears in source code outside of a string literal, the lexer emits a `NEWLINE` token (equivalent to a physical newline), so `;` can be used to separate statements on a single physical line.
 
 The program text is divided into several token kinds: binary integer literals (Section 3.1); string literals delimited by double or single quotation marks (`"`, `'`, Section 3.2); identifiers for variable names and user-defined function names (Section 2.5); keywords and built-ins (control-flow keywords, built-in operators and functions; see Sections 5 and 13); and delimiters, namely `(`, `)`, `{`, `}`, `[`, `]`, `,`, `:`, and `=`.
 
 Keywords: The language's reserved keywords (for example, `IF`, `WHILE`, `FUNC`, etc.) are matched by the lexer exactly as listed in this specification and are case-sensitive. Programs must use the keywords in their canonical uppercase form; otherwise the token will be recognized as an identifier. Built-in operator names such as `INPUT`, `PRINT`, and `IMPORT` follow the same case-sensitive matching rules.
 
-Line continuation: The character `^` serves as a line-continuation marker. When a caret `^` appears in the source and is followed immediately by a newline, both the `^` and the newline are ignored by the lexer (that is, the logical line continues on the next physical line). The lexer also accepts a caret immediately before a code note (a comment beginning with `#`); in this case the `^`, the comment text up to the line terminator, and the terminating newline are treated as if they were not present. If a `^` is present in a string, it does not count as a line continuation. If a caret appears and is not immediately followed by a newline, a code note, or the platform's single-character newline sequence, the lexer must raise a syntax error.
+Line continuation: The character `^` serves as a line-continuation marker. When a caret `^` appears in the source and is followed immediately by a newline, both the `^` and the newline are ignored by the lexer (that is, the logical line continues on the next physical line). The lexer also accepts a caret immediately before a code note (a comment beginning with `!`); in this case the `^`, the comment text up to the line terminator, and the terminating newline are treated as if they were not present. If a `^` is present in a string, it does not count as a line continuation. If a caret appears and is not immediately followed by a newline, a code note, or the platform's single-character newline sequence, the lexer must raise a syntax error.
 
 The character `-` primarily serves as the leading sign of a numeric literal (Section 3.1). When `-` appears immediately before optional whitespace and then binary digits, it is parsed as part of the numeric literal (that is, a signed literal). In other contexts (for example inside an index expression) a single `-` token is recognized as a dash used for slice notation `lo-hi`. If `-` appears in any other unsupported context the lexer must raise a syntax error.
 
-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: `{`, `}`, `[`, `]`, `(`, `)`, `=`, `,`, `#`. The first character of an identifier must not be the digit `0` or `1` (these digits are used to begin binary integer literals). However, the characters `0` and `1` are permitted in subsequent positions within an identifier (for example, `a01` and `X10Y` are valid identifiers, while `0foo` and `1bar` are not). The namespace is flat: variables and functions share a single identifier space, so a given name cannot simultaneously denote both. A user-defined function name must not conflict with the name of any built-in operator or function (see Section 13).
+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: `{`, `}`, `[`, `]`, `(`, `)`, `=`, `,`, `!`. The first character of an identifier must not be the digit `0` or `1` (these digits are used to begin binary integer literals). However, the characters `0` and `1` are permitted in subsequent positions within an identifier (for example, `a01` and `X10Y` are valid identifiers, while `0foo` and `1bar` are not). The namespace is flat: variables and functions share a single identifier space, so a given name cannot simultaneously denote both. A user-defined function name must not conflict with the name of any built-in operator or function (see Section 13).
 
 Identifier character set (clarification): The (non-empty) sequence of characters that forms an identifier is determined by the following rules, which match the reference lexer implementation:
 
@@ -99,7 +99,7 @@
   - Decimal digits `2`-`9`
 
   - The punctuation and symbol characters
-    `/ ! $ % & ~ _ + | ?`
+    `/ $ % & ~ _ + | ?`
 
 - Subsequent characters in an identifier may be any of the following:
 
@@ -110,9 +110,9 @@
   - Decimal digits `0`-`9`
 
   - The punctuation and symbol characters
-    `/ ! $ % & ~ _ + | ?`
+    `/ $ % & ~ _ + | ?`
 
-  As noted above, non-ASCII characters remain disallowed, and the delimiter characters `{`, `}`, `(`, `)`, `=`, `,`, and `#` are never permitted inside identifiers.
+  As noted above, non-ASCII characters remain disallowed, and the delimiter characters `{`, `}`, `(`, `)`, `=`, `,`, and `!` are never permitted inside identifiers.
 
 This deliberately-permissive identifier character set preserves an unambiguous lexical distinction between binary integer literals (which must begin with `0` or `1`) and identifiers, while allowing module-qualified names and other symbolic conventions to be expressed directly as plain identifiers in source code.
 
@@ -420,7 +420,7 @@
 
   - A Python extension is a `.py` file that defines `PREFIX_EXTENSION_API_VERSION = 1` (optional; defaults to 1) and a callable `prefix_register(ext)` entrypoint.
 
-  - A pointer file is a `.prex` 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 `.prex` 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.
+  - A pointer file is a `.prex` 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 `.prex` 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 `.prex` file is supplied as an argument, all of the linked extensions are loaded.
 

lib/csprng.pre

@@ -1,31 +1,31 @@
-# ChaCha20-based cryptographically secure pseudorandom number generator
-#
-# API:
-# SEED(INT: seed) -> INT
-# NEXT() -> INT
-# RANGE(INT: max) -> INT
-# RANGE_MIN_MAX(INT: min, INT: max) -> INT
+! ChaCha20-based cryptographically secure pseudorandom number generator
+!
+! API:
+! SEED(INT: seed) -> INT
+! NEXT() -> INT
+! RANGE(INT: max) -> INT
+! RANGE_MIN_MAX(INT: min, INT: max) -> INT
 
-INT: MASK32 = SUB( POW(10,100000), 1 )  # 2^32-1
+INT: MASK32 = SUB( POW(10,100000), 1 )  ! 2^32-1
 
-# ChaCha20 constants ("expand 32-byte k")
+! ChaCha20 constants ("expand 32-byte k")
 MAP: CH_CONST = < ^
     0 = 01100001011100000111000001100101, ^
     1 = 00110011001000000110010001101110, ^
     10 = 01111001011000100010110100110010, ^
     11 = 01101011001000000110010101110100 ^
 >
 
-TNS: ch_key = TNS([1000], 0)  # 8 words
-TNS: ch_nonce = [0, 0, 0] # use literals for short TNS
+TNS: ch_key = TNS([1000], 0)  ! 8 words
+TNS: ch_nonce = [0, 0, 0] ! use literals for short TNS
 INT: ch_counter = 0
-TNS: ch_buf = TNS([10000], 0) # 16 words
-INT: ch_buf_pos = TLEN(ch_buf, 1)  # set to buffer length to force refill
+TNS: ch_buf = TNS([10000], 0) ! 16 words
+INT: ch_buf_pos = TLEN(ch_buf, 1)  ! set to buffer length to force refill
 
 FUNC ROTL32(INT: x, INT: n):INT{
     INT: x32 = BAND(x, MASK32)
     INT: left = BAND(SHL(x32, n), MASK32)
-    INT: right = SHR(x32, SUB(100000, n))  # 32 - n
+    INT: right = SHR(x32, SUB(100000, n))  ! 32 - n
     RETURN( BAND(BOR(left, right), MASK32) )
 }
 
@@ -36,13 +36,13 @@ FUNC QR(TNS: s, INT: ia, INT: ib, INT: ic, INT: id):INT{
     INT: d = s[id]
 
     a = BAND( ADD(a, b), MASK32 )
-    d = ROTL32( BXOR(d, a), 10000 )   # 16
+    d = ROTL32( BXOR(d, a), 10000 )   ! 16
     c = BAND( ADD(c, d), MASK32 )
-    b = ROTL32( BXOR(b, c), 1100 )    # 12
+    b = ROTL32( BXOR(b, c), 1100 )    ! 12
     a = BAND( ADD(a, b), MASK32 )
-    d = ROTL32( BXOR(d, a), 1000 )    # 8
+    d = ROTL32( BXOR(d, a), 1000 )    ! 8
     c = BAND( ADD(c, d), MASK32 )
-    b = ROTL32( BXOR(b, c), 111 )     # 7
+    b = ROTL32( BXOR(b, c), 111 )     ! 7
 
     s[ia] = a
     s[ib] = b
@@ -72,7 +72,7 @@ FUNC CHACHA_BLOCK():INT{
         n[10], ^
         n[11] ^
     ]
-    FOR(i, 1010){  # 10 double-rounds
+    FOR(i, 1010){  ! 10 double-rounds
         QR(state, 1, 101, 1001, 1101)
         QR(state, 10, 110, 1010, 1110)
         QR(state, 11, 111, 1011, 1111)
@@ -113,15 +113,15 @@ FUNC REFILL_BUF():INT{
 
 FUNC DERIVE_KEY_AND_NONCE(INT: seed):INT{
     INT: s = BAND(seed, MASK32)
-    FOR(i, 1000){  # 8 key words (1000 == 8)
+    FOR(i, 1000){  ! 8 key words (1000 == 8)
         s = BAND( ADD( MUL(s, ^
             01000001110001100100111001101101), ^
             00000000000000000011000000111001 ), ^
             MASK32 ^
         )
         ch_key[i] = s
     }
-    FOR(j, 11){  # 3 nonce words (11 == 3)
+    FOR(j, 11){  ! 3 nonce words (11 == 3)
         s = BAND( ADD( MUL(s, ^
             01000001110001100100111001101101), ^
             00000000000000000011000000111001 ), ^
@@ -136,12 +136,12 @@ FUNC SEED(INT: seed):INT{
     DERIVE_KEY_AND_NONCE(seed)
     ch_counter = 0
     ch_buf = TNS([10000], 0)
-    ch_buf_pos = TLEN(ch_buf, 1)  # set to buffer length to force refill
+    ch_buf_pos = TLEN(ch_buf, 1)  ! set to buffer length to force refill
     RETURN(ch_counter)
 }
 
 FUNC NEXT():INT{
-    IF( GTE(ch_buf_pos, TLEN(ch_buf, 1)) ){  # buffer length
+    IF( GTE(ch_buf_pos, TLEN(ch_buf, 1)) ){  ! buffer length
         REFILL_BUF()
     }
     INT: v = ch_buf[ ADD(ch_buf_pos, 1) ]

lib/diff.pre

@@ -1,9 +1,9 @@
-# diff utilities for Prefix
-#
-# API:
-# UNIFIED(modified: STR, source: STR):STR
-# CONTEXT(modified: STR, source: STR):STR
-# SIDE_BY_SIDE(modified: STR, source: STR):STR
+! diff utilities for Prefix
+!
+! API:
+! UNIFIED(modified: STR, source: STR):STR
+! CONTEXT(modified: STR, source: STR):STR
+! SIDE_BY_SIDE(modified: STR, source: STR):STR
 
 FUNC _append_line(STR: acc, STR: line):STR{
     IF( EQ(acc, "") ){ RETURN(line) } ELSE { RETURN( JOIN(acc, "\n", line) ) }
@@ -42,10 +42,10 @@ FUNC UNIFIED(STR: mod, STR: src):STR{
 }
 
 FUNC CONTEXT(STR: mod, STR: src):STR{
-    # For simplicity, use the same output as UNIFIED but with a ' ' prefix
+    ! For simplicity, use the same output as UNIFIED but with a ' ' prefix
     STR: u = UNIFIED(mod, src)
     IF( EQ(u, "") ){ RETURN("") }
-    # Prepend a simple header to resemble context diff
+    ! Prepend a simple header to resemble context diff
     RETURN( JOIN("*** a", "\n", u) )
 }
 

lib/gui/init.pre

@@ -1,20 +1,20 @@
-# `image`-interoperable GUI operations for Prefix
-#
-# API:
-# CREATE_WINDOW(STR: type, INT: width, INT: height, STR: title, INT: scale_to_fit=1):INT returns handle
-# SHOW_IMAGE(INT: window_handle, TNS: img):INT `1` on success
-# CLOSE_WINDOW(INT: window_handle):INT `1` on success
-# SCREEN():TNS returns dimensions of screen.
-# SCREEN_WIDTH():INT
-# SCREEN_HEIGHT():INT
-# SCREENSHOT():TNS image of the entire screen
-# MINIMIZE(INT: window_handle):INT `1` on success
-# MAXIMIZE(INT: window_handle):INT `1` on success
-# TO_FRONT(INT: window_handle):INT `1` on success
-# TO_BACK(INT: window_handle):INT `1` on success
-# WINDOW(INT: handle):TNS returns [width, height] of the given window handle
-# WINDOW_WIDTH(INT: handle):INT
-# WINDOW_HEIGHT(INT: handle):INT
+! `image`-interoperable GUI operations for Prefix
+!
+! API:
+! CREATE_WINDOW(STR: type, INT: width, INT: height, STR: title, INT: scale_to_fit=1):INT returns handle
+! SHOW_IMAGE(INT: window_handle, TNS: img):INT `1` on success
+! CLOSE_WINDOW(INT: window_handle):INT `1` on success
+! SCREEN():TNS returns dimensions of screen.
+! SCREEN_WIDTH():INT
+! SCREEN_HEIGHT():INT
+! SCREENSHOT():TNS image of the entire screen
+! MINIMIZE(INT: window_handle):INT `1` on success
+! MAXIMIZE(INT: window_handle):INT `1` on success
+! TO_FRONT(INT: window_handle):INT `1` on success
+! TO_BACK(INT: window_handle):INT `1` on success
+! WINDOW(INT: handle):TNS returns [width, height] of the given window handle
+! WINDOW_WIDTH(INT: handle):INT
+! WINDOW_HEIGHT(INT: handle):INT
 
 FUNC SCREEN_WIDTH():INT{
     RETURN(gui.SCREEN()[1])

lib/image/init.pre

@@ -1,52 +1,52 @@
-# Image loading helpers for Prefix
-# Backed by ext/image.py (stdlib-only, prefers Windows GDI+).
-#
-# API (operators provided by the model/extension):
-# LOAD_PNG(STR: path):TNS[width,height,[r,g,b,a]]
-# LOAD_JPEG(STR: path):TNS[width,height,[r,g,b,a]]
-# LOAD_BMP(STR: path):TNS[width,height,[r,g,b,a]]
-# LOAD(STR: path):TNS[height,width,[r,g,b,a]]  # auto-detects format by extension
-# SAVE_PNG(TNS: img, STR: path, INT: compression_level)
-# SAVE_JPEG(TNS: img, STR: path, INT: compression_level)
-# SAVE_BMP(TNS: img, STR: path)
-# POLYGON(TNS:img, TNS:points[[x,y]...], TNS:color[r,g,b,a], INT:fill=1, INT:thickness=1):TNS
-# RECT(TNS: img, INT: x, INT: y, INT: width, INT: height, TNS: color[r,g,b,a], INT: fill = 1, INT: thickness = 1):TNS  # wraps POLYGON
-# ELLIPSE(TNS: img, TNS: center, INT: rx, INT: ry, TNS: color[r,g,b,a], INT: fill = 1, INT: thickness = 1):TNS
-# SQUARE(TNS: img, INT: x, INT: y, INT: size, TNS: color, INT: fill, INT: thickness):TNS
-# CIRCLE(TNS: img, TNS: center, INT: radius, TNS: color, INT: fill, INT: thickness):TNS
-# WIDTH(TNS: img):INT
-# HEIGHT(TNS: img):INT
-# CHANNELS(TNS: img):INT
-# R(TNS: img):TNS
-# G(TNS: img):TNS
-# B(TNS: img):TNS
-# A(TNS: img):TNS
-# PIXEL(TNS: img, INT: x, INT: y):TNS
-# PIXEL_R(TNS: img, INT: x, INT: y):INT
-# PIXEL_G(TNS: img, INT: x, INT: y):INT
-# PIXEL_B(TNS: img, INT: x, INT: y):INT
-# PIXEL_A(TNS: img, INT: x, INT: y):INT
-# THRESHHOLD_A(TNS:img, INT:a, TNS:color=[0,0,0,0]):TNS
-# THRESHHOLD_R(TNS:img, INT:r, TNS:color=[0,0,0,0]):TNS
-# THRESHHOLD_G(TNS:img, INT:g, TNS:color=[0,0,0,0]):TNS
-# THRESHHOLD_B(TNS:img, INT:b, TNS:color=[0,0,0,0]):TNS
-# FLIP_V(TNS: img):TNS
-# FLIP_H(TNS: img):TNS
-# INVERT(TNS: img):TNS
-# SCALE(TNS: src, FLT: scale_x, FLT: scale_y, INT: antialiasing = 1):TNS
-# RESIZE(TNS: img, INT: new_width, INT: new_height, INT: antialiasing = 1):TNS
-# CROP(TNS:img, TNS:corners[[tl_x,tl_y],[tr_x,tr_y],[bl_x,bl_y],[br_x,br_y]]):TNS
-# ROTATE(TNS: img, FLT: degrees):TNS
-# BLIT(TNS: src, TNS: dest, INT: x, INT: y, INT: mixalpha = 1):TNS
-# GRAYSCALE(TNS: img):TNS  # three-channel grayscale (rgb=luminance, alpha preserved)
-# REPLACE_COLOR(TNS: img, TNS: target_color, TNS: replacement_color):TNS
-# BLUR(TNS: img, INT: radius):TNS  # gaussian blur with integer radius
-# EDGE(TNS: img):TNS  # difference-of-gaussians edge detector
-# CELLSHADE(TNS: img, TNS: colors):TNS  # map pixels to nearest palette color
-# SHOW(TNS: img):INT  # saves to temp file and opens with default viewer (Windows only)
-#
-# The returned tensor layout is [column][row][channel] (width, height, channel)
-# in user code. Channels are ordered r,g,b,a and values are 0..255.
+! Image loading helpers for Prefix
+! Backed by ext/image.py (stdlib-only, prefers Windows GDI+).
+!
+! API (operators provided by the model/extension):
+! LOAD_PNG(STR: path):TNS[width,height,[r,g,b,a]]
+! LOAD_JPEG(STR: path):TNS[width,height,[r,g,b,a]]
+! LOAD_BMP(STR: path):TNS[width,height,[r,g,b,a]]
+! LOAD(STR: path):TNS[height,width,[r,g,b,a]]  ! auto-detects format by extension
+! SAVE_PNG(TNS: img, STR: path, INT: compression_level)
+! SAVE_JPEG(TNS: img, STR: path, INT: compression_level)
+! SAVE_BMP(TNS: img, STR: path)
+! POLYGON(TNS:img, TNS:points[[x,y]...], TNS:color[r,g,b,a], INT:fill=1, INT:thickness=1):TNS
+! RECT(TNS: img, INT: x, INT: y, INT: width, INT: height, TNS: color[r,g,b,a], INT: fill = 1, INT: thickness = 1):TNS  ! wraps POLYGON
+! ELLIPSE(TNS: img, TNS: center, INT: rx, INT: ry, TNS: color[r,g,b,a], INT: fill = 1, INT: thickness = 1):TNS
+! SQUARE(TNS: img, INT: x, INT: y, INT: size, TNS: color, INT: fill, INT: thickness):TNS
+! CIRCLE(TNS: img, TNS: center, INT: radius, TNS: color, INT: fill, INT: thickness):TNS
+! WIDTH(TNS: img):INT
+! HEIGHT(TNS: img):INT
+! CHANNELS(TNS: img):INT
+! R(TNS: img):TNS
+! G(TNS: img):TNS
+! B(TNS: img):TNS
+! A(TNS: img):TNS
+! PIXEL(TNS: img, INT: x, INT: y):TNS
+! PIXEL_R(TNS: img, INT: x, INT: y):INT
+! PIXEL_G(TNS: img, INT: x, INT: y):INT
+! PIXEL_B(TNS: img, INT: x, INT: y):INT
+! PIXEL_A(TNS: img, INT: x, INT: y):INT
+! THRESHHOLD_A(TNS:img, INT:a, TNS:color=[0,0,0,0]):TNS
+! THRESHHOLD_R(TNS:img, INT:r, TNS:color=[0,0,0,0]):TNS
+! THRESHHOLD_G(TNS:img, INT:g, TNS:color=[0,0,0,0]):TNS
+! THRESHHOLD_B(TNS:img, INT:b, TNS:color=[0,0,0,0]):TNS
+! FLIP_V(TNS: img):TNS
+! FLIP_H(TNS: img):TNS
+! INVERT(TNS: img):TNS
+! SCALE(TNS: src, FLT: scale_x, FLT: scale_y, INT: antialiasing = 1):TNS
+! RESIZE(TNS: img, INT: new_width, INT: new_height, INT: antialiasing = 1):TNS
+! CROP(TNS:img, TNS:corners[[tl_x,tl_y],[tr_x,tr_y],[bl_x,bl_y],[br_x,br_y]]):TNS
+! ROTATE(TNS: img, FLT: degrees):TNS
+! BLIT(TNS: src, TNS: dest, INT: x, INT: y, INT: mixalpha = 1):TNS
+! GRAYSCALE(TNS: img):TNS  ! three-channel grayscale (rgb=luminance, alpha preserved)
+! REPLACE_COLOR(TNS: img, TNS: target_color, TNS: replacement_color):TNS
+! BLUR(TNS: img, INT: radius):TNS  ! gaussian blur with integer radius
+! EDGE(TNS: img):TNS  ! difference-of-gaussians edge detector
+! CELLSHADE(TNS: img, TNS: colors):TNS  ! map pixels to nearest palette color
+! SHOW(TNS: img):INT  ! saves to temp file and opens with default viewer (Windows only)
+!
+! The returned tensor layout is [column][row][channel] (width, height, channel)
+! in user code. Channels are ordered r,g,b,a and values are 0..255.
 
 IMPORT(path)
 
@@ -151,12 +151,12 @@ FUNC CIRCLE(TNS: img, TNS: center, INT: radius, TNS: color, INT: fill, INT: thic
 }
 
 FUNC SHOW(TNS: img):INT{
-    # Save the image to the provided path and open it with the system default
-    # viewer on Windows. `img_path` is treated as the target file path.
+    ! Save the image to the provided path and open it with the system default
+    ! viewer on Windows. `img_path` is treated as the target file path.
     STR: img_path = "C:/Windows/Temp/tmp_img.png"
     image.SAVE_PNG(img, img_path, 0)
-    # ShellExecuteW(hwnd, operation, file, params, dir, showcmd)
-    # Use NULL hwnd (0), operation "open", empty params and dir, showcmd=1
+    ! 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", img_path, "", "", 1)
     DEL(img_path)
     RETURN(0)