clyx/clyx_manual.md

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.

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.

The conventional source file suffix for Clyx code is .clx.

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.

---

Conventions

Stack effects are described in the format:

( before -- after )

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 + ]).
• 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:

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.

---

4. Arithmetic & Mathematics

+

• Stack Effect: ( x y -- x+y )
• Description: Pops y, pops x, and pushes x + y.

-

• Stack Effect: ( x y -- x-y )
• Description: Pops y, pops x, and pushes x - y.

*

• Stack Effect: ( x y -- x*y )
• Description: Pops y, pops x, and pushes x * y.

/

• Stack Effect: ( x y -- x/y )
• Description: Pops y, pops x, and pushes x / y (floating-point division).

divmod (Divide/Modulo)

• Stack Effect: ( x y -- div mod )
• 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.

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.

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.

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.

.s (Print Stack)

• Stack Effect: ( -- )
• Description: Prints the current stack representation to standard output (useful for debugging).

hsargs (Host Arguments)

• Stack Effect: ( -- [args] )
• Description: Pushes a list/quotation of all passed command line arguments onto the stack.

hsexit (Host Exit)

• Stack Effect: ( code -- )
• Description: Exits the program/interpreter with the specified exit code.

hseval (Host Language Evaluation)

• 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

These words are defined in Clyx itself during the interpreter's bootstrap phase:

:: (Define Inline)

• Stack Effect: ( -- )
• Description: Metaprogramming helper used to define inline words. Defined as [ next defw ].

readf (Read File)

• Stack Effect: ( filename -- content )
• Description: Reads the entire contents of the file filename and pushes it as a string.

src (Source)

• Stack Effect: ( filename -- )
• Description: Reads the file filename using readf and runs the resulting string of Clyx code in real-time using i.

---

9. 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

over

• Stack Effect: ( x y -- x y x )
• Description: Copies the second stack element to the top of the stack.

nip

• Stack Effect: ( x y -- y )
• Description: Discards the second stack element from the top of the stack.

tuck

• Stack Effect: ( x y -- y x y )
• Description: Duplicates the top stack element and inserts it below the second element.

rot (ROTate)

• Stack Effect: ( x y z -- y z x )
• Description: Rotates the third element of the stack to the top.

9.2 Control Flow

if

• Syntax: if [true_actions] [false_actions]
• 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.

9.3 Mathematics & Arithmetic

div (Divide Integer Values)

• Stack Effect: ( x y -- div )
• Description: Performs integer division of x by y. Bootstrapped using divmod.

mod (MODulo)

• Stack Effect: ( x y -- mod )
• Description: Calculates the modulo remainder of x divided by y. Bootstrapped using divmod.

sqrt (Square Root)

• Stack Effect: ( x -- res )
• Description: Calculates the square root of x (by raising x to the power of 0.5).

tan (Tangent)

• Stack Effect: ( x -- tan(x) )
• Description: Calculates the tangent of x (defined as sin(x) / cos(x)).

cotan (Cotangent)

• Stack Effect: ( x -- cotan(x) )
• Description: Calculates the cotangent of x (defined as cos(x) / sin(x)).

neg (NEGate)

• Stack Effect: ( x -- -x )
• Description: Negates the number x (defined as 0 - x).

1/ (Reciprocal)

• Stack Effect: ( x -- 1/x )
• Description: Calculates the multiplicative inverse of x (defined as 1 / x).

shr (Shift Right)

• Stack Effect: ( x f -- res )
• Description: Performs bit shift right of x by f bits (defined using neg and shl).

9.4 Logical Operators

not

• Stack Effect: ( x -- c )
• Description: Logical NOT. Pushes 1 if x is zero, else pushes 0.

and

• Stack Effect: ( x y -- c )
• Description: Logical AND. Pushes 1 if both x and y are non-zero, else pushes 0.

or

• 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

cr (Carriage Return / Newline)

• Stack Effect: ( -- )
• Description: Emits a newline character (ASCII 10).

space

• Stack Effect: ( -- )
• Description: Emits a space character (ASCII 32).

puts (Put String)

• Stack Effect: ( s -- ) or ( [q] -- )
• Description: Outputs a string or list of character codes to standard output character-by-character.

readln (Read Line)

• Stack Effect: ( -- s )
• Description: Reads a line of input from standard input and pushes it as a string.

writef (Write File)

• Stack Effect: ( content filename -- count )
• 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.

N.B.: this word may not be supported on all targets.

9.6 Type Checking & Comparison

isnum (Is Number)

• Stack Effect: ( x -- x c )
• 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.

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.

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.

s2l (String to List)

• 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

qpush (Quotation Push)

• Stack Effect: ( [q] x -- [q... x] )
• Description: Appends the element x to the end of the quotation/list [q].

rev

• Stack Effect: ( [q] -- [q_rev] )
• Description: Reverses the order of elements in the list [q].

lcat (List Concatenation)

• Stack Effect: ( [q1] [q2] -- [q1_q2] )
• Description: Concatenates two lists [q1] and [q2].

9.9 Bitwise Operations

bitnot (Bitwise NOT)

• Stack Effect: ( x -- ~x )
• Description: Pops x and pushes its bitwise NOT equivalent ~x onto the stack.

bitand (Bitwise AND)

• Stack Effect: ( x y -- x&y )
• Description: Pops y, pops x, and pushes their bitwise AND result x & y onto the stack.

bitor (Bitwise OR)

• Stack Effect: ( x y -- x|y )
• Description: Pops y, pops x, and pushes their bitwise OR result x | y onto the stack.

bitxor (Bitwise XOR)

• Stack Effect: ( x y -- x^y )
• Description: Pops y, pops x, and pushes their bitwise XOR result x ^ y onto the stack.