15 KiB
15 KiB
Stack Language Specification v0.2
1. Overview
A statically-typed, stack-based language with pure postfix notation combining the execution model of HP's RPL, the type system of C and Rust, and modern array operations from Uiua.
Design Principles
- Everything is postfix - no exceptions
- Stack-based execution (no local variables)
- Static typing with type inference
- Manual heap memory management
- Types define what things are, traits define how things act
- All constructs are implicitly generic
2. Lexical Structure
2.1 Comments
// Single-line comment
2.2 Identifiers
- Start with letter or underscore:
[a-zA-Z_][a-zA-Z0-9_]* - Case-sensitive
2.3 Literals
Integer Literals
42 // i32 (default)
42 i64 // Annotate as i64
0xFF // hexadecimal
0b1010 // binary
Floating Point Literals
3.14 // f64 (default)
3.14 f32 // Annotate as f32
String Literals
"hello world"
"escape sequences: \n \t \\ \""
Boolean Literals
true
false
Array Literals
[1 2 3 4 5] // array of i32
[1.0 2.0 3.0] // array of f64
[[1 2] [3 4]] // 2D array
3. Type System
3.1 Primitive Types
i8,i16,i32,i64- Signed integersu8,u16,u32,u64- Unsigned integersf32,f64- Floating pointbool- Booleanchar- Single character (UTF-8)ptr- Raw pointer (generic over pointed type)
3.2 Types vs Traits
Types define the concrete structure and memory layout:
Point struct // Point is a type
Rectangle struct // Rectangle is a type
Traits define behavioral contracts - how things act:
Drawable trait // Drawable is a trait
Addable trait // Addable is a trait
Key Distinction:
- A value has a type (what it is structurally)
- A value implements a trait (how it behaves)
- Types are concrete; traits are interfaces
- Functions can be generic over both types and traits
3.3 All Constructs are Generic
Every function, struct, and union is implicitly generic. Constraints are specified via traits:
// Function generic over any type T
(T -- T) { dup * } square fn
// Function requiring T to implement Addable trait
(T T -- T) Addable { + } add_two fn
// Struct generic over field types
(T T --) { x: y: } Point struct
// Union generic over variant types
(T --) { Some(T) None } Option union
4. Stack Operations
4.1 Stack Manipulation
dup // ( a -- a a ) Duplicate top
drop // ( a -- ) Remove top
swap // ( a b -- b a ) Swap top two
over // ( a b -- a b a ) Copy second to top
rot // ( a b c -- b c a ) Rotate three items
-rot // ( a b c -- c a b ) Rotate three items reverse
2dup // ( a b -- a b a b ) Duplicate top two
2drop // ( a b -- ) Drop top two
nip // ( a b -- b ) Drop second
tuck // ( a b -- b a b ) Copy top below second
4.2 Stack Inspection
depth // ( -- n ) Push stack depth
pick // ( n -- x ) Copy nth item to top (0 = top)
roll // ( n -- ) Move nth item to top
5. Operators (Postfix)
5.1 Arithmetic
3 4 + // ( a b -- result ) Addition
10 3 - // Subtraction
5 6 * // Multiplication
20 4 / // Division
17 5 % // Modulo
2 8 ** // Exponentiation
5.2 Comparison
5 3 > // Greater than
5 3 >= // Greater or equal
5 3 < // Less than
5 3 <= // Less or equal
5 5 == // Equal
5 3 != // Not equal
5.3 Logical
true false and // Logical AND
true false or // Logical OR
true not // Logical NOT
5.4 Bitwise
0xFF 0x0F bitand // Bitwise AND
0xFF 0x0F bitor // Bitwise OR
0xFF 0x0F bitxor // Bitwise XOR
0xFF bitnot // Bitwise NOT
8 2 shl // Left shift
8 2 shr // Right shift
6. Functions (Postfix Definition)
Functions are defined in postfix notation. The signature and body come before the name.
6.1 Basic Function Definition
Syntax: (inputs -- outputs) { body } name fn
// Define a square function
(i32 -- i32) { dup * } square fn
// Use it
5 square // 25
// Multiple inputs and outputs
(i32 i32 -- i32 i32) {
2dup / -rot %
} divmod fn
10 3 divmod // 3 1 (quotient remainder)
6.2 Generic Functions with Trait Constraints
Syntax: (type_sig) trait_constraints { body } name fn
// Generic identity - works with any type
(T -- T) {} identity fn
// Requires T to be copyable
(T T -- T) Addable {
+
} add_values fn
// Multiple trait constraints
(T U -- U T) Copyable Swappable {
swap
} swap_generic fn
// Multiple type parameters with different traits
(T U -- T) Addable Numeric {
dup U as +
} add_converted fn
6.3 Function Examples
// No-op function
(-- ) {} noop fn
// Factorial (recursive)
(i32 -- i32) {
dup 1 { drop 1 } { dup 1 - factorial * } <= if
} factorial fn
// Constrained generic
(T -- T) Numeric {
dup 0 > { } { 0 T as - } if
} abs fn
7. Control Flow (Postfix)
7.1 Conditionals
Syntax: condition { then-block } { else-block } if
// if-then (else block is empty)
x 0 > { "positive" print } {} if
// if-then-else
x 0 >
{ "positive" print }
{ "non-positive" print }
if
// The condition comes first, then both blocks, then 'if'
a b >
{ a }
{ b }
if max set
// Nested
x 0 >
{
y 0 >
{ "both positive" print }
{ "x positive, y not" print }
if
}
{ "x not positive" print }
if
7.2 Loops
While Loop
Syntax: { condition-block } { body-block } while
// Sum 1 to 10
0 1 // sum counter
{ dup 10 <= } // condition block
{ // body block
2dup + // Add counter to sum
swap 1 + swap // Increment counter
}
while
drop // Drop counter, leave sum
// Infinite loop with break
{ true } {
// body
condition { break } {} if
} while
For Loop
Syntax: start end { body-with-counter } for
// The loop variable is implicitly pushed to stack in each iteration
1 10 {
// Stack has loop counter on top
dup print
} for
// More complex
1 100 {
dup fizzbuzz
} for
7.3 Loop Control
break // Exit loop
continue // Skip to next iteration
7.4 Match/Pattern Matching
Syntax: value { pattern => block ... } match
value {
Some(x) => { x print }
None => { "Nothing" print }
} match
// With multiple patterns
status {
Pending => { "Waiting" print }
Active => { "Running" print }
Complete => { "Done" print }
} match
8. Data Structures (Postfix)
8.1 Struct Definition
Syntax: (field_types -- ) { field_names } name struct
// Define Point struct - generic over coordinate types
(T T --) { x: y: } Point struct
// Use with specific types
3.0 4.0 Point // Creates Point with f64 fields
3 4 Point // Creates Point with i32 fields
// More complex struct
(T U V --) {
width:
height:
depth:
} Box3D struct
10.0 20.0 30.0 Box3D
8.2 Struct Field Access
Syntax (postfix): struct field get or struct value field set
point x get // Get x field
point 15.0 x set // Set x field to 15.0
// Chaining
point x get 2 * y get + // (point.x * 2) + point.y
8.3 Union Definition
Syntax: (variant_types -- ) { variants } name union
// Option type - generic over T
(T --) {
Some(T)
None
} Option union
// Result type - generic over T and E
(T E --) {
Ok(T)
Err(E)
} Result union
// Create union values
42 Some // Creates Option::Some(42)
None // Creates Option::None
"success" Ok // Creates Result::Ok("success")
"error" Err // Creates Result::Err("error")
8.4 Enum Definition
Syntax: () { variants } name enum
() {
Pending
Active
Complete
} Status enum
// Usage
Pending // Creates Status::Pending
Active // Creates Status::Active
9. Traits (Postfix)
9.1 Trait Definition
Syntax: { function_signatures } name trait
// Simple trait
{
(Self -- ) draw:
} Drawable trait
// Trait with multiple methods
{
(Self Self -- Self) add:
(Self Self -- Self) sub:
(Self -- Self) neg:
} Numeric trait
// Generic trait
{
(Self T -- Self) append:
(Self -- T) pop:
} Container trait
9.2 Trait Implementation
Syntax: type { method_implementations } trait impl
// Implement Drawable for Rectangle
Rectangle {
(Rectangle -- ) {
"Drawing rectangle" print
dup width get print
height get print
} draw:
} Drawable impl
// Implement Numeric for Point
Point {
(Point Point -- Point) {
over x get over x get +
-rot y get swap y get +
Point
} add:
(Point Point -- Point) {
over x get over x get -
-rot y get swap y get -
Point
} sub:
(Point -- Point) {
dup x get 0 swap - x set
dup y get 0 swap - y set
} neg:
} Numeric impl
9.3 Using Traits in Functions
// Function requiring Drawable trait
(T -- ) Drawable {
draw
} draw_twice fn
// Multiple trait requirements
(T -- T) Numeric Copyable {
dup abs swap dup * +
} complex_calc fn
10. Memory Management (Postfix)
10.1 Heap Operations
// Allocate
3.0 4.0 Point alloc // ( Point -- ptr<Point> )
// Dereference
ptr deref // ( ptr<T> -- T )
// Store (dereference and update)
new_value ptr store // ( T ptr<T> -- )
// Free
ptr free // ( ptr<T> -- )
10.2 Example
// Create heap-allocated point
3.0 4.0 Point alloc // Returns ptr<Point>
dup x get print // Dereference and print x
free // Clean up
11. Array Operations (Postfix)
11.1 Basic Array Operations
// Creation
1 10 range // Create range array [1..10]
// Shape operations
arr shape // Get shape
arr 2 3 reshape // Reshape to 2x3
// Element access
arr 2 at // Index access
arr 1 3 slice // Slice array
11.2 Array Combinators
// Map - apply function to each element
[1 2 3 4] { 2 * } map // [2 4 6 8]
// Filter - keep elements matching predicate
[1 2 3 4 5] { 2 % 0 == } filter // [2 4]
// Reduce - fold with function
[1 2 3 4] 0 { + } reduce // 10
// Each - apply to each element (side effects)
[[1 2] [3 4]] { sum print } each
11.3 Array Arithmetic
[1 2 3] [4 5 6] +. // Element-wise add: [5 7 9]
[1 2 3] [4 5 6] *. // Element-wise multiply: [4 10 18]
[1 2 3] 2 *. // Scalar multiply: [2 4 6]
11.4 Array Manipulation
[1 2 3] [4 5 6] concat // Concatenate: [1 2 3 4 5 6]
[1 2 3] reverse // [3 2 1]
[[1 2] [3 4]] transpose // [[1 3] [2 4]]
[1 2 3 4] 2 window // [[1 2] [2 3] [3 4]]
12. Eval Operator (Postfix)
Execute code dynamically at runtime.
// Evaluate string as code
"2 3 +" eval // Pushes 5
// Build and execute code
"(i32 -- i32) { dup * } square fn" eval
5 square // 25
// Dynamic dispatch
operation_name " get" concat eval
13. Standard Library Concepts
13.1 I/O
"Hello" print // Print to stdout
"Enter name: " input // Read from stdin
"file.txt" read // Read file contents
"data" "file.txt" write // Write to file
13.2 String Operations
"hello" " world" concat // Concatenate: "hello world"
"hello" length // 5
"hello" 1 3 substr // "el"
"a,b,c" "," split // ["a" "b" "c"]
["a" "b"] "," join // "a,b"
13.3 Type Conversion
42 f64 as // Convert i32 to f64
"123" i32 parse // Parse string to i32
3.14 str as // Convert to string
14. Complete Examples
14.1 Factorial
(i32 -- i32) {
dup 1
{ drop 1 }
{ dup 1 - factorial * }
<= if
} factorial fn
5 factorial print // 120
14.2 FizzBuzz
(i32 -- ) {
dup 15 % 0 ==
{ drop "FizzBuzz" print }
{
dup 3 % 0 ==
{ drop "Fizz" print }
{
dup 5 % 0 ==
{ drop "Buzz" print }
{ print }
if
}
if
}
if
} fizzbuzz fn
1 100 { fizzbuzz } for
14.3 Point with Traits
// Define Point struct
(T T --) { x: y: } Point struct
// Define Drawable trait
{ (Self -- ) draw: } Drawable trait
// Implement Drawable for Point
Point {
(Point -- ) {
"Point(" print
dup x get print
", " print
y get print
")" print
} draw:
} Drawable impl
// Define distance function (requires Numeric)
(T T -- T) Numeric {
over x get over x get - dup *
swap y get swap y get - dup *
+ sqrt
} distance fn
// Usage
3.0 4.0 Point
5.0 12.0 Point
distance print // 13.0
14.4 Generic Container
// Define a generic stack container
(T --) {
items:
size:
} Stack struct
// Push function
(Stack T -- Stack) {
over items get swap concat
over size get 1 +
Stack
} stack_push fn
// Pop function (returns Stack and popped value)
(Stack -- Stack T) {
dup items get
dup length 1 -
over length 1 - at // Get last item
-rot 0 swap 1 - slice // Remove last item
over size get 1 -
Stack
swap
} stack_pop fn
// Usage
[] 0 Stack // Empty stack
42 stack_push
100 stack_push
stack_pop drop // Pop and discard value
14.5 Array Processing
// Sum of squares of even numbers from 1 to 10
[1 2 3 4 5 6 7 8 9 10]
{ 2 % 0 == } filter // Keep even numbers
{ dup * } map // Square each
0 { + } reduce // Sum
print // 220
// More complex: find max of absolute differences
[1 5 2 8 3]
[2 3 7 4 6]
{ - abs } map2 // Element-wise abs difference
0 { max } reduce // Find maximum
print // 4
14.6 Result Type Usage
// Define Result union
(T E --) { Ok(T) Err(E) } Result union
// Function that returns Result
(i32 i32 -- Result) {
dup 0 ==
{ drop "Division by zero" Err }
{ / Ok }
if
} safe_div fn
// Use it
10 2 safe_div {
Ok(x) => { x print }
Err(e) => { "Error: " print e print }
} match
15. Syntax Summary
Complete Grammar Patterns
Functions: (in -- out) constraints { body } name fn
Structs: (types -- ) { fields: } name struct
Unions: (types -- ) { Variant(T) ... } name union
Enums: () { Variant ... } name enum
Traits: { (sig) method: ... } name trait
Trait Impl: Type { (sig) { body } method: ... } Trait impl
If: condition { then } { else } if
While: { condition } { body } while
For: start end { body } for
Match: value { pattern => block ... } match
Version: 0.2
Status: Draft Specification - Pure Postfix Edition