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 **50 primitive core words**, **3 bootstrapped core words**, and **42 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.
The conventional source file suffix for Clyx code is `.clx`.
The Clyx interpreter accepts one or more `.clx` source files as command-line arguments. If multiple files are specified, the interpreter executes them in the order they are passed.
After running all specified source files, the interpreter checks if a word named `_main` is defined in the workspace. If `_main` is present, it is automatically executed as the program's entry point. If no arguments are passed, it runs the standard interactive REPL.
With the reference implementation installed in a POSIX-compatible environment, Clyx program sources may be made executable if they start with a `#!/usr/bin/env clyx` shebang.
-`x`, `y`, `z` represent values (numbers, strings, or quotations).
-`[q]` represents a quotation (a block of code enclosed in brackets, e.g., `[ 1 + ]`).
-`s` represents a string.
-`c` represents a boolean flag (`1` for true, `0` for false).
---
## Syntax and Data Types
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 + ]`).
### 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.
For example:
- Running `"ok"` pushes the string `"ok"` onto the stack.
- Running `"."` executes the print/output primitive `.`, popping the top element of the stack instead of pushing a dot string.
#### Workaround: Constructing Colliding Strings
To push a string literal that collides with a word name onto the stack, you can construct it dynamically using ASCII codes and the `chr` primitive.
For example, to pass the current directory path `.` to `listd`:
```clx
46 chr listd
```
Where `46` is the ASCII value for `.`. This pushes the string `.` onto the stack without invoking the print primitive, allowing `listd` to consume it.
### Comments
Any line fragment starting with `#` to the end of the physical source line is regarded as a comment in Clyx.
---
## 1. Stack Manipulation Primitives
### `dup` (DUPlicate)
- **Stack Effect**: `( x -- x x )`
- **Description**: Duplicates the top element of the stack.
### `drop`
- **Stack Effect**: `( x -- )`
- **Description**: Discards the top element of the stack.
### `swap`
- **Stack Effect**: `( x y -- y x )`
- **Description**: Exchanges the top two elements of the stack.
---
## 2. Quotation Operations (Lists)
### `cons` (CONStruct)
- **Stack Effect**: `( x [q] -- [x q...] )`
- **Description**: Prepends the element `x` to the beginning of the quotation/list `[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`.
### `qpop` (Quotation 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.
### `qlen` (Quotation Length)
- **Stack Effect**: `( [q] -- len )`
- **Description**: Pushes the length of the list `[q]`. Pushes `0` if the operand is not a list.
### `qget` (Quotation 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.
### `qset` (Quotation 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.
---
## 3. String & Character Operations
### `slen` (String Length)
- **Stack Effect**: `( s -- len )`
- **Description**: Pushes the length of the string `s`. Pushes `0` if the operand is not a string.
### `chr` (Character)
- **Stack Effect**: `( code -- s )`
- **Description**: Converts the integer ASCII character code to a single-character string.
### `asc` (ASCII)
- **Stack Effect**: `( s -- code )`
- **Description**: Converts the first character of the string `s` to its integer ASCII character code.
- **Description**: Pops `y`, pops `x`, and pushes the integer division quotient `div` followed by the modulo remainder `mod` onto the stack.
### `shl` (Shift Left)
- **Stack Effect**: `( x f -- res )`
- **Description**: Pops the shift factor `f`, pops the argument `x`. Performs bit shift left `x << f` if `f` is positive (or zero), and bit shift right `x >> abs(f)` if `f` is negative.
### `^` (Power)
- **Stack Effect**: `( x y -- x^y )`
- **Description**: Pops `y`, pops `x`, and pushes `x` raised to the power of `y`.
### `sin` (Sine)
- **Stack Effect**: `( x -- sin(x) )`
- **Description**: Computes the sine of `x` (in radians).
### `cos` (Cosine)
- **Stack Effect**: `( x -- cos(x) )`
- **Description**: Computes the cosine of `x` (in radians).
### `atan` (Arctangent)
- **Stack Effect**: `( x -- atan(x) )`
- **Description**: Computes the arctangent of `x` (in radians).
### `exp` (Natural Exponent)
- **Stack Effect**: `( x -- exp(x) )`
- **Description**: Computes the exponential of `x` ($e^x$).
### `log` (Natural Logarithm)
- **Stack Effect**: `( x -- log(x) )`
- **Description**: Computes the natural logarithm of `x` ($\ln(x)$).
---
## 5. Logic & Control Flow
### `0=` (Equals to Zero)
- **Stack Effect**: `( x -- c )`
- **Description**: Pushes `1` if `x` is equal to `0`; otherwise pushes `0`.
### `0<` (Less than Zero)
- **Stack Effect**: `( x -- c )`
- **Description**: Pushes `1` if `x` is less than `0`; otherwise pushes `0`.
### `nand` (Bitwise NAND)
- **Stack Effect**: `( x y -- ~(x&y) )`
- **Description**: Pops `y`, pops `x`, and pushes the bitwise NAND of `x` and `y`.
### `i` (Interpret)
- **Stack Effect**: `( [q] -- )`
- **Description**: "De-quotes" and immediately executes the quotation `[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`.
### `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.
### `dip` (Stack-dip)
- **Stack Effect**: `( y [q] -- y )`
- **Description**: Pops `q` and `y`, executes `q` on the remaining stack, and then restores `y` back to the top of the stack.
---
## 6. Metaprogramming & Word Definition
### `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`.
### `next` (Next Token)
- **Stack Effect**: `( -- token )`
- **Description**: Pops and returns the next raw token string from the program execution stream. Returns `None` if the token stream is empty.
### `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).
---
## 7. I/O & System Primitives
### `.` (Print Value)
- **Stack Effect**: `( x -- )`
- **Description**: Outputs the top stack element `x` to standard output, followed by a newline.
### `emit` (Emit Character)
- **Stack Effect**: `( code -- )`
- **Description**: Prints the character represented by the ASCII/Unicode character code integer to standard output without a newline.
### `fopen` (File Open)
- **Stack Effect**: `( filename mode -- fd )`
- **Description**: Opens the file at `filename` with the specified `mode` string (e.g., `"r"` or `"w"`). Pushes the file descriptor/object onto the stack. If `filename` is `0` or `"0"`, it returns standard input (`sys.stdin`) or standard output (`sys.stdout`) depending on the mode.
### `nopen` (Network Open)
- **Stack Effect**: `( host port -- fd )`
- **Description**: Creates a TCP connection.
- If `host` is `"0.0.0.0"`, it starts a listening server TCP socket on `port` and pushes the server socket descriptor onto the stack.
- 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.
- **Description**: Writes the string/bytes `data` to the descriptor `fd`. Returns the number of characters/bytes written. Automatically flushes standard/socket buffers if possible.
### `read`
- **Stack Effect**: `( fd -- data )` or `( fd -- conn_fd )`
- **Description**: Reads from the descriptor `fd`.
- If `fd` is a listening server socket (created by `nlstn`), it accepts the incoming connection and returns the connection file-like descriptor.
- If `fd` is standard input or a socket connection wrapper, it reads a single line (up to a newline character) and returns it with trailing newlines stripped.
- Otherwise (for standard files), it reads the entire contents of the file until EOF.
### `close`
- **Stack Effect**: `( fd -- )`
- **Description**: Closes the file/socket descriptor `fd`. Safe against closing standard streams (`stdin`, `stdout`, `stderr`).
### `delf` (Delete File)
- **Stack Effect**: `( filename -- )`
- **Description**: Deletes the file named `filename` from the file system.
### `maked` (Make Directory)
- **Stack Effect**: `( path -- )`
- **Description**: Creates a new directory at the specified `path`.
- **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.
**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.
- **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.
- **Description**: Pops the string `expr` from the stack and evaluates or executes it in the host environment.
- In the Python implementation, it evaluates `expr` as a Python expression and pushes the resulting value back onto the stack.
- In the Go implementation, it executes `expr` as a system shell command, redirects its stdin/stdout/stderr to the current process, and pushes the command's exit code back onto the stack.
**N.B.**: this primitive may not be supported on all targets, and its behavior varies by implementation. Only use as a last resort in controlled and/or sandboxed environments. Never pass unvalidated user input to this primitive.
- **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`.
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:
- **Stack Effect**: `( c -- )` (pops condition from stack, parses branch quotations 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).
- **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.
- **Description**: Writes the `content` string to the file `filename`. Pushes the number of characters written onto the stack.
#### `nlstn` (Network Listen)
- **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.
- **Description**: Pushes `1` if the top stack element `x` is a number; otherwise pushes `0`. Does not pop `x`.
#### `isstr` (Is String)
- **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)
- **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`.
#### `=` (Equal)
- **Stack Effect**: `( a b -- c )`
- **Description**: Pops `b`, pops `a`, and pushes `1` if `a` is equal to `b`; otherwise pushes `0`.
#### `!=` (Not Equal)
- **Stack Effect**: `( a b -- c )`
- **Description**: Pops `b`, pops `a`, and pushes `1` if `a` is not equal to `b`; otherwise pushes `0`.
#### `<` (Less Than)
- **Stack Effect**: `( a b -- c )`
- **Description**: Pops `b`, pops `a`, and pushes `1` if `a` is less than `b`; otherwise pushes `0`.
#### `>=` (Greater Than or Equal)
- **Stack Effect**: `( a b -- c )`
- **Description**: Pops `b`, pops `a`, and pushes `1` if `a` is greater than or equal to `b`; otherwise pushes `0`.
#### `>` (Greater Than)
- **Stack Effect**: `( a b -- c )`
- **Description**: Pops `b`, pops `a`, and pushes `1` if `a` is greater than `b`; otherwise pushes `0`.
#### `<=` (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`.
#### `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**: 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 the string `s` and pushes its lowercase equivalent `s_lower` onto the stack.
#### `upper` (To Uppercase)
- **Stack Effect**: `( s -- s_upper )`
- **Description**: Pops the string `s` and pushes its uppercase equivalent `s_upper` onto the stack.
#### `s+` (String / List 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.
