stack_lang_spec.md

Home

Stack Language Specification

Version: 0.8.2
Status: Draft Specification
Changes:

1. Overview

A statically-typed, stack-based language with pure postfix notation combining the execution model of HP's RPL, the type system of C and Rust, and modern array operations from Uiua.

Design Principles

Operators vs Functions

Operators are operations that implement trait methods. They can be:

Functions are user-defined or library-defined procedures. They:

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:

Sections 8-10 cover intermediate concepts:

Section 11 covers advanced topics:

Appendices provide complete references:

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 and H for quick reference to standard library functions, traits, operators, and types.

2. Lexical Structure

2.1 Comments and Directives

Single-line Comments:

// Single-line comment

Compiler Directives:

The language reserves the # character for implementation-specific compiler directives. The # character cannot appear in identifiers.

#!/usr/bin/env stack_lang

Directives are implementation-specific and not part of the core language specification. Implementations may support various directives for version requirements, optimization hints, or other configuration.

2.2 Identifiers and Constants

Regular Identifiers

Identifier Literals

Constants

Constants are compile-time values that are immutable and available throughout the scope where they are defined.

Syntax: value ::name const

Examples:

3.1415926535 ::pi const
9.81 ::gravity const
299792458 ::speed_of_light const

// Use constants like any other value
10 pi * 2 /     // Calculate circumference / 2

Properties:

Advanced Usage: See Section 11.2 for complete identifier literal rules and context-dependent behavior.

2.3 Literals

Integer Literals

42          // i64 (default)
42:i32      // Annotate as i32
0xFF        // hexadecimal
0b1010      // binary
0o755       // octal
1_000_000   // underscore separators (ignored)

Overflow Behavior: Integer arithmetic wraps on overflow. For example, adding 1 to 127, the maximum value of an i8, produces -128.

Floating Point Literals

3.14        // f64 (default)
3.14:f32    // Annotate as f32
1_000.5     // underscore separators allowed

Overflow Behavior: Floating point operations follow IEEE 754 semantics, producing infinity or NaN for overflow/undefined operations.

Character Literals

'A'         // Single character
'\n'        // Escape sequence
'\x41'      // Hexadecimal (A)
'\u{1F600}' // Unicode (😀)

String Literals

"hello world"
"escape sequences: \n \t \\ \""

Escape Sequences

Boolean Literals

true
false

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

// Typed arrays
[1 2 3 :i16]             // array of i16
[[1.0 2.0] [3.0 4.0] :f32]  // 2D array of f32

// Arrays of structs (when Point is defined)
[{1 2} {3 4} :Point]     // array of Point structs

3. Primitive Types

The language provides several built-in primitive types for common values:

Integer Types

Floating Point Types

Other Types

Type Annotations

You can explicitly annotate literal types:

42:i32      // 32-bit integer
3.14:f32    // 32-bit float
'A'         // character

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. See Appendix H for detailed information about all types.

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

Mathematical Functions:

16 sqrt     // ( a -- result ) Square root
-5 abs      // ( a -- result ) Absolute value
0.0 sin     // ( a -- result ) Sine (radians)
0.0 cos     // ( a -- result ) Cosine (radians)
0.0 tan     // ( a -- result ) Tangent (radians)
1.0 asin    // ( a -- result ) Arc sine
1.0 acos    // ( a -- result ) Arc cosine
1.0 atan    // ( a -- result ) Arc tangent
1.0 0.0 atan2  // ( y x -- result ) Two-argument arc tangent
3.14 floor  // ( a -- result ) Round down
3.14 ceil   // ( a -- result ) Round up
3.14 round  // ( a -- result ) Round to nearest
3 5 min     // ( a b -- result ) Minimum of two values
3 5 max     // ( a b -- result ) Maximum of two values

Examples:

10 5 +      // => 15
10 3 /      // => 3
10 3 %      // => 1
2 10 ^      // => 1024
16 sqrt     // => 4.0
-42 abs     // => 42
3.14159 sin // => ~0.0
3.7 round   // => 4.0

Implementation Details: Arithmetic operators implement the ::Addable, ::Multiplyable, ::Exponentiable, ::Logarithmic, and ::Math 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.

4.6 Randomness

Random number generation is provided through built-in operators:

rand        // ( -- f64 ) Generate random f64 in range [0.0, 1.0)
seed        // ( u64 -- ) Seed the random number generator

Examples:

rand                    // => 0.7234... (random value)
12345 seed              // Seed RNG with specific value
rand                    // => 0.4321... (deterministic after seed)

// Random integer in range
100 rand * floor        // Random integer 0-99

Implementation Note: The specific random number generation algorithm is implementation-defined but should be a high-quality PRNG suitable for general use (not cryptography).

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:

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:

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:

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<type_params>? struct

Examples:

// Define Point struct - generic over coordinate types
(T T --) { x: y: } ::Point<T> 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<T U V> struct

10.0 20.0 30.0 Box3D

Field Access:

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<type_params>? union

Examples:

// Option type - generic over T
(T --) { 
    Some(T) 
    None 
} ::Option<T> union

// Result type - generic over T and E
(T E --) { 
    Ok(T) 
    Err(E) 
} ::Result<T E> 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

// Typed arrays
[1 2 3 :i16]             // array of i16
[[1.0 2.0] [3.0 4.0] :f32]  // 2D array of f32

// Arrays of structs (when Point is defined)
[{1 2} {3 4} :Point]     // array of Point structs

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

// Foldl - left fold with accumulator
[1 2 3 4] 0 { + } foldl      // => 10 (same as reduce)

// Foldr - right fold with accumulator
[1 2 3 4] 0 { + } foldr      // => 10 (for commutative ops)

Array Utilities:

// Zip - combine two arrays element-wise
[1 2 3] [4 5 6] zip          // => [[1 4] [2 5] [3 6]]

// Enumerate - add indices to elements
["a" "b" "c"] enumerate      // => [[0 "a"] [1 "b"] [2 "c"]]

// Sum - sum all numeric elements
[1 2 3 4 5] sum              // => 15

// Mean - calculate average
[1 2 3 4 5] mean             // => 3.0

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<T>, ::Selectable<T>, ::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:

Traits define behavioral contracts:

Key Distinction:

Examples:

// Point is a type
(T T --) { x: y: } ::Point<T> 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. See Appendix H for detailed information about all types.

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)               // 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 with Iterable:

For operations that need variable numbers of arguments, use the Iterable trait:

(-- Size) depth:                           // Zero arguments, returns stack depth
(String Iterable<Stringifiable> --) format: // String plus iterable of printable values
(Iterable<T> -- T) sum:                    // Iterable of values, returns sum

Examples:

"x=%d, y=%d" [x y] format    // Format string with array of values
[1 2 3 4 5] sum              // Sum array of numbers
depth print                   // No arguments needed

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:

// Point contains two T values
(T T --) { x: y: } ::Point<T> struct

// Line contains two Points
(Point<T> Point<T> --) { start: end: } ::Line<T> 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<T> struct

// Option can contain any type (or nothing)
(T --) { Some(T) None } ::Option<T> union

// Nested generics
Option<Point<f64>>               // Option containing a Point of f64s

9. Trait System

9.1 What are Traits

Traits define behavioral contracts - they specify what operations a type must support without dictating how those operations are implemented.

Why Traits Exist:

Standard Traits Overview:

The language provides many built-in traits:

Complete Reference: See Appendix B for all standard trait definitions with complete documentation.

9.2 Defining Traits

Syntax: { method_signatures } ::identifier<type_params>? trait

Traits can have methods or be empty (marker traits). Empty traits are typically used with inheritance.

Examples:

// Trait with methods
{
    (Self -- ) draw:
} ::Drawable trait

// Trait with multiple methods
{
    (Self Self -- Self) add:
    (Self Self -- Self) sub:
    (Self -- Self) neg:
} ::Numeric trait

// Generic trait
{
    (Self T -- Self) append:
    (Self -- T) pop:
} ::Container<T> trait

// Empty marker trait
{ } ::Serializable trait

Method Signatures: Within the TokenString, identifiers are method names and should not use the :: prefix.

9.3 Implementing Traits

Syntax: ::trait_identifier { method_implementations } ::type_identifier impl

Implementation Rules:

  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:

// Implement Addable for i32
::Addable {
    (Self Self -- Self) {
        // Native addition implementation
    } +:

    (Self Self -- Self) {
        // Native subtraction implementation
    } -:
} ::i32 impl

// Implement Drawable for Rectangle
::Drawable {
    (Self -- ) {
        "Drawing rectangle" print
        dup ::width get print
        ::height get print
    } draw:
} ::Rectangle impl

More Examples: See Appendix G for complete implementation examples and tutorials.

9.4 Trait Inheritance

Syntax: [ identifier_list ] ::identifier<type_params>? inher { methods } ::identifier<type_params>? trait

Trait inheritance allows a trait to include all methods from parent traits, optionally adding new methods.

Examples:

// Combine multiple arithmetic traits
[ ::Addable ::Multiplyable ] ::BasicNumber inher
{ } ::BasicNumber trait

// Full Number inherits everything numeric
[ ::Addable ::Multiplyable ::Exponentiable ::Comparable ::Logarithmic ] ::Number inher
{ } ::Number trait

// Inheritance with additional methods
[ ::Drawable ::Transformable ::Collidable ] ::GameObject inher
{
    (Self -- ) update:
    (Self -- ) destroy:
} ::GameObject trait

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
[ ::Container<T> ] ::Stack<T> inher
{
    (Self -- T) pop:
} ::Stack<T> trait

// Inheriting trait specifies concrete type
[ ::Container<i32> ] ::IntStack inher
{
    (Self -- i32) pop:
} ::IntStack trait

9.5 Using Traits in Functions

Traits can be used as type constraints in function signatures:

Examples:

// Function requiring Drawable trait
(Drawable -- ) {
    draw
} ::draw_object fn

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

Multiple Constraints: Use specific traits or composite traits that inherit from multiple parents:

// Requires both Addable and Comparable
(Number -- Number) { ... } ::some_function fn

// Number trait inherits from both, so this works

9.6 Standard Traits Overview

This section provides a brief overview of all standard traits. For complete definitions with all methods and documentation, see Appendix B.

Stack Operations:

Arithmetic:

Comparison:

Logical and Bitwise:

Containers:

Conversion:

String Operations:

Utilities:

Complete Reference: See Appendix B for full trait definitions with all methods, examples, and implementation details.

10. Generic Programming

10.1 Type Parameters

Type parameters allow functions, structs, and traits to work with multiple types.

Generic Syntax: <T> where T is a type parameter

Examples:

// Generic struct
(T T --) { x: y: } ::Point<T> struct

// Generic union
(T --) { Some(T) None } ::Option<T> union

// Generic trait
{
    (Self T -- Self) append:
} ::Container<T> trait

Type Parameter Constraints:

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<T E> 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 trait
(Addable Addable -- Addable) {
    +
} ::add_values fn

// Requires Number trait
(Number -- Number) {
    dup 0 > { } { 0 swap - } if
} ::abs fn

// Multiple constraints
(Number Number -- Number) {
    dup * swap dup * +  // a² + b²
} ::pythagorean fn

Type Inference: The compiler infers the actual type from usage:

5 identity          // T inferred as i64
"hello" identity    // T inferred as String
3 4 add_values      // Addable inferred as i64

10.3 Generic Data Structures

Structs and unions can be generic over type parameters:

Generic Structs:

// Point is generic over coordinate type
(T T --) { x: y: } ::Point<T> struct

// Use with different types
3.0 4.0 Point       // Point<f64>
3 4 Point           // Point<i64>

// Multiple type parameters
(T U --) { first: second: } ::Pair<T U> struct
5 "hello" Pair      // Pair<i64 String>

Generic Unions:

// Option is generic over contained type
(T --) { Some(T) None } ::Option<T> union

42 Option::Some     // Option<i64>::Some
"text" Option::Some // Option<String>::Some
Option::None        // Option<T>::None (T inferred from context)

// Result with two type parameters
(T E --) { Ok(T) Err(E) } ::Result<T E> union

Nested Generics:

// Array of Options
[Option::Some Option::None]           // Array of Option<T>

// Option of array
[1 2 3] Option::Some                  // Option<Array<i64>>

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<T> trait

// Map generic over key and value types
{
    (Self K -- V) get:
    (Self K V -- Self) insert:
} ::Map<K V> 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<T> ] ::Stack<T> inher
{
    (Self -- T) peek:
} ::Stack<T> trait

// Inheriting trait specifies concrete type
[ ::Container<i32> ] ::IntStack inher
{
    (Self -- i32) peek:
} ::IntStack trait

// Multiple generic inheritance
[ ::Selectable<T> ::Sized ::Sliceable ] ::ArrayOf<T> inher
{ } ::ArrayOf<T> 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:

// Evaluate simple expression
"2 3 +" eval            // Pushes 5

// Build and execute code
"(Multiplyable -- Multiplyable) { dup * } ::square fn" eval
5 square                // 25

// Dynamic dispatch
operation_name " get" concat eval

Use Cases:

Warnings:

11.2 Identifier Literals

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:

11.3 Testing and Assertions

The assert operator provides inline testing and verification.

Syntax: { expression } { condition } assert

The assert operator evaluates the expression block, then evaluates the condition block. If the condition returns false (or a falsy value), the program halts with an assertion failure.

Examples:

// Simple assertion
{ 2 3 + } { 5 == } assert

// Testing a function
{ 5 square } { 25 == } assert

// Multiple assertions
{ 10 3 divmod } { 3 == swap 1 == and } assert

// Assertion with message (implementation-specific)
{ 2 3 + } { 5 == } "Addition should work" assert

Use Cases:

Testing Framework (Future): A more comprehensive testing framework with test and test_error operators is planned for future versions. See Appendix F for details.

11.4 Reflection

Reflection operators provide runtime type and trait information for debugging and metaprogramming.

type_of Operator

Syntax: value type_of
Signature: (Self -- Identifier)

Returns the type of a value as an identifier literal.

Examples:

42 type_of              // Pushes ::i64
"hello" type_of         // Pushes ::String
3.14 type_of            // Pushes ::f64

// Use with conditionals
value type_of ::i64 ==
    { "It's an integer" print }
    { "It's not an integer" print }
if

implements Operator

Syntax: value ::TraitName implements
Signature: (Self Identifier -- bool)

Checks if a value's type implements a specific trait.

Examples:

42 ::Addable implements         // => true
42 ::Drawable implements        // => false

"hello" ::String implements     // => true
[1 2 3] ::Iterable implements   // => true

// Use with conditionals
value ::Serializable implements
    { value serialize }
    { "Cannot serialize" print }
if

Use Cases:

Examples:

// Generic print function with type info
(Self -- ) {
    dup type_of to_str "Type: " swap concat print
    dup ::Stringifiable implements
        { to_str print }
        { drop "Cannot print this type" print }
    if
} ::debug_print fn

// Trait-based dispatch
(Self -- ) {
    dup ::Drawable implements
        { draw }
        { drop "Not drawable" print }
    if
} ::try_draw fn

11.5 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
"file.txt" read         // Read file contents as string
"data" "file.txt" write // Write string to file

String Operations:

"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
"hello world" "world" "Stack" replace  // Replace substring
"  hello  " trim            // Remove whitespace
"hello world" "world" find  // Find substring position
"hello" "hel" starts_with   // Check prefix
"hello" "llo" ends_with     // Check suffix
"x=%d, y=%d" [5 10] format  // Format string with values

Type Conversion:

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

Array Operations:

Complete Reference: See Appendix A for the full standard library reference with all functions, signatures, and examples.

Appendix A: Standard Library

This appendix provides a complete alphabetical reference of all standard library functions and operations.

Standard Library Categories

Array Operations: at, concat, each, enumerate, filter, foldl, foldr, length, map, mean, reduce, reverse, shape, slice, sum, transpose, window, zip

I/O Operations: input, print, read, write

String Operations: concat, ends_with, find, format, join, length, replace, split, starts_with, substr, trim

Type Conversion: parse, to_f32, to_f64, to_i8, to_i16, to_i32, to_i64, to_str, to_u8, to_u16, to_u32, to_u64

Utility Operations: assert, implements, type_of

Alphabetical Reference

abs

Signature: (Math -- Math)
Trait: Math
Description: Return the absolute value of a number.
Example:

-42 abs      // Returns 42
3.14 abs     // Returns 3.14

See Also: min, max

acos

Signature: (Math -- Math)
Trait: Math
Description: Calculate arc cosine (inverse cosine) in radians.
Example:

1.0 acos     // Returns 0.0
0.0 acos     // Returns ~1.5708 (pi/2)

See Also: cos, asin, atan

asin

Signature: (Math -- Math)
Trait: Math
Description: Calculate arc sine (inverse sine) in radians.
Example:

1.0 asin     // Returns ~1.5708 (pi/2)
0.0 asin     // Returns 0.0

See Also: sin, acos, atan

assert

Signature: (TokenString TokenString --)
Description: Evaluate expression and condition, halt if condition is false.
Example:

{ 2 3 + } { 5 == } assert
{ 5 square } { 25 == } assert

See Also: type_of, implements

at

Signature: (Selectable<T> Size -- T)
Trait: Selectable
Description: Access element at the given index.
Example:

[10 20 30] 1 at  // Returns 20

See Also: slice, length

atan

Signature: (Math -- Math)
Trait: Math
Description: Calculate arc tangent (inverse tangent) in radians.
Example:

1.0 atan     // Returns ~0.7854 (pi/4)
0.0 atan     // Returns 0.0

See Also: tan, atan2, asin

atan2

Signature: (Math Math -- Math)
Trait: Math
Description: Calculate two-argument arc tangent of y/x in radians, using signs to determine quadrant.
Example:

1.0 1.0 atan2    // Returns ~0.7854 (pi/4)
1.0 0.0 atan2    // Returns ~1.5708 (pi/2)

See Also: atan, tan

ceil

Signature: (Math -- Math)
Trait: Math
Description: Round number up to nearest integer.
Example:

3.14 ceil    // Returns 4.0
-2.7 ceil    // Returns -2.0

See Also: floor, round

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

cos

Signature: (Math -- Math)
Trait: Math
Description: Calculate cosine of angle in radians.
Example:

0.0 cos      // Returns 1.0
3.14159 cos  // Returns ~-1.0

See Also: sin, tan, acos

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<T> TokenString --)
Description: Apply function to each element (side effects).
Example:

[1 2 3] { print } each  // Prints 1, 2, 3

See Also: map, filter

ends_with

Signature: (String String -- bool)
Trait: String
Description: Check if string ends with given suffix.
Example:

"hello" "lo" ends_with   // Returns true
"hello" "he" ends_with   // Returns false

See Also: starts_with, find

enumerate

Signature: (ArrayOf<T> -- ArrayOf<Pair<Size T>>)
Description: Add indices to array elements.
Example:

["a" "b" "c"] enumerate  // Returns [[0 "a"] [1 "b"] [2 "c"]]

See Also: zip, map

eval

Signature: (TokenString --)
Trait: Implementable
Description: Parse and execute TokenString as code.
Example:

"2 3 +" eval  // Returns 5

See Also: lambda

filter

Signature: (ArrayOf<T> TokenString -- ArrayOf<T>)
Description: Keep only elements matching predicate.
Example:

[1 2 3 4 5] { 2 % 0 == } filter  // Returns [2 4]

See Also: map, reduce

find

Signature: (String String -- Option<Size>)
Trait: String
Description: Find position of substring, returns Option::Some(index) or Option::None.
Example:

"hello world" "world" find  // Returns Option::Some(6)
"hello world" "xyz" find    // Returns Option::None

See Also: starts_with, ends_with

floor

Signature: (Math -- Math)
Trait: Math
Description: Round number down to nearest integer.
Example:

3.14 floor   // Returns 3.0
-2.7 floor   // Returns -3.0

See Also: ceil, round

foldl

Signature: (ArrayOf<T> U TokenString -- U)
Description: Left fold array with accumulator function.
Example:

[1 2 3 4] 0 { + } foldl  // Returns 10

See Also: foldr, reduce

foldr

Signature: (ArrayOf<T> U TokenString -- U)
Description: Right fold array with accumulator function.
Example:

[1 2 3 4] 0 { + } foldr  // Returns 10

See Also: foldl, reduce

format

Signature: (String Iterable<Stringifiable> -- String)
Trait: String
Description: Format string with values, replacing %d, %s, %f placeholders.
Example:

"x=%d, y=%d" [5 10] format      // Returns "x=5, y=10"
"Hello %s" ["World"] format     // Returns "Hello World"

See Also: to_str, concat

implements

Signature: (Self Identifier -- bool)
Description: Check if value's type implements a specific trait.
Example:

42 ::Addable implements         // Returns true
"hello" ::String implements     // Returns true

See Also: type_of, assert

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 -- 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<T> TokenString -- ArrayOf<U>)
Description: Transform each element with function.
Example:

[1 2 3 4] { 2 * } map  // Returns [2 4 6 8]

See Also: filter, reduce, each

max

Signature: (Math Math -- Math)
Trait: Math
Description: Return the maximum of two values.
Example:

3 5 max      // Returns 5
-2 1 max     // Returns 1

See Also: min, abs

mean

Signature: (ArrayOf<Number> -- f64)
Description: Calculate the average of numeric array elements.
Example:

[1 2 3 4 5] mean  // Returns 3.0

See Also: sum, reduce

min

Signature: (Math Math -- Math)
Trait: Math
Description: Return the minimum of two values.
Example:

3 5 min      // Returns 3
-2 1 min     // Returns -2

See Also: max, abs

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

rand

Signature: (-- f64)
Description: Generate random f64 in range [0.0, 1.0).
Example:

rand         // Returns 0.7234... (random value)
100 rand *   // Random value 0.0-99.999...

See Also: seed

read

Signature: (String -- String)
Description: Read file contents as string.
Example:

"file.txt" read  // Returns file contents

See Also: write

reduce

Signature: (ArrayOf<T> T TokenString -- T)
Description: Fold array with accumulator function.
Example:

[1 2 3 4] 0 { + } reduce  // Returns 10

See Also: map, filter, foldl

replace

Signature: (String String String -- String)
Trait: String
Description: Replace all occurrences of substring with replacement.
Example:

"hello world" "world" "Stack" replace  // Returns "hello Stack"

See Also: split, concat

reverse

Signature: (ArrayOf<T> -- ArrayOf<T>)
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

round

Signature: (Math -- Math)
Trait: Math
Description: Round number to nearest integer.
Example:

3.14 round   // Returns 3.0
3.7 round    // Returns 4.0

See Also: floor, ceil

seed

Signature: (u64 --)
Description: Seed the random number generator with specific value.
Example:

12345 seed   // Seed RNG for deterministic results
rand         // Returns deterministic value

See Also: rand

sin

Signature: (Math -- Math)
Trait: Math
Description: Calculate sine of angle in radians.
Example:

0.0 sin      // Returns 0.0
1.5708 sin   // Returns ~1.0 (pi/2)

See Also: cos, tan, asin

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<String>)
Trait: String
Description: Split string by delimiter.
Example:

"a,b,c" "," split  // Returns ["a" "b" "c"]

See Also: join, substr

sqrt

Signature: (Math -- Math)
Trait: Math
Description: Calculate square root.
Example:

16 sqrt      // Returns 4.0
2.0 sqrt     // Returns ~1.414

See Also: ^

starts_with

Signature: (String String -- bool)
Trait: String
Description: Check if string starts with given prefix.
Example:

"hello" "hel" starts_with   // Returns true
"hello" "lo" starts_with    // Returns false

See Also: ends_with, find

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

sum

Signature: (ArrayOf<Number> -- Number)
Description: Sum all numeric elements in array.
Example:

[1 2 3 4 5] sum  // Returns 15

See Also: mean, reduce

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

tan

Signature: (Math -- Math)
Trait: Math
Description: Calculate tangent of angle in radians.
Example:

0.0 tan      // Returns 0.0
0.7854 tan   // Returns ~1.0 (pi/4)

See Also: sin, cos, atan

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_i8, to_i16, to_i32, to_i64, to_u8, to_u16, to_u32, to_u64

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_u8, to_u16, to_u32, to_u64, to_f32, 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_i8, to_i16, to_i32, to_i64, to_f32, to_f64

transpose

Signature: (ArrayOf<ArrayOf<T>> -- ArrayOf<ArrayOf<T>>)
Description: Transpose a 2D array (swap rows and columns).
Example:

[[1 2] [3 4]] transpose  // Returns [[1 3] [2 4]]

See Also: reverse

trim

Signature: (String -- String)
Trait: String
Description: Remove leading and trailing whitespace.
Example:

"  hello  " trim  // Returns "hello"

See Also: split, replace

type_of

Signature: (Self -- Identifier)
Description: Return the type of a value as an identifier literal.
Example:

42 type_of           // Returns ::i64
"hello" type_of      // Returns ::String

See Also: implements, assert

window

Signature: (ArrayOf<T> Size -- ArrayOf<ArrayOf<T>>)
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

zip

Signature: (ArrayOf<T> ArrayOf<U> -- ArrayOf<Pair<T U>>)
Description: Combine two arrays element-wise into pairs.
Example:

[1 2 3] [4 5 6] zip  // Returns [[1 4] [2 5] [3 6]]

See Also: enumerate, map

Appendix B: Complete Trait Reference

This appendix contains all built-in trait definitions with complete documentation, organized alphabetically.

Trait List

Addable

Generic Parameters: None
Inherits: None

Definition:

{
    (Self Self -- Self) +:
    (Self Self -- Self) -:
} ::Addable trait

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, Math

See Also: Section 4.2 (Arithmetic Operators)

ArrayOf

Generic Parameters: T (element type)
Inherits: Sized, Selectable, Sliceable

Definition:

[ ::Sized ::Selectable<T> ::Sliceable ] ::ArrayOf<T> inher
{ } ::ArrayOf<T> trait

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:

{
    (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

Methods: Provides explicit type conversion methods to all numeric types.

Standard Implementations: All numeric types

Related Traits: Stringifiable, Parseable, Size

See Also: Section 11.5 (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, Math

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> 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> 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<T>) next:
} ::Iterable<T> trait

Methods:

next:

Signature: (Self -- Self Option<T>)
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, Math

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)

Math

Generic Parameters: None
Inherits: None

Definition:

{
    (Self -- Self) sqrt:
    (Self -- Self) abs:
    (Self -- Self) sin:
    (Self -- Self) cos:
    (Self -- Self) tan:
    (Self -- Self) asin:
    (Self -- Self) acos:
    (Self -- Self) atan:
    (Self Self -- Self) atan2:
    (Self -- Self) floor:
    (Self -- Self) ceil:
    (Self -- Self) round:
    (Self Self -- Self) min:
    (Self Self -- Self) max:
} ::Math trait

Methods:

sqrt:

Signature: (Self -- Self)
Description: Calculate square root.
Example: 16 sqrt // => 4.0

abs:

Signature: (Self -- Self)
Description: Return absolute value.
Example: -42 abs // => 42

sin:

Signature: (Self -- Self)
Description: Calculate sine (radians).
Example: 0.0 sin // => 0.0

cos:

Signature: (Self -- Self)
Description: Calculate cosine (radians).
Example: 0.0 cos // => 1.0

tan:

Signature: (Self -- Self)
Description: Calculate tangent (radians).
Example: 0.0 tan // => 0.0

asin:

Signature: (Self -- Self)
Description: Calculate arc sine (radians).
Example: 1.0 asin // => ~1.5708

acos:

Signature: (Self -- Self)
Description: Calculate arc cosine (radians).
Example: 1.0 acos // => 0.0

atan:

Signature: (Self -- Self)
Description: Calculate arc tangent (radians).
Example: 1.0 atan // => ~0.7854

atan2:

Signature: (Self Self -- Self)
Description: Two-argument arc tangent.
Example: 1.0 1.0 atan2 // => ~0.7854

floor:

Signature: (Self -- Self)
Description: Round down to nearest integer.
Example: 3.14 floor // => 3.0

ceil:

Signature: (Self -- Self)
Description: Round up to nearest integer.
Example: 3.14 ceil // => 4.0

round:

Signature: (Self -- Self)
Description: Round to nearest integer.
Example: 3.7 round // => 4.0

min:

Signature: (Self Self -- Self)
Description: Return minimum of two values.
Example: 3 5 min // => 3

max:

Signature: (Self Self -- Self)
Description: Return maximum of two values.
Example: 3 5 max // => 5

Standard Implementations: Numeric types (especially floating point)

Related Traits: Number, Addable, Multiplyable, Exponentiable, Logarithmic

See Also: Section 4.2 (Arithmetic Operators), Section 4.6 (Randomness)

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, Math

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, Math

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:

{
    (String -- Self) parse:
} ::Parseable trait

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<T> 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:

[ ::Addable ::Comparable ::Convertible ] ::Size inher
{ } ::Size trait

Description: Represents types suitable for indexing and sizing 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
{
    (Self Size Size -- Self) substr:
    (Self Self -- ArrayOf<Self>) split:
    (Self Self String -- Self) replace:
    (Self -- Self) trim:
    (Self Self -- Option<Size>) find:
    (Self Self -- bool) starts_with:
    (Self Self -- bool) ends_with:
} ::String trait

Methods:

substr:

Signature: (Self Size Size -- Self)
Description: Extract substring from start to end index.
Example: "hello" 1 3 substr // => "el"

split:

Signature: (Self Self -- ArrayOf<Self>)
Description: Split string by delimiter.
Example: "a,b,c" "," split // => ["a" "b" "c"]

replace:

Signature: (Self Self String -- Self)
Description: Replace all occurrences of substring.
Example: "hello world" "world" "Stack" replace // => "hello Stack"

trim:

Signature: (Self -- Self)
Description: Remove leading and trailing whitespace.
Example: " hello " trim // => "hello"

find:

Signature: (Self Self -- Option<Size>)
Description: Find position of substring.
Example: "hello world" "world" find // => Option::Some(6)

starts_with:

Signature: (Self Self -- bool)
Description: Check if string starts with prefix.
Example: "hello" "hel" starts_with // => true

ends_with:

Signature: (Self Self -- bool)
Description: Check if string ends with suffix.
Example: "hello" "lo" ends_with // => true

Standard Implementations: String type

Related Traits: Concatenable, Sized, Sliceable

See Also: Section 11.5 (String Operations)

Stringifiable

Generic Parameters: None
Inherits: None

Definition:

{
    (Self -- String) to_str:
} ::Stringifiable trait

Methods:

to_str:

Signature: (Self -- String)
Description: Convert value to string representation.
Example: 42 to_str // => "42"

Standard Implementations: All types

Related Traits: Parseable, Convertible

See Also: Section 11.5 (Type Conversion)

Appendix C: Complete Operator Reference

This appendix provides a complete alphabetical reference of all operators in the language.

Operator List

!=, %, *, +, -, /, <, <=, ==, >, >=, ^, abs, acos, asin, assert, at, atan, atan2, bitand, bitnot, bitor, bitxor, break, ceil, concat, continue, cos, depth, drop, dup, each, ends_with, enum, enumerate, eval, filter, find, floor, foldl, foldr, for, format, get, if, impl, implements, inher, lambda, length, ln, log, logb, map, match, max, mean, min, not, or, over, pick, rand, reduce, replace, reverse, roll, rot, round, seed, set, shl, shr, sin, slice, split, sqrt, starts_with, struct, substr, sum, swap, tan, trait, transpose, trim, type_of, union, while, window, zip

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, sqrt
Section: 4.2 (Arithmetic Operators)

abs

Operator Type: Mathematical
Signature: (Math -- Math)
Trait: Math
Description: Return absolute value of number.
Example: -42 abs // => 42
See Also: min, max
Section: 4.2 (Arithmetic Operators)

acos

Operator Type: Mathematical
Signature: (Math -- Math)
Trait: Math
Description: Calculate arc cosine in radians.
Example: 1.0 acos // => 0.0
See Also: cos, asin, atan
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)

asin

Operator Type: Mathematical
Signature: (Math -- Math)
Trait: Math
Description: Calculate arc sine in radians.
Example: 1.0 asin // => ~1.5708
See Also: sin, acos, atan
Section: 4.2 (Arithmetic Operators)

assert

Operator Type: Testing
Signature: (TokenString TokenString --)
Description: Evaluate expression and condition, halt if condition is false.
Example: { 2 3 + } { 5 == } assert
See Also: type_of, implements
Section: 11.3 (Testing and Assertions)

at

Operator Type: Container Access
Signature: (Selectable<T> 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)

atan

Operator Type: Mathematical
Signature: (Math -- Math)
Trait: Math
Description: Calculate arc tangent in radians.
Example: 1.0 atan // => ~0.7854
See Also: tan, atan2, asin
Section: 4.2 (Arithmetic Operators)

atan2

Operator Type: Mathematical
Signature: (Math Math -- Math)
Trait: Math
Description: Two-argument arc tangent using signs to determine quadrant.
Example: 1.0 1.0 atan2 // => ~0.7854
See Also: atan, tan
Section: 4.2 (Arithmetic Operators)

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)

ceil

Operator Type: Mathematical
Signature: (Math -- Math)
Trait: Math
Description: Round number up to nearest integer.
Example: 3.14 ceil // => 4.0
See Also: floor, round
Section: 4.2 (Arithmetic Operators)

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)

cos

Operator Type: Mathematical
Signature: (Math -- Math)
Trait: Math
Description: Calculate cosine of angle in radians.
Example: 0.0 cos // => 1.0
See Also: sin, tan, acos
Section: 4.2 (Arithmetic Operators)

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<T> TokenString --)
Description: Apply function to each element (side effects).
Example: [1 2 3] { print } each
See Also: map, filter, reduce
Section: 7.4 (Arrays)

ends_with

Operator Type: String
Signature: (String String -- bool)
Trait: String
Description: Check if string ends with given suffix.
Example: "hello" "lo" ends_with // => true
See Also: starts_with, find
Section: 11.5 (String Operations)

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)

enumerate

Operator Type: Array
Signature: (ArrayOf<T> -- ArrayOf<Pair<Size T>>)
Description: Add indices to array elements.
Example: ["a" "b" "c"] enumerate // => [[0 "a"] [1 "b"] [2 "c"]]
See Also: zip, map
Section: 7.4 (Arrays)

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<T> TokenString -- ArrayOf<T>)
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)

find

Operator Type: String
Signature: (String String -- Option<Size>)
Trait: String
Description: Find position of substring.
Example: "hello world" "world" find // => Option::Some(6)
See Also: starts_with, ends_with
Section: 11.5 (String Operations)

floor

Operator Type: Mathematical
Signature: (Math -- Math)
Trait: Math
Description: Round number down to nearest integer.
Example: 3.14 floor // => 3.0
See Also: ceil, round
Section: 4.2 (Arithmetic Operators)

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)

foldl

Operator Type: Array Combinator
Signature: (ArrayOf<T> U TokenString -- U)
Description: Left fold array with accumulator function.
Example: [1 2 3 4] 0 { + } foldl // => 10
See Also: foldr, reduce
Section: 7.4 (Arrays)

foldr

Operator Type: Array Combinator
Signature: (ArrayOf<T> U TokenString -- U)
Description: Right fold array with accumulator function.
Example: [1 2 3 4] 0 { + } foldr // => 10
See Also: foldl, reduce
Section: 7.4 (Arrays)

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)

format

Operator Type: String
Signature: (String Iterable<Stringifiable> -- String)
Trait: String
Description: Format string with values, replacing placeholders.
Example: "x=%d, y=%d" [5 10] format // => "x=5, y=10"
See Also: to_str, concat
Section: 11.5 (String Operations)

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)

implements

Operator Type: Reflection
Signature: (Self Identifier -- bool)
Description: Check if value's type implements a specific trait.
Example: 42 ::Addable implements // => true
See Also: type_of, assert
Section: 11.4 (Reflection)

inher

Operator Type: Definition
Signature: (ArrayOf<Identifier> 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<T> TokenString -- ArrayOf<U>)
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)

max

Operator Type: Mathematical
Signature: (Math Math -- Math)
Trait: Math
Description: Return the maximum of two values.
Example: 3 5 max // => 5
See Also: min, abs
Section: 4.2 (Arithmetic Operators)

mean

Operator Type: Array
Signature: (ArrayOf<Number> -- f64)
Description: Calculate average of numeric array elements.
Example: [1 2 3 4 5] mean // => 3.0
See Also: sum, reduce
Section: 7.4 (Arrays)

min

Operator Type: Mathematical
Signature: (Math Math -- Math)
Trait: Math
Description: Return the minimum of two values.
Example: 3 5 min // => 3
See Also: max, abs
Section: 4.2 (Arithmetic Operators)

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)

rand

Operator Type: Randomness
Signature: (-- f64)
Description: Generate random f64 in range [0.0, 1.0).
Example: rand // => 0.7234...
See Also: seed
Section: 4.6 (Randomness)

reduce

Operator Type: Array Combinator
Signature: (ArrayOf<T> T TokenString -- T)
Description: Fold array with accumulator function.
Example: [1 2 3 4] 0 { + } reduce // => 10
See Also: map, filter, foldl
Section: 7.4 (Arrays)

replace

Operator Type: String
Signature: (String String String -- String)
Trait: String
Description: Replace all occurrences of substring with replacement.
Example: "hello world" "world" "Stack" replace // => "hello Stack"
See Also: split, concat
Section: 11.5 (String Operations)

reverse

Operator Type: Array
Signature: (ArrayOf<T> -- ArrayOf<T>)
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)

round

Operator Type: Mathematical
Signature: (Math -- Math)
Trait: Math
Description: Round number to nearest integer.
Example: 3.7 round // => 4.0
See Also: floor, ceil
Section: 4.2 (Arithmetic Operators)

seed

Operator Type: Randomness
Signature: (u64 --)
Description: Seed the random number generator with specific value.
Example: 12345 seed
See Also: rand
Section: 4.6 (Randomness)

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)

sin

Operator Type: Mathematical
Signature: (Math -- Math)
Trait: Math
Description: Calculate sine of angle in radians.
Example: 0.0 sin // => 0.0
See Also: cos, tan, asin
Section: 4.2 (Arithmetic 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)

split

Operator Type: String
Signature: (String String -- ArrayOf<String>)
Trait: String
Description: Split string by delimiter.
Example: "a,b,c" "," split // => ["a" "b" "c"]
See Also: join, substr
Section: 11.5 (String Operations)

sqrt

Operator Type: Mathematical
Signature: (Math -- Math)
Trait: Math
Description: Calculate square root.
Example: 16 sqrt // => 4.0
See Also: ^
Section: 4.2 (Arithmetic Operators)

starts_with

Operator Type: String
Signature: (String String -- bool)
Trait: String
Description: Check if string starts with given prefix.
Example: "hello" "hel" starts_with // => true
See Also: ends_with, find
Section: 11.5 (String Operations)

struct

Operator Type: Definition
Signature: (TypeTuple TokenString Identifier --)
Trait: Implementable
Description: Define a struct type.
Example: (T T --) { x: y: } ::Point<T> 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.5 (String Operations)

sum

Operator Type: Array
Signature: (ArrayOf<Number> -- Number)
Description: Sum all numeric elements in array.
Example: [1 2 3 4 5] sum // => 15
See Also: mean, reduce
Section: 7.4 (Arrays)

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)

tan

Operator Type: Mathematical
Signature: (Math -- Math)
Trait: Math
Description: Calculate tangent of angle in radians.
Example: 0.0 tan // => 0.0
See Also: sin, cos, atan
Section: 4.2 (Arithmetic Operators)

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<T>> -- ArrayOf<ArrayOf<T>>)
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)

trim

Operator Type: String
Signature: (String -- String)
Trait: String
Description: Remove leading and trailing whitespace.
Example: " hello " trim // => "hello"
See Also: split, replace
Section: 11.5 (String Operations)

type_of

Operator Type: Reflection
Signature: (Self -- Identifier)
Description: Return the type of a value as an identifier literal.
Example: 42 type_of // => ::i64
See Also: implements, assert
Section: 11.4 (Reflection)

union

Operator Type: Definition
Signature: (TypeTuple TokenString Identifier --)
Trait: Implementable
Description: Define a union type with tagged variants.
Example: (T --) { Some(T) None } ::Option<T> 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<T> Size -- ArrayOf<ArrayOf<T>>)
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)

zip

Operator Type: Array
Signature: (ArrayOf<T> ArrayOf<U> -- ArrayOf<Pair<T U>>)
Description: Combine two arrays element-wise into pairs.
Example: [1 2 3] [4 5 6] zip // => [[1 4] [2 5] [3 6]]
See Also: enumerate, map
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 and Directives:

line_comment ::= "//" <any characters until newline>
directive ::= "#" <implementation-specific>
shebang ::= "#!/" <path to interpreter>

Identifiers:

identifier ::= [a-zA-Z_][a-zA-Z0-9_]*
identifier_literal ::= "::" identifier

Integer Literals:

integer ::= decimal | hexadecimal | binary | octal
decimal ::= [0-9](_?[0-9])* (":" type_name)?
hexadecimal ::= "0x" [0-9a-fA-F](_?[0-9a-fA-F])*
binary ::= "0b" [01](_?[01])*
octal ::= "0o" [0-7](_?[0-7])*

Floating Point Literals:

float ::= [0-9](_?[0-9])* "." [0-9](_?[0-9])* (":" type_name)?

Character Literals:

char ::= "'" (character | escape_sequence) "'"

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)* (":"|type_annotation)? "]"
typed_array ::= "[" (expression)* ":" type_name "]"

Constants:

constant ::= literal "::" identifier "const"

Token Strings:

token_string ::= "{" (token)* "}"

D.2 Expression Grammar

expression ::= literal 
             | identifier 
             | identifier_literal 
             | expression operator
             | control_flow
             | definition

literal ::= integer | float | string | boolean | char | 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:

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.

Future Design: A module system for organizing code and managing namespaces.

Proposed Syntax:

// Import entire module (using :: prefix)
::std::math use

// Import specific items
::std::collections::HashMap use

// Import with alias - Option 1: Inline alias
::std::io::File ::F as use

// Import with alias - Option 2: Separate alias operator
::std::io::File ::F use_as

// Import with alias - Option 3: Block syntax
{ ::std::io::File ::F as } use

// Export from current module
::Point ::geometry export
::distance ::geometry export

// Module declaration
::my_module module {
    // Module contents
}

Module Resolution:

Benefits:

Appendix F: Memory Management (Future)

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

// Dereference
ptr deref               // ( ptr<T> -- T )

// Store through pointer
new_value ptr store     // ( T ptr<T> -- )

// Free memory
ptr free                // ( ptr<T> -- )

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

// 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<Point> )

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

Testing Framework (Future):

Current State: Basic assert operator is available for inline testing.

Future Design: A comprehensive testing framework with dedicated operators.

Proposed Operators:

// Define a test
{ { 2 3 + } { 5 == } assert } "addition test" test

// Test for expected errors
{ 1 0 / } "division by zero test" test_error

// Test suites
{ 
    { 2 3 + 5 == } "addition" test
    { 5 2 - 3 == } "subtraction" test
} "arithmetic tests" test_suite

Features:

Documentation Comments (Future):

Proposed Syntax:

/// Calculates the square of a number.
/// Takes a number and returns its square.
(Number -- Number) { dup * } ::square fn

/// A point in 2D space.
/// Fields:
///   x: The x-coordinate
///   y: The y-coordinate
(T T --) { x: y: } ::Point<T> struct

Features:

Advanced Compiler Directives (Future):

Beyond the basic shebang, future versions may support:

#require "0.9.0"          // Minimum language version
#optimize speed            // Optimization hints
#allow unsafe              // Enable unsafe operations
#deprecated "Use new_fn"   // Deprecation warnings

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:

// 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<T U> struct

// Use with different types
5 "hello" Pair                         // Pair<i64, String>
3.14 true Pair                         // Pair<f64, bool>

// 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<T> union

42 Option::Some                        // Option<i64>::Some
Option::None                           // Option<T>::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

{
    (Self Self -- Self) *:
    (Self Self -- Self) /:
} ::Multiplyable trait

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

G.4.3 Mathematical Functions Usage

// Square root
16 sqrt print       // => 4.0
2.0 sqrt print      // => ~1.414

// Trigonometric functions
0.0 sin print       // => 0.0
0.0 cos print       // => 1.0
1.0 atan print      // => ~0.7854

// Rounding functions
3.14 floor print    // => 3.0
3.14 ceil print     // => 4.0
3.7 round print     // => 4.0

// Min/max
3 5 min print       // => 3
3 5 max print       // => 5

// Absolute value
-42 abs print       // => 42

// Random numbers
rand print          // => 0.7234... (random)
12345 seed          // Seed for deterministic results
rand print          // => 0.4321... (deterministic after seed)

G.4.4 Factorial

(Number -- Number) {
    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
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

G.4.5 FizzBuzz

(Number -- ) {
    dup 15 % 0 ==
        { drop "FizzBuzz" print }
        {
            dup 3 % 0 ==
                { drop "Fizz" print }
                {
                    dup 5 % 0 ==
                        { drop "Buzz" print }
                        { print }
                    if
                }
            if
        }
    if
} ::fizzbuzz fn

// Print FizzBuzz for 1 to 100
1 100 { fizzbuzz } for

G.4.6 Using Roll

// Roll rotates the top n items, times times
// Stack: 1 2 3 4 5

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

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: [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

// Or use built-in functions
[10 20 30 40 50] mean print           // => 30.0
[1 2 3 4 5] sum print                 // => 15

// Zip and enumerate
[1 2 3] [4 5 6] zip print             // => [[1 4] [2 5] [3 6]]
["a" "b" "c"] enumerate print         // => [[0 "a"] [1 "b"] [2 "c"]]

G.4.8 String Operations

// String manipulation
"hello" " world" concat print         // => "hello world"
"hello" 1 3 substr print              // => "el"
"a,b,c" "," split print               // => ["a" "b" "c"]
["a" "b" "c"] "," join print          // => "a,b,c"

// String searching
"hello world" "world" find            // => Option::Some(6)
"hello" "hel" starts_with print       // => true
"hello" "lo" ends_with print          // => true

// String modification
"hello world" "world" "Stack" replace print  // => "hello Stack"
"  hello  " trim print                       // => "hello"

// String formatting
"x=%d, y=%d" [5 10] format print     // => "x=5, y=10"
"Name: %s, Age: %d" ["Alice" 30] format print  // => "Name: Alice, Age: 30"

G.4.9 Reflection Examples

// Type checking
(Self -- ) {
    dup type_of to_str "Type: " swap concat print

    dup ::Addable implements
        { "Supports addition" print }
        { "Does not support addition" print }
    if

    dup ::Stringifiable implements
        { to_str print }
        { drop "Cannot convert to string" print }
    if
} ::debug_print fn

42 debug_print
// Output:
// Type: i64
// Supports addition
// 42

// Dynamic dispatch based on traits
(Self -- ) {
    dup ::Drawable implements
        { draw }
        { drop "Not drawable" print }
    if
} ::try_draw fn

// Generic type information
(Self -- String) {
    type_of to_str
} ::type_name fn

42 type_name print           // => "i64"
"hello" type_name print      // => "String"
[1 2 3] type_name print      // => "Array<i64>"

G.4.10 Testing Examples

// Simple assertions
{ 2 3 + } { 5 == } assert
{ 5 square } { 25 == } assert

// Testing a function thoroughly
(Number -- Number) { dup * } ::square fn

// Test with multiple values
{ 0 square } { 0 == } assert
{ 1 square } { 1 == } assert
{ 5 square } { 25 == } assert
{ -3 square } { 9 == } assert

// Testing edge cases
(Number Number -- Number) { / } ::divide fn

// This will pass
{ 10 2 divide } { 5 == } assert

// This will halt (division by zero should be handled)
// { 10 0 divide } { ... } assert  // Don't do this!

// Testing string operations
{ "hello" " world" concat } { "hello world" == } assert
{ "hello" length } { 5 == } assert
{ "hello" 1 3 substr } { "el" == } assert

G.4.11 Constants Example

// Define mathematical constants
3.1415926535 ::pi const
2.7182818284 ::e const
1.6180339887 ::phi const

// Use in calculations
(Number -- Number) {
    dup * pi *                         // Area = r² * π
} ::circle_area fn

5 circle_area print                    // => ~78.54

// Physical constants
299792458 ::speed_of_light const       // m/s
9.81 ::gravity const                   // m/s²

// Use in physics calculations
(Number -- Number) {
    dup * 2 / gravity *                // E = mgh where h = v²/2g
} ::kinetic_to_potential fn

10 kinetic_to_potential print          // => ~490.5

Appendix H: Complete Type Reference

This appendix provides detailed information about all types in the language, organized alphabetically.

Primitive Types

bool

Description: Boolean value representing true or false.
Size: 1 byte
Values: true, false
Default: false
Traits Implemented: Stackable, Equatable, Logical, Stringifiable
Conversions: to_str
Example:

true
false
5 3 > // => true

char

Description: Single UTF-8 character.
Size: 4 bytes (Unicode code point)
Values: Any valid Unicode character
Literals: 'A', '\n', '\u{1F600}'
Traits Implemented: Stackable, Equatable, Orderable, Comparable, Stringifiable
Conversions: to_str
Example:

'A'
'😀'
'\n'

f32

Description: 32-bit floating point number (IEEE 754 single precision).
Size: 4 bytes
Range: ±1.18e-38 to ±3.40e+38
Precision: ~7 decimal digits
Default: 0.0
Traits Implemented: Stackable, Addable, Multiplyable, Exponentiable, Logarithmic, Math, Orderable, Equatable, Comparable, Number, Convertible, Stringifiable, Parseable
Conversions: to_i8, to_i16, to_i32, to_i64, to_u8, to_u16, to_u32, to_u64, to_f64, to_str
Overflow Behavior: IEEE 754 (infinity/NaN)
Example:

3.14:f32
1.0:f32 2.0:f32 +

f64

Description: 64-bit floating point number (IEEE 754 double precision).
Size: 8 bytes
Range: ±2.23e-308 to ±1.80e+308
Precision: ~15 decimal digits
Default: 0.0 (default float type)
Traits Implemented: Stackable, Addable, Multiplyable, Exponentiable, Logarithmic, Math, Orderable, Equatable, Comparable, Number, Convertible, Stringifiable, Parseable
Conversions: to_i8, to_i16, to_i32, to_i64, to_u8, to_u16, to_u32, to_u64, to_f32, to_str
Overflow Behavior: IEEE 754 (infinity/NaN)
Example:

3.14
1.0 2.0 +

i8

Description: 8-bit signed integer.
Size: 1 byte
Range: -128 to 127
Default: 0
Traits Implemented: Stackable, Addable, Multiplyable, Exponentiable, Logarithmic, Math, Orderable, Equatable, Comparable, Bitwise, Number, Size, Convertible, Stringifiable, Parseable
Conversions: to_i16, to_i32, to_i64, to_u8, to_u16, to_u32, to_u64, to_f32, to_f64, to_str
Overflow Behavior: Wrapping
Example:

42:i8
127:i8 1:i8 + // => -128 (wraps)

i16

Description: 16-bit signed integer.
Size: 2 bytes
Range: -32,768 to 32,767
Default: 0
Traits Implemented: Stackable, Addable, Multiplyable, Exponentiable, Logarithmic, Math, Orderable, Equatable, Comparable, Bitwise, Number, Size, Convertible, Stringifiable, Parseable
Conversions: to_i8, to_i32, to_i64, to_u8, to_u16, to_u32, to_u64, to_f32, to_f64, to_str
Overflow Behavior: Wrapping
Example:

1000:i16

i32

Description: 32-bit signed integer.
Size: 4 bytes
Range: -2,147,483,648 to 2,147,483,647
Default: 0
Traits Implemented: Stackable, Addable, Multiplyable, Exponentiable, Logarithmic, Math, Orderable, Equatable, Comparable, Bitwise, Number, Size, Convertible, Stringifiable, Parseable
Conversions: to_i8, to_i16, to_i64, to_u8, to_u16, to_u32, to_u64, to_f32, to_f64, to_str
Overflow Behavior: Wrapping
Example:

1000000:i32

i64

Description: 64-bit signed integer.
Size: 8 bytes
Range: -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807
Default: 0 (default integer type)
Traits Implemented: Stackable, Addable, Multiplyable, Exponentiable, Logarithmic, Math, Orderable, Equatable, Comparable, Bitwise, Number, Size, Convertible, Stringifiable, Parseable
Conversions: to_i8, to_i16, to_i32, to_u8, to_u16, to_u32, to_u64, to_f32, to_f64, to_str
Overflow Behavior: Wrapping
Example:

42
1000000000

u8

Description: 8-bit unsigned integer.
Size: 1 byte
Range: 0 to 255
Default: 0
Traits Implemented: Stackable, Addable, Multiplyable, Exponentiable, Logarithmic, Math, Orderable, Equatable, Comparable, Bitwise, Number, Size, Convertible, Stringifiable, Parseable
Conversions: to_i8, to_i16, to_i32, to_i64, to_u16, to_u32, to_u64, to_f32, to_f64, to_str
Overflow Behavior: Wrapping
Example:

255:u8

u16

Description: 16-bit unsigned integer.
Size: 2 bytes
Range: 0 to 65,535
Default: 0
Traits Implemented: Stackable, Addable, Multiplyable, Exponentiable, Logarithmic, Math, Orderable, Equatable, Comparable, Bitwise, Number, Size, Convertible, Stringifiable, Parseable
Conversions: to_i8, to_i16, to_i32, to_i64, to_u8, to_u32, to_u64, to_f32, to_f64, to_str
Overflow Behavior: Wrapping
Example:

65535:u16

u32

Description: 32-bit unsigned integer.
Size: 4 bytes
Range: 0 to 4,294,967,295
Default: 0
Traits Implemented: Stackable, Addable, Multiplyable, Exponentiable, Logarithmic, Math, Orderable, Equatable, Comparable, Bitwise, Number, Size, Convertible, Stringifiable, Parseable
Conversions: to_i8, to_i16, to_i32, to_i64, to_u8, to_u16, to_u64, to_f32, to_f64, to_str
Overflow Behavior: Wrapping
Example:

4000000000:u32

u64

Description: 64-bit unsigned integer.
Size: 8 bytes
Range: 0 to 18,446,744,073,709,551,615
Default: 0
Traits Implemented: Stackable, Addable, Multiplyable, Exponentiable, Logarithmic, Math, Orderable, Equatable, Comparable, Bitwise, Number, Size, Convertible, Stringifiable, Parseable
Conversions: to_i8, to_i16, to_i32, to_i64, to_u8, to_u16, to_u32, to_f32, to_f64, to_str
Overflow Behavior: Wrapping
Example:

18000000000000000000:u64

Composite Types

Array

Description: Homogeneous collection of values of type T.
Size: Variable (depends on length and element type)
Syntax: [elements] or [elements :type]
Traits Implemented: Stackable, ArrayOf, Sized, Selectable, Sliceable, Iterable, Concatenable, Equatable, Stringifiable
Operations: at, slice, length, map, filter, reduce, each, foldl, foldr, concat, reverse, transpose, window, zip, enumerate, sum, mean
Example:

[1 2 3 4 5]
[1.0 2.0 3.0 :f32]
[[1 2] [3 4]]

String

Description: UTF-8 encoded string of characters.
Size: Variable
Syntax: "text"
Traits Implemented: Stackable, String, Sized, Sliceable, Concatenable, Iterable, Orderable, Equatable, Comparable, Stringifiable, Parseable
Operations: length, concat, substr, split, join, replace, trim, find, starts_with, ends_with, format
Example:

"hello world"
"hello" " world" concat

Struct

Description: User-defined composite type with named fields.
Size: Sum of field sizes
Syntax: (field_types --) { field_names: } ::Name<T>? struct
Traits Implemented: Stackable, Equatable (if fields are), Stringifiable (if fields are)
Operations: get, set (field access)
Example:

(Number Number --) { x: y: } ::Point struct
3.0 4.0 Point
point ::x get

Union

Description: Tagged union with multiple possible variant types.
Size: Size of largest variant plus tag
Syntax: (variant_types --) { variants } ::Name<T>? union
Traits Implemented: Stackable, Equatable (if variants are), Stringifiable (if variants are)
Operations: Pattern matching with match
Example:

(T --) { Some(T) None } ::Option<T> union
42 Option::Some
Option::None

Enum

Description: Fixed set of named integer values.
Size: Size of underlying integer type (typically i64)
Syntax: { variants } ::Name enum
Traits Implemented: Stackable, Equatable, Orderable, Comparable, Convertible, Stringifiable
Operations: Pattern matching, comparison
Example:

{ Pending: Active: Complete: } ::Status enum
Status::Active

Standard Generic Types

Option

Description: Represents an optional value - either Some(T) or None.
Definition: (T --) { Some(T) None } ::Option<T> union
Use Cases: Nullable values, error handling, optional parameters
Traits Implemented: Stackable, Logical (None is falsy), Equatable, Stringifiable
Example:

42 Option::Some
Option::None

opt {
    Some(x) => { x print }
    None => { "Nothing" print }
} match

Result

Description: Represents success (Ok) or failure (Err) with values.
Definition: (T E --) { Ok(T) Err(E) } ::Result<T E> union
Use Cases: Error handling with details, operations that can fail
Traits Implemented: Stackable, Logical (Err is falsy), Equatable, Stringifiable
Example:

"success" Result::Ok
"error message" Result::Err

result {
    Ok(val) => { val process }
    Err(e) => { e "Error: " swap concat print }
} match

Special Types

Identifier

Description: Represents an identifier literal (name pushed as value).
Syntax: ::name
Traits Implemented: Identifier, Stackable, Equatable, Stringifiable
Use Cases: Struct/trait definitions, field access, meta-programming
Example:

::Point
::Addable
point ::x get

TokenString

Description: Unparsed code block enclosed in braces.
Syntax: { code }
Traits Implemented: Implementable
Use Cases: Function bodies, control flow blocks, lambda expressions
Example:

{ dup * }
{ 2 3 + } eval

Callable

Description: Executable code block created by lambda operator.
Created By: lambda operator
Traits Implemented: Stackable
Use Cases: First-class functions, higher-order operations
Example:

{ dup * } lambda ::square swap
5 square eval // => 25