## 5. Functions

Functions are user-defined procedures that encapsulate reusable code. They are the primary abstraction mechanism in the language.

### 5.1 What are Functions

Functions differ from operators:
- **Operators** implement trait methods and are the fundamental building blocks
- **Functions** are user-defined procedures that use operators
- Operators and functions cannot share names

> **Related**: See Section 1 "Operators vs Functions" for a complete explanation of the distinction.

### 5.2 Defining Functions

**Syntax**: `(inputs -- outputs) { body } ::name fn`

The function signature specifies stack effects (what is consumed and produced), the body contains the implementation, and the name identifies the function.

**Examples**:
```
// Simple function - requires Multiplyable trait
(Multiplyable -- Multiplyable) { dup * } ::square fn

// Use it
5 square      // => 25

// Multiple inputs and outputs
(Number Number -- Number Number) {
    over over / swap %
} ::divmod fn

10 3 divmod   // => 3 1 (quotient remainder)
```

**Function Bodies**: The `{ }` braces contain a TokenString that is parsed as the function body when the function is defined. See Section 5.5 for details on TokenStrings.

> **Related**: See Section 10.2 for generic functions with type parameters.

### 5.3 Calling Functions

Functions are called by simply writing their name. The postfix notation means arguments must be on the stack before the function name:

```
// Define a function
(Number Number -- Number) { + } ::add fn

// Call it
3 4 add       // => 7

// Chain functions
5 square 2 * // => 50 (square 5, then multiply by 2)
```

**Function Chaining**: Since everything is postfix, functions naturally chain left-to-right:
```
10 square 2 / 5 +    // ((10²) / 2) + 5 = 55
```

### 5.4 Recursion

Functions can call themselves recursively:

```
(Number -- Number) {
    dup 1 <=
        { drop 1 }
        { dup 1 - factorial * }
    if
} ::factorial fn

5 factorial    // => 120
```

**Stack Considerations**: Recursive functions consume stack space. Deep recursion may cause stack overflow. Consider iterative alternatives for performance-critical code.

### 5.5 Token Strings

Token strings are lexed but unparsed code blocks enclosed in `{ }`. They are parsed differently depending on which operator uses them.

**Operators that parse TokenStrings:**
- `fn` - Parses as function body (code block)
- `trait` - Parses as trait definition (method signatures)
- `impl` - Parses as trait implementation (method definitions)
- `eval` - Parses and executes as code block immediately
- `lambda` - Parses as code block, pushes the block as a callable value
- `if` - Parses both TokenStrings as code blocks (then/else branches)
- `while` - Parses both TokenStrings as code blocks (condition/body)
- `for` - Parses TokenString as code block (loop body)
- `match` - Parses TokenString as pattern matching arms
- `map`, `filter`, `reduce`, `each` - Parse TokenStrings as code blocks for array operations

**Examples**:
```
// Function body (parsed by fn)
(Number -- Number) { dup * } ::square fn

// Conditional branches (parsed by if)
x 0 > { "positive" print } { "negative" print } if

// Loop body (parsed by while)
{ dup 10 < } { dup print 1 + } while
```

### 5.6 Lambda Functions

The `lambda` operator converts a TokenString into a callable code block that can be stored and passed around:

```
{ dup * } lambda        // Creates a callable code block
::square_fn swap        // Store reference to the lambda

// Later use:
5 square_fn eval        // Calls the lambda: pushes 25
```

**Use Cases**:
- Creating first-class functions
- Passing code blocks as values
- Dynamic dispatch
- Higher-order operations

**Example with arrays**:
```
// Store a lambda and use it with map
{ 2 * } lambda ::double swap
[1 2 3 4] double map    // => [2 4 6 8]
```

> **Related**: See Section 11.1 for the `eval` operator used to execute lambdas.

---