diff --git a/clyx_manual.md b/clyx_manual.md index 4180b40..22cfd55 100644 --- a/clyx_manual.md +++ b/clyx_manual.md @@ -282,13 +282,23 @@ Any line fragment starting with `#` to the end of the physical source line is re - **Stack Effect**: `( -- )` - **Description**: Prints the current stack representation to standard output (useful for debugging). +--- + +## 8. Host-specific (HS) Primitives + +**Warning**: relying upon the primitives from this group reduces your Clyx application's portability and the amount of platforms it can potentially run on, so they should be used very carefully. + ### `hsargs` (Host Arguments) - **Stack Effect**: `( -- [args] )` - **Description**: Pushes a list/quotation of all passed command line arguments onto the stack. +**N.B.**: on the platforms that don't support CLI arguments, this primitive will always push an empty quotation. + ### `hsexit` (Host Exit) - **Stack Effect**: `( code -- )` -- **Description**: Exits the program/interpreter with the specified exit code. +- **Description**: Exits the program/interpreter process with the specified exit code. + +**N.B.**: on the platforms that don't support specifying process exit codes, this primitive may either do nothing, exit the program the usual way supported by the platform or trigger a global interpreter restart. ### `hseval` (Host Language Evaluation) - **Stack Effect**: `( expr -- val )` @@ -298,7 +308,7 @@ Any line fragment starting with `#` to the end of the physical source line is re --- -## 8. Bootstrapped Core Words +## 9. Bootstrapped Core Words These words are defined in Clyx itself during the interpreter's bootstrap phase: @@ -316,11 +326,11 @@ These words are defined in Clyx itself during the interpreter's bootstrap phase: --- -## 9. Standard Library Words +## 10. Standard Library Words These words are defined in the standard library file `lib.clx` and loaded dynamically during interpreter initialization. They are categorized below by domain and purpose: -### 9.1 Stack Manipulation +### 10.1 Stack Manipulation #### `over` - **Stack Effect**: `( x y -- x y x )` @@ -338,7 +348,7 @@ These words are defined in the standard library file `lib.clx` and loaded dynami - **Stack Effect**: `( x y z -- y z x )` - **Description**: Rotates the third element of the stack to the top. -### 9.2 Control Flow +### 10.2 Control Flow #### `if` - **Syntax**: `if [true_actions] [false_actions]` @@ -350,7 +360,7 @@ These words are defined in the standard library file `lib.clx` and loaded dynami - **Stack Effect**: `( -- )` (parses body quotation from the execution stream). - **Description**: Loops repeatedly. The body `actions` is executed, and must leave the next condition value on the stack. If the condition is non-zero, the loop repeats; otherwise it terminates. -### 9.3 Mathematics & Arithmetic +### 10.3 Mathematics & Arithmetic #### `div` (Divide Integer Values) - **Stack Effect**: `( x y -- div )` @@ -384,7 +394,7 @@ These words are defined in the standard library file `lib.clx` and loaded dynami - **Stack Effect**: `( x f -- res )` - **Description**: Performs bit shift right of `x` by `f` bits (defined using `neg` and `shl`). -### 9.4 Logical Operators +### 10.4 Logical Operators #### `not` - **Stack Effect**: `( x -- c )` @@ -398,7 +408,7 @@ These words are defined in the standard library file `lib.clx` and loaded dynami - **Stack Effect**: `( x y -- c )` - **Description**: Logical OR. Pushes `1` if either `x` or `y` is non-zero, else pushes `0`. -### 9.5 Input / Output & Networking +### 10.5 Input / Output & Networking #### `cr` (Carriage Return / Newline) - **Stack Effect**: `( -- )` @@ -426,7 +436,7 @@ These words are defined in the standard library file `lib.clx` and loaded dynami **N.B.**: this word may not be supported on all targets. -### 9.6 Type Checking & Comparison +### 10.6 Type Checking & Comparison #### `isnum` (Is Number) - **Stack Effect**: `( x -- x c )` @@ -467,7 +477,7 @@ These words are defined in the standard library file `lib.clx` and loaded dynami - **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 +### 10.7 String Operations #### `streq` (String Equal) - **Stack Effect**: `( s1 s2 -- c )` @@ -489,7 +499,7 @@ These words are defined in the standard library file `lib.clx` and loaded dynami - **Stack Effect**: `( val -- [q] )` - **Description**: Converts the value `val` (if it is a string) to a list of its ASCII character codes. If `val` is already a list, it does nothing. -### 9.8 List Operations +### 10.8 List Operations #### `qpush` (Quotation Push) - **Stack Effect**: `( [q] x -- [q... x] )` @@ -503,7 +513,7 @@ These words are defined in the standard library file `lib.clx` and loaded dynami - **Stack Effect**: `( [q1] [q2] -- [q1_q2] )` - **Description**: Concatenates two lists `[q1]` and `[q2]`. -### 9.9 Bitwise Operations +### 10.9 Bitwise Operations #### `bitnot` (Bitwise NOT) - **Stack Effect**: `( x -- ~x )`