v0.3.1: range/qfor/for in stdlib

README.md

@@ -10,7 +10,7 @@ Clyx aims for maximum portability and can be implemented in any modern runtime e
 
 The core spec of Clyx is mostly stable but the standard library is still a work-in-progress.
 
-The most recent Clyx version is **0.3**. The version is bumped every time the language core words (aka primitives), the standard library or the REPL get updated. The primitive set is expected to be indefinitely frozen once the version number reaches 1.0.
+The most recent Clyx version is **0.3.1**. The version is bumped every time the language core words (aka primitives), the standard library or the REPL get updated. The primitive set is expected to be indefinitely frozen once the version number reaches 1.0.
 
 ## Language features
 

clyx-python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "clyx"
-version = "0.3"
+version = "0.3.1"
 description = "Clyx programming language interpreter"
 readme = "README.md"
 requires-python = ">=3.7"

clyx_manual.md

@@ -2,7 +2,7 @@
 
 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.
+This document describes the stack effects and behavior of the **50 primitive core words**, **3 bootstrapped core words**, and **45 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.
 
@@ -375,6 +375,15 @@ These words are defined in the standard library file `lib.clx` and loaded dynami
 - **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)
@@ -524,6 +533,10 @@ These words are defined in the standard library file `lib.clx` and loaded dynami
 - **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`.
+
 ### 10.9 Bitwise Operations
 
 #### `bitnot` (Bitwise NOT)

examples/hello.clx

@@ -0,0 +1,4 @@
+#!/usr/bin/env clyx
+:: _main [
+  "Hello, world!" puts cr
+]

lib.clx

@@ -47,3 +47,6 @@
 :: bitxor [ over over bitnot bitand [ swap bitnot bitand ] dip bitor ]
 :: rev [ [] swap uncons while [ [ swap ] dip swap cons swap uncons ] drop ]
 :: s+ [ s2q [ s2q ] dip lcat ]
+:: range [ [] [ over over < ] dip swap while [ [ over ] dip qpush [ swap 1 + swap ] dip [ over over < ] dip swap ] nip nip ]
+:: qfor [ dup qlen while [ uncons drop [ [] cons cons ] dip swap dup 0 qget dip uncons drop swap 0 qget dup qlen ] drop drop ]
+:: for [ next next [ i ] dip swap qfor ]

test.clx

@@ -21,6 +21,9 @@
 0 if [ "  if false FAIL" ] [ "  if false PASS" ] puts cr  # Test if false
 10 20 [ 5 - ] dip [] cons cons [ 5 20 ] streq if [ "  dip PASS" puts cr ] [ "  dip FAIL" puts cr ]  # Test dip
 5 dup while [ 1 - dup ] 0 = if [ "  while loop PASS" puts cr ] [ "  while loop FAIL" puts cr ]  # Test while
+0 [ + ] [ 1 2 3 ] qfor 6 = 0 [ + ] [] qfor 0 = and if [ "  qfor PASS" puts cr ] [ "  qfor FAIL" puts cr ]  # Test qfor
+0 for [ 1 4 range ] [ + ] 6 = 0 for [ [] ] [ + ] 0 = and if [ "  for PASS" puts cr ] [ "  for FAIL" puts cr ]  # Test for
+
 
 # 3. Mathematics & Arithmetic
 "Testing math and logic..." puts cr
@@ -188,6 +191,8 @@ if [
 ] [
   "  rev, lcat and s2q FAIL" puts cr
 ]
+2 5 range [ 2 3 4 ] streq 5 2 range [] streq and 5 5 range [] streq and if [ "  range PASS" puts cr ] [ "  range FAIL" puts cr ]  # Test range
+
 
 # 9. Bitwise Operations
 "Testing bitwise operations..." puts cr