introduced hseval

clyx_manual.md

@@ -2,7 +2,7 @@
 
 Clyx is a concatenative, stack-oriented programming language designed for simplicity, minimalism, and metaprogramming capabilities. It uses postfix notation (aka Reverse Polish Notation, RPN), where operations are performed on a global stack. Clyx features homoiconicity: code is structured as quotations (lists), which can be manipulated as data and executed dynamically.
 
-This document describes the stack effects and behavior of the **47 primitive core words**, **3 bootstrapped core words**, and **41 standard library words** present in the reference implementation.
+This document describes the stack effects and behavior of the **48 primitive core words**, **3 bootstrapped core words**, and **41 standard library words** present in the reference implementation.
 
 The Clyx runtime itself allows the programmer to redefine any already defined word, including the core ones and the ones from the standard library. Unlike e.g. Forth, where words are resolved at compile-time, Clyx words are resolved at runtime, so such redefinitions may affect all previously established behavior. That's why, as a rule, any **predefined** Clyx word, both in the language core and the standard library, must not exceed 6 characters. This is done to encourage programmers to define their own human-readable words (7+ characters long) without any risk of overwriting existing word definitions.
 
@@ -235,6 +235,8 @@ Any line fragment starting with `#` to the end of the physical source line is re
   - Otherwise, it creates a client TCP connection to `host` on `port` and pushes the connection file-like descriptor onto the stack.
   - Sets `SO_REUSEADDR` to ensure the socket is instantly released upon termination.
 
+**N.B.**: this primitive may not be supported on all targets.
+
 ### `write`
 - **Stack Effect**: `( fd data -- count )`
 - **Description**: Writes the string/bytes `data` to the descriptor `fd`. Returns the number of characters/bytes written. Automatically flushes standard/socket buffers if possible.
@@ -258,14 +260,20 @@ Any line fragment starting with `#` to the end of the physical source line is re
 - **Stack Effect**: `( path -- )`
 - **Description**: Creates a new directory at the specified `path`.
 
+**N.B.**: this primitive may not be supported on all targets.
+
 ### `listd` (List Directory)
 - **Stack Effect**: `( path -- [contents] )`
 - **Description**: Lists the contents of the directory at `path`. Pushes a quotation containing a list of strings representing the names of the files and directories inside the directory.
 
+**N.B.**: this primitive may not be supported on all targets.
+
 ### `deld` (Delete Directory)
 - **Stack Effect**: `( path -- )`
 - **Description**: Deletes the directory at `path` from the file system. The directory must be empty.
 
+**N.B.**: this primitive may not be supported on all targets.
+
 ### `rand` (Random)
 - **Stack Effect**: `( limit -- val )`
 - **Description**: Generates a random integer in the range `[0, limit - 1]` and pushes it to the stack.
@@ -278,6 +286,8 @@ Any line fragment starting with `#` to the end of the physical source line is re
 - **Stack Effect**: `( expr -- val )`
 - **Description**: Pops the string `expr` from the stack, evaluates it as an expression in the host language (e.g., Python), and pushes the resulting value back onto the stack.
 
+**N.B.**: this primitive may not be supported on all targets. Only use as a last resort in controlled and/or sandboxed environments. Never pass user input to this primitive.
+
 ---
 
 ## 8. Bootstrapped Core Words
@@ -406,6 +416,8 @@ These words are defined in the standard library file `lib.clx` and loaded dynami
 - **Stack Effect**: `( port -- fd )`
 - **Description**: Creates a server TCP socket listening on all interfaces (`"0.0.0.0"`) on the specified `port`. Pushes the server socket descriptor onto the stack.
 
+**N.B.**: this word may not be supported on all targets.
+
 ### 9.6 Type Checking & Comparison
 
 #### `isnum` (Is Number)
@@ -443,17 +455,16 @@ These words are defined in the standard library file `lib.clx` and loaded dynami
 #### `<=` (Less Than or Equal)
 - **Stack Effect**: `( a b -- c )`
 - **Description**: Pops `b`, pops `a`, and pushes `1` if `a` is less than or equal to `b`; otherwise pushes `0`.
-
-#### `streq` (String Equal)
-- **Stack Effect**: `( s1 s2 -- c )`
-- **Description**: Pops `s2`, pops `s1`, and pushes `1` if the two strings `s1` and `s2` (or their character list equivalents) are equal; otherwise pushes `0`.
-
 #### `vlen` (Value Length)
 - **Stack Effect**: `( val -- len )`
 - **Description**: Pushes the length of `val`. If `val` is a list, it returns the number of elements; if it is a string, it returns the number of characters.
 
 ### 9.7 String Operations
 
+#### `streq` (String Equal)
+- **Stack Effect**: `( s1 s2 -- c )`
+- **Description**: Pops `s2`, pops `s1`, and pushes `1` if the two strings `s1` and `s2` (or their character list equivalents) are equal; otherwise pushes `0`.
+
 #### `lower` (To Lowercase)
 - **Stack Effect**: `( s -- s_lower )`
 - **Description**: Pops the string `s` and pushes its lowercase equivalent `s_lower` onto the stack.