From 8f07dc9d424e0130ca382c57438a81a2690d3991 Mon Sep 17 00:00:00 2001
From: Kyler Olsen <yrea2001@gmail.com>
Date: Fri, 24 Oct 2025 11:18:56 -0600
Subject: [PATCH] Added v0.3

---
 stack_lang_spec_v03.md | 817 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 817 insertions(+)
 create mode 100644 stack_lang_spec_v03.md

diff --git a/stack_lang_spec_v03.md b/stack_lang_spec_v03.md
new file mode 100644
index 0000000..207d027
--- /dev/null
+++ b/stack_lang_spec_v03.md
@@ -0,0 +1,817 @@
+# Stack Language Specification v0.3
+
+## 1. Overview
+
+A statically-typed, stack-based language with pure postfix notation combining the execution model of HP's RPL, the type system of C and Rust, and modern array operations from Uiua.
+
+### Design Principles
+- **Everything is postfix** - no exceptions
+- Stack-based execution (no local variables)
+- Static typing with type inference
+- Manual heap memory management
+- Types define what things **are**, traits define how things **act**
+- All constructs are implicitly generic
+- **Every operator is defined by a trait**
+
+## 2. Lexical Structure
+
+### 2.1 Comments
+```
+// Single-line comment
+```
+
+### 2.2 Identifiers
+- Start with letter or underscore: `[a-zA-Z_][a-zA-Z0-9_]*`
+- Case-sensitive
+- Trait names prefixed with `::` (e.g., `::Addable`, `::Number`)
+
+### 2.3 Literals
+
+**Integer Literals**
+```
+42          // i32 (default)
+42 i64      // Annotate as i64
+0xFF        // hexadecimal
+0b1010      // binary
+```
+
+**Floating Point Literals**
+```
+3.14        // f64 (default)
+3.14 f32    // Annotate as f32
+```
+
+**String Literals**
+```
+"hello world"
+"escape sequences: \n \t \\ \""
+```
+
+**Boolean Literals**
+```
+true
+false
+```
+
+**Array Literals**
+```
+[1 2 3 4 5]              // array of i32
+[1.0 2.0 3.0]            // array of f64
+[[1 2] [3 4]]            // 2D array
+```
+
+## 3. Type System
+
+### 3.1 Primitive Types
+- `i8`, `i16`, `i32`, `i64` - Signed integers
+- `u8`, `u16`, `u32`, `u64` - Unsigned integers
+- `f32`, `f64` - Floating point
+- `bool` - Boolean
+- `char` - Single character (UTF-8)
+- `ptr` - Raw pointer (generic over pointed type)
+
+### 3.2 Types vs Traits
+
+**Types** define the concrete structure and memory layout:
+```
+Point struct              // Point is a type
+Rectangle struct          // Rectangle is a type
+```
+
+**Traits** define behavioral contracts - how things act:
+```
+::Drawable trait          // Drawable is a trait
+::Addable trait          // Addable is a trait
+```
+
+**Key Distinction:**
+- A value **has** a type (what it is structurally)
+- A value **implements** a trait (how it behaves)
+- Types are concrete; traits are interfaces
+- Functions can be generic over both types and traits
+- **Every operator must be backed by a trait**
+
+### 3.3 All Constructs are Generic
+
+Every function, struct, and union is implicitly generic. Constraints are specified via traits:
+
+```
+// Function generic over any type T
+(T -- T) { dup * } square fn
+
+// Function requiring T to implement Addable trait
+(T T -- T) ::Addable { + } add_two fn
+
+// Struct generic over field types
+(T T --) { x: y: } Point struct
+
+// Union generic over variant types
+(T --) { Some(T) None } Option union
+```
+
+## 4. Base Traits (Non-Exhaustive)
+
+### 4.1 Core Traits
+
+**::Pushable** - Can be pushed onto the stack
+```
+{ (-- Self) push: } ::Pushable trait
+```
+
+**::ArrayOf** - Array container trait
+```
+{ (-- ArrayOf[T]) create: (ArrayOf[T] i32 -- T) at: } ::ArrayOf trait
+```
+
+**::Addable** - Supports addition and subtraction
+```
+{ (Self Self -- Self) +: (Self Self -- Self) -: } ::Addable trait
+```
+
+**::Number** - Numeric operations
+```
+// Number inherits from multiple traits
+[ ::Addable ::Multiplyable ::Comparable ] ::Number inher
+```
+
+**::String** - String operations
+```
+{ (Self Self -- Self) concat: (Self -- i32) length: } ::String trait
+```
+
+**::Identifier** - Represents identifiers/symbols
+```
+{ (-- TokenString) name: } ::Identifier trait
+```
+
+**::Trait** - Meta-trait for trait operations
+```
+{ (TokenString Identifier --) trait: (Identifier TokenString Identifier --) impl: (ArrayOf[Identifier] Identifier --) inher: } ::Trait trait
+```
+
+### 4.2 Additional Core Traits
+
+**::Multiplyable** - Multiplication and division
+```
+{ (Self Self -- Self) *: (Self Self -- Self) /: (Self Self -- Self) %: } ::Multiplyable trait
+```
+
+**::Comparable** - Comparison operations
+```
+{ (Self Self -- bool) >: (Self Self -- bool) >=: (Self Self -- bool) <: (Self Self -- bool) <=: (Self Self -- bool) ==: (Self Self -- bool) !=: } ::Comparable trait
+```
+
+**::Logical** - Logical operations
+```
+{ (Self Self -- Self) and: (Self Self -- Self) or: (Self -- Self) not: } ::Logical trait
+```
+
+**::Bitwise** - Bitwise operations
+```
+{ (Self Self -- Self) bitand: (Self Self -- Self) bitor: (Self Self -- Self) bitxor: (Self -- Self) bitnot: (Self i32 -- Self) shl: (Self i32 -- Self) shr: } ::Bitwise trait
+```
+
+**::Exponentiable** - Exponentiation
+```
+{ (Self Self -- Self) ^: } ::Exponentiable trait
+```
+
+## 5. Stack Operations
+
+### 5.1 Stack Manipulation
+
+All stack operations are backed by traits.
+
+```
+dup         // ( a -- a a ) Duplicate top [::Duplicable]
+drop        // ( a -- ) Remove top [::Droppable]
+swap        // ( a b -- b a ) Swap top two [::Swappable]
+over        // ( a b -- a b a ) Copy second to top [::Overable]
+rot         // ( a b c -- b c a ) Rotate three items [::Rotatable]
+```
+
+### 5.2 Stack Inspection
+```
+depth       // ( -- n ) Push stack depth [::Inspectable]
+pick        // ( n -- x ) Copy nth item to top (0 = top) [::Pickable]
+roll        // ( n times -- ) Rotate n items, times times [::Rollable]
+```
+
+**Roll Examples:**
+```
+// Stack: a b c d e
+3 1 roll    // Rotate top 3 items once: a b d e c
+3 2 roll    // Rotate top 3 items twice: a b e c d
+5 1 roll    // Rotate all 5 items once: b c d e a
+```
+
+## 6. Operators (Postfix)
+
+**Every operator is backed by a trait and must be implemented for types that use it.**
+
+### 6.1 Arithmetic (::Addable, ::Multiplyable, ::Exponentiable)
+
+```
+3 4 +       // ( a b -- result ) Addition [::Addable]
+10 3 -      // Subtraction [::Addable]
+5 6 *       // Multiplication [::Multiplyable]
+20 4 /      // Division [::Multiplyable]
+17 5 %      // Modulo [::Multiplyable]
+2 8 ^       // Exponentiation [::Exponentiable]
+```
+
+### 6.2 Comparison (::Comparable)
+```
+5 3 >       // Greater than [::Comparable]
+5 3 >=      // Greater or equal [::Comparable]
+5 3 <       // Less than [::Comparable]
+5 3 <=      // Less or equal [::Comparable]
+5 5 ==      // Equal [::Comparable]
+5 3 !=      // Not equal [::Comparable]
+```
+
+### 6.3 Logical (::Logical)
+```
+true false and    // Logical AND [::Logical]
+true false or     // Logical OR [::Logical]
+true not          // Logical NOT [::Logical]
+```
+
+### 6.4 Bitwise (::Bitwise)
+```
+0xFF 0x0F bitand     // Bitwise AND [::Bitwise]
+0xFF 0x0F bitor      // Bitwise OR [::Bitwise]
+0xFF 0x0F bitxor     // Bitwise XOR [::Bitwise]
+0xFF bitnot          // Bitwise NOT [::Bitwise]
+8 2 shl              // Left shift [::Bitwise]
+8 2 shr              // Right shift [::Bitwise]
+```
+
+## 7. Trait System
+
+### 7.1 Trait Definition
+
+**Syntax**: `{ function_signatures } ::name trait`
+
+```
+// Simple trait
+{
+    (Self -- ) draw:
+} ::Drawable trait
+
+// Trait with multiple methods
+{
+    (Self Self -- Self) add:
+    (Self Self -- Self) sub:
+    (Self -- Self) neg:
+} ::Numeric trait
+
+// The comprehensive Trait meta-trait
+{
+    (TokenString Identifier --) trait:
+    (Identifier TokenString Identifier --) impl:
+    (ArrayOf[Identifier] Identifier --) inher:
+} ::Implementable trait
+```
+
+### 7.2 Trait Implementation
+
+**Syntax**: `::type { method_implementations } ::trait impl`
+
+```
+// Implement Addable for i32
+::i32 {
+    (Self Self -- Self) {
+        // Native addition implementation
+    } +:
+    
+    (Self Self -- Self) {
+        // Native subtraction implementation
+    } -:
+} ::Addable impl
+
+// Implement Drawable for Rectangle
+::Rectangle {
+    (Rectangle -- ) {
+        "Drawing rectangle" print
+        dup width get print
+        height get print
+    } draw:
+} ::Drawable impl
+```
+
+### 7.3 Trait Inheritance
+
+**Syntax**: `[ ::trait1 ::trait2 ... ] ::derived_trait inher`
+
+```
+// Number inherits from Addable and Multiplyable
+[ ::Addable ::Multiplyable ] ::Number inher
+
+// Numeric inherits from Number, Comparable, and Exponentiable
+[ ::Number ::Comparable ::Exponentiable ] ::Numeric inher
+
+// Complex inheritance
+[ ::Drawable ::Transformable ::Collidable ] ::GameObject inher
+```
+
+### 7.4 Using Traits in Functions
+
+```
+// Function requiring Drawable trait
+(T -- ) ::Drawable {
+    draw
+} draw_twice fn
+
+// Multiple trait requirements
+(T -- T) ::Numeric ::Copyable {
+    dup abs swap dup * +
+} complex_calc fn
+```
+
+## 8. Functions (Postfix Definition)
+
+Functions are defined in postfix notation. The signature and body come before the name.
+
+### 8.1 Basic Function Definition
+
+**Syntax**: `(inputs -- outputs) { body } name fn`
+
+```
+// Define a square function
+(i32 -- i32) { dup * } square fn
+
+// Use it
+5 square      // 25
+
+// Multiple inputs and outputs
+(i32 i32 -- i32 i32) {
+    2dup / swap %
+} divmod fn
+
+10 3 divmod   // 3 1 (quotient remainder)
+```
+
+### 8.2 Generic Functions with Trait Constraints
+
+**Syntax**: `(type_sig) ::trait_constraints { body } name fn`
+
+```
+// Generic identity - works with any type
+(T -- T) {} identity fn
+
+// Requires T to be Addable
+(T T -- T) ::Addable {
+    +
+} add_values fn
+
+// Multiple trait constraints
+(T U -- U T) ::Copyable ::Swappable {
+    swap
+} swap_generic fn
+
+// Multiple type parameters with different traits
+(T U -- T) ::Addable ::Numeric {
+    dup U as +
+} add_converted fn
+```
+
+## 9. Control Flow (Postfix)
+
+### 9.1 Conditionals
+
+**Syntax**: `condition { then-block } { else-block } if`
+
+```
+// if-then (else block is empty)
+x 0 > { "positive" print } {} if
+
+// if-then-else
+x 0 > 
+    { "positive" print } 
+    { "non-positive" print } 
+if
+
+// The condition comes first, then both blocks, then 'if'
+a b > 
+    { a } 
+    { b } 
+if max set
+
+// Nested
+x 0 >
+    {
+        y 0 >
+            { "both positive" print }
+            { "x positive, y not" print }
+        if
+    }
+    { "x not positive" print }
+if
+```
+
+### 9.2 Loops
+
+**While Loop**
+
+**Syntax**: `{ condition-block } { body-block } while`
+
+```
+// Sum 1 to 10
+0 1                              // sum counter
+    { dup 10 <= }                // condition block
+    {                            // body block
+        over over +              // Add counter to sum
+        swap 1 + swap            // Increment counter
+    }
+while
+drop                             // Drop counter, leave sum
+
+// Infinite loop with break
+{ true } {
+    // body
+    condition { break } {} if
+} while
+```
+
+**For Loop**
+
+**Syntax**: `start end { body-with-counter } for`
+
+```
+// The loop variable is implicitly pushed to stack in each iteration
+1 10 { 
+    // Stack has loop counter on top
+    dup print
+} for
+
+// More complex
+1 100 {
+    dup fizzbuzz
+} for
+```
+
+### 9.3 Loop Control
+```
+break       // Exit loop
+continue    // Skip to next iteration
+```
+
+### 9.4 Match/Pattern Matching
+
+**Syntax**: `value { pattern => block ... } match`
+
+```
+value {
+    Some(x) => { x print }
+    None => { "Nothing" print }
+} match
+
+// With multiple patterns
+status {
+    Pending => { "Waiting" print }
+    Active => { "Running" print }
+    Complete => { "Done" print }
+} match
+```
+
+## 10. Data Structures (Postfix)
+
+### 10.1 Struct Definition
+
+**Syntax**: `(field_types -- ) { field_names } name struct`
+
+```
+// Define Point struct - generic over coordinate types
+(T T --) { x: y: } Point struct
+
+// Use with specific types
+3.0 4.0 Point       // Creates Point with f64 fields
+3 4 Point           // Creates Point with i32 fields
+
+// More complex struct
+(T U V --) { 
+    width: 
+    height: 
+    depth: 
+} Box3D struct
+
+10.0 20.0 30.0 Box3D
+```
+
+### 10.2 Struct Field Access
+
+**Syntax (postfix)**: `struct field get` or `struct value field set`
+
+```
+point x get         // Get x field
+point 15.0 x set    // Set x field to 15.0
+
+// Chaining
+point x get 2 * y get +     // (point.x * 2) + point.y
+```
+
+### 10.3 Union Definition
+
+**Syntax**: `(variant_types -- ) { variants } name union`
+
+```
+// Option type - generic over T
+(T --) { 
+    Some(T) 
+    None 
+} Option union
+
+// Result type - generic over T and E
+(T E --) { 
+    Ok(T) 
+    Err(E) 
+} Result union
+
+// Create union values
+42 Some             // Creates Option::Some(42)
+None                // Creates Option::None
+"success" Ok        // Creates Result::Ok("success")
+"error" Err         // Creates Result::Err("error")
+```
+
+### 10.4 Enum Definition
+
+**Syntax**: `() { variants } name enum`
+
+```
+() { 
+    Pending 
+    Active 
+    Complete 
+} Status enum
+
+// Usage
+Pending             // Creates Status::Pending
+Active              // Creates Status::Active
+```
+
+## 11. Memory Management (Postfix)
+
+### 11.1 Heap Operations
+
+```
+// Allocate
+3.0 4.0 Point alloc     // ( Point -- ptr<Point> )
+
+// Dereference
+ptr deref               // ( ptr<T> -- T )
+
+// Store (dereference and update)
+new_value ptr store     // ( T ptr<T> -- )
+
+// Free
+ptr free                // ( ptr<T> -- )
+```
+
+### 11.2 Example
+
+```
+// Create heap-allocated point
+3.0 4.0 Point alloc     // Returns ptr<Point>
+dup x get print         // Dereference and print x
+free                    // Clean up
+```
+
+## 12. Array Operations (Postfix)
+
+### 12.1 Basic Array Operations
+
+```
+// Creation
+1 10 range              // Create range array [1..10]
+
+// Shape operations
+arr shape               // Get shape
+arr 2 3 reshape         // Reshape to 2x3
+
+// Element access
+arr 2 at                // Index access
+arr 1 3 slice           // Slice array
+```
+
+### 12.2 Array Combinators
+
+```
+// Map - apply function to each element
+[1 2 3 4] { 2 * } map        // [2 4 6 8]
+
+// Filter - keep elements matching predicate
+[1 2 3 4 5] { 2 % 0 == } filter   // [2 4]
+
+// Reduce - fold with function
+[1 2 3 4] 0 { + } reduce     // 10
+
+// Each - apply to each element (side effects)
+[[1 2] [3 4]] { sum print } each
+```
+
+### 12.3 Array Arithmetic
+
+```
+[1 2 3] [4 5 6] +.      // Element-wise add: [5 7 9]
+[1 2 3] [4 5 6] *.      // Element-wise multiply: [4 10 18]
+[1 2 3] 2 *.            // Scalar multiply: [2 4 6]
+```
+
+### 12.4 Array Manipulation
+
+```
+[1 2 3] [4 5 6] concat  // Concatenate: [1 2 3 4 5 6]
+[1 2 3] reverse         // [3 2 1]
+[[1 2] [3 4]] transpose // [[1 3] [2 4]]
+[1 2 3 4] 2 window      // [[1 2] [2 3] [3 4]]
+```
+
+## 13. Eval Operator (Postfix)
+
+Execute code dynamically at runtime.
+
+```
+// Evaluate string as code
+"2 3 +" eval            // Pushes 5
+
+// Build and execute code
+"(i32 -- i32) { dup * } square fn" eval
+5 square                // 25
+
+// Dynamic dispatch
+operation_name " get" concat eval
+```
+
+## 14. Standard Library Concepts
+
+### 14.1 I/O
+
+```
+"Hello" print           // Print to stdout
+"Enter name: " input    // Read from stdin
+"file.txt" read         // Read file contents
+"data" "file.txt" write // Write to file
+```
+
+### 14.2 String Operations
+
+```
+"hello" " world" concat     // Concatenate: "hello world"
+"hello" length              // 5
+"hello" 1 3 substr          // "el"
+"a,b,c" "," split           // ["a" "b" "c"]
+["a" "b"] "," join          // "a,b"
+```
+
+### 14.3 Type Conversion
+
+```
+42 f64 as               // Convert i32 to f64
+"123" i32 parse         // Parse string to i32
+3.14 str as             // Convert to string
+```
+
+## 15. Complete Examples
+
+### 15.1 Trait Implementation Example
+
+```
+// Define the Addable trait
+{
+    (Self Self -- Self) +:
+    (Self Self -- Self) -:
+} ::Addable trait
+
+// Implement for i32
+::i32 {
+    (Self Self -- Self) {
+        // Native addition
+    } +:
+    
+    (Self Self -- Self) {
+        // Native subtraction
+    } -:
+} ::Addable impl
+
+// Implement for Point
+::Point {
+    (Point Point -- Point) {
+        over x get over x get +
+        swap y get swap y get +
+        Point
+    } +:
+    
+    (Point Point -- Point) {
+        over x get over x get -
+        swap y get swap y get -
+        Point
+    } -:
+} ::Addable impl
+```
+
+### 15.2 Trait Inheritance Example
+
+```
+// Define base traits
+{ (Self Self -- Self) +: (Self Self -- Self) -: } ::Addable trait
+{ (Self Self -- Self) *: (Self Self -- Self) /: } ::Multiplyable trait
+{ (Self Self -- Self) ^: } ::Exponentiable trait
+
+// Number inherits from multiple traits
+[ ::Addable ::Multiplyable ] ::Number inher
+
+// Numeric extends Number further
+[ ::Number ::Exponentiable ] ::Numeric inher
+```
+
+### 15.3 Factorial
+
+```
+(i32 -- i32) {
+    dup 1 
+        { drop 1 } 
+        { dup 1 - factorial * } 
+    <= if
+} factorial fn
+
+5 factorial print       // 120
+```
+
+### 15.4 FizzBuzz
+
+```
+(i32 -- ) {
+    dup 15 % 0 ==
+        { drop "FizzBuzz" print }
+        {
+            dup 3 % 0 ==
+                { drop "Fizz" print }
+                {
+                    dup 5 % 0 ==
+                        { drop "Buzz" print }
+                        { print }
+                    if
+                }
+            if
+        }
+    if
+} fizzbuzz fn
+
+1 100 { fizzbuzz } for
+```
+
+### 15.5 Using Roll
+
+```
+// Stack: 1 2 3 4 5
+3 1 roll    // Rotate top 3 once: 1 2 4 5 3
+3 2 roll    // Rotate top 3 twice: 1 2 5 3 4
+
+// More complex example
+10 20 30 40 50
+4 2 roll    // Rotate top 4, twice: 10 30 40 50 20
+```
+
+### 15.6 Array Processing
+
+```
+// Sum of squares of even numbers from 1 to 10
+[1 2 3 4 5 6 7 8 9 10]
+    { 2 % 0 == } filter     // Keep even numbers
+    { dup * } map           // Square each
+    0 { + } reduce          // Sum
+print                       // 220
+```
+
+## 16. Syntax Summary
+
+### Complete Grammar Patterns
+
+**Functions**: `(in -- out) ::constraints { body } name fn`
+
+**Structs**: `(types -- ) { fields: } name struct`
+
+**Unions**: `(types -- ) { Variant(T) ... } name union`
+
+**Enums**: `() { Variant ... } name enum`
+
+**Traits**: `{ (sig) method: ... } ::name trait`
+
+**Trait Impl**: `::Type { (sig) { body } method: ... } ::Trait impl`
+
+**Trait Inheritance**: `[ ::Trait1 ::Trait2 ] ::NewTrait inher`
+
+**If**: `condition { then } { else } if`
+
+**While**: `{ condition } { body } while`
+
+**For**: `start end { body } for`
+
+**Match**: `value { pattern => block ... } match`
+
+---
+
+**Version**: 0.3  
+**Status**: Draft Specification - Trait-Backed Operations Edition
\ No newline at end of file