# APEX Language Specification v0.1 **Array-oriented Postfix Expression Language** ## Design Philosophy APEX combines the clarity of postfix notation (RPL), the power of systems programming (C), and modern array-oriented programming (Uiua). The language uses strict postfix (RPN) syntax where all operators follow their operands, promoting a natural stack-based evaluation model. --- ## Tier System ### Tier 1: Foundation Core stack operations, basic arithmetic, simple control flow ### Tier 2: Structured Programming Functions, arrays, complex data types, advanced control structures ### Tier 3: Systems Programming Memory management, pointers, foreign function interface, concurrency --- ## Tier 1: Foundation ### Stack Operations ``` dup - Duplicate top item: a → a a drop - Remove top item: a → swap - Swap top two items: a b → b a over - Copy second item: a b → a b a rot - Rotate three items: a b c → b c a ``` ### Arithmetic Operators (Postfix) ``` + - Addition: a b → (a+b) - - Subtraction: a b → (a-b) * - Multiplication: a b → (a*b) / - Division: a b → (a/b) % - Modulo: a b → (a%b) neg - Negate: a → (-a) ``` ### Comparison Operators ``` = - Equal: a b → bool < - Less than: a b → bool > - Greater than: a b → bool <= - Less or equal: a b → bool >= - Greater or equal: a b → bool != - Not equal: a b → bool ``` ### Logical Operators ``` and - Logical AND: a b → bool or - Logical OR: a b → bool not - Logical NOT: a → bool ``` ### Basic Control Flow ``` [ condition ] [ true-branch ] if [ condition ] [ true-branch ] [ false-branch ] ifelse ``` Example: ```apex 5 3 > [ "greater" ] [ "not greater" ] ifelse print ``` ### Variables ``` var-name ! - Store to variable (pop from stack) var-name @ - Load from variable (push to stack) ``` Example: ```apex 42 x ! # Store 42 to x x @ 10 + # Load x, add 10 → 52 ``` ### Comments ``` # Single line comment (* Multi-line comment *) ``` --- ## Tier 2: Structured Programming ### Functions Functions are defined with postfix syntax: ``` [ body ] function-name : ``` Example: ```apex [ dup * ] square : # Define square function 5 square # Call: 5 → 25 ``` ### Functions with Local Variables ``` [ arg1 arg2 | body ] function-name : ``` The `|` separator indicates parameter binding from stack: ```apex [ x y | x @ y @ + ] add : # Pop two values, bind to x and y 3 5 add # → 8 ``` ### Recursion ```apex [ n | n @ 1 <= [ 1 ] [ n @ n @ 1 - factorial * ] ifelse ] factorial : 5 factorial # → 120 ``` ### Arrays (Uiua-inspired) ``` [ e1 e2 e3 ... ] - Array literal length - Get array length: arr → n @i - Index access: arr i → element !i - Index store: arr i val → range - Create range: n → [0..n-1] each - Map function: arr [fn] → arr' reduce - Fold: arr init [fn] → value filter - Filter: arr [predicate] → arr' ``` Example: ```apex [1 2 3 4 5] # Array on stack [ 2 * ] each # → [2 4 6 8 10] 10 range [ 2 % 0 = ] filter # Even numbers: [0 2 4 6 8] ``` ### Loops ``` [ condition ] [ body ] while n [ body ] times ``` Example: ```apex 0 i ! [ i @ 10 < ] [ i @ print i @ 1 + i ! ] while 5 [ "hello" print ] times # Print "hello" 5 times ``` ### Structures (Records) ``` { field1 field2 ... } struct-name struct ``` Example: ```apex { x y } Point struct 3 4 Point.new p ! # Create Point(3, 4) p @ .x # Access field x → 3 p @ 5 .x! # Set field x to 5 ``` --- ## Tier 3: Systems Programming ### Memory Management ``` size alloc - Allocate memory: n → ptr ptr free - Free memory ptr @ peek - Read from pointer: ptr → value ptr value ! poke - Write to pointer sizeof - Size of type: type → n ``` ### Pointers (C-inspired) ``` &var - Address of variable: → ptr ptr * - Dereference: ptr → value ptr n +ptr - Pointer arithmetic: ptr n → ptr' ``` Example: ```apex 42 x ! &x # Get address of x dup * # Dereference: → 42 100 swap ! poke # Write 100 to that address x @ # x now contains 100 ``` ### Type System ``` :i32 :i64 :f32 :f64 - Numeric types :bool :char - Basic types :ptr - Pointer type [ type ] :array - Array type ``` Example with type annotations: ```apex [ x:i32 y:i32 | x @ y @ + ]:i32 add : ``` ### Foreign Function Interface ``` "lib.so" import-lib [ arg-types... ] ret-type "func_name" foreign ``` Example: ```apex "libc.so.6" import-lib [ :ptr ] :i32 "strlen" foreign strlen-ffi : "hello" strlen-ffi # Call C strlen ``` ### Concurrency ``` [ body ] spawn - Spawn thread: → thread-id thread-id join - Wait for thread value channel.send - Send to channel channel.recv - Receive from channel: → value lock.acquire lock.release ``` Example: ```apex [ 1 100 range [ . ] each ] spawn worker ! worker @ join ``` ### System Calls ``` :read :write :open :close syscall ``` --- ## Complete Example Program ```apex # Fibonacci sequence generator (Tier 2) [ n | n @ 0 = [ 0 ] [ n @ 1 = [ 1 ] [ n @ 1 - fib n @ 2 - fib + ] ifelse ] ifelse ] fib : # Calculate and print first 10 Fibonacci numbers 10 [ dup fib print ] each # Array operations (Uiua-style) [1 2 3 4 5] [ dup * ] each # Square each: [1 4 9 16 25] 0 [ + ] reduce # Sum: 55 print ``` --- ## Syntax Summary ### Key Principles 1. **Postfix everywhere**: All operators come after operands 2. **Stack-based**: Implicit stack for data flow 3. **Brackets for grouping**: `[ ]` for code blocks and arrays 4. **Sigils for operations**: `!` for store, `@` for load, `.` for field access 5. **Natural composition**: Functions compose left-to-right ### Operator Precedence None! Being postfix eliminates precedence issues. Evaluation is strictly left-to-right, consuming operands from the stack. --- ## Implementation Notes - **Tier 1** can be implemented as a simple stack-based interpreter - **Tier 2** requires a symbol table for functions and array support - **Tier 3** needs memory management, type checking, and possibly compilation The tier system allows learners to master concepts progressively while enabling systems programming when needed.