Added v0.3

2025-10-24 11:18:56 -06:00 · 2025-10-24 11:18:56 -06:00 · 8f07dc9d42
parent 40671f6d5c
commit 8f07dc9d42
1 changed files with 817 additions and 0 deletions
--- a/stack_lang_spec_v03.md
+++ 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