luxferre/clyx
1
0
Fork 0
Code Actions Activity

q-form renaming effort

Browse Source
This commit is contained in:
Luxferre
2026-07-04 16:56:08 +03:00
parent 33a94f0084
commit 46ff217e14
6 changed files with 96 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files
clyx_manual.md
+44 -44
View File
@@ -1,6 +1,6 @@
# Clyx Reference Manual
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.
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 Q-forms (special forms to represent data similar to Python or Tcl lists), which can be manipulated as data and executed dynamically.
This document describes the stack effects and behavior of the **50 primitive core words**, **3 bootstrapped core words**, and **42 standard library words** present in the reference implementation.
@@ -25,8 +25,8 @@ Stack effects are described in the format:
```
Where:
- The rightmost element is the top of the stack.
- `x`, `y`, `z` represent values (numbers, strings, or quotations).
- `[q]` represents a quotation (a block of code enclosed in brackets, e.g., `[ 1 + ]`).
- `x`, `y`, `z` represent values (numbers, strings, or Q-forms).
- `[q]` represents a Q-form (a block of code or data enclosed in brackets, e.g., `[ 1 + ]`).
- `s` represents a string.
- `c` represents a boolean flag (`1` for true, `0` for false).
@@ -37,7 +37,7 @@ Where:
Clyx supports three basic data types:
1. **Numbers**: Integers (e.g., `42`) and Floating-point numbers (e.g., `3.14`).
2. **Strings**: Sequences of characters enclosed in double quotes. Escaping double quotes (`\"`), backslashes (`\\`), and whitespace characters (`\n` for newline, `\t` for tab, `\r` for carriage return, `\s` for space, `\b` for backspace, `\f` for form feed) is supported inside strings using a backslash (e.g., `"hello \"world\""`, `"a\\b"`, or `"hello\nworld"`).
3. **Quotations**: Ordered lists of values or code blocks enclosed in square brackets (e.g., `[ 1 2 + ]`).
3. **Q-forms** (short for _quotation forms_): Ordered lists of values or code blocks enclosed in square brackets (e.g., `[ 1 2 + ]`).
### Word Name Collision Rule
In Clyx, the evaluation engine executes any string token that matches a defined word name. This means that double-quoted string literals that match a registered word name (such as `"dup"`, `"+"`, or `"."`) **will be executed as that word** when evaluated, rather than being pushed as a literal string.
@@ -75,31 +75,31 @@ Any line fragment starting with `#` to the end of the physical source line is re
---
## 2. Quotation Operations (Lists)
## 2. Q-form Operations
### `cons` (CONStruct)
- **Stack Effect**: `( x [q] -- [x q...] )`
- **Description**: Prepends the element `x` to the beginning of the quotation/list `[q]`.
- **Description**: Prepends the element `x` to the beginning of the Q-form `[q]`.
### `uncons` (UNCONStruct)
- **Stack Effect**: `( [q] -- [q_rest] x 1 )` or `( [] -- [] 0 )`
- **Description**: Deconstructs a quotation or string. If it is non-empty, it pushes the remaining list/string, the first element/character code, and a success flag `1`. If it is empty, it pushes the empty list/string and a failure flag `0`.
- **Description**: Deconstructs a Q-form or string. If it is non-empty, it pushes the remaining Q-form/string, the first element/character code, and a success flag `1`. If it is empty, it pushes the empty Q-form/string and a failure flag `0`.
### `qpop` (Quotation Pop)
### `qpop` (Q-form Pop)
- **Stack Effect**: `( [q] -- [q_rest] x )`
- **Description**: Pops the last element `x` from the quotation/list `[q]`, returning the remaining list and the popped element.
- **Description**: Pops the last element `x` from the Q-form `[q]`, returning the remaining Q-form and the popped element.
### `qlen` (Quotation Length)
### `qlen` (Q-form Length)
- **Stack Effect**: `( [q] -- len )`
- **Description**: Pushes the length of the list `[q]`. Pushes `0` if the operand is not a list.
- **Description**: Pushes the length of the Q-form `[q]`. Pushes `0` if the operand is not a Q-form.
### `qget` (Quotation Get)
### `qget` (Q-form Get)
- **Stack Effect**: `( [q] idx -- x )`
- **Description**: Pushes the element at index `idx` from the list `[q]`. Pushes `None` if the operand is not a list.
- **Description**: Pushes the element at index `idx` from the Q-form `[q]`. Pushes `None` if the operand is not a Q-form.
### `qset` (Quotation Set)
### `qset` (Q-form Set)
- **Stack Effect**: `( x [q] idx -- [q_new] )`
- **Description**: Sets the element at index `idx` in the list `[q]` to the value `x`, returning the modified list. Pushes `None` if the operand is not a list.
- **Description**: Sets the element at index `idx` in the Q-form `[q]` to the value `x`, returning the modified Q-form. Pushes `None` if the operand is not a Q-form.
---
@@ -117,13 +117,13 @@ Any line fragment starting with `#` to the end of the physical source line is re
- **Stack Effect**: `( s -- code )`
- **Description**: Converts the first character of the string `s` to its integer ASCII character code.
### `s2l` (String to List)
### `s2l` (String to Q-form)
- **Stack Effect**: `( val -- [q] )`
- **Description**: Converts the value `val` (if it is a string) to a list of its byte values/integers. If `val` is already a list, it does nothing.
- **Description**: Converts the value `val` (if it is a string) to a Q-form of its byte values/integers. If `val` is already a Q-form, it does nothing.
### `l2s` (List to String)
### `l2s` (Q-form to String)
- **Stack Effect**: `( [q] -- s )`
- **Description**: Converts the list of integers `[q]` (character/byte codes) into its string representation `s`. Reverts the operation of `s2l`.
- **Description**: Converts the Q-form of integers `[q]` (character/byte codes) into its string representation `s`. Reverts the operation of `s2l`.
---
@@ -195,15 +195,15 @@ Any line fragment starting with `#` to the end of the physical source line is re
### `i` (Interpret)
- **Stack Effect**: `( [q] -- )`
- **Description**: "De-quotes" and immediately executes the quotation `[q]`.
- **Description**: "De-quotes" and immediately executes the Q-form `[q]`.
### `cond`
- **Stack Effect**: `( f t c -- )`
- **Description**: Pops the condition `c`, the true branch quotation `t`, and the false branch quotation `f`. If `c` is non-zero, executes `t`; otherwise executes `f`.
- **Description**: Pops the condition `c`, the true branch Q-form `t`, and the false branch Q-form `f`. If `c` is non-zero, executes `t`; otherwise executes `f`.
### `loop`
- **Stack Effect**: `( [cond] [body] -- )`
- **Description**: Repeatedly executes the condition quotation `[cond]`. If the top element of the stack after `[cond]` is non-zero, executes `[body]` and loops again; otherwise terminates.
- **Description**: Repeatedly executes the condition Q-form `[cond]`. If the top element of the stack after `[cond]` is non-zero, executes `[body]` and loops again; otherwise terminates.
### `dip` (Stack-dip)
- **Stack Effect**: `( y [q] -- y )`
@@ -215,7 +215,7 @@ Any line fragment starting with `#` to the end of the physical source line is re
### `defw` (Define Word)
- **Stack Effect**: `( name [q] -- )` or `( name x -- )`
- **Description**: Defines a new word associated with `name`. If the next token in the interpreter stream is `[`, parses it as a quotation and defines `name` to execute that quotation. Otherwise, defines `name` to represent the top stack value `x`.
- **Description**: Defines a new word associated with `name`. If the next token in the interpreter stream is `[`, parses it as a Q-form and defines `name` to execute that Q-form. Otherwise, defines `name` to represent the top stack value `x`.
### `next` (Next Token)
- **Stack Effect**: `( -- token )`
@@ -223,7 +223,7 @@ Any line fragment starting with `#` to the end of the physical source line is re
### `type`
- **Stack Effect**: `( x -- x type_code )`
- **Description**: Inspects the top element of the stack `x` (without popping it) and pushes its type code: `0` if it's a number, `1` if it's a string, or `2` if it's a list (quotation).
- **Description**: Inspects the top element of the stack `x` (without popping it) and pushes its type code: `0` if it's a number, `1` if it's a string, or `2` if it's a Q-form.
---
@@ -277,7 +277,7 @@ Any line fragment starting with `#` to the end of the physical source line is re
### `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.
- **Description**: Lists the contents of the directory at `path`. Pushes a Q-form of strings representing the names of the files and directories inside the directory.
**N.B.**: this primitive may not be supported on all targets.
@@ -303,9 +303,9 @@ Any line fragment starting with `#` to the end of the physical source line is re
### `hsargs` (Host Arguments)
- **Stack Effect**: `( -- [args] )`
- **Description**: Pushes a list/quotation of all passed command line arguments onto the stack.
- **Description**: Pushes a Q-form 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.
**N.B.**: on the platforms that don't support CLI arguments, this primitive will always push an empty Q-form.
### `hsexit` (Host Exit)
- **Stack Effect**: `( code -- )`
@@ -333,11 +333,11 @@ These words are defined in Clyx itself during the interpreter's bootstrap phase:
### `readf` (Read File)
- **Stack Effect**: `( filename -- [content] )`
- **Description**: Reads the entire contents of the file `filename` and pushes it as a list of bytes.
- **Description**: Reads the entire contents of the file `filename` and pushes it as a Q-form of byte values.
### `src` (Source)
- **Stack Effect**: `( filename -- )`
- **Description**: Reads the file `filename` using `readf`, converts the list of bytes to a string using `l2s`, and runs the resulting Clyx code in real-time using `i`.
- **Description**: Reads the file `filename` using `readf`, converts the Q-form of bytes to a string using `l2s`, and runs the resulting Clyx code in real-time using `i`.
---
@@ -367,12 +367,12 @@ These words are defined in the standard library file `lib.clx` and loaded dynami
#### `if`
- **Syntax**: `if [true_actions] [false_actions]`
- **Stack Effect**: `( c -- )` (pops condition from stack, parses branch quotations from the execution stream).
- **Stack Effect**: `( c -- )` (pops condition from stack, parses branch Q-forms from the execution stream).
- **Description**: Executes `true_actions` if `c` is non-zero, otherwise executes `false_actions`.
#### `while`
- **Syntax**: `while [actions]`
- **Stack Effect**: `( -- )` (parses body quotation from the execution stream).
- **Stack Effect**: `( -- )` (parses body Q-form 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.
### 10.3 Mathematics & Arithmetic
@@ -435,7 +435,7 @@ These words are defined in the standard library file `lib.clx` and loaded dynami
#### `puts` (Put String)
- **Stack Effect**: `( s -- )` or `( [q] -- )`
- **Description**: Outputs a string or list of character codes to standard output character-by-character.
- **Description**: Outputs a string or Q-form of character codes to standard output character-by-character.
#### `readln` (Read Line)
- **Stack Effect**: `( -- s )`
@@ -461,9 +461,9 @@ These words are defined in the standard library file `lib.clx` and loaded dynami
- **Stack Effect**: `( x -- x c )`
- **Description**: Pushes `1` if the top stack element `x` is a string; otherwise pushes `0`. Does not pop `x`.
#### `isquot` (Is Quotation)
#### `isq` (Is Q-form)
- **Stack Effect**: `( x -- x c )`
- **Description**: Pushes `1` if the top stack element `x` is a list (quotation); otherwise pushes `0`. Does not pop `x`.
- **Description**: Pushes `1` if the top stack element `x` is a Q-form; otherwise pushes `0`. Does not pop `x`.
#### `=` (Equal)
- **Stack Effect**: `( a b -- c )`
@@ -490,13 +490,13 @@ These words are defined in the standard library file `lib.clx` and loaded dynami
- **Description**: Pops `b`, pops `a`, and pushes `1` if `a` is less than or equal to `b`; 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.
- **Description**: Pushes the length of `val`. If `val` is a Q-form, it returns the number of elements; if it is a string, it returns the number of characters.
### 10.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`.
- **Description**: Pops `s2`, pops `s1`, and pushes `1` if the two strings `s1` and `s2` (or their character Q-form equivalents) are equal; otherwise pushes `0`.
#### `lower` (To Lowercase)
- **Stack Effect**: `( s -- s_lower )`
@@ -506,23 +506,23 @@ These words are defined in the standard library file `lib.clx` and loaded dynami
- **Stack Effect**: `( s -- s_upper )`
- **Description**: Pops the string `s` and pushes its uppercase equivalent `s_upper` onto the stack.
#### `s+` (String / List Concatenation)
#### `s+` (String / Q-form Concatenation)
- **Stack Effect**: `( s1 s2 -- [s1_s2] )`
- **Description**: Concatenates `s1` and `s2` (which can be strings or lists of character codes) and pushes the result as a list of character codes representing the concatenated string.
- **Description**: Concatenates `s1` and `s2` (which can be strings or Q-forms of character codes) and pushes the result as a Q-form of character codes representing the concatenated string.
### 10.8 List Operations
### 10.8 Q-form Operations
#### `qpush` (Quotation Push)
#### `qpush` (Q-form Push)
- **Stack Effect**: `( [q] x -- [q... x] )`
- **Description**: Appends the element `x` to the end of the quotation/list `[q]`.
- **Description**: Appends the element `x` to the end of the Q-form `[q]`.
#### `rev`
- **Stack Effect**: `( [q] -- [q_rev] )`
- **Description**: Reverses the order of elements in the list `[q]`.
- **Description**: Reverses the order of elements in the Q-form `[q]`.
#### `lcat` (List Concatenation)
#### `lcat` (Q-form Concatenation)
- **Stack Effect**: `( [q1] [q2] -- [q1_q2] )`
- **Description**: Concatenates two lists `[q1]` and `[q2]`.
- **Description**: Concatenates two Q-forms `[q1]` and `[q2]`.
### 10.9 Bitwise Operations