From 6bab5067612cf2013a0ed2f60148510ca2df874d Mon Sep 17 00:00:00 2001 From: Kyler Date: Sun, 26 Oct 2025 22:23:24 -0600 Subject: [PATCH] v0.8 --- stack_lang_spec.md | 4468 +++++++++++++++++++++++++++++++------------- 1 file changed, 3213 insertions(+), 1255 deletions(-) diff --git a/stack_lang_spec.md b/stack_lang_spec.md index 5793c33..8300e1e 100644 --- a/stack_lang_spec.md +++ b/stack_lang_spec.md @@ -1,6 +1,6 @@ # Stack Language Specification -**Version**: 0.7.1 +**Version**: 0.8 **Status**: Draft Specification **Changes**: - 0.5 (AI) @@ -60,6 +60,15 @@ 1. Formatting changes - 0.7.2 (Human) 1. Removed AI editing restrictions of reviewed code blocks +- 0.8 (AI) + 1. **Document reorganization** - Restructured for user-focused learning + 2. **Section consolidation** - Moved implementation details to appendices + 3. **Minimal duplication** - Added cross-references instead of repeating content + 4. **Shorter sections** - Split large sections into focused subsections + 5. **New appendices** - Added Standard Library and Operator references + 6. **Tutorial content** - Added beginner tutorials to Appendix G + 7. **Trait reference** - Consolidated all trait definitions in Appendix B + 8. **Grammar simplification** - Referenced Implementable trait instead of repeating --- @@ -95,6 +104,46 @@ A statically-typed, stack-based language with pure postfix notation combining th **Naming Rule**: Once a name is used for either an operator or a function, it cannot be reused for the other category. +### Document Organization + +This specification is organized to support both learning and reference: + +**Sections 1-7** cover the fundamentals needed to write basic programs: +- Lexical structure, primitive types, basic operations +- Functions and control flow +- Data structures + +**Sections 8-10** cover intermediate concepts: +- Type system formalization +- Trait system for behavioral contracts +- Generic programming + +**Section 11** covers advanced topics: +- Dynamic code evaluation +- Identifier literals +- Standard library overview + +**Appendices** provide complete references: +- A: Standard Library (alphabetical reference) +- B: Complete Trait Reference (all trait definitions) +- C: Complete Operator Reference (all operators) +- D: Grammar Summary +- E: Module System (future) +- F: Memory Management (future) +- G: Examples & Tutorials + +### Reading Guide + +**New users**: Start with Sections 1-7 to learn the language basics. Work through the tutorials in Appendix G as you go. + +**Experienced programmers**: Skim Sections 1-4, focus on Sections 5-11 for language-specific features. + +**Implementers**: Read all sections, paying special attention to Sections 8-10 and Appendices B-D for complete specifications. + +**Reference lookup**: Use Appendices A-C for quick reference to standard library functions, traits, and operators. + +--- + ## 2. Lexical Structure ### 2.1 Comments @@ -115,10 +164,7 @@ A statically-typed, stack-based language with pure postfix notation combining th - Example: `::Addable` pushes the identifier `Addable` onto the stack - Example: `::Point` pushes the identifier `Point` onto the stack -**Identifier Literal Rules by Context**: -- **Function bodies and eval**: `::` is required for identifier literals -- **Trait definitions**: `::` is not allowed (identifiers are method names) -- **Trait implementations**: `::` is not allowed (identifiers are method names) +> **Advanced Usage**: See Section 11.2 for complete identifier literal rules and context-dependent behavior. ### 2.3 Literals @@ -168,19 +214,709 @@ false [[1 2] [3 4]] // 2D array ``` -**Type Tuples** +--- + +## 3. Primitive Types + +The language provides several built-in primitive types for common values: + +**Integer Types** +- `i8`, `i16`, `i32`, `i64` - Signed integers (8, 16, 32, 64 bits) +- `u8`, `u16`, `u32`, `u64` - Unsigned integers (8, 16, 32, 64 bits) +- Default integer literal type: `i64` + +**Floating Point Types** +- `f32` - Single-precision floating point (32 bits) +- `f64` - Double-precision floating point (64 bits) +- Default floating point literal type: `f64` + +**Other Types** +- `bool` - Boolean values (`true` or `false`) +- `char` - Single UTF-8 character + +**Type Annotations** + +You can explicitly annotate literal types: +``` +42:i32 // 32-bit integer +3.14:f32 // 32-bit float +``` + +**Pointer Types** + +Raw pointers (`ptr`) are a future feature. See Appendix F for the planned pointer type system. + +> **Related**: See Section 8 for the complete type system, including composite types and type inference. + +--- + +## 4. Basic Operations + +### 4.1 Stack Operations + +Stack manipulation is fundamental to the language. All values exist on the stack, and these operations let you rearrange them. + +**Basic Manipulation** +``` +dup // ( a -- a a ) Duplicate top item +drop // ( a -- ) Remove top item +swap // ( a b -- b a ) Swap top two items +over // ( a b -- a b a ) Copy second item to top +rot // ( a b c -- b c a) Rotate top three items +``` + +**Stack Inspection** +``` +depth // ( -- n ) Push current stack depth +pick // ( n -- x ) Copy nth item to top (0 = top) +roll // ( n times -- ) Rotate n items, times times +``` + +**Stack Effect Notation**: Throughout this specification, comments use stack effect notation to show what operations consume and produce. The format is `// ( before -- after )` where items on the left of `--` are consumed from the stack, and items on the right are produced. + +**Examples**: +``` +5 dup // => 5 5 +5 10 swap // => 10 5 +1 2 3 rot // => 2 3 1 +1 2 3 depth // => 1 2 3 3 +``` + +> **Implementation Details**: Stack operations implement the `::Stackable` trait. See Appendix B for the complete trait definition. + +### 4.2 Arithmetic Operators + +Basic arithmetic operations work on numeric types: + +``` +3 4 + // ( a b -- result ) Addition +10 3 - // ( a b -- result ) Subtraction +5 6 * // ( a b -- result ) Multiplication +20 4 / // ( a b -- result ) Division +17 5 % // ( a b -- result ) Modulo (remainder) +2 8 ^ // ( a b -- result ) Exponentiation +100 log // ( a -- result ) Logarithm base 10 +2.718 ln // ( a -- result ) Natural logarithm +``` + +**Examples**: +``` +10 5 + // => 15 +10 3 / // => 3 +10 3 % // => 1 +2 10 ^ // => 1024 +``` + +> **Implementation Details**: Arithmetic operators implement the `::Addable`, `::Multiplyable`, `::Exponentiable`, and `::Logarithmic` traits. See Appendix B for complete trait definitions and Appendix C for the full operator reference. + +### 4.3 Comparison Operators + +Comparison operations return boolean values: + +``` +5 3 > // ( a b -- bool ) Greater than +5 3 >= // ( a b -- bool ) Greater or equal +5 3 < // ( a b -- bool ) Less than +5 3 <= // ( a b -- bool ) Less or equal +5 5 == // ( a b -- bool ) Equal +5 3 != // ( a b -- bool ) Not equal +``` + +**Examples**: +``` +10 5 > // => true +10 10 == // => true +10 5 < // => false +``` + +> **Implementation Details**: Comparison operators implement the `::Orderable` and `::Equatable` traits. See Appendix B for complete trait definitions. + +### 4.4 Logical Operators + +Logical operations work with boolean values and truthiness: + +``` +true false and // ( a b -- result ) Logical AND +true false or // ( a b -- result ) Logical OR +true not // ( a -- result ) Logical NOT +``` + +**Truthiness**: Non-boolean values can be tested for truthiness. By default, most values are truthy. Numbers are falsy when zero, `Option::None` is falsy, `Result::Err` is falsy. + +**Examples**: +``` +true true and // => true +true false or // => true +false not // => true +5 0 and // => 0 (falsy) +``` + +> **Implementation Details**: Logical operators implement the `::Logical` trait. See Appendix B for the complete trait definition and truthiness rules. + +### 4.5 Bitwise Operators + +Bitwise operations work on integer types: + +``` +0xFF 0x0F bitand // ( a b -- result ) Bitwise AND +0xFF 0x0F bitor // ( a b -- result ) Bitwise OR +0xFF 0x0F bitxor // ( a b -- result ) Bitwise XOR +0xFF bitnot // ( a -- result ) Bitwise NOT +8 2 shl // ( a n -- result ) Left shift +8 2 shr // ( a n -- result ) Right shift +``` + +**Examples**: +``` +0xFF 0x0F bitand // => 0x0F +0xF0 0x0F bitor // => 0xFF +0xFF bitnot // => 0xFFFFFFFFFFFFFF00 (on 64-bit) +4 2 shl // => 16 +``` + +> **Implementation Details**: Bitwise operators implement the `::Bitwise` trait. See Appendix B for the complete trait definition. + +--- + +## 5. Functions + +Functions are user-defined procedures that encapsulate reusable code. They are the primary abstraction mechanism in the language. + +### 5.1 What are Functions + +Functions differ from operators: +- **Operators** implement trait methods and are the fundamental building blocks +- **Functions** are user-defined procedures that use operators +- Operators and functions cannot share names + +> **Related**: See Section 1 "Operators vs Functions" for a complete explanation of the distinction. + +### 5.2 Defining Functions + +**Syntax**: `(inputs -- outputs) { body } ::name fn` + +The function signature specifies stack effects (what is consumed and produced), the body contains the implementation, and the name identifies the function. + +**Examples**: +``` +// Simple function - requires Multiplyable trait +(Multiplyable -- Multiplyable) { dup * } ::square fn + +// Use it +5 square // => 25 + +// Multiple inputs and outputs +(Number Number -- Number Number) { + over over / swap % +} ::divmod fn + +10 3 divmod // => 3 1 (quotient remainder) +``` + +**Function Bodies**: The `{ }` braces contain a TokenString that is parsed as the function body when the function is defined. See Section 5.5 for details on TokenStrings. + +> **Related**: See Section 10.2 for generic functions with type parameters. + +### 5.3 Calling Functions + +Functions are called by simply writing their name. The postfix notation means arguments must be on the stack before the function name: + +``` +// Define a function +(Number Number -- Number) { + } ::add fn + +// Call it +3 4 add // => 7 + +// Chain functions +5 square 2 * // => 50 (square 5, then multiply by 2) +``` + +**Function Chaining**: Since everything is postfix, functions naturally chain left-to-right: +``` +10 square 2 / 5 + // ((10²) / 2) + 5 = 55 +``` + +### 5.4 Recursion + +Functions can call themselves recursively: + +``` +(Number -- Number) { + dup 1 <= + { drop 1 } + { dup 1 - factorial * } + if +} ::factorial fn + +5 factorial // => 120 +``` + +**Stack Considerations**: Recursive functions consume stack space. Deep recursion may cause stack overflow. Consider iterative alternatives for performance-critical code. + +### 5.5 Token Strings + +Token strings are lexed but unparsed code blocks enclosed in `{ }`. They are parsed differently depending on which operator uses them. + +**Operators that parse TokenStrings:** +- `fn` - Parses as function body (code block) +- `trait` - Parses as trait definition (method signatures) +- `impl` - Parses as trait implementation (method definitions) +- `eval` - Parses and executes as code block immediately +- `lambda` - Parses as code block, pushes the block as a callable value +- `if` - Parses both TokenStrings as code blocks (then/else branches) +- `while` - Parses both TokenStrings as code blocks (condition/body) +- `for` - Parses TokenString as code block (loop body) +- `match` - Parses TokenString as pattern matching arms +- `map`, `filter`, `reduce`, `each` - Parse TokenStrings as code blocks for array operations + +**Examples**: +``` +// Function body (parsed by fn) +(Number -- Number) { dup * } ::square fn + +// Conditional branches (parsed by if) +x 0 > { "positive" print } { "negative" print } if + +// Loop body (parsed by while) +{ dup 10 < } { dup print 1 + } while +``` + +### 5.6 Lambda Functions + +The `lambda` operator converts a TokenString into a callable code block that can be stored and passed around: + +``` +{ dup * } lambda // Creates a callable code block +::square_fn swap // Store reference to the lambda + +// Later use: +5 square_fn eval // Calls the lambda: pushes 25 +``` + +**Use Cases**: +- Creating first-class functions +- Passing code blocks as values +- Dynamic dispatch +- Higher-order operations + +**Example with arrays**: +``` +// Store a lambda and use it with map +{ 2 * } lambda ::double swap +[1 2 3 4] double map // => [2 4 6 8] +``` + +> **Related**: See Section 11.1 for the `eval` operator used to execute lambdas. + +--- + +## 6. Control Flow + +### 6.1 Conditionals + +**Syntax**: `condition { then-block } { else-block } if` + +The condition is evaluated first, then both code blocks are provided, followed by the `if` operator which chooses which block to execute. + +**Examples**: +``` +// if-then (else block is empty) +x 0 > { "positive" print } { } if + +// if-then-else +x 0 > + { "positive" print } + { "non-positive" print } +if + +// Returning values +a b > + { a } + { b } +if // Pushes the maximum of a and b + +// Nested conditionals +x 0 > + { + y 0 > + { "both positive" print } + { "x positive, y not" print } + if + } + { "x not positive" print } +if +``` + +**Important**: The `if` operator parses both TokenStrings as code blocks. The condition must produce a boolean value (or truthy value) before the `if` operator. + +### 6.2 While Loops + +**Syntax**: `{ condition-block } { body-block } while` + +The while loop repeatedly evaluates the condition block and executes the body block as long as the condition is truthy. + +**Examples**: +``` +// 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 +``` + +**Condition Evaluation**: The condition block is re-evaluated before each iteration. It should leave a boolean (or truthy) value on the stack. + +### 6.3 For Loops + +**Syntax**: `start end { body-with-counter } for` + +The for loop iterates from `start` to `end` (inclusive), pushing the loop counter onto the stack for each iteration before executing the body. + +**Examples**: +``` +// Print 1 to 10 +1 10 { + // Stack has loop counter on top + dup print +} for + +// FizzBuzz +1 100 { + dup fizzbuzz +} for + +// Accumulation +0 // accumulator +1 10 { + + // add counter to accumulator +} for +// Result: 55 (sum of 1 to 10) +``` + +**Loop Counter**: The loop counter is automatically pushed onto the stack before each iteration. Your body block should consume it or clean it up. + +### 6.4 Loop Control + +``` +break // Exit the current loop immediately +continue // Skip to the next iteration of the current loop +``` + +**Examples**: +``` +// Break example +1 100 { + dup 50 == + { break } + { dup print } + if +} for // Prints 1-49, stops at 50 + +// Continue example +1 10 { + dup 2 % 0 == + { continue } + { dup print } + if +} for // Prints only odd numbers: 1 3 5 7 9 +``` + +### 6.5 Pattern Matching + +**Syntax**: `value { pattern => block ... } match` + +Pattern matching allows you to test a value against multiple patterns and execute the corresponding block. + +**Examples**: +``` +// Option matching +opt_value { + Some(x) => { x print } + None => { "Nothing" print } +} match + +// Multiple patterns +status { + Pending => { "Waiting" print } + Active => { "Running" print } + Complete => { "Done" print } +} match + +// Result matching +result { + Ok(val) => { val process } + Err(e) => { e "Error: " swap concat print } +} match +``` + +**Pattern Syntax**: Patterns can match enum variants, union variants, or literal values. The matched value (if any) is bound and available in the corresponding block. + +--- + +## 7. Data Structures + +### 7.1 Structs + +Structs define composite types with named fields. + +**Definition Syntax**: `(field_types -- ) { field_names: } ::name? struct` + +**Examples**: + +``` +// 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 i64 fields + +// More complex struct +(T U V --) { + width: + height: + depth: +} ::Box3D struct + +10.0 20.0 30.0 Box3D +``` + +**Field Access**: +- **get**: `struct ::field get` - Consumes struct and field identifier, returns field value +- **set**: `value ::field set` - Consumes value and field identifier, returns modified struct + +**Examples**: +``` +point ::x get // Get x field (consumes point and ::x) +15.0 ::x set // Set x field to 15.0 (consumes value and ::x) + +// Chaining with duplication +point dup ::x get 2 * over ::y get + // (point.x * 2) + point.y +``` + +> **Note**: Structs can be generic. See Section 10.3 for details on generic data structures. + +### 7.2 Unions + +Unions define tagged variants, where a value is one of several possible types. + +**Definition Syntax**: `(variant_types -- ) { variants } ::name? union` + +**Examples**: +``` +// 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 Option::Some // Creates Option::Some(42) +Option::None // Creates Option::None +"success" Result::Ok // Creates Result::Ok("success") +"error" Result::Err // Creates Result::Err("error") +``` + +**Pattern Matching**: Unions are typically used with pattern matching (Section 6.5) to handle different variants. + +> **Note**: Unions can be generic. See Section 10.3 for details on generic data structures. + +### 7.3 Enums + +Enums define a fixed set of named values with optional integer assignments. + +**Definition Syntax**: `{ variants } ::name enum` + +**Examples**: +``` +{ + Pending 1: // Explicitly set to 1 + Active: // Defaults to 2 (one plus the last) + Complete 0: // Explicitly set to 0 +} ::Status enum + +// Usage +Status::Pending // Creates Status::Pending (value 1) +Status::Active // Creates Status::Active (value 2) +Status::Complete // Creates Status::Complete (value 0) +``` + +**Automatic Values**: If not specified, enum values start at 0 and increment by 1 for each subsequent variant. + +### 7.4 Arrays + +Arrays are homogeneous collections of values. + +**Array Literals**: +``` +[1 2 3 4 5] // array of i64 +[1.0 2.0 3.0] // array of f64 +[[1 2] [3 4]] // 2D array +``` + +**Basic Operations**: +``` +arr 2 at // ( array index -- element ) Access element at index +arr 1 3 slice // ( array start end -- subarray ) Extract slice +arr length // ( array -- length ) Get array length +``` + +**Array Combinators**: + +These operations take TokenString arguments containing function bodies: + +``` +// Map - transform 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 accumulator +[1 2 3 4] 0 { + } reduce // => 10 + +// Each - apply to each element (side effects) +[[1 2] [3 4]] { sum print } each +``` + +**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] +``` + +**Array Manipulation**: +``` +[1 2 3] [4 5 6] concat // Concatenate: [1 2 3 4 5 6] +[1 2 3] reverse // Reverse: [3 2 1] +[[1 2] [3 4]] transpose // Transpose: [[1 3] [2 4]] +[1 2 3 4] 2 window // Sliding window: [[1 2] [2 3] [3 4]] +``` + +> **Implementation Details**: Array operations implement various traits including `::ArrayOf`, `::Selectable`, `::Sliceable`, and `::Sized`. See Appendix B for complete trait definitions and Appendix A for the full array operation reference. + +--- + +## 8. Type System + +### 8.1 Types vs Traits + +The language distinguishes between types (what things are) and traits (how things behave): + +**Types** define the concrete structure and memory layout: +- `Point` - A struct type with two fields +- `Rectangle` - A struct type with width and height +- `i32` - A primitive integer type +- `Option` - A union type that may contain a value + +**Traits** define behavioral contracts: +- `::Addable` - Types that support addition and subtraction +- `::Drawable` - Types that can be drawn +- `::Stackable` - Types that support stack operations + +**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 traits +- Functions can specify types or traits in signatures +- Every operator must be backed by a trait + +**Examples**: +``` +// Point is a type +(T T --) { x: y: } ::Point struct + +// Addable is a trait +{ + (Self Self -- Self) +: + (Self Self -- Self) -: +} ::Addable trait + +// Point implements Addable (Point now behaves additively) +::Addable { + (Self Self -- Self) { + over ::x get over ::x get + + swap ::y get swap ::y get + + Point + } +: + // ... subtract implementation ... +} ::Point impl +``` + +> **Related**: See Section 9 for the complete trait system and Appendix B for all standard trait definitions. + +### 8.2 Type Inference + +The compiler infers types in most situations, minimizing the need for explicit type annotations. + +**When Type Inference Works**: +``` +42 // Inferred as i64 (default integer) +3.14 // Inferred as f64 (default float) +[1 2 3] // Inferred as array of i64 + +// Function return type inferred from body +(Number -- Number) { dup * } ::square fn +5 square // Compiler knows result is Number +``` + +**When Annotations Are Needed**: +``` +42:i32 // Explicit annotation for 32-bit integer +3.14:f32 // Explicit annotation for 32-bit float + +// Ambiguous generic contexts may need hints +parse // May need type context to know what to parse to +``` + +**Type Inference with Generics**: +``` +// Type parameter T is inferred from usage +(T -- T) { } ::identity fn + +5 identity // T inferred as i64 +"hello" identity // T inferred as String +``` + +> **Related**: See Section 10 for generic programming and type parameter inference. + +### 8.3 Type Tuples Type tuples represent stack effects and are used in function signatures to specify what a function consumes from and produces to the stack. +**Syntax**: `(inputs -- outputs)` + +**Examples**: ``` -(T T -- T) // Function signature: two inputs of type T, one output of type T +(T T -- T) // Two inputs of type T, one output of type T (i32 f64 -- String) // Takes i32 and f64, returns String (-- bool) // No inputs, returns bool (Point --) // Takes Point, no outputs (---) // No inputs, no outputs (side effects only) ``` -**Variable Arguments**: For operations that need variable numbers of arguments, use the `Iterable` trait: +**Variable Arguments with Iterable**: + +For operations that need variable numbers of arguments, use the `Iterable` trait: ``` (-- Size) depth: // Zero arguments, returns stack depth @@ -188,351 +924,83 @@ Type tuples represent stack effects and are used in function signatures to speci (Iterable -- T) sum: // Iterable of values, returns sum ``` -This approach: -- Keeps the type system simple (no special variadic syntax) -- Works with arrays, ranges, and other iterable types -- Trait-based, consistent with language design - -**Usage Examples**: +**Examples**: ``` -"x=%d, y=%d, z=%d" [x y z] printf // Format string with array of values -[1 2 3 4 5] sum // Sum array of numbers -1 100 range sum // Sum range (also iterable) -depth print // No arguments needed +"x=%d, y=%d" [x y] printf // Format string with array of values +[1 2 3 4 5] sum // Sum array of numbers +depth print // No arguments needed ``` -**Token Strings** +This approach keeps the type system simple without special variadic syntax. +### 8.4 Type Composition + +Types can contain other types, creating composite data structures: + +**Nested Structures**: ``` -{ code here } // TokenString - lexed but not parsed/executed -``` - -Token strings contain lexed tokens that are not parsed or executed until an operator causes them to be parsed. Different operators parse TokenStrings in different ways: - -**Operators that parse TokenStrings:** -- `trait` - Parses as trait definition (method signatures) -- `impl` - Parses as trait implementation (method definitions) -- `fn` - Parses as function body (code block) -- `eval` - Parses and executes as code block immediately -- `lambda` - Parses as code block, pushes the block as a callable value -- `if` - Parses both TokenStrings as code blocks (then/else branches) -- `while` - Parses both TokenStrings as code blocks (condition/body) -- `for` - Parses TokenString as code block (loop body) -- `match` - Parses TokenString as pattern matching arms -- `map` - Parses TokenString as code block (transformation function) -- `filter` - Parses TokenString as code block (predicate function) -- `reduce` - Parses TokenString as code block (accumulator function) -- `each` - Parses TokenString as code block (iteration function) - -**Lambda Operator** - -The `lambda` operator converts a TokenString into a callable code block that can be stored and passed around: - -``` -{ dup * } lambda // Creates a callable code block -::square_fn swap // Store reference to the lambda -// Later use: -5 square_fn eval // Calls the lambda: pushes 25 -``` - -Lambdas are useful for: -- Creating first-class functions -- Passing code blocks as values -- Dynamic dispatch -- Higher-order array operations - -## 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) - **Future feature, see Appendix** - -### 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: -- `{ ... } ::Addable trait` - Addable is a trait -- `{ ... } ::Drawable trait` - Drawable 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 traits -- Functions can have types and traits defined as return types -- Every operator must be backed by a trait - -### 3.3 Generic Constructs - -Functions, structs, and unions can be generic over type parameters using the `<>` syntax. Type parameters must be constrained by traits when operations are performed on them. - -**Note on Type Parameters**: Type parameters are currently only suggestions when parsing code blocks. The compiler does not yet enforce that type parameters actually constrain how operators and functions act at parse time. This is documented as a possible future enhancement in the Appendix. - -``` -// Function generic over any type with Multiplyable constraint -(T -- T) { dup * } ::square fn - -// Struct generic over field type T +// Point contains two T values (T T --) { x: y: } ::Point struct -// Union generic over variant type T +// Line contains two Points +(Point Point --) { start: end: } ::Line struct +``` + +**Arrays of Types**: +``` +[1 2 3] // Array of i64 +[[1 2] [3 4]] // Array of arrays +[Point Point Point] // Array of Points +``` + +**Generic Composition**: +``` +// Box contains a value of any type +(T --) { value: } ::Box struct + +// Option can contain any type (or nothing) (T --) { Some(T) None } ::Option union + +// Nested generics +Option> // Option containing a Point of f64s ``` -**Generic Trait Syntax** +--- -Traits can be generic using the `<>` syntax: +## 9. Trait System -``` -// Generic trait over type T -{ (Self T -- Self) append: } ::Container trait +### 9.1 What are Traits -// Generic trait with multiple type parameters -{ (Self K -- V) get: (Self K V -- Self) insert: } ::Map trait -``` +Traits define behavioral contracts - they specify what operations a type must support without dictating how those operations are implemented. -**Generic Trait Inheritance** +**Why Traits Exist**: +- Define common behavior across different types +- Enable generic programming with constraints +- Back every operator in the language +- Allow user-defined operators through trait implementation -When inheriting from a generic trait, you must either: -1. Make the inheriting trait similarly generic with the same parameters -2. Specify concrete types for the generic parameters +**Standard Traits Overview**: -``` -// Inheriting trait is also generic -[ ::Container ] ::Stack inher -{ (Self -- T) pop: } ::Stack trait +The language provides many built-in traits: +- `::Stackable` - Stack manipulation operations +- `::Addable`, `::Multiplyable` - Arithmetic operations +- `::Comparable`, `::Equatable` - Comparison operations +- `::Logical`, `::Bitwise` - Boolean and bit operations +- `::Sized`, `::Selectable`, `::Sliceable` - Container operations +- `::Number` - Composite numeric operations +- And many more... -// Inheriting trait specifies concrete type -[ ::Container ] ::IntStack inher -{ (Self -- i32) pop: } ::IntStack trait -``` +> **Complete Reference**: See Appendix B for all standard trait definitions with complete documentation. -**Important**: Unconstrained generic functions (those that don't perform operations on their type parameters) can omit trait constraints. +### 9.2 Defining Traits -``` -// Generic identity - works with any type (no operations performed) -(T -- T) { } ::identity fn -``` +**Syntax**: `{ method_signatures } ::identifier? trait` -## 4. Trait System - -### 4.1 Standard Traits - -Traits define behavioral contracts. Every operator in the language is backed by one or more traits. See Appendix A for complete trait definitions. - -**Stack Manipulation Trait** - -The `Stackable` trait provides fundamental stack manipulation operations: - -``` -{ - (Self -- Self Self) dup: // Duplicate the top item - (Self -- ) drop: // Remove the top item - (Self Self -- Self Self) swap: // Swap the top two items - (Self Self -- Self Self Self) over: // Copy second item to top - (Self Self Self -- Self Self Self) rot: // Rotate top three items - (Size -- Self) pick: // Copy nth item to top (0 = top, the item before the size is 1) - (Size Size -- ) roll: // Rotate n items, times times - (-- Size) depth: // Push current stack depth -} ::Stackable trait -``` - -**Size Trait** - -The `Size` trait represents types suitable for indexing and sizing operations: - -``` -[ ::Addable ::Comparable ::Convertible ] ::Size inher -{ } ::Size trait -``` - -Types implementing `Size` can be used as indices, loop bounds, and array sizes. Standard implementations include all integer types (`i8`, `i16`, `i32`, `i64`, `u8`, `u16`, `u32`, `u64`). - -**Arithmetic Traits** - -``` -// Addition and subtraction operations -{ - (Self Self -- Self) +: // Add two values - (Self Self -- Self) -: // Subtract two values -} ::Addable trait - -// Multiplication, division, and modulo operations -{ - (Self Self -- Self) *: // Multiply two values - (Self Self -- Self) /: // Divide two values - (Self Self -- Self) %: // Modulo operation -} ::Multiplyable trait - -// Exponentiation operations -{ - (Self Self -- Self) ^: // Raise to power -} ::Exponentiable trait - -// Logarithmic operations -{ - (Self Self -- Self) logb: // Logarithm with custom base - (Self -- Self) log: // Logarithm base 10 - (Self -- Self) ln: // Natural logarithm -} ::Logarithmic trait -``` - -**Comparison Traits** - -``` -// Ordering operations -{ - (Self Self -- bool) >: // Greater than - (Self Self -- bool) >=: // Greater than or equal - (Self Self -- bool) <: // Less than - (Self Self -- bool) <=: // Less than or equal -} ::Orderable trait - -// Equality operations -{ - (Self Self -- bool) ==: // Equal to - (Self Self -- bool) !=: // Not equal to -} ::Equatable trait - -// Comparable combines ordering and equality -[ ::Orderable ::Equatable ] ::Comparable inher -{ } ::Comparable trait -``` - -**Logical Operations Traits** - -``` -// Logical operations -{ - (Self -- bool) truthy: // Convert to boolean (truthiness) - (Self Self -- Self) and: // Logical AND - (Self Self -- Self) or: // Logical OR - (Self -- Self) not: // Logical NOT -} ::Logical trait -``` - -**Bitwise Operations Traits** - -``` -// Bitwise operations -{ - (Self Self -- Self) bitand: // Bitwise AND - (Self Self -- Self) bitor: // Bitwise OR - (Self Self -- Self) bitxor: // Bitwise XOR - (Self -- Self) bitnot: // Bitwise NOT - (Self Size -- Self) shl: // Left shift - (Self Size -- Self) shr: // Right shift -} ::Bitwise trait -``` - -**Container Traits** - -``` -// Size information -{ - (Self -- i64) length: // Get length/size of container -} ::Sized trait - -// Element selection -{ - (Self Size -- T) at: // Access element at index -} ::Selectable trait - -// Concatenation -{ - (Self Self -- Self) concat: // Concatenate two containers -} ::Concatenable trait - -// Slicing -{ - (Self Size Size -- Self) slice: // Extract slice from start to end -} ::Sliceable trait - -// ArrayOf combines container operations -[ ::Sized ::Selectable ::Sliceable ] ::ArrayOf inher -{ } ::ArrayOf trait -``` - -**String Traits** - -``` -// String operations -[ ::Concatenable ] ::String inher -{ - (Self Size Size -- Self) substr: // Extract substring - (Self Self -- ArrayOf) split: // Split by delimiter -} ::String trait -``` - -**Conversion Traits** - -``` -// Type conversion (uses explicit conversion functions) -{ - (Self -- i8) to_i8: - (Self -- i16) to_i16: - (Self -- i32) to_i32: - (Self -- i64) to_i64: - (Self -- u8) to_u8: - (Self -- u16) to_u16: - (Self -- u32) to_u32: - (Self -- u64) to_u64: - (Self -- f32) to_f32: - (Self -- f64) to_f64: -} ::Convertible trait - -// String conversion -{ - (Self -- String) to_str: // Convert to string representation -} ::Stringifiable trait - -// Parse from string -{ - (String -- Self) parse: // Parse from string -} ::Parseable trait -``` - -**Numeric Composite Trait** - -The `Number` trait represents the full suite of numeric operations by inheriting from multiple traits: - -``` -[ ::Addable ::Multiplyable ::Exponentiable ::Comparable ::Logarithmic ] ::Number inher -{ } ::Number trait -``` - -**Meta-Traits** - -Traits for defining and working with traits themselves: - -``` -// Marks identifiers -{ } ::Identifier trait - -// Operations for trait manipulation -{ - (TokenString Identifier --) trait: // Define a trait - (Identifier TokenString Identifier --) impl: // Implement a trait - (ArrayOf Identifier --) inher: // Declare trait inheritance -} ::Implementable trait -``` - -### 4.2 Trait Definition - -**Syntax**: `{ function_signatures } ::identifier? trait` - -Traits can be defined with or without method signatures. Empty traits are valid and are typically used when inheriting from other traits to create composite traits (marker traits). +Traits can have methods or be empty (marker traits). Empty traits are typically used with inheritance. **Examples**: ``` -// Trait with methods (no inheritance) +// Trait with methods { (Self -- ) draw: } ::Drawable trait @@ -550,31 +1018,20 @@ Traits can be defined with or without method signatures. Empty traits are valid (Self -- T) pop: } ::Container trait -// Empty trait (marker trait, no inheritance) +// Empty marker trait { } ::Serializable trait - -// Trait with inheritance (no additional methods) -[ ::Orderable ::Equatable ] ::Comparable inher -{ } ::Comparable trait - -// Trait with inheritance and additional methods -[ ::Drawable ::Transformable ] ::GameObject inher -{ - (Self -- ) update: - (Self -- ) destroy: -} ::GameObject trait ``` -Within the TokenString (the `{ }` block), identifiers like `Self`, `add:`, `draw:` are part of the trait definition syntax and should not use the `::` prefix. +**Method Signatures**: Within the TokenString, identifiers are method names and should not use the `::` prefix. -### 4.3 Trait Implementation +### 9.3 Implementing Traits -**Syntax**: `::trait_identifier { method_implementations } ::type_or_trait_identifier impl` +**Syntax**: `::trait_identifier { method_implementations } ::type_identifier impl` **Implementation Rules**: -1. Implementing a trait for itself (`::Trait { ... } ::Trait impl`) implements the trait for all types as a default implementation -2. A trait must be defined before it can be implemented for types or traits -3. It is not required for all operators of a trait to be in the same implementation block - implementations can be split across multiple blocks +1. Implementing a trait for itself (`::Trait { ... } ::Trait impl`) creates a default implementation for all types +2. A trait must be defined before it can be implemented +3. Method implementations can be split across multiple `impl` blocks 4. Later implementations can override earlier ones for the same type **Examples**: @@ -601,79 +1058,13 @@ Within the TokenString (the `{ }` block), identifiers like `Self`, `add:`, `draw } ::Rectangle impl ``` -``` -// Implement Addable for Point -::Addable { - (Self Self -- Self) { - over ::x get over ::x get + - 3 pick ::y get 3 pick ::y get + - Point - } +: +> **More Examples**: See Appendix G for complete implementation examples and tutorials. - (Self Addable -- Self) { - over ::x get over + - 3 pick ::y get 3 pick + - Point - } +: - - (Addable Self -- Self) { - over over ::x get + - 3 pick 3 pick ::y get + - Point - } +: - - (Self Self -- Self) { - over ::x get over ::x get - - 3 pick ::y get 3 pick ::y get - - Point - } -: - - (Self Addable -- Self) { - over ::x get over - - 3 pick ::y get 3 pick - - Point - } -: -} ::Point impl - -// Implement Logical for everything (default implementation) -::Logical { - (Self -- bool) { true } truthy: - - (Self Self -- Self) { - over truthy { } { swap } if drop - } and: - - (Self Self -- Self) { - over truthy { swap } { } if drop - } or: -} ::Logical impl - -// Overload Logical for bool -::Logical { - (Self -- Self) { } truthy: -} ::bool impl - -// Overload Logical for Numeric -::Logical { - (Self -- bool) { 0 != } truthy: -} ::Number impl - -// Overload Logical for Option -::Logical { - (Self -- bool) { { Some(_) => { true } None => { false } } match } truthy: -} ::Option impl - -// Overload Logical for Result -::Logical { - (Self -- bool) { { Ok(_) => { true } Err(_) => { false } } match } truthy: -} ::Result impl -``` - -### 4.4 Trait Inheritance +### 9.4 Trait Inheritance **Syntax**: `[ identifier_list ] ::identifier? inher { methods } ::identifier? trait` -Trait inheritance is specified by providing an array of trait identifiers, followed by the trait identifier and the `inher` operator, then the trait body and trait definition. +Trait inheritance allows a trait to include all methods from parent traits, optionally adding new methods. **Examples**: ``` @@ -691,23 +1082,14 @@ Trait inheritance is specified by providing an array of trait identifiers, follo (Self -- ) update: (Self -- ) destroy: } ::GameObject trait - -// Size trait with composite behavior -[ ::Addable ::Comparable ::Convertible ] ::Size inher -{ } ::Size trait - -// String trait inheriting and adding methods -[ ::Concatenable ] ::String inher -{ - (Self Size Size -- Self) substr: - (Self Self -- ArrayOf) split: -} ::String trait ``` -**Generic Trait Inheritance**: When inheriting from generic traits, you must either make the inheriting trait similarly generic or specify concrete types: +**Generic Trait Inheritance**: + +When inheriting from generic traits, you must either make the inheriting trait similarly generic or specify concrete types: ``` -// Inheriting trait is also generic (generic parameter matches) +// Inheriting trait is also generic [ ::Container ] ::Stack inher { (Self -- T) pop: @@ -718,406 +1100,270 @@ Trait inheritance is specified by providing an array of trait identifiers, follo { (Self -- i32) pop: } ::IntStack trait - -// Multiple generic inheritance -[ ::Selectable ::Sized ::Sliceable ] ::ArrayOf inher -{ } ::ArrayOf trait ``` -### 4.5 Using Traits in Functions +### 9.5 Using Traits in Functions + +Traits can be used as type constraints in function signatures: **Examples**: ``` // Function requiring Drawable trait (Drawable -- ) { draw -} ::draw_twice fn +} ::draw_object fn -// Function requiring multiple trait bounds +// Function requiring Number trait (Number Number -- Number) { dup * swap dup * + // Pythagorean: a² + b² } ::sum_of_squares fn + +// Generic function with trait constraint +(Multiplyable -- Multiplyable) { + dup * +} ::square fn ``` -## 5. Stack Operations - -### 5.1 Stack Manipulation - -All stack operations are backed by the `Stackable` trait. - +**Multiple Constraints**: Use specific traits or composite traits that inherit from multiple parents: ``` -dup // ( a -- a a ) Duplicate top item -drop // ( a -- ) Remove top item -swap // ( a b -- b a ) Swap top two items -over // ( a b -- a b a ) Copy second item to top -rot // ( a b c -- b c a) Rotate top three items +// Requires both Addable and Comparable +(Number -- Number) { ... } ::some_function fn + +// Number trait inherits from both, so this works ``` -### 5.2 Stack Inspection +### 9.6 Standard Traits Overview -``` -depth // ( -- n ) Push current stack depth -pick // ( n -- x ) Copy nth item to top (0 = top) -roll // ( n times -- ) Rotate n items, times times -``` +This section provides a brief overview of all standard traits. For complete definitions with all methods and documentation, see Appendix B. -**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 -4 3 roll // Rotate top 4 items three times: a d e c b -``` +**Stack Operations**: +- `::Stackable` - Fundamental stack manipulation (dup, drop, swap, over, rot, pick, roll, depth) -## 6. Built-in Operators +**Arithmetic**: +- `::Addable` - Addition and subtraction (+, -) +- `::Multiplyable` - Multiplication, division, modulo (*, /, %) +- `::Exponentiable` - Exponentiation (^) +- `::Logarithmic` - Logarithm operations (log, ln, logb) +- `::Number` - Composite trait combining all arithmetic and comparison -Every operator is backed by a trait and must be implemented for types that use it. +**Comparison**: +- `::Orderable` - Ordering comparisons (>, >=, <, <=) +- `::Equatable` - Equality comparisons (==, !=) +- `::Comparable` - Composite trait combining Orderable and Equatable -### 6.1 Arithmetic +**Logical and Bitwise**: +- `::Logical` - Boolean operations (and, or, not, truthy) +- `::Bitwise` - Bit manipulation (bitand, bitor, bitxor, bitnot, shl, shr) -``` -3 4 + // ( a b -- result ) Addition - add two numbers -10 3 - // ( a b -- result ) Subtraction - subtract b from a -5 6 * // ( a b -- result ) Multiplication - multiply two numbers -20 4 / // ( a b -- result ) Division - divide a by b -17 5 % // ( a b -- result ) Modulo - remainder of a divided by b -2 8 ^ // ( a b -- result ) Exponentiation - raise a to power b -100 log // ( a -- result ) Logarithm base 10 of a -2.718 ln // ( a -- result ) Natural logarithm of a -``` +**Containers**: +- `::Sized` - Length information (length) +- `::Selectable` - Element access (at) +- `::Sliceable` - Slicing operations (slice) +- `::Concatenable` - Concatenation (concat) +- `::ArrayOf` - Composite array trait +- `::Iterable` - Iteration support (next) -### 6.2 Comparison +**Conversion**: +- `::Convertible` - Type conversions (to_i8, to_i16, ..., to_f32, to_f64) +- `::Stringifiable` - String conversion (to_str) +- `::Parseable` - Parse from string (parse) -``` -5 3 > // ( a b -- bool ) Greater than - true if a > b -5 3 >= // ( a b -- bool ) Greater or equal - true if a >= b -5 3 < // ( a b -- bool ) Less than - true if a < b -5 3 <= // ( a b -- bool ) Less or equal - true if a <= b -5 5 == // ( a b -- bool ) Equal - true if a == b -5 3 != // ( a b -- bool ) Not equal - true if a != b -``` +**String Operations**: +- `::String` - String-specific operations (substr, split) - inherits from Concatenable -### 6.3 Logical +**Utilities**: +- `::Size` - Types suitable for indexing (inherits Addable, Comparable, Convertible) +- `::Identifier` - Marks identifiers +- `::Implementable` - Meta-trait for defining language constructs (trait, impl, inher) -``` -true false and // ( a b -- result ) Logical AND - true if both are truthy -true false or // ( a b -- result ) Logical OR - true if either is truthy -true not // ( a -- result ) Logical NOT - inverts truthiness -``` +> **Complete Reference**: See Appendix B for full trait definitions with all methods, examples, and implementation details. -### 6.4 Bitwise +--- -``` -0xFF 0x0F bitand // ( a b -- result ) Bitwise AND - AND each bit -0xFF 0x0F bitor // ( a b -- result ) Bitwise OR - OR each bit -0xFF 0x0F bitxor // ( a b -- result ) Bitwise XOR - XOR each bit -0xFF bitnot // ( a -- result ) Bitwise NOT - invert all bits -8 2 shl // ( a n -- result ) Left shift - shift a left by n bits -8 2 shr // ( a n -- result ) Right shift - shift a right by n bits -``` +## 10. Generic Programming -## 7. Functions +### 10.1 Type Parameters -Functions are defined in postfix notation. The signature and body come before the name. +Type parameters allow functions, structs, and traits to work with multiple types. -### 7.1 Basic Function Definition - -**Syntax**: `(inputs -- outputs) { body } ::name fn` +**Generic Syntax**: `` where T is a type parameter **Examples**: ``` -// Define a square function (requires Multiplyable trait) -(Multiplyable -- Multiplyable) { dup * } ::square fn +// Generic struct +(T T --) { x: y: } ::Point struct -// Use it -5 square // 25 +// Generic union +(T --) { Some(T) None } ::Option union -// Multiple inputs and outputs -(Number Number -- Number Number) { - over over / swap % -} ::divmod fn - -10 3 divmod // 3 1 (quotient remainder) +// Generic trait +{ + (Self T -- Self) append: +} ::Container trait ``` -### 7.2 Generic Functions with Trait Constraints +**Type Parameter Constraints**: -**Syntax**: `(type_sig) { body } ::name fn` +When operations are performed on type parameters, they must be constrained by traits: + +``` +// Unconstrained - no operations on T +(T -- T) { } ::identity fn + +// Constrained - T must support multiplication +(T:Multiplyable -- T) { dup * } ::square fn +``` + +**Multiple Type Parameters**: +``` +(T E --) { Ok(T) Err(E) } ::Result union +``` + +### 10.2 Generic Functions + +Generic functions work with multiple types by using trait constraints in their type tuples. + +**Syntax**: `(trait_constraints -- outputs) { body } ::name fn` **Examples**: ``` // Generic identity - works with any type (no operations, no constraint needed) (T -- T) { } ::identity fn -// Requires Addable - use trait name in type tuple +// Requires Addable trait (Addable Addable -- Addable) { + } ::add_values fn -// Requires Number +// Requires Number trait (Number -- Number) { dup 0 > { } { 0 swap - } if } ::abs fn + +// Multiple constraints +(Number Number -- Number) { + dup * swap dup * + // a² + b² +} ::pythagorean fn ``` -## 8. Control Flow - -### 8.1 Conditionals - -**Syntax**: `condition { then-block } { else-block } if` - -The `if` operator parses both TokenStrings as code blocks (then/else branches). - -**Examples**: +**Type Inference**: The compiler infers the actual type from usage: ``` -// 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 - -// Nested -x 0 > - { - y 0 > - { "both positive" print } - { "x positive, y not" print } - if - } - { "x not positive" print } -if +5 identity // T inferred as i64 +"hello" identity // T inferred as String +3 4 add_values // Addable inferred as i64 ``` -### 8.2 Loops +### 10.3 Generic Data Structures -**While Loop** +Structs and unions can be generic over type parameters: -**Syntax**: `{ condition-block } { body-block } while` - -The `while` operator parses both TokenStrings as code blocks (condition/body). - -**Examples**: +**Generic Structs**: ``` -// 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 `for` operator parses the TokenString as a code block (loop body). - -**Examples**: -``` -// 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 -``` - -### 8.3 Loop Control -``` -break // Exit the current loop immediately -continue // Skip to the next iteration of the current loop -``` - -### 8.4 Match/Pattern Matching - -**Syntax**: `value { pattern => block ... } match` - -The `match` operator parses the TokenString as pattern matching arms. - -**Examples**: -``` -value { - Some(x) => { x print } - None => { "Nothing" print } -} match - -// With multiple patterns -status { - Pending => { "Waiting" print } - Active => { "Running" print } - Complete => { "Done" print } -} match -``` - -## 9. Data Structures - -### 9.1 Struct Definition - -**Syntax**: `(field_types -- ) { field_names } ::name struct` - -**Examples**: - -``` -// Define Point struct - generic over coordinate types +// Point is generic over coordinate type (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 i64 fields +// Use with different types +3.0 4.0 Point // Point +3 4 Point // Point -// More complex struct -(T U V --) { - width: - height: - depth: -} ::Box3D struct - -10.0 20.0 30.0 Box3D +// Multiple type parameters +(T U --) { first: second: } ::Pair struct +5 "hello" Pair // Pair ``` -### 9.2 Struct Field Access +**Generic Unions**: +``` +// Option is generic over contained type +(T --) { Some(T) None } ::Option union -**Syntax**: -- **get**: `struct ::field get` consumes struct and field identifier, returns field value -- **set**: `value ::field set` consumes value and field identifier, returns modified struct +42 Option::Some // Option::Some +"text" Option::Some // Option::Some +Option::None // Option::None (T inferred from context) + +// Result with two type parameters +(T E --) { Ok(T) Err(E) } ::Result union +``` + +**Nested Generics**: +``` +// Array of Options +[Option::Some Option::None] // Array of Option + +// Option of array +[1 2 3] Option::Some // Option> +``` + +### 10.4 Generic Traits + +Traits can be generic, allowing them to describe behavior parameterized over types. + +**Generic Trait Syntax**: +``` +// Container generic over element type +{ + (Self T -- Self) append: + (Self -- T) pop: +} ::Container trait + +// Map generic over key and value types +{ + (Self K -- V) get: + (Self K V -- Self) insert: +} ::Map trait +``` + +**Generic Trait Inheritance**: + +When inheriting from generic traits, you must either: +1. Make the inheriting trait similarly generic +2. Specify concrete types for the generic parameters + +``` +// Inheriting trait is also generic +[ ::Container ] ::Stack inher +{ + (Self -- T) peek: +} ::Stack trait + +// Inheriting trait specifies concrete type +[ ::Container ] ::IntStack inher +{ + (Self -- i32) peek: +} ::IntStack trait + +// Multiple generic inheritance +[ ::Selectable ::Sized ::Sliceable ] ::ArrayOf inher +{ } ::ArrayOf trait +``` + +### 10.5 Type Parameter Enforcement + +**Current Behavior**: Type parameters are currently suggestions when parsing code blocks. The compiler does not yet enforce that type parameters actually constrain how operators and functions act at parse time. + +**Example**: +``` +// Currently no error even without Multiplyable constraint +(T -- T) { dup * } ::square fn + +// Should require constraint +(Multiplyable -- Multiplyable) { dup * } ::square fn +``` + +> **Future Enhancement**: See Appendix F for planned type parameter enforcement at parse time. + +--- + +## 11. Advanced Topics + +### 11.1 Dynamic Code Evaluation + +The `eval` operator executes code dynamically at runtime by parsing and executing a TokenString. + +**Syntax**: `{ code } eval` **Examples**: ``` -point ::x get // Get x field (consumes point and ::x) -15.0 ::x set // Set x field to 15.0 (consumes value and ::x) - -// Chaining with duplication -point dup ::x get 2 * over ::y get + // (point.x * 2) + point.y -``` - -### 9.3 Union Definition - -**Syntax**: `(variant_types -- ) { variants } ::name union` - -**Examples**: -``` -// 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 Option::Some // Creates Option::Some(42) -Option::None // Creates Option::None -"success" Result::Ok // Creates Result::Ok("success") -"error" Result::Err // Creates Result::Err("error") -``` - -### 9.4 Enum Definition - -**Syntax**: `{ variants } ::name enum` - -**Examples**: -``` -{ - Pending 1: // Normally starts at 0 - Active: // Defaults to 2 (one plus the last) - Complete 0: -} ::Status enum - -// Usage -Status::Pending // Creates Status::Pending -Status::Active // Creates Status::Active -``` - -## 10. Array Operations - -### 10.1 Basic Array Operations - -**Examples**: -``` -// Creation -1 10 range // Create range array [1..10] - -// Shape operations -arr shape // Get shape of array -arr 2 3 reshape // Reshape to 2x3 - -// Element access -arr 2 at // Access element at index 2 -arr 1 3 slice // Slice from index 1 to 3 -``` - -### 10.2 Array Combinators - -Array combinators take TokenString arguments containing the function bodies to apply. The `if`, `while`, and other control structures inside these function bodies parse their own TokenString arguments. - -**Examples**: -``` -// 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 -``` - -### 10.3 Array Arithmetic - -**Examples**: -``` -[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] -``` - -### 10.4 Array Manipulation - -**Examples**: -``` -[1 2 3] [4 5 6] concat // Concatenate: [1 2 3 4 5 6] -[1 2 3] reverse // Reverse: [3 2 1] -[[1 2] [3 4]] transpose // Transpose: [[1 3] [2 4]] -[1 2 3 4] 2 window // Sliding window: [[1 2] [2 3] [3 4]] -``` - -## 11. Eval Operator - -Execute code dynamically at runtime. The `eval` operator parses and executes its TokenString argument immediately. - -**Examples**: -``` -// Evaluate string as code +// Evaluate simple expression "2 3 +" eval // Pushes 5 // Build and execute code @@ -1128,13 +1374,58 @@ Execute code dynamically at runtime. The `eval` operator parses and executes its operation_name " get" concat eval ``` -## 12. Standard Library +**Use Cases**: +- Building code at runtime +- Dynamic dispatch based on runtime values +- Implementing interpreters or REPLs +- Meta-programming -All standard library functions and traits are automatically in scope (no imports needed in current version). See Appendix C for future module system design. +**Warnings**: +- Eval introduces runtime overhead (parsing) +- Type safety is reduced (types checked at eval time, not compile time) +- Security risk if evaluating untrusted code +- Use sparingly and prefer static alternatives when possible -### 12.1 I/O +### 11.2 Identifier Literals -**Examples**: +Identifier literals use the `::` prefix to push an identifier as a value rather than executing it. + +**Syntax**: `::name` + +**Context-Dependent Rules**: + +**In function bodies and eval**: `::` is required for identifier literals +``` +::Point // Pushes identifier "Point" +::Addable // Pushes identifier "Addable" +``` + +**In trait definitions**: `::` is not allowed (identifiers are method names) +``` +{ + (Self -- ) draw: // "draw:" is a method name, not a literal +} ::Drawable trait +``` + +**In trait implementations**: `::` is not allowed (identifiers are method names) +``` +::Drawable { + (Self -- ) { ... } draw: // "draw:" is a method name +} ::Rectangle impl +``` + +**Use Cases**: +- Defining structs: `(T T --) { x: y: } ::Point struct` +- Defining traits: `{ ... } ::Drawable trait` +- Field access: `point ::x get` +- Dynamic trait operations +- Meta-programming + +### 11.3 Standard Library + +The standard library provides I/O, string operations, type conversions, and utility functions. All standard library functions are automatically in scope (no imports needed in current version). + +**I/O Operations**: ``` "Hello" print // Print string to stdout "Enter name: " input // Read line from stdin @@ -1142,246 +1433,562 @@ All standard library functions and traits are automatically in scope (no imports "data" "file.txt" write // Write string to file ``` -### 12.2 String Operations - -**Examples**: +**String Operations**: ``` -"hello" " world" concat // Concatenate: "hello world" -"hello" length // Get length: 5 -"hello" 1 3 substr // Substring: "el" -"a,b,c" "," split // Split: ["a" "b" "c"] -["a" "b"] "," join // Join: "a,b" +"hello" " world" concat // Concatenate strings +"hello" length // Get string length +"hello" 1 3 substr // Extract substring +"a,b,c" "," split // Split by delimiter +["a" "b"] "," join // Join with delimiter ``` -### 12.3 Type Conversion - -Type conversion uses explicit conversion functions: - -**Examples**: +**Type Conversion**: ``` -42 to_f64 // Convert i32 to f64: 42.0 -3.14 to_i32 // Convert f64 to i32: 3 (truncates) +42 to_f64 // Convert i32 to f64 +3.14 to_i32 // Convert f64 to i32 (truncates) "123" parse // Parse string to inferred type -42 to_str // Convert to string: "42" +42 to_str // Convert to string ``` +**Array Operations**: +- Element access: `at`, `slice` +- Information: `length`, `shape` +- Combinators: `map`, `filter`, `reduce`, `each` +- Manipulation: `concat`, `reverse`, `transpose`, `window` + +> **Complete Reference**: See Appendix A for the full standard library reference with all functions, signatures, and examples. + --- -## Appendix A: Complete Trait Definitions +## Appendix A: Standard Library -This appendix contains all built-in trait definitions with complete documentation. +This appendix provides a complete alphabetical reference of all standard library functions and operations. -### A.1 Stackable Trait +### Standard Library Categories -Provides fundamental stack manipulation operations. +**Array Operations**: at, concat, each, filter, length, map, reduce, reverse, shape, slice, transpose, window +**I/O Operations**: input, print, read, write + +**String Operations**: concat, join, length, split, substr + +**Type Conversion**: parse, to_i8, to_i16, to_i32, to_i64, to_u8, to_u16, to_u32, to_u64, to_f32, to_f64, to_str + +**Utility Operations**: eval, lambda + +### Alphabetical Reference + +#### at +**Signature**: `(Selectable Size -- T)` +**Trait**: Selectable +**Description**: Access element at the given index. +**Example**: +``` +[10 20 30] 1 at // Returns 20 +``` +**See Also**: slice, length + +#### concat +**Signature**: `(Concatenable Concatenable -- Concatenable)` +**Trait**: Concatenable +**Description**: Concatenate two containers or strings. +**Example**: +``` +[1 2 3] [4 5 6] concat // Returns [1 2 3 4 5 6] +"hello" " world" concat // Returns "hello world" +``` +**See Also**: join, split + +#### depth +**Signature**: `(-- Size)` +**Trait**: Stackable +**Description**: Push current stack depth onto the stack. +**Example**: +``` +1 2 3 depth // Returns 1 2 3 3 +``` +**See Also**: pick, roll + +#### drop +**Signature**: `(Self --)` +**Trait**: Stackable +**Description**: Remove and discard the top item from the stack. +**Example**: +``` +5 10 drop // Returns 5 +``` +**See Also**: dup, swap + +#### dup +**Signature**: `(Self -- Self Self)` +**Trait**: Stackable +**Description**: Duplicate the top item on the stack. +**Example**: +``` +5 dup // Returns 5 5 +``` +**See Also**: drop, over + +#### each +**Signature**: `(ArrayOf TokenString --)` +**Description**: Apply function to each element (side effects). +**Example**: +``` +[1 2 3] { print } each // Prints 1, 2, 3 +``` +**See Also**: map, filter + +#### eval +**Signature**: `(TokenString --)` +**Trait**: Implementable +**Description**: Parse and execute TokenString as code. +**Example**: +``` +"2 3 +" eval // Returns 5 +``` +**See Also**: lambda + +#### filter +**Signature**: `(ArrayOf TokenString -- ArrayOf)` +**Description**: Keep only elements matching predicate. +**Example**: +``` +[1 2 3 4 5] { 2 % 0 == } filter // Returns [2 4] +``` +**See Also**: map, reduce + +#### input +**Signature**: `(String -- String)` +**Description**: Print prompt and read line from stdin. +**Example**: +``` +"Enter name: " input // Prompts and returns user input +``` +**See Also**: print, read + +#### join +**Signature**: `(ArrayOf String -- String)` +**Description**: Join array of strings with delimiter. +**Example**: +``` +["a" "b" "c"] "," join // Returns "a,b,c" +``` +**See Also**: split, concat + +#### lambda +**Signature**: `(TokenString -- Callable)` +**Trait**: Implementable +**Description**: Convert TokenString to callable code block. +**Example**: +``` +{ dup * } lambda ::square swap +5 square eval // Returns 25 +``` +**See Also**: eval + +#### length +**Signature**: `(Sized -- i64)` +**Trait**: Sized +**Description**: Get the number of elements in a container. +**Example**: +``` +[1 2 3 4 5] length // Returns 5 +"hello" length // Returns 5 +``` +**See Also**: at, slice + +#### map +**Signature**: `(ArrayOf TokenString -- ArrayOf)` +**Description**: Transform each element with function. +**Example**: +``` +[1 2 3 4] { 2 * } map // Returns [2 4 6 8] +``` +**See Also**: filter, reduce, each + +#### over +**Signature**: `(Self Self -- Self Self Self)` +**Trait**: Stackable +**Description**: Copy the second item to the top of the stack. +**Example**: +``` +5 10 over // Returns 5 10 5 +``` +**See Also**: dup, swap, rot + +#### parse +**Signature**: `(String -- Parseable)` +**Trait**: Parseable +**Description**: Parse string to value of inferred type. +**Example**: +``` +"123" parse // Returns 123 (as appropriate numeric type) +``` +**See Also**: to_str + +#### pick +**Signature**: `(Size -- Self)` +**Trait**: Stackable +**Description**: Copy nth item to top (0 = top, 1 = second, etc.). +**Example**: +``` +1 2 3 4 2 pick // Returns 1 2 3 4 2 +``` +**See Also**: roll, depth + +#### print +**Signature**: `(Stringifiable --)` +**Description**: Print value to stdout. +**Example**: +``` +"Hello" print // Prints: Hello +42 print // Prints: 42 +``` +**See Also**: input, to_str + +#### read +**Signature**: `(String -- String)` +**Description**: Read file contents as string. +**Example**: +``` +"file.txt" read // Returns file contents +``` +**See Also**: write + +#### reduce +**Signature**: `(ArrayOf T TokenString -- T)` +**Description**: Fold array with accumulator function. +**Example**: +``` +[1 2 3 4] 0 { + } reduce // Returns 10 +``` +**See Also**: map, filter + +#### reverse +**Signature**: `(ArrayOf -- ArrayOf)` +**Description**: Reverse order of array elements. +**Example**: +``` +[1 2 3] reverse // Returns [3 2 1] +``` +**See Also**: transpose + +#### roll +**Signature**: `(Size Size --)` +**Trait**: Stackable +**Description**: Rotate n items, times times. +**Example**: +``` +1 2 3 4 3 1 roll // Rotates top 3 once: 1 3 4 2 +``` +**See Also**: rot, pick + +#### rot +**Signature**: `(Self Self Self -- Self Self Self)` +**Trait**: Stackable +**Description**: Rotate the top three items. +**Example**: +``` +1 2 3 rot // Returns 2 3 1 +``` +**See Also**: swap, roll + +#### slice +**Signature**: `(Sliceable Size Size -- Sliceable)` +**Trait**: Sliceable +**Description**: Extract elements from start to end index. +**Example**: +``` +[10 20 30 40] 1 3 slice // Returns [20 30] +``` +**See Also**: at, length + +#### split +**Signature**: `(String String -- ArrayOf)` +**Trait**: String +**Description**: Split string by delimiter. +**Example**: +``` +"a,b,c" "," split // Returns ["a" "b" "c"] +``` +**See Also**: join, substr + +#### substr +**Signature**: `(String Size Size -- String)` +**Trait**: String +**Description**: Extract substring from start to end index. +**Example**: +``` +"hello" 1 3 substr // Returns "el" +``` +**See Also**: slice, split + +#### swap +**Signature**: `(Self Self -- Self Self)` +**Trait**: Stackable +**Description**: Swap the top two items on the stack. +**Example**: +``` +5 10 swap // Returns 10 5 +``` +**See Also**: dup, rot + +#### to_f32, to_f64 +**Signature**: `(Convertible -- f32/f64)` +**Trait**: Convertible +**Description**: Convert value to 32-bit or 64-bit float. +**Example**: +``` +42 to_f64 // Returns 42.0 +``` +**See Also**: to_i32, to_str + +#### to_i8, to_i16, to_i32, to_i64 +**Signature**: `(Convertible -- i8/i16/i32/i64)` +**Trait**: Convertible +**Description**: Convert value to signed integer type. +**Example**: +``` +3.14 to_i32 // Returns 3 (truncates) +``` +**See Also**: to_u32, to_f64 + +#### to_str +**Signature**: `(Stringifiable -- String)` +**Trait**: Stringifiable +**Description**: Convert value to string representation. +**Example**: +``` +42 to_str // Returns "42" +``` +**See Also**: parse, print + +#### to_u8, to_u16, to_u32, to_u64 +**Signature**: `(Convertible -- u8/u16/u32/u64)` +**Trait**: Convertible +**Description**: Convert value to unsigned integer type. +**Example**: +``` +42 to_u32 // Returns 42 (as u32) +``` +**See Also**: to_i32, to_f64 + +#### transpose +**Signature**: `(ArrayOf> -- ArrayOf>)` +**Description**: Transpose a 2D array (swap rows and columns). +**Example**: +``` +[[1 2] [3 4]] transpose // Returns [[1 3] [2 4]] +``` +**See Also**: reverse + +#### window +**Signature**: `(ArrayOf Size -- ArrayOf>)` +**Description**: Create sliding windows of given size. +**Example**: +``` +[1 2 3 4] 2 window // Returns [[1 2] [2 3] [3 4]] +``` +**See Also**: slice + +#### write +**Signature**: `(String String --)` +**Description**: Write string to file. +**Example**: +``` +"data" "file.txt" write // Writes "data" to file.txt +``` +**See Also**: read + +--- + +## Appendix B: Complete Trait Reference + +This appendix contains all built-in trait definitions with complete documentation, organized alphabetically. + +### Trait List + +- Addable +- ArrayOf +- Bitwise +- Comparable +- Concatenable +- Convertible +- Equatable +- Exponentiable +- Identifier +- Implementable +- Iterable +- Logarithmic +- Logical +- Multiplyable +- Number +- Orderable +- Parseable +- Selectable +- Size +- Sized +- Sliceable +- Stackable +- String +- Stringifiable + +### Addable + +**Generic Parameters**: None +**Inherits**: None + +**Definition**: ``` { - // Duplicate the top item on the stack - // Example: 5 dup => 5 5 - (Self -- Self Self) dup: - - // Remove and discard the top item - // Example: 5 10 drop => 5 - (Self -- ) drop: - - // Swap the top two items - // Example: 5 10 swap => 10 5 - (Self Self -- Self Self) swap: - - // Copy the second item to the top - // Example: 5 10 over => 5 10 5 - (Self Self -- Self Self Self) over: - - // Rotate the top three items - // Example: 1 2 3 rot => 2 3 1 - (Self Self Self -- Self Self Self) rot: - - // Copy the nth item to top (0 = top) - // Example: 1 2 3 4 2 pick => 1 2 3 4 2 - (Size -- Self) pick: - - // Rotate n items, times times - // Example: 1 2 3 4 3 1 roll => 1 3 4 2 - (Size Size -- ) roll: - - // Push the current stack depth - // Example: 1 2 3 depth => 1 2 3 3 - (-- Size) depth: -} ::Stackable trait -``` - -### A.2 Arithmetic Traits - -``` -// Addition and subtraction -{ - // Add two values - // Example: 3 4 + => 7 (Self Self -- Self) +: - - // Subtract second from first - // Example: 10 3 - => 7 (Self Self -- Self) -: } ::Addable trait - -// Multiplication, division, and modulo -{ - // Multiply two values - // Example: 5 6 * => 30 - (Self Self -- Self) *: - - // Divide first by second - // Example: 20 4 / => 5 - (Self Self -- Self) /: - - // Remainder after division - // Example: 17 5 % => 2 - (Self Self -- Self) %: -} ::Multiplyable trait - -// Exponentiation -{ - // Raise first to power of second - // Example: 2 8 ^ => 256 - (Self Self -- Self) ^: -} ::Exponentiable trait - -// Logarithmic operations -{ - // Logarithm with custom base - // Example: 8 2 logb => 3.0 - (Self Self -- Self) logb: - - // Logarithm base 10 - // Example: 100 log => 2.0 - (Self -- Self) log: - - // Natural logarithm (base e) - // Example: 2.718 ln => 1.0 - (Self -- Self) ln: -} ::Logarithmic trait ``` -### A.3 Comparison Traits +**Methods**: +#### +: +**Signature**: `(Self Self -- Self)` +**Description**: Add two values together. +**Example**: `3 4 + // => 7` + +#### -: +**Signature**: `(Self Self -- Self)` +**Description**: Subtract second value from first. +**Example**: `10 3 - // => 7` + +**Standard Implementations**: All numeric types (i8, i16, i32, i64, u8, u16, u32, u64, f32, f64) + +**Related Traits**: Multiplyable, Number + +**See Also**: Section 4.2 (Arithmetic Operators) + +### ArrayOf + +**Generic Parameters**: T (element type) +**Inherits**: Sized, Selectable, Sliceable + +**Definition**: ``` -// Ordering operations -{ - // True if first > second - (Self Self -- bool) >: - - // True if first >= second - (Self Self -- bool) >=: - - // True if first < second - (Self Self -- bool) <: - - // True if first <= second - (Self Self -- bool) <=: -} ::Orderable trait - -// Equality operations -{ - // True if values are equal - (Self Self -- bool) ==: - - // True if values are not equal - (Self Self -- bool) !=: -} ::Equatable trait - -// Combined comparison (inherits both) -[ ::Orderable ::Equatable ] ::Comparable inher -{ } ::Comparable trait -``` - -### A.4 Logical Operations - -``` -{ - // Convert to boolean (truthiness check) - // Default: all values are truthy - // Numbers: 0 is falsy, others truthy - // Option: Some is truthy, None is falsy - (Self -- bool) truthy: - - // Logical AND - returns first if falsy, else second - (Self Self -- Self) and: - - // Logical OR - returns first if truthy, else second - (Self Self -- Self) or: - - // Logical NOT - inverts truthiness - (Self -- Self) not: -} ::Logical trait -``` - -### A.5 Bitwise Operations - -``` -{ - // Bitwise AND of two values - (Self Self -- Self) bitand: - - // Bitwise OR of two values - (Self Self -- Self) bitor: - - // Bitwise XOR of two values - (Self Self -- Self) bitxor: - - // Bitwise NOT (complement) - (Self -- Self) bitnot: - - // Shift left by n bits - (Self Size -- Self) shl: - - // Shift right by n bits - (Self Size -- Self) shr: -} ::Bitwise trait -``` - -### A.6 Container Traits - -``` -// Size information -{ - // Get the number of elements - (Self -- i64) length: -} ::Sized trait - -// Iterable -{ - // Get next item - (Self -- Self Option) next: -} ::Iterable trait - -// Element access -{ - // Get element at index - (Self Size -- T) at: -} ::Selectable trait - -// Concatenation -{ - // Join two containers - (Self Self -- Self) concat: -} ::Concatenable trait - -// Slicing -{ - // Extract elements from start to end index - (Self Size Size -- Self) slice: -} ::Sliceable trait - -// Complete array operations (inherits all above) [ ::Sized ::Selectable ::Sliceable ] ::ArrayOf inher { } ::ArrayOf trait ``` -### A.7 Conversion Traits +**Description**: Composite trait for arrays, inheriting all container operations. +**Standard Implementations**: Array types + +**Related Traits**: Sized, Selectable, Sliceable, Iterable + +**See Also**: Section 7.4 (Arrays) + +### Bitwise + +**Generic Parameters**: None +**Inherits**: None + +**Definition**: +``` +{ + (Self Self -- Self) bitand: + (Self Self -- Self) bitor: + (Self Self -- Self) bitxor: + (Self -- Self) bitnot: + (Self Size -- Self) shl: + (Self Size -- Self) shr: +} ::Bitwise trait +``` + +**Methods**: + +#### bitand: +**Signature**: `(Self Self -- Self)` +**Description**: Bitwise AND of two values. +**Example**: `0xFF 0x0F bitand // => 0x0F` + +#### bitor: +**Signature**: `(Self Self -- Self)` +**Description**: Bitwise OR of two values. +**Example**: `0xF0 0x0F bitor // => 0xFF` + +#### bitxor: +**Signature**: `(Self Self -- Self)` +**Description**: Bitwise XOR of two values. +**Example**: `0xFF 0x0F bitxor // => 0xF0` + +#### bitnot: +**Signature**: `(Self -- Self)` +**Description**: Bitwise NOT (complement) of value. +**Example**: `0xFF bitnot // => (inverted bits)` + +#### shl: +**Signature**: `(Self Size -- Self)` +**Description**: Shift bits left by n positions. +**Example**: `4 2 shl // => 16` + +#### shr: +**Signature**: `(Self Size -- Self)` +**Description**: Shift bits right by n positions. +**Example**: `16 2 shr // => 4` + +**Standard Implementations**: Integer types (i8, i16, i32, i64, u8, u16, u32, u64) + +**Related Traits**: None + +**See Also**: Section 4.5 (Bitwise Operators) + +### Comparable + +**Generic Parameters**: None +**Inherits**: Orderable, Equatable + +**Definition**: +``` +[ ::Orderable ::Equatable ] ::Comparable inher +{ } ::Comparable trait +``` + +**Description**: Composite trait combining ordering and equality comparisons. + +**Standard Implementations**: All numeric types, strings, characters + +**Related Traits**: Orderable, Equatable, Size, Number + +**See Also**: Section 4.3 (Comparison Operators) + +### Concatenable + +**Generic Parameters**: None +**Inherits**: None + +**Definition**: +``` +{ + (Self Self -- Self) concat: +} ::Concatenable trait +``` + +**Methods**: + +#### concat: +**Signature**: `(Self Self -- Self)` +**Description**: Join two containers or strings together. +**Example**: `"hello" " world" concat // => "hello world"` + +**Standard Implementations**: Arrays, strings + +**Related Traits**: String, ArrayOf + +**See Also**: Section 7.4 (Arrays), Appendix A (concat) + +### Convertible + +**Generic Parameters**: None +**Inherits**: None + +**Definition**: ``` -// Type conversions { (Self -- i8) to_i8: (Self -- i16) to_i16: @@ -1394,132 +2001,1228 @@ Provides fundamental stack manipulation operations. (Self -- f32) to_f32: (Self -- f64) to_f64: } ::Convertible trait +``` -// String conversion -{ - // Convert value to string representation - (Self -- String) to_str: -} ::Stringifiable trait +**Methods**: Provides explicit type conversion methods to all numeric types. -// Parse from string +**Standard Implementations**: All numeric types + +**Related Traits**: Stringifiable, Parseable, Size + +**See Also**: Section 11.3 (Type Conversion) + +### Equatable + +**Generic Parameters**: None +**Inherits**: None + +**Definition**: +``` +{ + (Self Self -- bool) ==: + (Self Self -- bool) !=: +} ::Equatable trait +``` + +**Methods**: + +#### ==: +**Signature**: `(Self Self -- bool)` +**Description**: Test if two values are equal. +**Example**: `5 5 == // => true` + +#### !=: +**Signature**: `(Self Self -- bool)` +**Description**: Test if two values are not equal. +**Example**: `5 3 != // => true` + +**Standard Implementations**: All types + +**Related Traits**: Orderable, Comparable + +**See Also**: Section 4.3 (Comparison Operators) + +### Exponentiable + +**Generic Parameters**: None +**Inherits**: None + +**Definition**: +``` +{ + (Self Self -- Self) ^: +} ::Exponentiable trait +``` + +**Methods**: + +#### ^: +**Signature**: `(Self Self -- Self)` +**Description**: Raise first value to the power of the second. +**Example**: `2 8 ^ // => 256` + +**Standard Implementations**: Numeric types + +**Related Traits**: Addable, Multiplyable, Number + +**See Also**: Section 4.2 (Arithmetic Operators) + +### Identifier + +**Generic Parameters**: None +**Inherits**: None + +**Definition**: +``` +{ } ::Identifier trait +``` + +**Description**: Marker trait for identifier types. + +**Standard Implementations**: Identifier literals + +**Related Traits**: Implementable + +**See Also**: Section 11.2 (Identifier Literals) + +### Implementable + +**Generic Parameters**: None +**Inherits**: None + +**Definition**: +``` +{ + (TokenString Identifier --) trait: + (Identifier TokenString Identifier --) impl: + (ArrayOf Identifier --) inher: +} ::Implementable trait +``` + +**Methods**: + +#### trait: +**Signature**: `(TokenString Identifier --)` +**Description**: Define a new trait. +**Example**: `{ (Self -- ) draw: } ::Drawable trait` + +#### impl: +**Signature**: `(Identifier TokenString Identifier --)` +**Description**: Implement a trait for a type. +**Example**: `::Drawable { ... } ::Rectangle impl` + +#### inher: +**Signature**: `(ArrayOf Identifier --)` +**Description**: Declare trait inheritance. +**Example**: `[ ::Orderable ::Equatable ] ::Comparable inher` + +**Standard Implementations**: Language-level operators + +**Related Traits**: Identifier + +**See Also**: Section 9 (Trait System) + +### Iterable + +**Generic Parameters**: T (element type) +**Inherits**: None + +**Definition**: +``` +{ + (Self -- Self Option) next: +} ::Iterable trait +``` + +**Methods**: + +#### next: +**Signature**: `(Self -- Self Option)` +**Description**: Get next item from iterator. +**Example**: Iterator protocol for collections + +**Standard Implementations**: Arrays, ranges, iterators + +**Related Traits**: ArrayOf, Selectable + +**See Also**: Section 8.3 (Type Tuples - Variable Arguments) + +### Logarithmic + +**Generic Parameters**: None +**Inherits**: None + +**Definition**: +``` +{ + (Self Self -- Self) logb: + (Self -- Self) log: + (Self -- Self) ln: +} ::Logarithmic trait +``` + +**Methods**: + +#### logb: +**Signature**: `(Self Self -- Self)` +**Description**: Logarithm with custom base. +**Example**: `8 2 logb // => 3.0` + +#### log: +**Signature**: `(Self -- Self)` +**Description**: Logarithm base 10. +**Example**: `100 log // => 2.0` + +#### ln: +**Signature**: `(Self -- Self)` +**Description**: Natural logarithm (base e). +**Example**: `2.718 ln // => 1.0` + +**Standard Implementations**: Floating point types + +**Related Traits**: Exponentiable, Number + +**See Also**: Section 4.2 (Arithmetic Operators) + +### Logical + +**Generic Parameters**: None +**Inherits**: None + +**Definition**: +``` +{ + (Self -- bool) truthy: + (Self Self -- Self) and: + (Self Self -- Self) or: + (Self -- Self) not: +} ::Logical trait +``` + +**Methods**: + +#### truthy: +**Signature**: `(Self -- bool)` +**Description**: Convert to boolean (truthiness check). +**Example**: `5 truthy // => true`, `0 truthy // => false` + +#### and: +**Signature**: `(Self Self -- Self)` +**Description**: Logical AND - returns first if falsy, else second. +**Example**: `true false and // => false` + +#### or: +**Signature**: `(Self Self -- Self)` +**Description**: Logical OR - returns first if truthy, else second. +**Example**: `true false or // => true` + +#### not: +**Signature**: `(Self -- Self)` +**Description**: Logical NOT - inverts truthiness. +**Example**: `false not // => true` + +**Standard Implementations**: bool, numbers, Option, Result + +**Related Traits**: None + +**See Also**: Section 4.4 (Logical Operators) + +### Multiplyable + +**Generic Parameters**: None +**Inherits**: None + +**Definition**: +``` +{ + (Self Self -- Self) *: + (Self Self -- Self) /: + (Self Self -- Self) %: +} ::Multiplyable trait +``` + +**Methods**: + +#### *: +**Signature**: `(Self Self -- Self)` +**Description**: Multiply two values. +**Example**: `5 6 * // => 30` + +#### /: +**Signature**: `(Self Self -- Self)` +**Description**: Divide first value by second. +**Example**: `20 4 / // => 5` + +#### %: +**Signature**: `(Self Self -- Self)` +**Description**: Remainder after division (modulo). +**Example**: `17 5 % // => 2` + +**Standard Implementations**: All numeric types + +**Related Traits**: Addable, Exponentiable, Number + +**See Also**: Section 4.2 (Arithmetic Operators) + +### Number + +**Generic Parameters**: None +**Inherits**: Addable, Multiplyable, Exponentiable, Comparable, Logarithmic + +**Definition**: +``` +[ ::Addable ::Multiplyable ::Exponentiable ::Comparable ::Logarithmic ] ::Number inher +{ } ::Number trait +``` + +**Description**: Composite trait representing the full suite of numeric operations. + +**Standard Implementations**: All numeric types (i8, i16, i32, i64, u8, u16, u32, u64, f32, f64) + +**Related Traits**: Addable, Multiplyable, Exponentiable, Comparable, Logarithmic + +**See Also**: Section 4.2 (Arithmetic Operators) + +### Orderable + +**Generic Parameters**: None +**Inherits**: None + +**Definition**: +``` +{ + (Self Self -- bool) >: + (Self Self -- bool) >=: + (Self Self -- bool) <: + (Self Self -- bool) <=: +} ::Orderable trait +``` + +**Methods**: + +#### >: +**Signature**: `(Self Self -- bool)` +**Description**: True if first value is greater than second. +**Example**: `5 3 > // => true` + +#### >=: +**Signature**: `(Self Self -- bool)` +**Description**: True if first value is greater than or equal to second. +**Example**: `5 5 >= // => true` + +#### <: +**Signature**: `(Self Self -- bool)` +**Description**: True if first value is less than second. +**Example**: `3 5 < // => true` + +#### <=: +**Signature**: `(Self Self -- bool)` +**Description**: True if first value is less than or equal to second. +**Example**: `5 5 <= // => true` + +**Standard Implementations**: All numeric types, strings, characters + +**Related Traits**: Equatable, Comparable + +**See Also**: Section 4.3 (Comparison Operators) + +### Parseable + +**Generic Parameters**: None +**Inherits**: None + +**Definition**: +``` { - // Parse string to value (may fail) (String -- Self) parse: } ::Parseable trait ``` -### A.8 Composite Traits +**Methods**: +#### parse: +**Signature**: `(String -- Self)` +**Description**: Parse string to value of this type. +**Example**: `"123" parse // => 123` + +**Standard Implementations**: All numeric types, bool + +**Related Traits**: Stringifiable, Convertible + +**See Also**: Appendix A (parse) + +### Selectable + +**Generic Parameters**: T (element type) +**Inherits**: None + +**Definition**: +``` +{ + (Self Size -- T) at: +} ::Selectable trait +``` + +**Methods**: + +#### at: +**Signature**: `(Self Size -- T)` +**Description**: Access element at given index. +**Example**: `[10 20 30] 1 at // => 20` + +**Standard Implementations**: Arrays, strings + +**Related Traits**: ArrayOf, Sized, Sliceable + +**See Also**: Section 7.4 (Arrays) + +### Size + +**Generic Parameters**: None +**Inherits**: Addable, Comparable, Convertible + +**Definition**: ``` -// Size for indexing [ ::Addable ::Comparable ::Convertible ] ::Size inher { } ::Size trait +``` -// Full numeric operations -[ ::Addable ::Multiplyable ::Exponentiable ::Comparable ::Logarithmic ] ::Number inher -{ } ::Number trait +**Description**: Represents types suitable for indexing and sizing operations. -// String operations +**Standard Implementations**: All integer types (i8, i16, i32, i64, u8, u16, u32, u64) + +**Related Traits**: Addable, Comparable, Convertible + +**See Also**: Section 4.1 (Stack Operations - pick, roll) + +### Sized + +**Generic Parameters**: None +**Inherits**: None + +**Definition**: +``` +{ + (Self -- i64) length: +} ::Sized trait +``` + +**Methods**: + +#### length: +**Signature**: `(Self -- i64)` +**Description**: Get the number of elements in a container. +**Example**: `[1 2 3 4 5] length // => 5` + +**Standard Implementations**: Arrays, strings + +**Related Traits**: ArrayOf, Selectable, Sliceable + +**See Also**: Section 7.4 (Arrays) + +### Sliceable + +**Generic Parameters**: None +**Inherits**: None + +**Definition**: +``` +{ + (Self Size Size -- Self) slice: +} ::Sliceable trait +``` + +**Methods**: + +#### slice: +**Signature**: `(Self Size Size -- Self)` +**Description**: Extract elements from start to end index. +**Example**: `[10 20 30 40] 1 3 slice // => [20 30]` + +**Standard Implementations**: Arrays, strings + +**Related Traits**: ArrayOf, Sized, Selectable + +**See Also**: Section 7.4 (Arrays) + +### Stackable + +**Generic Parameters**: None +**Inherits**: None + +**Definition**: +``` +{ + (Self -- Self Self) dup: + (Self -- ) drop: + (Self Self -- Self Self) swap: + (Self Self -- Self Self Self) over: + (Self Self Self -- Self Self Self) rot: + (Size -- Self) pick: + (Size Size -- ) roll: + (-- Size) depth: +} ::Stackable trait +``` + +**Methods**: + +#### dup: +**Signature**: `(Self -- Self Self)` +**Description**: Duplicate the top item on the stack. +**Example**: `5 dup // => 5 5` + +#### drop: +**Signature**: `(Self -- )` +**Description**: Remove and discard the top item. +**Example**: `5 10 drop // => 5` + +#### swap: +**Signature**: `(Self Self -- Self Self)` +**Description**: Swap the top two items. +**Example**: `5 10 swap // => 10 5` + +#### over: +**Signature**: `(Self Self -- Self Self Self)` +**Description**: Copy the second item to the top. +**Example**: `5 10 over // => 5 10 5` + +#### rot: +**Signature**: `(Self Self Self -- Self Self Self)` +**Description**: Rotate the top three items. +**Example**: `1 2 3 rot // => 2 3 1` + +#### pick: +**Signature**: `(Size -- Self)` +**Description**: Copy nth item to top (0 = top). +**Example**: `1 2 3 4 2 pick // => 1 2 3 4 2` + +#### roll: +**Signature**: `(Size Size -- )` +**Description**: Rotate n items, times times. +**Example**: `1 2 3 4 3 1 roll // => 1 3 4 2` + +#### depth: +**Signature**: `(-- Size)` +**Description**: Push current stack depth. +**Example**: `1 2 3 depth // => 1 2 3 3` + +**Standard Implementations**: All primitive types + +**Related Traits**: None + +**See Also**: Section 4.1 (Stack Operations) + +### String + +**Generic Parameters**: None +**Inherits**: Concatenable + +**Definition**: +``` [ ::Concatenable ] ::String inher { - // Extract substring from start to end (Self Size Size -- Self) substr: - - // Split by delimiter (Self Self -- ArrayOf) split: } ::String trait ``` ---- +**Methods**: -## Appendix B: Future Features +#### substr: +**Signature**: `(Self Size Size -- Self)` +**Description**: Extract substring from start to end index. +**Example**: `"hello" 1 3 substr // => "el"` -### B.1 Memory Management +#### split: +**Signature**: `(Self Self -- ArrayOf)` +**Description**: Split string by delimiter. +**Example**: `"a,b,c" "," split // => ["a" "b" "c"]` -The language specification currently does not include heap memory management. This appendix documents potential future approaches. +**Standard Implementations**: String type -**Current State**: All values are stack-allocated or embedded in data structures. +**Related Traits**: Concatenable, Sized, Sliceable -**Potential Approaches**: +**See Also**: Section 11.3 (String Operations) -**Option A: Manual Management** +### Stringifiable + +**Generic Parameters**: None +**Inherits**: None + +**Definition**: ``` -// Allocate on heap -3.0 4.0 Point alloc // ( Point -- ptr ) - -// Dereference -ptr deref // ( ptr -- T ) - -// Store through pointer -new_value ptr store // ( T ptr -- ) - -// Free memory -ptr free // ( ptr -- ) +{ + (Self -- String) to_str: +} ::Stringifiable trait ``` -Pros: Full control, predictable, zero overhead -Cons: Error-prone, requires discipline, potential memory leaks +**Methods**: -**Option B: Reference Counting** -``` -// Create reference-counted value -3.0 4.0 Point rc // ( Point -- rc ) +#### to_str: +**Signature**: `(Self -- String)` +**Description**: Convert value to string representation. +**Example**: `42 to_str // => "42"` -// Automatic reference counting -value dup // Increments count -drop // Decrements count, frees if zero -``` +**Standard Implementations**: All types -Pros: Automatic cleanup, relatively simple -Cons: Runtime overhead, cannot handle cycles, larger memory footprint +**Related Traits**: Parseable, Convertible -**Option C: Ownership System (Rust-like)** -``` -// Linear types - each value has one owner -value // Move semantics by default -value dup // Error: cannot copy owned value -value ::clone call // Explicit clone required -``` - -Pros: Memory safe, zero overhead, prevents leaks -Cons: Complex type system, restricts stack operations, steep learning curve - -**Option D: Arena/Region-Based** -``` -// Create arena -::arena new // ( -- arena ) - -// Allocate in arena -arena 3.0 4.0 Point alloc_in // ( arena Point -- ptr ) - -// Free entire arena -arena free_arena // ( arena -- ) -``` - -Pros: Fast allocation, simple bulk deallocation -Cons: Less granular control, memory held until arena freed - -**Recommendation**: Start without heap allocation (current approach). When needed, implement Option A (manual) for simplicity, with Option D (arenas) added later for performance-critical code. The stack-based nature makes ownership tracking (Option C) particularly challenging. - -### B.2 Type Parameter Enforcement - -**Current State**: Type parameters in generic functions are currently suggestions and are not enforced at parse time. - -**Example**: -``` -(T -- T) { dup * } ::square fn // Currently no error even without Multiplyable constraint -``` - -**Future Enhancement**: The compiler could enforce that type parameters actually constrain how operators and functions act, validated at parse time: -``` -(Multiplyable -- Multiplyable) { dup * } ::square fn // Enforced constraint -``` - -This would provide stronger type safety but add complexity to the type checker. +**See Also**: Section 11.3 (Type Conversion) --- -## Appendix C: Module System (Future) +## Appendix C: Complete Operator Reference + +This appendix provides a complete alphabetical reference of all operators in the language. + +### Operator List + +`!=`, `%`, `&` (bitand), `*`, `+`, `-`, `/`, `<`, `<=`, `==`, `>`, `>=`, `^`, `|` (bitor), `and`, `at`, `bitand`, `bitnot`, `bitor`, `bitxor`, `break`, `concat`, `continue`, `depth`, `drop`, `dup`, `each`, `enum`, `eval`, `filter`, `fn`, `for`, `get`, `if`, `impl`, `inher`, `lambda`, `length`, `ln`, `log`, `logb`, `map`, `match`, `not`, `or`, `over`, `pick`, `reduce`, `reverse`, `roll`, `rot`, `set`, `shl`, `shr`, `slice`, `struct`, `substr`, `swap`, `trait`, `transpose`, `union`, `while`, `window` + +### Alphabetical Operator Reference + +#### != +**Operator Type**: Comparison +**Signature**: `(Equatable Equatable -- bool)` +**Trait**: Equatable +**Description**: Test if two values are not equal. +**Example**: `5 3 != // => true` +**See Also**: ==, <, > +**Section**: 4.3 (Comparison Operators) + +#### % +**Operator Type**: Arithmetic +**Signature**: `(Multiplyable Multiplyable -- Multiplyable)` +**Trait**: Multiplyable +**Description**: Remainder after division (modulo). +**Example**: `17 5 % // => 2` +**See Also**: /, * +**Section**: 4.2 (Arithmetic Operators) + +#### * +**Operator Type**: Arithmetic +**Signature**: `(Multiplyable Multiplyable -- Multiplyable)` +**Trait**: Multiplyable +**Description**: Multiply two values. +**Example**: `5 6 * // => 30` +**See Also**: /, +, - +**Section**: 4.2 (Arithmetic Operators) + +#### + +**Operator Type**: Arithmetic +**Signature**: `(Addable Addable -- Addable)` +**Trait**: Addable +**Description**: Add two values. +**Example**: `3 4 + // => 7` +**See Also**: -, *, / +**Section**: 4.2 (Arithmetic Operators) + +#### - +**Operator Type**: Arithmetic +**Signature**: `(Addable Addable -- Addable)` +**Trait**: Addable +**Description**: Subtract second value from first. +**Example**: `10 3 - // => 7` +**See Also**: +, *, / +**Section**: 4.2 (Arithmetic Operators) + +#### / +**Operator Type**: Arithmetic +**Signature**: `(Multiplyable Multiplyable -- Multiplyable)` +**Trait**: Multiplyable +**Description**: Divide first value by second. +**Example**: `20 4 / // => 5` +**See Also**: *, %, + +**Section**: 4.2 (Arithmetic Operators) + +#### < +**Operator Type**: Comparison +**Signature**: `(Orderable Orderable -- bool)` +**Trait**: Orderable +**Description**: True if first value is less than second. +**Example**: `3 5 < // => true` +**See Also**: <=, >, >= +**Section**: 4.3 (Comparison Operators) + +#### <= +**Operator Type**: Comparison +**Signature**: `(Orderable Orderable -- bool)` +**Trait**: Orderable +**Description**: True if first value is less than or equal to second. +**Example**: `5 5 <= // => true` +**See Also**: <, >, >= +**Section**: 4.3 (Comparison Operators) + +#### == +**Operator Type**: Comparison +**Signature**: `(Equatable Equatable -- bool)` +**Trait**: Equatable +**Description**: Test if two values are equal. +**Example**: `5 5 == // => true` +**See Also**: !=, <, > +**Section**: 4.3 (Comparison Operators) + +#### > +**Operator Type**: Comparison +**Signature**: `(Orderable Orderable -- bool)` +**Trait**: Orderable +**Description**: True if first value is greater than second. +**Example**: `5 3 > // => true` +**See Also**: >=, <, <= +**Section**: 4.3 (Comparison Operators) + +#### >= +**Operator Type**: Comparison +**Signature**: `(Orderable Orderable -- bool)` +**Trait**: Orderable +**Description**: True if first value is greater than or equal to second. +**Example**: `5 5 >= // => true` +**See Also**: >, <, <= +**Section**: 4.3 (Comparison Operators) + +#### ^ +**Operator Type**: Arithmetic +**Signature**: `(Exponentiable Exponentiable -- Exponentiable)` +**Trait**: Exponentiable +**Description**: Raise first value to power of second (exponentiation). +**Example**: `2 8 ^ // => 256` +**See Also**: log, ln, logb +**Section**: 4.2 (Arithmetic Operators) + +#### and +**Operator Type**: Logical +**Signature**: `(Logical Logical -- Logical)` +**Trait**: Logical +**Description**: Logical AND - returns first if falsy, else second. +**Example**: `true false and // => false` +**See Also**: or, not +**Section**: 4.4 (Logical Operators) + +#### at +**Operator Type**: Container Access +**Signature**: `(Selectable Size -- T)` +**Trait**: Selectable +**Description**: Access element at given index. +**Example**: `[10 20 30] 1 at // => 20` +**See Also**: slice, length +**Section**: 7.4 (Arrays) + +#### bitand +**Operator Type**: Bitwise +**Signature**: `(Bitwise Bitwise -- Bitwise)` +**Trait**: Bitwise +**Description**: Bitwise AND of two values. +**Example**: `0xFF 0x0F bitand // => 0x0F` +**See Also**: bitor, bitxor, bitnot +**Section**: 4.5 (Bitwise Operators) + +#### bitnot +**Operator Type**: Bitwise +**Signature**: `(Bitwise -- Bitwise)` +**Trait**: Bitwise +**Description**: Bitwise NOT (complement) of value. +**Example**: `0xFF bitnot // => (inverted bits)` +**See Also**: bitand, bitor, bitxor +**Section**: 4.5 (Bitwise Operators) + +#### bitor +**Operator Type**: Bitwise +**Signature**: `(Bitwise Bitwise -- Bitwise)` +**Trait**: Bitwise +**Description**: Bitwise OR of two values. +**Example**: `0xF0 0x0F bitor // => 0xFF` +**See Also**: bitand, bitxor, bitnot +**Section**: 4.5 (Bitwise Operators) + +#### bitxor +**Operator Type**: Bitwise +**Signature**: `(Bitwise Bitwise -- Bitwise)` +**Trait**: Bitwise +**Description**: Bitwise XOR of two values. +**Example**: `0xFF 0x0F bitxor // => 0xF0` +**See Also**: bitand, bitor, bitnot +**Section**: 4.5 (Bitwise Operators) + +#### break +**Operator Type**: Control Flow +**Signature**: `(--)` +**Description**: Exit the current loop immediately. +**Example**: `{ true } { condition { break } { } if } while` +**See Also**: continue, while, for +**Section**: 6.4 (Loop Control) + +#### concat +**Operator Type**: Container +**Signature**: `(Concatenable Concatenable -- Concatenable)` +**Trait**: Concatenable +**Description**: Concatenate two containers or strings. +**Example**: `[1 2 3] [4 5 6] concat // => [1 2 3 4 5 6]` +**See Also**: slice, reverse +**Section**: 7.4 (Arrays) + +#### continue +**Operator Type**: Control Flow +**Signature**: `(--)` +**Description**: Skip to the next iteration of the current loop. +**Example**: `1 10 { dup 2 % 0 == { continue } { print } if } for` +**See Also**: break, while, for +**Section**: 6.4 (Loop Control) + +#### depth +**Operator Type**: Stack Manipulation +**Signature**: `(-- Size)` +**Trait**: Stackable +**Description**: Push current stack depth onto the stack. +**Example**: `1 2 3 depth // => 1 2 3 3` +**See Also**: pick, roll +**Section**: 4.1 (Stack Operations) + +#### drop +**Operator Type**: Stack Manipulation +**Signature**: `(Self --)` +**Trait**: Stackable +**Description**: Remove and discard the top item from the stack. +**Example**: `5 10 drop // => 5` +**See Also**: dup, swap +**Section**: 4.1 (Stack Operations) + +#### dup +**Operator Type**: Stack Manipulation +**Signature**: `(Self -- Self Self)` +**Trait**: Stackable +**Description**: Duplicate the top item on the stack. +**Example**: `5 dup // => 5 5` +**See Also**: drop, over +**Section**: 4.1 (Stack Operations) + +#### each +**Operator Type**: Array Combinator +**Signature**: `(ArrayOf TokenString --)` +**Description**: Apply function to each element (side effects). +**Example**: `[1 2 3] { print } each` +**See Also**: map, filter, reduce +**Section**: 7.4 (Arrays) + +#### enum +**Operator Type**: Definition +**Signature**: `(TokenString Identifier --)` +**Trait**: Implementable +**Description**: Define an enumeration type. +**Example**: `{ Pending: Active: Complete: } ::Status enum` +**See Also**: struct, union, trait +**Section**: 7.3 (Enums) + +#### eval +**Operator Type**: Meta +**Signature**: `(TokenString --)` +**Trait**: Implementable +**Description**: Parse and execute TokenString as code. +**Example**: `"2 3 +" eval // => 5` +**See Also**: lambda +**Section**: 11.1 (Dynamic Code Evaluation) + +#### filter +**Operator Type**: Array Combinator +**Signature**: `(ArrayOf TokenString -- ArrayOf)` +**Description**: Keep only elements matching predicate. +**Example**: `[1 2 3 4 5] { 2 % 0 == } filter // => [2 4]` +**See Also**: map, reduce, each +**Section**: 7.4 (Arrays) + +#### fn +**Operator Type**: Definition +**Signature**: `(TypeTuple TokenString Identifier --)` +**Trait**: Implementable +**Description**: Define a function. +**Example**: `(Number -- Number) { dup * } ::square fn` +**See Also**: lambda, trait, impl +**Section**: 5.2 (Defining Functions) + +#### for +**Operator Type**: Control Flow +**Signature**: `(Size Size TokenString --)` +**Description**: Loop from start to end, pushing counter each iteration. +**Example**: `1 10 { dup print } for` +**See Also**: while, break, continue +**Section**: 6.3 (For Loops) + +#### get +**Operator Type**: Struct Access +**Signature**: `(Struct Identifier -- FieldValue)` +**Description**: Get field value from struct (consumes struct and field identifier). +**Example**: `point ::x get` +**See Also**: set +**Section**: 7.1 (Structs) + +#### if +**Operator Type**: Control Flow +**Signature**: `(bool TokenString TokenString --)` +**Description**: Conditional execution - execute first block if true, second if false. +**Example**: `x 0 > { "positive" print } { "negative" print } if` +**See Also**: match, while +**Section**: 6.1 (Conditionals) + +#### impl +**Operator Type**: Definition +**Signature**: `(Identifier TokenString Identifier --)` +**Trait**: Implementable +**Description**: Implement a trait for a type. +**Example**: `::Addable { ... } ::Point impl` +**See Also**: trait, inher +**Section**: 9.3 (Implementing Traits) + +#### inher +**Operator Type**: Definition +**Signature**: `(ArrayOf Identifier --)` +**Trait**: Implementable +**Description**: Declare trait inheritance. +**Example**: `[ ::Orderable ::Equatable ] ::Comparable inher` +**See Also**: trait, impl +**Section**: 9.4 (Trait Inheritance) + +#### lambda +**Operator Type**: Meta +**Signature**: `(TokenString -- Callable)` +**Trait**: Implementable +**Description**: Convert TokenString to callable code block. +**Example**: `{ dup * } lambda ::square swap` +**See Also**: eval, fn +**Section**: 5.6 (Lambda Functions) + +#### length +**Operator Type**: Container +**Signature**: `(Sized -- i64)` +**Trait**: Sized +**Description**: Get the number of elements in a container. +**Example**: `[1 2 3 4 5] length // => 5` +**See Also**: at, slice +**Section**: 7.4 (Arrays) + +#### ln +**Operator Type**: Arithmetic +**Signature**: `(Logarithmic -- Logarithmic)` +**Trait**: Logarithmic +**Description**: Natural logarithm (base e). +**Example**: `2.718 ln // => 1.0` +**See Also**: log, logb, ^ +**Section**: 4.2 (Arithmetic Operators) + +#### log +**Operator Type**: Arithmetic +**Signature**: `(Logarithmic -- Logarithmic)` +**Trait**: Logarithmic +**Description**: Logarithm base 10. +**Example**: `100 log // => 2.0` +**See Also**: ln, logb, ^ +**Section**: 4.2 (Arithmetic Operators) + +#### logb +**Operator Type**: Arithmetic +**Signature**: `(Logarithmic Logarithmic -- Logarithmic)` +**Trait**: Logarithmic +**Description**: Logarithm with custom base. +**Example**: `8 2 logb // => 3.0` +**See Also**: log, ln, ^ +**Section**: 4.2 (Arithmetic Operators) + +#### map +**Operator Type**: Array Combinator +**Signature**: `(ArrayOf TokenString -- ArrayOf)` +**Description**: Transform each element with function. +**Example**: `[1 2 3 4] { 2 * } map // => [2 4 6 8]` +**See Also**: filter, reduce, each +**Section**: 7.4 (Arrays) + +#### match +**Operator Type**: Control Flow +**Signature**: `(Value TokenString --)` +**Description**: Pattern match value against multiple patterns. +**Example**: `opt { Some(x) => { x print } None => { "Nothing" print } } match` +**See Also**: if +**Section**: 6.5 (Pattern Matching) + +#### not +**Operator Type**: Logical +**Signature**: `(Logical -- Logical)` +**Trait**: Logical +**Description**: Logical NOT - inverts truthiness. +**Example**: `false not // => true` +**See Also**: and, or +**Section**: 4.4 (Logical Operators) + +#### or +**Operator Type**: Logical +**Signature**: `(Logical Logical -- Logical)` +**Trait**: Logical +**Description**: Logical OR - returns first if truthy, else second. +**Example**: `true false or // => true` +**See Also**: and, not +**Section**: 4.4 (Logical Operators) + +#### over +**Operator Type**: Stack Manipulation +**Signature**: `(Self Self -- Self Self Self)` +**Trait**: Stackable +**Description**: Copy the second item to the top of the stack. +**Example**: `5 10 over // => 5 10 5` +**See Also**: dup, swap, rot +**Section**: 4.1 (Stack Operations) + +#### pick +**Operator Type**: Stack Manipulation +**Signature**: `(Size -- Self)` +**Trait**: Stackable +**Description**: Copy nth item to top (0 = top, 1 = second, etc.). +**Example**: `1 2 3 4 2 pick // => 1 2 3 4 2` +**See Also**: roll, depth +**Section**: 4.1 (Stack Operations) + +#### reduce +**Operator Type**: Array Combinator +**Signature**: `(ArrayOf T TokenString -- T)` +**Description**: Fold array with accumulator function. +**Example**: `[1 2 3 4] 0 { + } reduce // => 10` +**See Also**: map, filter, each +**Section**: 7.4 (Arrays) + +#### reverse +**Operator Type**: Array +**Signature**: `(ArrayOf -- ArrayOf)` +**Description**: Reverse order of array elements. +**Example**: `[1 2 3] reverse // => [3 2 1]` +**See Also**: transpose, concat +**Section**: 7.4 (Arrays) + +#### roll +**Operator Type**: Stack Manipulation +**Signature**: `(Size Size --)` +**Trait**: Stackable +**Description**: Rotate n items, times times. +**Example**: `1 2 3 4 3 1 roll // => 1 3 4 2` +**See Also**: rot, pick +**Section**: 4.1 (Stack Operations) + +#### rot +**Operator Type**: Stack Manipulation +**Signature**: `(Self Self Self -- Self Self Self)` +**Trait**: Stackable +**Description**: Rotate the top three items. +**Example**: `1 2 3 rot // => 2 3 1` +**See Also**: swap, roll +**Section**: 4.1 (Stack Operations) + +#### set +**Operator Type**: Struct Access +**Signature**: `(Value Identifier -- Struct)` +**Description**: Set field value in struct (consumes value and field identifier). +**Example**: `15.0 ::x set` +**See Also**: get +**Section**: 7.1 (Structs) + +#### shl +**Operator Type**: Bitwise +**Signature**: `(Bitwise Size -- Bitwise)` +**Trait**: Bitwise +**Description**: Shift bits left by n positions. +**Example**: `4 2 shl // => 16` +**See Also**: shr, bitand, bitor +**Section**: 4.5 (Bitwise Operators) + +#### shr +**Operator Type**: Bitwise +**Signature**: `(Bitwise Size -- Bitwise)` +**Trait**: Bitwise +**Description**: Shift bits right by n positions. +**Example**: `16 2 shr // => 4` +**See Also**: shl, bitand, bitor +**Section**: 4.5 (Bitwise Operators) + +#### slice +**Operator Type**: Container +**Signature**: `(Sliceable Size Size -- Sliceable)` +**Trait**: Sliceable +**Description**: Extract elements from start to end index. +**Example**: `[10 20 30 40] 1 3 slice // => [20 30]` +**See Also**: at, length +**Section**: 7.4 (Arrays) + +#### struct +**Operator Type**: Definition +**Signature**: `(TypeTuple TokenString Identifier --)` +**Trait**: Implementable +**Description**: Define a struct type. +**Example**: `(T T --) { x: y: } ::Point struct` +**See Also**: union, enum, get, set +**Section**: 7.1 (Structs) + +#### substr +**Operator Type**: String +**Signature**: `(String Size Size -- String)` +**Trait**: String +**Description**: Extract substring from start to end index. +**Example**: `"hello" 1 3 substr // => "el"` +**See Also**: slice, split +**Section**: 11.3 (String Operations) + +#### swap +**Operator Type**: Stack Manipulation +**Signature**: `(Self Self -- Self Self)` +**Trait**: Stackable +**Description**: Swap the top two items on the stack. +**Example**: `5 10 swap // => 10 5` +**See Also**: dup, rot +**Section**: 4.1 (Stack Operations) + +#### trait +**Operator Type**: Definition +**Signature**: `(TokenString Identifier --)` +**Trait**: Implementable +**Description**: Define a new trait. +**Example**: `{ (Self -- ) draw: } ::Drawable trait` +**See Also**: impl, inher +**Section**: 9.2 (Defining Traits) + +#### transpose +**Operator Type**: Array +**Signature**: `(ArrayOf> -- ArrayOf>)` +**Description**: Transpose a 2D array (swap rows and columns). +**Example**: `[[1 2] [3 4]] transpose // => [[1 3] [2 4]]` +**See Also**: reverse +**Section**: 7.4 (Arrays) + +#### union +**Operator Type**: Definition +**Signature**: `(TypeTuple TokenString Identifier --)` +**Trait**: Implementable +**Description**: Define a union type with tagged variants. +**Example**: `(T --) { Some(T) None } ::Option union` +**See Also**: struct, enum, match +**Section**: 7.2 (Unions) + +#### while +**Operator Type**: Control Flow +**Signature**: `(TokenString TokenString --)` +**Description**: Loop while condition is truthy, executing body each iteration. +**Example**: `{ dup 10 < } { dup print 1 + } while` +**See Also**: for, break, continue, if +**Section**: 6.2 (While Loops) + +#### window +**Operator Type**: Array +**Signature**: `(ArrayOf Size -- ArrayOf>)` +**Description**: Create sliding windows of given size. +**Example**: `[1 2 3 4] 2 window // => [[1 2] [2 3] [3 4]]` +**See Also**: slice +**Section**: 7.4 (Arrays) + +--- + +## Appendix D: Grammar Summary + +This appendix provides a concise grammar reference. For complete specifications of language constructs (fn, struct, trait, impl, etc.), see the `::Implementable` trait in Appendix B. + +### D.1 Lexical Grammar + +**Comments**: +``` +line_comment ::= "//" +``` + +**Identifiers**: +``` +identifier ::= [a-zA-Z_][a-zA-Z0-9_]* +identifier_literal ::= "::" identifier +``` + +**Integer Literals**: +``` +integer ::= decimal | hexadecimal | binary +decimal ::= [0-9]+ (":" type_name)? +hexadecimal ::= "0x" [0-9a-fA-F]+ +binary ::= "0b" [01]+ +``` + +**Floating Point Literals**: +``` +float ::= [0-9]+ "." [0-9]+ (":" type_name)? +``` + +**String Literals**: +``` +string ::= '"' (character | escape_sequence)* '"' +escape_sequence ::= "\n" | "\r" | "\t" | "\\" | '\"' | "\'" | "\0" + | "\x" hex_digit hex_digit + | "\u{" hex_digit+ "}" +``` + +**Boolean Literals**: +``` +boolean ::= "true" | "false" +``` + +**Array Literals**: +``` +array ::= "[" (expression)* "]" +``` + +**Token Strings**: +``` +token_string ::= "{" (token)* "}" +``` + +### D.2 Expression Grammar + +``` +expression ::= literal + | identifier + | identifier_literal + | expression operator + | control_flow + | definition + +literal ::= integer | float | string | boolean | array + +operator ::= built_in_operator | user_defined_operator + +control_flow ::= if_expr | while_expr | for_expr | match_expr +``` + +**Note on Operator Precedence**: Stack-based postfix notation eliminates the need for operator precedence. Operations are performed in the order they appear, operating on values already on the stack. + +### D.3 Type Grammar + +**Type Tuples (Stack Signatures)**: +``` +type_tuple ::= "(" type_list "--" type_list ")" + | "(---)" +type_list ::= (type)* +type ::= identifier + | generic_type + | trait_constraint + +generic_type ::= identifier "<" type_param_list ">" +type_param_list ::= type_param ("," type_param)* +type_param ::= identifier (":" trait_constraint)? +``` + +### D.4 Construct Grammar + +Language constructs (fn, struct, trait, impl, enum, union, inher) are defined by operators in the `::Implementable` trait. These operators parse TokenStrings to create language-level definitions. + +**High-Level Patterns**: +- Functions: `(inputs -- outputs) { body } ::name fn` +- Structs: `(field_types --) { field_names: } ::name? struct` +- Unions: `(variant_types --) { Variant(T) ... } ::name? union` +- Enums: `{ Variant value?: ... } ::name enum` +- Traits: `{ (sig) method: ... } ::identifier? trait` +- Trait Impl: `::trait_id { (sig) { body } method: ... } ::type_id? impl` +- Trait Inheritance: `[ identifier_list ] ::identifier? inher { } ::identifier? trait` + +> **Complete Specification**: See Appendix B (`::Implementable` trait) for precise definitions of these construct operators. + +--- + +## Appendix E: Module System (Future) **Current State**: All standard library functions and traits are automatically in scope. @@ -1565,87 +3268,402 @@ This would provide stronger type safety but add complexity to the type checker. --- -## Appendix D: Examples +## Appendix F: Memory Management (Future) -### D.1 Trait Implementation Example +The language specification currently does not include heap memory management. This appendix documents potential future approaches. + +**Current State**: All values are stack-allocated or embedded in data structures. + +**Pointer Types**: The `ptr` type for raw pointers is planned as a future feature and will be part of the memory management system. + +**Potential Approaches**: + +**Option A: Manual Management** +``` +// Allocate on heap +3.0 4.0 Point alloc // ( Point -- ptr ) + +// Dereference +ptr deref // ( ptr -- T ) + +// Store through pointer +new_value ptr store // ( T ptr -- ) + +// Free memory +ptr free // ( ptr -- ) +``` + +Pros: Full control, predictable, zero overhead +Cons: Error-prone, requires discipline, potential memory leaks + +**Option B: Reference Counting** +``` +// Create reference-counted value +3.0 4.0 Point rc // ( Point -- rc ) + +// Automatic reference counting +value dup // Increments count +drop // Decrements count, frees if zero +``` + +Pros: Automatic cleanup, relatively simple +Cons: Runtime overhead, cannot handle cycles, larger memory footprint + +**Option C: Ownership System (Rust-like)** +``` +// Linear types - each value has one owner +value // Move semantics by default +value dup // Error: cannot copy owned value +value ::clone call // Explicit clone required +``` + +Pros: Memory safe, zero overhead, prevents leaks +Cons: Complex type system, restricts stack operations, steep learning curve + +**Option D: Arena/Region-Based** +``` +// Create arena +::arena new // ( -- arena ) + +// Allocate in arena +arena 3.0 4.0 Point alloc_in // ( arena Point -- ptr ) + +// Free entire arena +arena free_arena // ( arena -- ) +``` + +Pros: Fast allocation, simple bulk deallocation +Cons: Less granular control, memory held until arena freed + +**Recommendation**: Start without heap allocation (current approach). When needed, implement Option A (manual) for simplicity, with Option D (arenas) added later for performance-critical code. The stack-based nature makes ownership tracking (Option C) particularly challenging. + +**Type Parameter Enforcement Enhancement**: + +**Current State**: Type parameters in generic functions are currently suggestions and are not enforced at parse time. + +**Example**: +``` +(T -- T) { dup * } ::square fn // Currently no error even without Multiplyable constraint +``` + +**Future Enhancement**: The compiler could enforce that type parameters actually constrain how operators and functions act, validated at parse time: +``` +(Multiplyable -- Multiplyable) { dup * } ::square fn // Enforced constraint +``` + +This would provide stronger type safety but add complexity to the type checker. + +--- + +## Appendix G: Examples & Tutorials + +### G.1 Tutorial: First Steps + +**Hello World**: +``` +"Hello, World!" print +``` + +**Basic Arithmetic**: +``` +// Simple calculations +3 4 + // => 7 +10 3 - // => 7 +5 6 * // => 30 +20 4 / // => 5 + +// Chaining operations +2 3 + 4 * // => 20 (addition happens first due to postfix order) + +// Using the stack +10 dup * // => 100 (duplicate 10, then multiply) +``` + +**Simple Functions**: +``` +// Square function +(Number -- Number) { dup * } ::square fn +5 square // => 25 + +// Absolute value +(Number -- Number) { + dup 0 > + { } // If positive, do nothing + { 0 swap - } // If negative, negate + if +} ::abs fn + +-5 abs // => 5 +``` + +**Stack Manipulation Practice**: +``` +// Basic stack operations +5 dup // => 5 5 +5 10 swap // => 10 5 +5 10 over // => 5 10 5 +1 2 3 rot // => 2 3 1 + +// More complex example - swap two items below top +// Stack: a b c +// Want: b a c +rot rot // First rot: b c a, Second rot: c a b... wait, that's wrong! + +// Better approach: +// Stack: a b c +swap rot rot // swap: a c b, rot: c b a, rot: b a c (correct!) +``` + +### G.2 Tutorial: Working with Traits + +**Implementing a Trait for a Custom Type**: ``` -// Define the Addable trait +// Step 1: Define a struct +(Number Number --) { x: y: } ::Point struct + +// Step 2: Implement Addable trait +::Addable { + // Add two points + (Self Self -- Self) { + over ::x get over ::x get + // Add x coordinates + swap ::y get swap ::y get + // Add y coordinates + Point // Construct new point + } +: + + // Subtract two points + (Self Self -- Self) { + over ::x get over ::x get - // Subtract x coordinates + swap ::y get swap ::y get - // Subtract y coordinates + Point // Construct new point + } -: +} ::Point impl + +// Step 3: Use it +3.0 4.0 Point // First point +1.0 2.0 Point // Second point ++ // => Point with x=4.0, y=6.0 +``` + +**Using Trait Bounds**: + +``` +// Function that works with any Addable type +(Addable Addable Addable -- Addable) { + + + // Add all three +} ::sum_three fn + +// Works with numbers +1 2 3 sum_three // => 6 + +// Works with Points +1.0 2.0 Point +3.0 4.0 Point +5.0 6.0 Point +sum_three // => Point(9.0, 12.0) +``` + +**Understanding Standard Traits**: + +``` +// Number trait combines many operations +(Number Number -- Number) { + dup * swap dup * + // a² + b² +} ::pythagorean fn + +3.0 4.0 pythagorean // => 25.0 + +// This works because Number inherits from: +// - Addable (for +) +// - Multiplyable (for *) +// - Comparable (for comparisons) +// - And more... +``` + +### G.3 Tutorial: Generic Programming + +**Writing Generic Functions**: + +``` +// Generic identity - works with any type +(T -- T) { } ::identity fn + +5 identity // => 5 +"hello" identity // => "hello" + +// Generic swap function +(T U -- U T) { swap } ::generic_swap fn + +// Constrained generic - requires Comparable +(Comparable Comparable -- Comparable) { + over over > + { } // First is larger, do nothing + { swap } // Second is larger, swap them + if + drop // Drop the smaller value +} ::max fn + +5 10 max // => 10 +10 5 max // => 10 +``` + +**Generic Data Structures**: + +``` +// Define a generic Pair +(T U --) { first: second: } ::Pair struct + +// Use with different types +5 "hello" Pair // Pair +3.14 true Pair // Pair + +// Access fields +dup ::first get // Get first element +::second get // Get second element + +// Generic Option (already defined in standard library) +(T --) { Some(T) None } ::Option union + +42 Option::Some // Option::Some +Option::None // Option::None +``` + +**Trait Constraints in Generics**: + +``` +// This function requires the type to be Multiplyable +(T:Multiplyable -- T) { + dup * +} ::square_generic fn + +// Works with any Multiplyable type +5 square_generic // => 25 +3.14 square_generic // => 9.8596 + +// Multiple constraints using composite traits +(Number -- Number) { + dup 0 > + { } + { 0 swap - } + if +} ::abs_generic fn +``` + +### G.4 Complete Examples + +#### G.4.1 Trait Implementation Example + +``` +// Define a trait for drawable objects +{ + (Self -- ) draw: +} ::Drawable trait + +// Define a Rectangle struct +(Number Number --) { width: height: } ::Rectangle struct + +// Implement Drawable for Rectangle +::Drawable { + (Self -- ) { + "Drawing rectangle:" print + dup ::width get "Width: " swap concat print + ::height get "Height: " swap concat print + } draw: +} ::Rectangle impl + +// Use it +10.0 20.0 Rectangle draw +// Output: +// Drawing rectangle: +// Width: 10.0 +// Height: 20.0 +``` + +#### G.4.2 Trait Inheritance Example + +``` +// Define base traits { (Self Self -- Self) +: (Self Self -- Self) -: } ::Addable trait -// Implement for i32 -::Addable { - (Self Self -- Self) { - // Native addition - } +: - - (Self Self -- Self) { - // Native subtraction - } -: -} ::i32 impl +{ + (Self Self -- Self) *: + (Self Self -- Self) /: +} ::Multiplyable trait -// Implement for Point -::Addable { - (Self Self -- Self) { - over ::x get over ::x get + - swap ::y get swap ::y get + - Point - } +: - - (Self Self -- Self) { - over ::x get over ::x get - - swap ::y get swap ::y get - - Point - } -: -} ::Point impl +// Composite trait inheriting from both +[ ::Addable ::Multiplyable ] ::BasicMath inher +{ } ::BasicMath trait + +// Now any type implementing BasicMath must support +, -, *, / +// And functions can require BasicMath as a constraint +(BasicMath BasicMath -- BasicMath) { + over over * swap dup * + // (a * b) + (b * b) +} ::weird_math fn + +3 4 weird_math // => 28 ``` -### D.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 -{ (Self Self -- Self) logb: (Self -- Self) log: (Self -- Self) ln: } ::Logarithmic trait - -// Number inherits from multiple traits -[ ::Addable ::Multiplyable ::Exponentiable ::Comparable ::Logarithmic ] ::Number inher -{ } ::Number trait -``` - -### D.3 Logarithm Usage +#### G.4.3 Logarithm Usage ``` // Calculate log base 10 -100 log print // 2.0 -1000 log print // 3.0 +100 log print // => 2.0 +1000 log print // => 3.0 // Calculate natural logarithm -2.718 ln print // ~1.0 -7.389 ln print // ~2.0 +2.718 ln print // => ~1.0 +7.389 ln print // => ~2.0 + +// Calculate with custom base +8 2 logb print // => 3.0 (2³ = 8) +27 3 logb print // => 3.0 (3³ = 27) // Combine with other operations -10 3 ^ log print // 3.0 (log of 1000) +10 3 ^ log print // => 3.0 (log of 1000) + +// Logarithm laws verification +// log(a*b) = log(a) + log(b) +10 100 * log // log(1000) = 3.0 +10 log 100 log + // log(10) + log(100) = 1.0 + 2.0 = 3.0 ``` -### D.4 Factorial +#### G.4.4 Factorial ``` (Number -- Number) { - dup 1 - { drop 1 } - { dup 1 - factorial * } - <= if + dup 1 <= + { drop 1 } // Base case: 0! = 1! = 1 + { dup 1 - factorial * } // Recursive case: n! = n * (n-1)! + if } ::factorial fn -5 factorial print // 120 +5 factorial print // => 120 +10 factorial print // => 3628800 + +// Iterative version (more efficient) +(Number -- Number) { + 1 swap // Start with accumulator = 1 + 1 swap // Start counter at 1 + { // While counter <= n + dup 3 pick <= + } + { // Body: multiply accumulator by counter + 2 pick over * // acc * counter + 3 roll drop // Drop old accumulator + swap 1 + swap // Increment counter + } + while + drop // Drop counter + swap drop // Drop original n +} ::factorial_iter fn + +5 factorial_iter print // => 120 ``` -### D.5 FizzBuzz +#### G.4.5 FizzBuzz ``` (Number -- ) { @@ -1665,163 +3683,103 @@ This would provide stronger type safety but add complexity to the type checker. if } ::fizzbuzz fn +// Print FizzBuzz for 1 to 100 1 100 { fizzbuzz } for ``` -### D.6 Using Roll +#### G.4.6 Using Roll ``` +// Roll rotates the top n items, times times // 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 +// Rotate top 3 items once +3 1 roll // Stack: 1 2 4 5 3 + +// Start fresh: 1 2 3 4 5 +// Rotate top 3 items twice +3 2 roll // Stack: 1 2 5 3 4 + +// Start fresh: 1 2 3 4 5 +// Rotate all 5 items once +5 1 roll // Stack: 2 3 4 5 1 + +// Start fresh: 1 2 3 4 5 +// Rotate top 4 items three times +4 3 roll // Stack: 1 4 5 2 3 + +// Practical use: bring nth item to top +// Stack: a b c d e +// Want to bring 'b' (index 3) to top +4 3 roll // Rotates top 4 three times: a c d e b + +// Or use pick for non-destructive copy +// Stack: a b c d e +3 pick // Stack: a b c d e b (copied from index 3) ``` -### D.7 Array Processing +#### G.4.7 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 + { 2 % 0 == } filter // Keep even: [2 4 6 8 10] + { dup * } map // Square each: [4 16 36 64 100] + 0 { + } reduce // Sum: 220 +print + +// Find maximum in array +[5 2 9 1 7 6] + dup 0 at // Start with first element + { + over over > + { swap } // If current > max, swap + { } // Otherwise keep max + if + drop // Drop the smaller value + } reduce +print // => 9 + +// Average of array +[10 20 30 40 50] + dup 0 { + } reduce // Sum: 150 + swap length // Length: 5 + / // Average: 30 +print ``` -### D.8 Identifier Literals in Practice +#### G.4.8 Identifier Literals in Practice ``` -// Push identifier literal to stack -::Point // Pushes identifier "Point" +// Identifier literals are used in struct/trait definitions +// and field access -// Use with trait definition +// Defining a struct requires ::StructName identifier literal +(Number Number --) { x: y: } ::Point struct + +// Field access requires ::field_name identifier literal +3.0 4.0 Point +dup ::x get print // Prints: 3.0 +::y get print // Prints: 4.0 + +// Dynamic field access (advanced) +"x" :: // Convert string to identifier +// (This would require string-to-identifier conversion, which +// may be a future feature) + +// Traits use identifier literals { (Self -- ) draw: } ::Drawable trait -// Use with struct definition -(T T --) { x: y: } ::Point struct +// Implementations use identifier literals +::Drawable { ... } ::Rectangle impl -// Dynamic trait implementation -::MyType { ... } ::MyTrait impl +// Identifier literals are NOT used inside trait/impl bodies +// (those are method names) +{ + (Self -- ) { "Drawing" print } draw: // "draw:" is method name +} ::Drawable trait ``` --- -## Appendix E: Grammar Summary - -### E.1 Lexical Elements - -``` -// Comments -line_comment ::= "//" - -// Identifiers -identifier ::= [a-zA-Z_][a-zA-Z0-9_]* -identifier_literal ::= "::" identifier - -// Integer literals -integer ::= decimal | hexadecimal | binary -decimal ::= [0-9]+ (":" type_name)? -hexadecimal ::= "0x" [0-9a-fA-F]+ -binary ::= "0b" [01]+ - -// Floating point literals -float ::= [0-9]+ "." [0-9]+ (":" type_name)? - -// String literals -string ::= '"' (character | escape_sequence)* '"' -escape_sequence ::= "\n" | "\r" | "\t" | "\\" | '\"' | "\'" | "\0" | "\x" hex_digit hex_digit | "\u{" hex_digit+ "}" - -// Boolean literals -boolean ::= "true" | "false" - -// Array literals -array ::= "[" (expression)* "]" - -// Token strings -token_string ::= "{" (token)* "}" -``` - -### E.2 Type Expressions - -``` -// Type tuples (stack signatures) -type_tuple ::= "(" type_list "--" type_list ")" -type_list ::= (type)* - -// Generic types -generic_type ::= identifier "<" type_param_list ">" -type_param_list ::= type_param ("," type_param)* -type_param ::= identifier (":" trait_constraint)? -``` - -### E.3 Definitions - -``` -// Function definition -function_def ::= type_tuple token_string identifier_literal "fn" - -// Struct definition -struct_def ::= type_tuple token_string identifier_literal generic_params? "struct" - -// Union definition -union_def ::= type_tuple token_string identifier_literal generic_params? "union" - -// Enum definition -enum_def ::= token_string identifier_literal "enum" - -// Trait definition -trait_def ::= (inheritance)? token_string identifier_literal generic_params? "trait" - -// Trait implementation -trait_impl ::= identifier_literal token_string identifier_literal generic_params? "impl" - -// Trait inheritance -inheritance ::= "[" identifier_list "]" identifier_literal generic_params? "inher" -``` - -### E.4 Control Flow - -``` -// Conditional -if_expr ::= expression token_string token_string "if" - -// While loop -while_expr ::= token_string token_string "while" - -// For loop -for_expr ::= expression expression token_string "for" - -// Match expression -match_expr ::= expression token_string "match" -``` - -### E.5 Complete Grammar Patterns - -**Functions**: `(inputs -- outputs) { body } ::name fn` - -**Structs**: `(field_types --) { field_names: } ::name struct` - -**Unions**: `(variant_types --) { Variant(T) ... } ::name union` - -**Enums**: `{ Variant value?: ... } ::name enum` - -**Traits**: `{ (sig) method: ... } ::identifier? trait` - -**Trait Impl**: `::trait_id { (sig) { body } method: ... } ::type_id? impl` - -**Trait Inheritance**: `[ identifier_list ] ::identifier inher { } ::identifier trait` - -**If**: `condition { then } { else } if` - -**While**: `{ condition } { body } while` - -**For**: `start end { body } for` - -**Match**: `value { pattern => block ... } match` - -**Lambda**: `{ code } lambda` - -**Identifier Literal**: `::name` +**End of Stack Language Specification v0.8**