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

Execution and Entry Point

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.

---

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

---

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

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. Q-form Operations

cons (CONStruct)

• Stack Effect: ( x [q] -- [x 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 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 (Q-form Pop)

• Stack Effect: ( [q] -- [q_rest] x )
• Description: Pops the last element x from the Q-form [q], returning the remaining Q-form and the popped element.

qlen (Q-form Length)

• Stack Effect: ( [q] -- len )
• Description: Pushes the length of the Q-form [q]. Pushes 0 if the operand is not a Q-form.

qget (Q-form Get)

• Stack Effect: ( [q] idx -- x )
• Description: Pushes the element at index idx from the Q-form [q]. Pushes None if the operand is not a Q-form.

qset (Q-form Set)

• Stack Effect: ( x [q] idx -- [q_new] )
• 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.

---

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.

s2q (String to Q-form)

• Stack Effect: ( val -- [q] )
• 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.

q2s (Q-form to String)

• Stack Effect: ( [q] -- s )
• Description: Converts the Q-form of integers [q] (character/byte codes) into its string representation s. Reverts the operation of s2q.

---

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 Q-form [q].

cond

• Stack Effect: ( f t c -- )
• 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 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 )
• 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 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 )
• 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 Q-form.

---

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

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

---

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 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 Q-form.

hsexit (Host Exit)

• Stack Effect: ( 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 Evaluation / Execution)

• Stack Effect: ( expr -- val )
• 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.

---

9. 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 Q-form of byte values.

src (Source)

• Stack Effect: ( filename -- )
• Description: Reads the file filename using readf, converts the Q-form of bytes to a string using q2s, and runs the resulting Clyx code in real-time using i.

---

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:

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

10.2 Control Flow

if

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

qfor

• Stack Effect: ( [actions] [list] -- )
• Description: Iterates the action Q-form [actions] for every item in [list]. Pushes the item on top of the stack before executing [actions].

for

• Syntax: for [range_qform] [actions]
• Stack Effect: ( -- ) (parses range and action Q-forms from the execution stream).
• Description: Evaluates [range_qform] to produce a list, then performs the same operation as qfor using the resulting list and the action Q-form [actions].

10.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).

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

10.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 Q-form of character codes to standard output character-by-character.

say

• Syntax: say "message"
• Stack Effect: ( -- ) (parses string literal from the execution stream).
• Description: Parses a string literal from the execution stream, prints it to standard output, and outputs a newline. Defined as [ next puts cr ].

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.

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

isq (Is Q-form)

• Stack Effect: ( x -- x c )
• 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 )
• 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 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 Q-form 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 / Q-form Concatenation)

• Stack Effect: ( s1 s2 -- [s1_s2] )
• 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 Q-form Operations

qpush (Q-form Push)

• Stack Effect: ( [q] x -- [q... x] )
• 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 Q-form [q].

lcat (Q-form Concatenation)

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

range

• Stack Effect: ( start end -- [q] )
• Description: Generates a Q-form containing all integer numbers from start to end (including start but not including end). Returns an empty Q-form if start is greater than or equal to end.

allot

• Stack Effect: ( length -- [q] )
• Description: Pops the length integer from the stack, creates a contiguous Q-form of that length where every element is the number 0, and pushes it back onto the stack. If length is less than or equal to 0, returns an empty Q-form.

map

• Stack Effect: ( [list] [op] -- [res] ) or ( [list] name -- [res] )
• Description: Applies the operation [op] (either an executable Q-form or a defined word name) to each element of the Q-form [list]. Pushes the resulting Q-form [res] back onto the stack.

filter

• Stack Effect: ( [list] [op] -- [res] ) or ( [list] name -- [res] )
• Description: Filters elements of the Q-form [list] by applying the predicate operation [op] (either an executable Q-form or a defined word name) to each element. Returns a new Q-form [res] containing only the elements for which the predicate returned a truthy value.

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

10.10 Metaprogramming & System

source

• Syntax: source filename
• Stack Effect: ( -- ) (parses filename from the execution stream).
• Description: Reads and executes the Clyx source file filename dynamically.

then

• Stack Effect: ( -- )
• Description: A no-op word (does nothing). Useful for syntactic readability in control flow.

_start

• Syntax: _start [actions]
• Stack Effect: ( -- ) (parses actions Q-form from the execution stream).
• Description: Defines the entry point of the program by setting the _main word to execute [actions].

is

• Syntax: name is [actions]
• Stack Effect: ( name -- ) (parses actions Q-form from the execution stream).
• Description: A synonym/helper for :: used to define inline words. Defined as [ next defw ].

set

• Syntax: set name [actions]
• Stack Effect: ( -- ) (parses name and actions Q-form from the execution stream).
• Description: Defines a word dynamically by parsing its name and its actions Q-form from the execution stream. Defined as [ next next defw ].