Introduction

This document is the formal specification for the Forge programming language, version 0.3.3.

Forge is an internet-native, general-purpose programming language implemented in Rust. It is designed for application-layer work: web services, scripts, data pipelines, prototypes, and tooling. Forge ships with built-in support for HTTP clients and servers, databases (SQLite and PostgreSQL), cryptography, JSON, CSV, terminal UI, AI/LLM integration, and more — eliminating the need for third-party packages for common internet-oriented tasks.

Design Philosophy

Forge is guided by three core principles:

1. Internet-native. The operations developers perform most frequently — HTTP requests, database queries, JSON parsing, cryptographic hashing — are built into the language and its standard library. A REST API server is four lines. A database query is two.

2. Dual syntax. Every construct in Forge has two spellings: a classic syntax familiar to developers who have written JavaScript, Python, Rust, or Go; and a natural-language syntax that reads like English prose. Both forms compile to identical internal representations and may be mixed freely within the same source file.

3. Batteries included. Forge ships 16 standard library modules with over 230 functions, 30 interactive tutorials, a built-in test runner, a formatter, an LSP server, and a project scaffolding tool. A single cargo install provides a complete development environment.

Language Overview

Forge is dynamically typed at runtime with optional type annotations (gradual typing). It supports first-class functions, closures, algebraic data types, pattern matching, Result/Option error handling, structural interfaces, composition via delegation, async/await concurrency, and channels. Programs are executed top-to-bottom without requiring a main function.

The default execution engine is a tree-walking interpreter. A bytecode VM (--vm) and a JIT compiler (--jit) are available for performance-critical workloads but support fewer features.

How to Read This Specification

This specification is organized into five parts:

• Part I: Language Core covers lexical structure, types, expressions, statements, the type system, error handling, and concurrency.
• Part II: Standard Library documents each of the 16 built-in modules.
• Part III: Built-in Functions catalogs all globally available functions.
• Part IV: Dual Syntax Reference provides the complete mapping between classic and natural syntax forms.
• Part V: Runtime and Internals describes the interpreter, bytecode VM, JIT compiler, and HTTP server runtime.

Grammar rules are presented in block quotes using an informal EBNF notation. Code examples use forge syntax highlighting. Where both classic and natural syntax exist for a construct, both forms are shown.

Notation Conventions

Throughout this specification:

• monospace text in prose refers to keywords, operators, or identifiers.
• Code blocks labeled forge contain valid Forge source code.
• Grammar productions use → for derivation, | for alternatives, [ ] for optional elements, and { } for zero-or-more repetition.
• The term “implementation-defined” means the behavior is determined by the specific execution engine (interpreter, VM, or JIT).

Links

• Source code: https://github.com/humancto/forge-lang
• Website and book: https://humancto.github.io/forge-lang/

Credits

Forge was created by Archith Rapaka / HumanCTO.

Lexical Structure

This chapter defines the lexical grammar of Forge: how source text is decomposed into a sequence of tokens. The lexer (tokenizer) reads UTF-8 encoded source text and produces a flat stream of tokens that the parser consumes.

Overview

A Forge source file is a sequence of Unicode characters encoded as UTF-8. The lexer processes this character stream left-to-right, greedily matching the longest valid token at each position. The resulting token stream consists of:

• Keywords — reserved words with special meaning (e.g., let, fn, set, define)
• Identifiers — user-defined names for variables, functions, types, and fields
• Literals — integer, float, string, boolean, and null values
• Operators — arithmetic, comparison, logical, assignment, and special operators
• Punctuation — delimiters and separators ((, ), {, }, [, ], ,, :, ;)
• Comments — line comments and block comments, discarded during tokenization
• Newlines — significant for statement termination
• Decorators — @ prefixed annotations

Whitespace and Line Termination

Spaces (U+0020) and horizontal tabs (U+0009) are whitespace characters. They separate tokens but are otherwise insignificant and are not included in the token stream.

Newline characters (U+000A, and the sequence U+000D U+000A) serve as statement terminators. Unlike whitespace, newlines are emitted as Newline tokens because Forge uses newlines (rather than semicolons) to separate statements. Semicolons (;) are recognized as explicit statement terminators but are not required.

Tokenization Order

When the lexer encounters a character sequence, it applies the following precedence:

1. Skip whitespace (spaces and tabs).
2. If the character begins a comment (// or /*), consume the entire comment.
3. If the character is a newline, emit a Newline token.
4. If the character is a digit, lex a numeric literal (integer or float).
5. If the character is ", lex a string literal (or """ for raw strings).
6. If the character is a letter or underscore, lex an identifier or keyword.
7. Otherwise, lex an operator or punctuation token.

Each token carries a span consisting of the line number, column number, byte offset, and byte length within the source text.

Subsections

The following subsections define each lexical element in detail:

• Source Text — encoding, file extension, line endings
• Keywords — complete keyword list with dual-syntax mappings
• Identifiers — naming rules and special identifiers
• Literals — numeric, string, boolean, null, array, and object literals
• Operators and Punctuation — all operator and delimiter tokens
• Comments — line and block comment syntax

Source Text

Encoding

Forge source files must be encoded in UTF-8. The lexer assumes UTF-8 input and will produce errors on invalid byte sequences. No byte-order mark (BOM) is required or expected; if present, it is treated as ordinary content and will likely cause a parse error.

File Extension

Forge source files use the .fg file extension by convention. The CLI tools (forge run, forge test, forge fmt) expect this extension. Example:

hello.fg
server.fg
tests/math_test.fg

Line Endings

Forge recognizes two line ending sequences:

A bare carriage return (\r without a following \n) is not treated as a line ending. Both recognized forms are normalized to a single Newline token in the token stream.

Source Structure

A Forge source file consists of a sequence of top-level statements executed in order. There is no required main function, module declaration, or package header. The simplest valid Forge program is:

say "hello"

Forge programs are executed from the first statement to the last, top to bottom. Functions and type definitions are hoisted conceptually in that they can be referenced before their textual position, but side effects in top-level statements execute in source order.

Character Set

Within string literals, Forge supports the full Unicode character set. Outside of string literals, the following characters are meaningful to the lexer:

• ASCII letters (a-z, A-Z) and underscore (_) begin identifiers and keywords.
• ASCII digits (0-9) begin numeric literals.
• Operator and punctuation characters: +, -, *, /, %, =, !, <, >, &, |, ., ,, :, ;, (, ), {, }, [, ], @, ?, #.
• The double-quote character (") begins string literals.
• Whitespace characters: space (U+0020), horizontal tab (U+0009).
• Line terminators: line feed (U+000A), carriage return (U+000D).

All other characters outside of string literals are lexer errors.

Keywords

Keywords are reserved identifiers with special syntactic meaning. A keyword cannot be used as a variable name, function name, or type name.

Forge’s keyword set is organized into five categories: classic keywords (familiar from other languages), natural-language keywords (Forge’s English-like alternatives), innovation keywords (unique to Forge), error handling keywords, and type keywords.

Classic Keywords

These keywords provide syntax familiar to developers coming from Rust, JavaScript, Go, or Python.

Natural-Language Keywords

These keywords provide English-like alternatives to classic syntax. Each natural keyword maps to an equivalent classic construct.

Dual Syntax Mapping

The following table shows equivalent forms for the most common constructs:

Innovation Keywords

These keywords introduce constructs unique to Forge that have no direct equivalent in other mainstream languages.

Error Handling Keywords

Type Keywords

These identifiers are reserved as built-in type names. They are recognized by the lexer as keyword tokens, not as general identifiers.

Operators as Keywords

The following operators are lexed as keyword tokens rather than punctuation:

Complete Alphabetical Index

For reference, the complete set of keyword strings recognized by the lexer (case-sensitive):

Int, Float, String, Bool, Json,
any, ask, async, await, break, by, catch, change, continue, craft,
crawl, define, download, each, else, emit, every, false, fn, for,
forge, freeze, from, give, grab, hold, if, impl, import, in,
interface, keep, let, limit, loop, match, mut, nah, null, order,
otherwise, power, prompt, pub, repeat, retry, return, safe, say,
schedule, seconds, select, set, spawn, struct, table, take, the,
thing, timeout, times, to, transform, true, try, type, unless,
unpack, until, wait, watch, when, where, while, whisper, yell, yield

All keywords are case-sensitive. Let and LET are identifiers, not keywords. The type keywords Int, Float, String, Bool, and Json are the only keywords that begin with an uppercase letter.

Identifiers

An identifier is a name that refers to a variable, function, type, field, or module. Identifiers are the primary mechanism for binding values to names in Forge programs.

Syntax

Identifier → IdentStart IdentContinue*

IdentStart → a-z | A-Z | _

IdentContinue → IdentStart | 0-9

An identifier begins with an ASCII letter or underscore, followed by zero or more ASCII letters, digits, or underscores. Identifiers have no maximum length.

x
name
_private
camelCase
snake_case
PascalCase
item2
MAX_RETRIES
__internal

Case Sensitivity

Identifiers are case-sensitive. The names name, Name, and NAME refer to three distinct bindings.

let name = "alice"
let Name = "Bob"
let NAME = "CHARLIE"
say name   // alice
say Name   // Bob
say NAME   // CHARLIE

Reserved Words

If an identifier matches a keyword string (see Keywords), it is lexed as that keyword token rather than as an Ident token. Keywords cannot be used as identifiers.

// Error: 'let' is a keyword, not a valid variable name
let let = 5  // parse error

Naming Conventions

Forge does not enforce naming conventions, but the following are idiomatic:

The it Identifier

The identifier it has special meaning inside method blocks defined with give (or impl). When used as the first parameter of a method, it refers to the receiver instance — the object on which the method was called.

thing Person {
    name: String,
    age: Int
}

give Person {
    define greet(it) {
        return "Hi, I'm " + it.name
    }
}

set p to craft Person { name: "Alice", age: 30 }
say p.greet()  // Hi, I'm Alice

When p.greet() is called, the value of p is automatically bound to it inside the method body. The caller does not pass it explicitly.

If the first parameter of a method is not named it, the method is treated as a static method — it is called on the type itself rather than on an instance:

give Person {
    define infant(name) {
        return craft Person { name: name, age: 0 }
    }
}

set baby to Person.infant("Bob")

Outside of method blocks, it has no special meaning and may be used as an ordinary identifier, though this is discouraged for clarity.

Underscore

A lone underscore (_) is a valid identifier. By convention, it is used as a placeholder for values that are intentionally ignored:

match result {
    Ok(_) => say "success"
    Err(msg) => say "error: {msg}"
}

for _, value in enumerate(items) {
    say value
}

Shadowing

A new let or set declaration may reuse an identifier that is already in scope. The new binding shadows the previous one within the inner scope:

let x = 10
say x        // 10

if true {
    let x = 20
    say x    // 20 (shadows outer x)
}

say x        // 10 (outer x is unchanged)

Shadowing creates a new binding; it does not mutate the original variable.

Literals

A literal is a notation for representing a fixed value in source code. Forge supports integer, float, string, raw string, boolean, null, array, and object literals.

Integer Literals

IntLiteral → Digit+

Digit → 0-9

An integer literal is a sequence of one or more decimal digits. Integer literals produce values of type Int (64-bit signed integer).

0
42
1000000

Negative integer values are expressed using the unary negation operator:

let x = -42

Integer literals do not support underscores as digit separators, hexadecimal, octal, or binary notation in the current version.

Float Literals

FloatLiteral → Digit+ . Digit+

A float literal contains a decimal point with digits on both sides. Float literals produce values of type Float (64-bit IEEE 754 double-precision).

3.14
0.5
100.0

A leading dot (.5) or trailing dot (5.) is not valid. Both sides of the decimal point must have at least one digit.

Negative float values use unary negation:

let temp = -0.5

Scientific notation (e.g., 1.5e10) is not supported in the current version.

String Literals

StringLiteral → " StringContent* "

StringContent → Character | EscapeSequence | Interpolation

EscapeSequence → \n | \t | \\ | \"

Interpolation → { Expression }

A string literal is a sequence of characters enclosed in double quotes. String literals produce values of type String (UTF-8 encoded, immutable).

"hello, world"
"line one\nline two"
"she said \"hi\""

Escape Sequences

The following escape sequences are recognized within string literals:

String Interpolation

Curly braces within a string literal delimit an interpolation expression. The expression is evaluated at runtime, converted to a string, and inserted at that position:

let name = "Forge"
let version = 3
say "Welcome to {name} v{version}!"
// Output: Welcome to Forge v3!

Interpolation supports arbitrary expressions, not just variable names:

let x = 7
say "Seven squared is {x * x}"
say "Length: {len("hello")}"
say "Upper: {name}"

To include a literal { in a string without triggering interpolation, there is no dedicated escape sequence in the current version. Use string concatenation or a variable if needed.

Raw String Literals

RawStringLiteral → """ RawContent* """

A raw string literal is delimited by triple double quotes. Raw strings preserve their content exactly as written: no escape sequences are processed and no interpolation occurs.

let sql = """SELECT * FROM users WHERE active = true"""

let html = """<div class="container">
    <h1>Hello</h1>
</div>"""

Raw strings may span multiple lines. They are particularly useful for SQL queries, regular expressions, and embedded markup.

Boolean Literals

BoolLiteral → true | false

The boolean literals true and false produce values of type Bool. They are keyword tokens.

let active = true
let deleted = false

Null Literal

NullLiteral → null

The null literal represents the absence of a value. It produces a value of type Null. It is a keyword token.

let nothing = null
say typeof(nothing)  // Null

Array Literals

ArrayLiteral → [ ( Expression ( , Expression )* ,? )? ]

An array literal is a comma-separated list of expressions enclosed in square brackets. Arrays are ordered, heterogeneous (elements may have different types), and 0-indexed.

let empty = []
let nums = [1, 2, 3]
let mixed = [1, "two", true, null]
let nested = [[1, 2], [3, 4]]

A trailing comma after the last element is permitted.

Object Literals

ObjectLiteral → { ( Field ( , Field )* ,? )? }

Field → Identifier : Expression

An object literal is a comma-separated list of key-value pairs enclosed in curly braces. Keys are identifiers (unquoted). Objects maintain insertion order.

let empty = {}
let user = { name: "Alice", age: 30 }
let config = {
    host: "localhost",
    port: 8080,
    debug: false,
}

Object keys are strings at runtime, even though they appear as bare identifiers in the literal syntax. A trailing comma after the last field is permitted.

Shorthand Field Syntax

When a variable name matches the desired key name, the value may be omitted:

let name = "Alice"
let age = 30
let user = { name, age }
// Equivalent to: { name: "Alice", age: 30 }

Operators and Punctuation

This section defines all operator and punctuation tokens in Forge.

Arithmetic Operators

When both operands of / are integers, the result is an integer (truncating division). When either operand is a float, the result is a float.

The + operator is overloaded for string concatenation when both operands are strings.

Comparison Operators

All comparison operators return a Bool value. Strings are compared lexicographically.

Logical Operators

The keywords and and or are not reserved keywords in Forge. Logical operations use the symbolic && and || forms exclusively. The not keyword is also not reserved; use the ! prefix operator.

Both && and || use short-circuit evaluation: the right operand is not evaluated if the result can be determined from the left operand alone.

Assignment Operators

Assignment and compound assignment operators require the left-hand side to be a mutable variable (declared with mut). Compound assignment is syntactic sugar for the expanded form.

Member Access and Navigation

The dot operator accesses fields on objects and struct instances, and invokes methods. It binds very tightly (highest precedence among binary operators).

The range operator .. creates a range value from a start (inclusive) to an end (exclusive). It is used primarily with for loops and the range() built-in.

Pipe Operators

The pipe operator passes the value on the left as the first argument to the function on the right:

let result = [3, 1, 4, 1, 5]
    |> sort
    |> reverse

Spread Operator

The spread operator expands an array or object into individual elements within an array literal or object literal:

let a = [1, 2, 3]
let b = [...a, 4, 5]       // [1, 2, 3, 4, 5]

let base = { x: 1, y: 2 }
let ext = { ...base, z: 3 } // { x: 1, y: 2, z: 3 }

Arrow Operators

The thin arrow -> is used in when guard arms. The fat arrow => is used in match pattern arms. Both separate a pattern/condition from its corresponding body.

Special Operators

The ? postfix operator propagates errors: if the expression evaluates to Err(e), the enclosing function returns Err(e) immediately. If the expression is Ok(v), the ? unwraps it to v.

Delimiters

Operator Precedence

Operators are listed from highest to lowest precedence:

Parentheses may be used to override the default precedence.

Comments

Comments are annotations in source code intended for human readers. The lexer recognizes comments and discards them; they do not appear in the token stream and have no effect on program behavior.

Forge supports two forms of comments: line comments and block comments.

Line Comments

LineComment → // Character* Newline

A line comment begins with // and extends to the end of the line (the next newline character or end of file). Everything after // on that line is ignored by the lexer.

// This is a line comment
let x = 42  // This is an inline comment

Line comments may appear on their own line or at the end of a line containing code.

Block Comments

BlockComment → /* Character* */

A block comment begins with /* and ends with the next occurrence of */. Block comments may span multiple lines.

/* This is a block comment */

/*
  This block comment
  spans multiple lines.
*/

let x = /* inline block comment */ 42

Block comments do not nest. The first */ encountered after a /* ends the comment, regardless of any intervening /* sequences:

/* outer /* inner */ this is NOT inside the comment */

In the example above, the comment ends at the first */, and the text this is NOT inside the comment */ would be parsed as code (and likely produce a syntax error).

Doc Comments

Forge does not currently have a dedicated doc comment syntax (such as /// or /** */). Documentation is written using regular line comments or block comments by convention.

Comments in String Literals

Comment sequences (// and /* */) within string literals are part of the string content and are not treated as comments:

let url = "https://example.com"   // The // in the string is not a comment
let msg = "use /* carefully */"    // The /* */ in the string is not a comment

Placement

Comments may appear anywhere that whitespace is permitted. They cannot appear inside tokens (e.g., in the middle of an identifier or numeric literal).

Types

This chapter describes the type system of the Forge programming language.

Overview

Forge is dynamically typed at runtime: variables do not have fixed types, and any variable may hold a value of any type at any point during execution. However, Forge supports optional type annotations (gradual typing) on variable declarations, function parameters, and return types. These annotations serve as documentation and enable the optional type checker to detect certain errors before execution.

Every value in Forge belongs to exactly one of the following type categories:

Type Annotations

Type annotations use a colon after the name, followed by the type:

let name: String = "Alice"
let age: Int = 30
let score: Float = 98.5
let active: Bool = true

Function parameters and return types may also be annotated:

fn add(a: Int, b: Int) -> Int {
    return a + b
}

When annotations are omitted, types are inferred from the assigned values. Annotations are always optional.

Type Inspection at Runtime

The built-in typeof() function (aliased as type()) returns a string describing the runtime type of a value:

say typeof(42)                 // Int
say typeof(3.14)               // Float
say typeof("hello")            // String
say typeof(true)               // Bool
say typeof(null)               // Null
say typeof([1, 2, 3])          // Array
say typeof({ name: "Alice" })  // Object

For struct instances, typeof() returns the struct name (e.g., "Person").

Truthiness

When a value is used in a boolean context (such as an if condition), Forge evaluates it as “truthy” or “falsy” according to the following rules:

Subsections

The following subsections define each type category in detail:

• Primitive Types — Int, Float, String, Bool, Null
• Collection Types — Array, Object
• Struct Types — struct / thing definitions
• Interface Types — interface / power contracts
• Function Types — functions as first-class values
• Algebraic Data Types — type Name = Variant | ...
• Option and Result — Option and Result wrapper types
• Type Conversions — str(), int(), float(), type(), typeof()

Primitive Types

Forge has five primitive types. Primitive values are immutable and compared by value.

Int

The Int type represents a 64-bit signed integer. Its range is -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807 (i.e., the range of a Rust i64).

let x = 42
let y = -7
let z = 0
say typeof(x)  // Int

Integer arithmetic follows standard rules. Division between two integers produces an integer result (truncating toward zero):

say 7 / 2    // 3
say -7 / 2   // -3

Integer overflow behavior is implementation-defined. The interpreter wraps on overflow (Rust’s default for i64 in release mode).

Float

The Float type represents a 64-bit IEEE 754 double-precision floating-point number. This provides approximately 15-17 significant decimal digits of precision.

let pi = 3.14159
let temp = -0.5
let one = 1.0
say typeof(pi)  // Float

When an arithmetic operation involves both an Int and a Float, the integer is implicitly promoted to a float, and the result is a Float:

say 5 + 2.0    // 7.0
say 10 / 3.0   // 3.3333333333333335

Special float values (NaN, Infinity, -Infinity) may arise from operations like division by zero on floats, but there is no literal syntax for these values.

String

The String type represents an immutable sequence of UTF-8 encoded characters. Strings are created using double-quoted literals and support interpolation and escape sequences (see Literals).

let greeting = "Hello, World!"
let empty = ""
let multiline = """This is
a raw string."""
say typeof(greeting)  // String

Key Properties

• Immutable. String operations always return new strings; the original is never modified.
• UTF-8. All strings are valid UTF-8. The len() function returns the number of bytes, not Unicode code points.
• Interpolation. Double-quoted strings support {expr} interpolation. Raw strings ("""...""") do not.
• Concatenation. The + operator concatenates two strings.

let name = "Forge"
let version = 3
say "Welcome to {name} v{version}!"  // Welcome to Forge v3!
say "Hello" + ", " + "World!"         // Hello, World!

String Comparison

Strings are compared lexicographically (byte-by-byte) using the standard comparison operators:

say "apple" < "banana"   // true
say "hello" == "hello"   // true

Bool

The Bool type has exactly two values: true and false.

let active = true
let deleted = false
say typeof(active)  // Bool

Boolean values result from comparison operators (==, !=, <, >, <=, >=) and logical operators (&&, ||, !). They are the natural type for if conditions, while conditions, and other control flow predicates.

Logical Operations

Both && and || use short-circuit evaluation.

Null

The Null type has exactly one value: null. It represents the absence of a meaningful value.

let nothing = null
say typeof(nothing)  // Null

null is returned by functions that have no explicit return statement. It is falsy in boolean contexts.

Null vs. None

Forge distinguishes between null and None:

• null is a bare value representing “no value.” It is a primitive.
• None is a variant of the Option type representing “intentionally absent.” It is a wrapper.

In practice, null appears in dynamic code and untyped contexts, while None is used in the Option/Result error-handling pattern. See Option and Result for details.

Type Comparison Summary

All primitive types are compared by value. Two integers with the same numeric value are equal regardless of how they were computed.

Collection Types

Forge has two built-in collection types: Array and Object. Both are mutable, heap-allocated, and compared by reference for identity but by value for equality.

Array

An array is an ordered, heterogeneous, 0-indexed sequence of values. Elements may be of any type, including other arrays and objects.

Creation

Arrays are created with square bracket literals:

let empty = []
let nums = [1, 2, 3]
let mixed = [1, "two", true, null]
let nested = [[1, 2], [3, 4]]

Indexing

Elements are accessed by zero-based integer index using bracket notation:

let fruits = ["apple", "banana", "cherry"]
say fruits[0]   // apple
say fruits[1]   // banana
say fruits[2]   // cherry

Negative indices count from the end of the array:

say fruits[-1]  // cherry

Accessing an out-of-bounds index produces a runtime error.

Mutation

Arrays are mutable. Elements can be replaced by index assignment:

let mut items = [1, 2, 3]
items[0] = 10
say items  // [10, 2, 3]

The push() built-in appends an element:

let mut items = [1, 2]
push(items, 3)
say items  // [1, 2, 3]

The pop() built-in removes and returns the last element:

let mut items = [1, 2, 3]
let last = pop(items)
say last   // 3
say items  // [1, 2]

Length

The len() built-in returns the number of elements:

say len([1, 2, 3])  // 3
say len([])          // 0

Spread

The spread operator ... expands an array within another array literal:

let a = [1, 2, 3]
let b = [...a, 4, 5]
say b  // [1, 2, 3, 4, 5]

Iteration

Arrays are iterable with for/in:

for item in [10, 20, 30] {
    say item
}

With enumerate() for index-value pairs:

for i, item in enumerate(["a", "b", "c"]) {
    say "{i}: {item}"
}

Functional Operations

Arrays support map, filter, reduce, sort, reverse, find, flat_map, any, all, and other functional built-ins:

let nums = [1, 2, 3, 4, 5]
let doubled = map(nums, fn(x) { return x * 2 })
let evens = filter(nums, fn(x) { return x % 2 == 0 })
let sum = reduce(nums, 0, fn(acc, x) { return acc + x })

Truthiness

An empty array [] is falsy. All non-empty arrays are truthy.

Object

An object is an insertion-ordered map from string keys to arbitrary values. Objects are Forge’s general-purpose key-value data structure.

Creation

Objects are created with curly brace literals:

let empty = {}
let user = { name: "Alice", age: 30 }
let config = {
    host: "localhost",
    port: 8080,
    debug: false,
}

Keys are written as bare identifiers in the literal syntax. At runtime, they are strings.

Field Access

Fields are accessed with dot notation or bracket notation:

let user = { name: "Alice", age: 30 }
say user.name       // Alice
say user["age"]     // 30

Dot notation requires the field name to be a valid identifier. Bracket notation accepts any string expression, making it suitable for dynamic keys:

let key = "name"
say user[key]  // Alice

Mutation

Objects are mutable. Fields can be added, updated, or accessed dynamically:

let mut obj = { x: 1 }
obj.y = 2
obj.x = 10
say obj  // { x: 10, y: 2 }

Key Operations

Spread

The spread operator expands an object within another object literal:

let base = { x: 1, y: 2 }
let ext = { ...base, z: 3 }
say ext  // { x: 1, y: 2, z: 3 }

When keys conflict, later values overwrite earlier ones:

let a = { x: 1, y: 2 }
let b = { ...a, x: 10 }
say b  // { x: 10, y: 2 }

Iteration

Objects are iterable. A for/in loop over an object yields [key, value] pairs in insertion order:

let user = { name: "Alice", age: 30 }
for key, value in user {
    say "{key}: {value}"
}

Truthiness

An empty object {} is truthy (unlike empty arrays, which are falsy). All objects, including empty ones, are truthy.

Objects vs. Structs

Plain objects are untyped: any object can have any set of keys. Structs (defined with struct or thing) provide named types with declared fields, type annotations, default values, and methods. Under the hood, struct instances are objects with a __type__ field. See Struct Types for details.

Struct Types

A struct defines a named data type with declared fields, optional type annotations, and optional default values. Structs are the primary mechanism for defining domain-specific types in Forge.

Definition

Structs are defined with the struct keyword (classic syntax) or the thing keyword (natural syntax). Both forms are equivalent.

StructDef → ( struct | thing ) Identifier { FieldList }

FieldList → ( Field ( , Field )* ,? )?

Field → Identifier : TypeAnnotation ( = Expression )? | has Identifier : TypeAnnotation

// Classic syntax
struct Point {
    x: Int,
    y: Int
}

// Natural syntax — identical result
thing Point {
    x: Int,
    y: Int
}

Field type annotations are part of the struct definition syntax. Each field has a name, a colon, and a type name.

Default Values

Fields may have default values. If a field with a default is omitted during construction, the default value is used:

thing Config {
    host: String = "localhost",
    port: Int = 8080,
    debug: Bool = false
}

set cfg to craft Config {}
say cfg.host   // localhost
say cfg.port   // 8080
say cfg.debug  // false

Fields without defaults are required — omitting them during construction produces a runtime error.

set prod to craft Config { host: "api.example.com", port: 443 }
say prod.host   // api.example.com
say prod.debug  // false (default)

Construction

There are two ways to create a struct instance:

Direct Construction (Classic)

Use the type name followed by a field initializer block:

let p = Point { x: 3, y: 4 }

Craft Construction (Natural)

Use the craft keyword:

set p to craft Point { x: 3, y: 4 }

Both forms produce the same value: an object with the declared fields plus a __type__ field set to the struct name.

Field Access

Fields are accessed with dot notation:

let p = Point { x: 3, y: 4 }
say p.x  // 3
say p.y  // 4

The __type__ Field

Every struct instance has an internal __type__ field containing the struct name as a string. This field is set automatically during construction and is used by the runtime for method dispatch, interface satisfaction checking, and typeof():

let p = Point { x: 3, y: 4 }
say typeof(p)  // Point

Methods

Methods are attached to a struct using give (natural) or impl (classic) blocks. See Method Blocks for full details.

give Point {
    define distance(it) {
        return math.sqrt(it.x * it.x + it.y * it.y)
    }
}

let p = Point { x: 3, y: 4 }
say p.distance()  // 5.0

The first parameter it is the receiver. When p.distance() is called, p is automatically bound to it.

Static Methods

If a method’s first parameter is not it, it is a static method called on the type rather than on an instance:

give Person {
    define infant(name) {
        return craft Person { name: name, age: 0 }
    }
}

set baby to Person.infant("Bob")

Multiple give Blocks

Multiple give blocks for the same type are permitted. Methods accumulate across all blocks:

give Person {
    define greet(it) {
        return "Hi, I'm " + it.name
    }
}

give Person {
    define birthday(it) {
        return craft Person { name: it.name, age: it.age + 1 }
    }
}

Composition with has

The has keyword inside a struct body embeds one type within another, enabling field and method delegation:

thing Address {
    street: String,
    city: String
}

thing Employee {
    name: String,
    has addr: Address
}

The has keyword provides two delegation mechanisms:

1. Field delegation. Accessing a field that does not exist on the outer type delegates to the embedded type. emp.city resolves to emp.addr.city.

2. Method delegation. Calling a method that does not exist on the outer type delegates to the embedded type. emp.full() resolves to emp.addr.full().

give Address {
    define full(it) {
        return it.street + ", " + it.city
    }
}

set emp to craft Employee {
    name: "Charlie",
    addr: craft Address { street: "123 Main St", city: "Portland" }
}

say emp.city     // Portland (delegated)
say emp.full()   // 123 Main St, Portland (delegated)

The explicit path (emp.addr.city) also works and produces the same result.

Struct vs. Object

Interface Types

An interface (or “power” in natural syntax) defines a contract: a set of method signatures that a type must provide. Interfaces enable polymorphism in Forge — any type that satisfies an interface’s contract can be used wherever that interface is expected.

Definition

Interfaces are defined with the interface keyword (classic) or the power keyword (natural).

InterfaceDef → ( interface | power ) Identifier { MethodSignature* }

MethodSignature → fn Identifier ( ParamList? ) ( -> Type )?

// Classic syntax
interface Describable {
    fn describe() -> String
}

// Natural syntax — identical result
power Describable {
    fn describe() -> String
}

An interface body contains one or more method signatures. Each signature specifies the method name, parameter types, and optional return type. No method body is provided — interfaces declare what methods must exist, not how they work.

Implementing an Interface

A type satisfies an interface by providing implementations of all required methods. This is done using give ... the power ... (natural) or impl ... for ... (classic).

thing Person {
    name: String,
    age: Int
}

// Natural syntax
give Person the power Describable {
    define describe(it) {
        return it.name + " (" + str(it.age) + ")"
    }
}

// Classic syntax — identical result
impl Describable for Person {
    fn describe(it) {
        return it.name + " (" + str(it.age) + ")"
    }
}

The implementation block must provide a method for every signature in the interface. Missing methods produce a compile-time (definition-time) error.

Checking Satisfaction

The satisfies() built-in function checks whether a value’s type satisfies a given interface at runtime:

set alice to craft Person { name: "Alice", age: 30 }
say satisfies(alice, Describable)   // true

If a type has not implemented the interface, satisfies() returns false:

thing Robot {
    id: Int
}

set r to craft Robot { id: 1 }
say satisfies(r, Describable)   // false

Multiple Interfaces

A single type may implement multiple interfaces:

power Describable {
    fn describe() -> String
}

power Vocal {
    fn speak() -> String
}

thing Animal {
    species: String,
    sound: String
}

give Animal the power Describable {
    define describe(it) {
        return it.species + " that says " + it.sound
    }
}

give Animal the power Vocal {
    define speak(it) {
        return it.sound + "! " + it.sound + "!"
    }
}

Each interface implementation is provided in a separate give...the power block. A type accumulates all its interface implementations.

No Default Implementations

In the current version of Forge, interfaces cannot provide default method implementations. Every method in an interface must be explicitly implemented by each type that satisfies it.

Interface Inheritance

Interface inheritance (one interface extending another) is not supported in the current version. Each interface is independent.

Structural vs. Nominal

Forge uses a nominal approach to interface satisfaction: a type satisfies an interface only if it has been explicitly declared to do so via a give...the power or impl...for block. Simply having methods with matching names and signatures is not sufficient.

However, the satisfies() built-in performs a structural check at runtime — it verifies that the required methods actually exist on the value. This means satisfaction is ultimately determined by the presence of the declared methods, but the declaration is required to register the type-interface relationship.

Function Types

Functions are first-class values in Forge. They can be stored in variables, passed as arguments, returned from other functions, and placed in data structures.

Named Functions

A named function is declared with fn (classic) or define (natural):

fn add(a, b) {
    return a + b
}

define multiply(a, b) {
    return a * b
}

Named functions are hoisted within their scope — they can be called before their textual definition in the source file.

Anonymous Functions (Closures)

An anonymous function is created with the fn keyword in expression position:

let double = fn(x) { return x * 2 }
say double(21)  // 42

Anonymous functions are also called closures because they capture variables from their enclosing scope.

Closure Semantics

Closures capture variables from the enclosing scope by reference. The closure retains access to the captured variables for its entire lifetime:

fn make_counter() {
    let mut count = 0
    return fn() {
        count = count + 1
        return count
    }
}

let counter = make_counter()
say counter()  // 1
say counter()  // 2
say counter()  // 3

Each call to make_counter() creates a new independent closure with its own count variable.

Factory Pattern

Closures are commonly used to create specialized functions:

fn make_adder(n) {
    return fn(x) {
        return x + n
    }
}

let add5 = make_adder(5)
let add10 = make_adder(10)
say add5(3)   // 8
say add10(3)  // 13

Functions as Arguments (Higher-Order Functions)

Functions can be passed as arguments to other functions:

fn apply(f, value) {
    return f(value)
}

fn square(x) { return x * x }
say apply(square, 7)  // 49

The built-in map, filter, reduce, and sort functions all accept function arguments:

let nums = [1, 2, 3, 4, 5]
let doubled = map(nums, fn(x) { return x * 2 })
say doubled  // [2, 4, 6, 8, 10]

Functions in Data Structures

Functions can be stored in arrays and objects:

fn add(a, b) { return a + b }
fn sub(a, b) { return a - b }

let ops = [add, sub]
say ops[0](10, 3)  // 13
say ops[1](10, 3)  // 7

let handlers = {
    greet: fn(name) { return "Hello, {name}!" },
    farewell: fn(name) { return "Goodbye, {name}!" }
}
say handlers.greet("World")  // Hello, World!

Type-Annotated Functions

Function parameters and return values may carry type annotations:

fn add(a: Int, b: Int) -> Int {
    return a + b
}

fn format_price(amount: Float) -> String {
    return "${amount}"
}

Annotations are optional and serve as documentation. The optional type checker can use them to report errors before execution.

Return Values

Functions return a value via the return statement. If no return is executed, the function returns null:

fn greet(name) {
    println("Hello, {name}!")
}

let result = greet("World")
say typeof(result)  // Null

A function may return early from any point:

fn classify(n) {
    if n < 0 { return "negative" }
    if n == 0 { return "zero" }
    return "positive"
}

Async Functions

Async functions are declared with async fn (classic) or forge (natural):

// Classic
async fn fetch_data() {
    let resp = await http.get("https://api.example.com/data")
    return resp
}

// Natural
forge fetch_data() {
    let resp = hold http.get("https://api.example.com/data")
    return resp
}

Async functions return a future that must be awaited with await (classic) or hold (natural). See Concurrency for details.

Function Equality

Functions are compared by reference identity, not by their code. Two function values are equal only if they refer to the same function object:

fn f() { return 1 }
let a = f
let b = f
say a == b  // true (same function object)

let c = fn() { return 1 }
say a == c  // false (different function objects)

Algebraic Data Types

Algebraic data types (ADTs) define a type as a fixed set of variants. Each variant may optionally carry data. ADTs enable exhaustive pattern matching — the compiler/runtime can verify that all variants are handled.

Definition

An ADT is defined with the type keyword, listing variants separated by |:

ADTDef → type Identifier = Variant ( | Variant )*

Variant → Identifier ( ( TypeList ) )?

TypeList → Type ( , Type )*

Unit Variants

Variants without data fields are called unit variants:

type Color = Red | Green | Blue

Unit variants are used as simple enumeration values:

set c to Red
say c  // Red

Data Variants

Variants may carry typed data fields:

type Shape = Circle(Float) | Rect(Float, Float)

Data variants are constructed by calling the variant name as a function:

set circle to Circle(5.0)
set rect to Rect(3.0, 4.0)
say circle  // Circle(5.0)
say rect    // Rect(3.0, 4.0)

Mixed Variants

An ADT may freely mix unit variants and data variants:

type Result = Ok(String) | Err(String) | Pending

Construction

Unit variants are referenced by name alone:

let color = Red

Data variants are constructed by calling the variant name with the appropriate arguments:

let shape = Circle(5.0)
let rect = Rect(3.0, 4.0)

The number and types of arguments must match the variant definition.

Pattern Matching

ADT values are destructured using match expressions. Each arm matches a variant and optionally binds its data fields to variables.

Basic Matching

type Color = Red | Green | Blue

let c = Red

match c {
    Red => say "Red!"
    Green => say "Green!"
    Blue => say "Blue!"
}

Destructuring Data Variants

Data fields are bound to named variables in the match arm:

type Shape = Circle(Float) | Rect(Float, Float)

define describe_shape(s) {
    match s {
        Circle(r) => {
            say "Circle with radius {r}, area = {3.14159 * r * r}"
        }
        Rect(w, h) => {
            say "Rectangle {w}x{h}, area = {w * h}"
        }
    }
}

describe_shape(Circle(5.0))
// Output: Circle with radius 5.0, area = 78.53975

describe_shape(Rect(3.0, 4.0))
// Output: Rectangle 3.0x4.0, area = 12.0

Match as Expression

match can be used as an expression that returns a value:

let area = match shape {
    Circle(r) => 3.14159 * r * r
    Rect(w, h) => w * h
}

Exhaustiveness

A match expression on an ADT should handle all variants. If a variant is missing, the runtime will produce an error when an unhandled variant is encountered.

type Color = Red | Green | Blue

// This handles all variants
match c {
    Red => say "Red!"
    Green => say "Green!"
    Blue => say "Blue!"
}

Wildcard Pattern

The _ pattern matches any value, serving as a catch-all:

match c {
    Red => say "It's red"
    _ => say "It's not red"
}

Built-in ADTs

Forge provides two built-in algebraic types:

• Option: Some(value) | None — see Option and Result
• Result: Ok(value) | Err(message) — see Option and Result

These follow the same pattern matching conventions as user-defined ADTs:

let x = Some(42)

match x {
    Some(val) => say "Got: {val}"
    None => say "Nothing"
}

Scope

Variant constructors (e.g., Red, Circle, Some, Ok) are introduced into the scope where the type definition appears. For built-in types like Option and Result, the constructors are globally available.

Option and Result

Forge provides two built-in wrapper types for representing optional values and fallible operations: Option and Result. These types enable explicit, composable error handling without exceptions.

Option Type

The Option type represents a value that may or may not be present.

Variants

Construction

let x = Some(42)
let y = None

Both Some and None are globally available constructors.

Inspection

let x = Some(42)
say is_some(x)  // true
say is_none(x)  // false

let y = None
say is_some(y)  // false
say is_none(y)  // true

Pattern Matching

Option values are destructured with match:

let value = Some(42)

match value {
    Some(v) => say "Got: {v}"
    None => say "Nothing"
}

Unwrapping

let x = Some(42)
say unwrap(x)          // 42
say unwrap_or(x, 0)    // 42

let y = None
say unwrap_or(y, 0)    // 0
// unwrap(y) would crash with an error

Result Type

The Result type represents the outcome of an operation that may succeed or fail.

Variants

Construction

let success = Ok(42)
let failure = Err("something went wrong")

Result constructors accept both cases: Ok(42) and ok(42) are equivalent, as are Err("msg") and err("msg").

Inspection

let result = Ok(42)
say is_ok(result)   // true
say is_err(result)  // false

Pattern Matching

Result values are destructured with match:

fn parse_number(s) {
    let n = int(s)
    if n == null {
        return Err("invalid number: {s}")
    }
    return Ok(n)
}

match parse_number("42") {
    Ok(n) => say "Parsed: {n}"
    Err(msg) => say "Error: {msg}"
}

Unwrapping

let result = Ok(42)
say unwrap(result)          // 42
say unwrap_or(result, 0)    // 42

let err = Err("failed")
say unwrap_or(err, 0)       // 0

The ? Operator

The ? postfix operator provides concise error propagation. When applied to a Result value:

• If the value is Ok(v), the ? unwraps it to v and execution continues.
• If the value is Err(e), the enclosing function immediately returns Err(e).

fn read_config(path) {
    if !fs.exists(path) {
        return Err("config file not found")
    }
    return Ok(fs.read(path))
}

fn start_server() {
    let config = read_config("server.toml")?
    say "Starting with config: {config}"
    return Ok(true)
}

match start_server() {
    Ok(_) => say "Server started"
    Err(msg) => say "Failed: {msg}"
}

The ? operator can only be used inside functions that return Result. It is syntactic sugar for:

let result = read_config("server.toml")
if is_err(result) {
    return result
}
let config = unwrap(result)

The must Keyword

The must keyword is an assertion on Result values. It unwraps an Ok value or crashes the program with a clear error message on Err:

let config = must read_config("server.toml")

Use must for errors that are truly unrecoverable — situations where the program cannot meaningfully continue (e.g., missing configuration, failed database connection).

The safe Block

The safe block catches any errors within its body and returns null instead of crashing:

safe {
    let result = risky_operation()
    say result
}
// If risky_operation() fails, execution continues here

safe is a statement-level construct. It does not return a value and cannot be used as an expression.

Idiomatic Error Handling

The recommended patterns for error handling in Forge, in order of preference:

1. ? for propagation. Pass errors up the call stack to a centralized handler.
2. match for handling. Explicitly handle both Ok and Err at the appropriate level.
3. unwrap_or for defaults. Provide a fallback when an error is acceptable.
4. must for fatal errors. Crash with a clear message when recovery is impossible.
5. safe for silencing. Suppress errors only when the operation is truly optional.

Type Conversions

Forge is dynamically typed and does not perform implicit type coercion between incompatible types (with the exception of Int to Float promotion in mixed arithmetic). Explicit conversion functions are provided for converting between types.

Conversion Functions

str(value) — Convert to String

Converts any value to its string representation.

say str(42)       // "42"
say str(3.14)     // "3.14"
say str(true)     // "true"
say str(null)     // "null"
say str([1, 2])   // "[1, 2]"

str() never fails. Every Forge value has a string representation.

int(value) — Convert to Int

Converts a value to a 64-bit signed integer.

say int("42")     // 42
say int("100")    // 100
say int(3.14)     // 3 (truncates toward zero)
say int(true)     // 1
say int(false)    // 0

If the input string cannot be parsed as an integer, int() produces a runtime error. Always validate user input before converting.

float(value) — Convert to Float

Converts a value to a 64-bit floating-point number.

say float("3.14")  // 3.14
say float(42)      // 42.0
say float(true)    // 1.0
say float(false)   // 0.0

If the input string cannot be parsed as a float, float() produces a runtime error.

Type Inspection Functions

typeof(value) — Get Type Name

Returns a string describing the runtime type of a value.

say typeof(42)                  // Int
say typeof(3.14)                // Float
say typeof("hello")             // String
say typeof(true)                // Bool
say typeof(null)                // Null
say typeof([1, 2, 3])           // Array
say typeof({ name: "Alice" })   // Object

For struct instances, typeof() returns the struct name:

thing Point { x: Int, y: Int }
let p = Point { x: 1, y: 2 }
say typeof(p)   // Point

For functions:

fn f() { return 1 }
say typeof(f)   // Function

type(value) — Alias for typeof

The type() function is an alias for typeof(). Both return identical results:

let value = 3.14
if type(value) == "Float" {
    say "It's a float"
}

Implicit Conversions

Forge performs very few implicit conversions:

Int-to-Float Promotion

When an arithmetic operator has one Int operand and one Float operand, the integer is implicitly promoted to a float. The result is a Float:

say 5 + 2.0    // 7.0 (Int promoted to Float)
say 10 / 3.0   // 3.3333333333333335

String Interpolation

Inside string interpolation ({expr}), the expression result is implicitly converted to a string using the same logic as str():

let n = 42
say "The answer is {n}"  // "The answer is 42"

Truthiness

When a value is used in a boolean context (e.g., if condition), it is evaluated for truthiness (see Types). This is not a type conversion — the value itself is not changed. It is a contextual interpretation.

No Other Implicit Coercion

Operations between incompatible types (e.g., adding a string and an integer) produce a runtime error. Explicit conversion is required:

// Error: cannot add String and Int
// say "age: " + 30

// Correct: convert explicitly
say "age: " + str(30)

Expressions

An expression is a syntactic construct that evaluates to a value. Every expression in Forge has a type and produces a result when evaluated.

Forge distinguishes expressions from statements: expressions produce values, statements produce effects. An expression can appear anywhere a value is expected – as the right-hand side of a variable binding, as a function argument, or as the body of a when arm.

Expression Categories

Literal Expressions

Literal expressions produce values directly from source text.

String literals support interpolation with embedded expressions.

Identifier Expressions

An identifier evaluates to the value bound to that name in the current scope.

let x = 10
say x       // evaluates to 10

If the identifier is not in scope, evaluation produces a runtime error.

Arithmetic Expressions

Binary operations on numeric values: +, -, *, /, %. The + operator also performs string concatenation.

See Arithmetic.

Comparison and Logical Expressions

Comparison operators (==, !=, <, >, <=, >=) produce boolean values. Logical operators (and/&&, or/||, not/!) combine boolean expressions with short-circuit evaluation.

See Comparison and Logical.

Field Access Expressions

Dot notation accesses fields on objects and struct instances. Embedded fields are resolved through delegation.

let user = { name: "Alice", age: 30 }
say user.name   // "Alice"

See Field Access.

Index Expressions

Bracket notation accesses elements by position in arrays or by key in objects.

let items = [10, 20, 30]
say items[0]    // 10

let obj = { x: 1 }
say obj["x"]    // 1

Method Call Expressions

Method calls use dot notation followed by a function call. Forge resolves methods through a multi-step dispatch chain: object fields, type method tables, embedded field delegation, then known built-in methods.

let names = ["Charlie", "Alice", "Bob"]
say names.sort()    // ["Alice", "Bob", "Charlie"]

See Method Calls.

Function Call Expressions

A function call evaluates a callable expression and applies it to a list of argument expressions.

fn square(n) { n * n }
say square(5)   // 25

Closures and Lambdas

Anonymous functions that capture their enclosing environment.

let double = fn(x) { x * 2 }
say double(5)   // 10

See Closures and Lambdas.

When Guard Expressions

Pattern-matching on a scrutinee value using comparison operators.

let label = when age {
    < 13 -> "child",
    < 18 -> "teen",
    else -> "adult"
}

See When Guards.

Match Expressions

Structural pattern matching with destructuring of algebraic data types.

match shape {
    Circle(r) => say "radius: {r}",
    Rect(w, h) => say "area: {w * h}",
    _ => say "unknown"
}

See Match Expressions.

String Interpolation Expressions

Double-quoted strings with embedded expressions in {...} delimiters.

let name = "world"
say "hello, {name}!"   // "hello, world!"

See String Interpolation.

Pipeline Expressions

The pipe operator |> threads a value through a chain of function calls.

[1, 2, 3, 4, 5]
    |> filter(fn(x) { x > 2 })
    |> map(fn(x) { x * 10 })

Unary Expressions

Unary operators: - (numeric negation) and not/! (logical negation).

let x = -5
let flag = not true

Try Expressions

The ? operator propagates errors from Result values. If the value is Err, evaluation returns early from the enclosing function.

let data = fs.read("config.json")?

Must Expressions

The must keyword unwraps a Result or crashes with a descriptive error message.

let data = must fs.read("config.json")

Struct Initialization Expressions

Creates an instance of a named struct type.

thing Point { x: int, y: int }
let p = Point { x: 10, y: 20 }

Spread Expressions

The ... operator expands an array or object in a literal context.

let base = [1, 2, 3]
let extended = [...base, 4, 5]

Expression Evaluation Order

Forge evaluates expressions left to right. In a binary expression a + b, a is evaluated before b. In a function call f(x, y), f is evaluated first, then x, then y.

Logical operators and/&& and or/|| use short-circuit evaluation: the right operand is not evaluated if the left operand determines the result. See Comparison and Logical for details.

Arithmetic Expressions

Arithmetic expressions perform numeric computations and string concatenation.

Operators

Integer Arithmetic

Integer arithmetic uses 64-bit signed integers (i64). Operations that overflow follow Rust’s default behavior (panic in debug, wrap in release).

let a = 10 + 3      // 13
let b = 10 - 3      // 7
let c = 10 * 3      // 30
let d = 10 / 3      // 3 (truncated toward zero)
let e = 10 % 3      // 1

Integer Division

Integer division truncates toward zero. The result is always an integer when both operands are integers.

say 7 / 2       // 3
say -7 / 2      // -3
say 7 / -2      // -3

Float Arithmetic

Float arithmetic uses 64-bit IEEE 754 double-precision floating-point numbers (f64).

let a = 3.14 + 2.0     // 5.14
let b = 10.0 / 3.0     // 3.3333333333333335
let c = 2.5 % 1.0      // 0.5

Mixed Arithmetic

When one operand is int and the other is float, the integer is promoted to a float before the operation. The result is always float.

say 5 + 2.0      // 7.0
say 10 / 3.0     // 3.3333333333333335
say 3 * 1.5      // 4.5

String Concatenation

The + operator concatenates two strings. If one operand is a string and the other is not, the non-string operand is converted to its string representation.

say "hello" + " " + "world"    // "hello world"
say "count: " + str(42)        // "count: 42"

For embedding expressions in strings, prefer string interpolation:

say "count: {42}"              // "count: 42"

Unary Negation

The - prefix operator negates a numeric value.

let x = 5
say -x          // -5
say -3.14       // -3.14

Operator Precedence

Arithmetic operators follow standard mathematical precedence:

1. Unary - (highest)
2. *, /, %
3. +, - (lowest among arithmetic)

Parentheses override precedence:

say 2 + 3 * 4       // 14
say (2 + 3) * 4     // 20

See the Operator Precedence appendix for the full precedence table including all operator categories.

Division by Zero

Dividing by zero produces a runtime error:

say 10 / 0      // runtime error: division by zero

Float division by zero follows IEEE 754 rules and may produce infinity or NaN.

Comparison and Logical Expressions

Comparison operators produce boolean values by comparing two operands. Logical operators combine boolean expressions using short-circuit evaluation.

Comparison Operators

Equality

The == operator tests structural equality. Two values are equal if they have the same type and the same content.

say 1 == 1              // true
say "abc" == "abc"      // true
say [1, 2] == [1, 2]   // true
say null == null        // true
say 1 == 1.0            // true (numeric promotion)
say 1 == "1"            // false (different types)

Numeric Comparison

Integers and floats can be compared directly. When comparing an int with a float, the integer is promoted to float.

say 3 < 5           // true
say 3.14 > 2.71     // true
say 10 >= 10        // true
say 5 <= 3          // false
say 1 < 2.5         // true (int promoted to float)

String Comparison

Strings are compared lexicographically (by Unicode code points).

say "apple" < "banana"      // true
say "abc" == "abc"          // true
say "a" < "b"               // true

Null Comparison

Only null is equal to null. Comparing null with any other value using == yields false.

say null == null        // true
say null == 0           // false
say null == ""          // false
say null == false       // false

Logical Operators

Forge supports two syntactic forms for each logical operator. Both forms are equivalent.

Logical AND

Returns true if both operands are truthy. Uses short-circuit evaluation: if the left operand is falsy, the right operand is not evaluated.

say true and true       // true
say true and false      // false
say false and true      // false (right side not evaluated)

Logical OR

Returns true if either operand is truthy. Uses short-circuit evaluation: if the left operand is truthy, the right operand is not evaluated.

say false or true       // true
say true or false       // true (right side not evaluated)
say false or false      // false

Logical NOT

Returns the boolean negation of the operand. Applies truthiness rules.

say not true        // false
say not false       // true
say !null           // true
say not 0           // false (0 is truthy in Forge)

Short-Circuit Evaluation

Short-circuit evaluation means the right operand of and/&& or or/|| is only evaluated when necessary.

// The function is never called because the left side is false
false and expensive_computation()

// The function is never called because the left side is true
true or expensive_computation()

This is significant when the right operand has side effects:

let x = null
// Safe: the right side is not evaluated when x is null
x != null and x.name == "Alice"

Truthiness Rules

Forge uses the following truthiness rules when a value appears in a boolean context (such as an if condition or a logical operator):

Notably, the following values are truthy (unlike some other languages):

• 0 (zero)
• "" (empty string)
• [] (empty array)
• {} (empty object)

if 0 {
    say "zero is truthy"    // this executes
}

if "" {
    say "empty string is truthy"    // this executes
}

if null {
    say "unreachable"
} otherwise {
    say "null is falsy"     // this executes
}

Operator Precedence

From highest to lowest precedence:

1. not / ! (unary)
2. <, >, <=, >=
3. ==, !=
4. and / &&
5. or / ||

say true or false and false     // true (and binds tighter than or)
say not false and true          // true (not binds tightest)

See the Operator Precedence appendix for the full table.

String Interpolation

Double-quoted string literals in Forge support interpolation: embedding arbitrary expressions inside { and } delimiters. The expressions are evaluated at runtime and their results are converted to string representations and spliced into the surrounding text.

Syntax

" ... {expression} ... "

Any valid Forge expression may appear between the braces.

Basic Usage

let name = "Forge"
say "Hello, {name}!"           // "Hello, Forge!"

let x = 10
let y = 20
say "{x} + {y} = {x + y}"     // "10 + 20 = 30"

Arbitrary Expressions

The interpolated expression is not limited to identifiers. Any expression that produces a value is permitted, including function calls, arithmetic, method calls, and field access.

say "length: {len([1, 2, 3])}"             // "length: 3"
say "upper: {"hello".upper()}"             // "upper: HELLO"
say "sum: {1 + 2 + 3}"                     // "sum: 6"
say "type: {typeof(42)}"                    // "type: int"

Value Conversion

Interpolated values are converted to their string representation using the same rules as the str() builtin:

Escape Sequences

The following escape sequences are recognized inside double-quoted strings:

To include a literal { character without triggering interpolation, escape it:

say "use \{braces\} for interpolation"
// Output: use {braces} for interpolation

Nesting

Interpolated expressions may themselves contain string literals with interpolation, though this is discouraged for readability:

let items = ["a", "b", "c"]
say "result: {join(items, ", ")}"

Non-Interpolated Strings

Single-quoted strings do not support interpolation. Use single quotes when the string contains braces that should be treated literally:

say 'no {interpolation} here'
// Output: no {interpolation} here

Empty Interpolation

An empty interpolation {} is not valid and produces a parse error.

Implementation Notes

String interpolation is parsed into a StringInterp AST node containing a sequence of StringPart elements, each being either a Literal (raw text) or an Expr (an evaluated expression). At runtime, all parts are evaluated and concatenated to produce the final string value.

Field Access

The dot operator (.) accesses fields on objects and struct instances. Forge resolves field access through direct lookup followed by delegation through embedded fields.

Syntax

expression.identifier

The left operand is evaluated to produce an object. The identifier names the field to retrieve.

Object Field Access

Objects are unordered collections of key-value pairs. Dot notation retrieves a value by key.

let user = { name: "Alice", age: 30 }
say user.name       // "Alice"
say user.age        // 30

If the field does not exist on the object, a runtime error is produced:

let user = { name: "Alice" }
say user.email      // runtime error: no field 'email' on object

Struct Field Access

Struct instances (created from thing/struct definitions) are objects with a __type__ field. Field access works identically.

thing Point { x: int, y: int }
let p = Point { x: 10, y: 20 }
say p.x     // 10
say p.y     // 20

Embedded Field Delegation

When a struct uses has to embed another type, field access delegates to the embedded field if the field is not found directly on the outer object.

thing Base { id: int }
thing Extended {
    has base: Base
    name: string
}

let e = Extended { base: Base { id: 1 }, name: "test" }
say e.name      // "test" (direct)
say e.id        // 1 (delegated to e.base.id)

Resolution Order

Field access resolves in this order:

1. Direct field lookup: Check if the object has a field with the given name.
2. Embedded field delegation: If the object has a __type__, check each embedded field’s sub-object for the field name. Embedded fields are checked in definition order.

If neither step finds the field, a runtime error is produced.

Chaining

Field access expressions can be chained to traverse nested structures.

let config = {
    server: {
        host: "localhost",
        port: 8080
    }
}
say config.server.host      // "localhost"
say config.server.port      // 8080

Built-in Field Access on Primitives

Certain built-in fields are available on primitive types:

Strings

let s = "  Hello  "
say s.len       // 9
say s.upper     // "  HELLO  "
say s.trim      // "Hello"

Arrays

let items = [1, 2, 3]
say items.len   // 3

Index-Based Access

For dynamic key access, use bracket notation instead of dot notation:

let obj = { name: "Alice" }
let key = "name"
say obj[key]        // "Alice"

Bracket notation works on both objects (with string keys) and arrays (with integer indices).

Method Calls

A method call uses dot notation to invoke a function on a receiver value. Forge resolves method calls through a multi-step dispatch process.

Syntax

expression.method(arguments)

The left operand (the receiver) is evaluated first, then the method is resolved, then arguments are evaluated left to right.

Method Dispatch

When evaluating obj.method(args), the interpreter follows this resolution order:

1. Object Field Lookup

If the receiver is an object and has a field named method whose value is callable (a function or closure), that field is invoked directly.

let obj = {
    greet: fn(name) { "hello, {name}" }
}
say obj.greet("world")      // "hello, world"

2. Static Method Lookup

If the receiver is a struct type reference (not an instance), static methods registered via give/impl blocks are checked.

thing Counter { value: int }

give Counter {
    fn new() {
        Counter { value: 0 }
    }
}

let c = Counter.new()   // static method call

3. Instance Method Lookup (method_tables)

If the receiver is a typed object (has a __type__ field), the interpreter looks up the type name in the global method table. Methods registered via give/impl blocks are found here. The receiver is automatically passed as the first argument (self).

thing Circle { radius: float }

give Circle {
    fn area(self) {
        3.14159 * self.radius * self.radius
    }
}

let c = Circle { radius: 5.0 }
say c.area()    // 78.53975

4. Embedded Field Delegation

If the receiver is a typed object and no method is found in step 3, the interpreter checks embedded fields (declared with has). For each embedded field, the interpreter looks up the embedded type’s method table. If a match is found, the embedded sub-object is passed as self instead of the outer object.

thing Animal { name: string }
give Animal {
    fn speak(self) { "{self.name} speaks" }
}

thing Pet {
    has animal: Animal
    owner: string
}

let p = Pet { animal: Animal { name: "Rex" }, owner: "Alice" }
say p.speak()   // "Rex speaks" (delegated to Animal.speak)

5. Built-in String Methods

Strings have a small set of built-in methods that are resolved directly without going through the method table:

say "hello".upper()     // "HELLO"
say "  hi  ".trim()     // "hi"
say "abc".chars()       // ["a", "b", "c"]

6. Known Built-in Methods

If none of the above steps match, Forge checks a set of known built-in method names. If the method name matches, the call is rewritten as a function call with the receiver prepended to the argument list: obj.method(args) becomes method(obj, args).

This allows calling built-in functions with method syntax:

let nums = [3, 1, 2]
say nums.sort()             // [1, 2, 3]
say nums.map(fn(x) { x * 2 })  // [6, 2, 4]
say nums.filter(fn(x) { x > 1 })   // [3, 2]

let text = "hello world"
say text.split(" ")        // ["hello", "world"]
say text.starts_with("hello")  // true

The full list of known built-in methods includes: map, filter, reduce, sort, reverse, push, pop, len, contains, keys, values, enumerate, split, join, replace, find, flat_map, has_key, get, pick, omit, merge, entries, from_entries, starts_with, ends_with, upper, lower, trim, substring, index_of, last_index_of, pad_start, pad_end, capitalize, title, repeat_str, count, sum, min_of, max_of, any, all, unique, zip, flatten, group_by, chunk, slice, slugify, snake_case, camel_case, sample, shuffle, partition, diff.

Self Parameter

Methods defined in give/impl blocks receive the receiver as their first argument, conventionally named self. This parameter must be declared explicitly.

thing Rect { w: int, h: int }

give Rect {
    fn area(self) {
        self.w * self.h
    }
    fn scale(self, factor) {
        Rect { w: self.w * factor, h: self.h * factor }
    }
}

Method Chaining

Method calls can be chained. Each call in the chain returns a value that becomes the receiver for the next call.

let result = [5, 2, 8, 1, 9]
    .sort()
    .filter(fn(x) { x > 3 })
    .map(fn(x) { x * 10 })
// result: [50, 80, 90]

Resolution Failure

If method resolution exhausts all steps without finding a match, a runtime error is produced:

let x = 42
say x.nonexistent()     // runtime error: unknown method 'nonexistent'

Closures and Lambdas

A closure (also called a lambda) is an anonymous function expression that captures variables from its enclosing scope. Closures are first-class values: they can be stored in variables, passed as arguments, and returned from functions.

Syntax

fn(parameters) { body }

The keyword fn introduces a closure. Parameters are comma-separated identifiers enclosed in parentheses. The body is a block of statements.

let double = fn(x) { x * 2 }
say double(5)       // 10

No-Parameter Closures

Closures with no parameters use empty parentheses:

let greet = fn() { "hello" }
say greet()         // "hello"

Implicit Return

The last expression in a closure body is its return value. An explicit return statement is also permitted but rarely needed.

let add = fn(a, b) { a + b }       // implicit return
say add(3, 4)                       // 7

let abs = fn(x) {
    if x < 0 {
        return -x                   // explicit return
    }
    x
}

Capture Semantics

Closures capture variables from their enclosing scope by reference. Changes to captured variables are visible inside the closure, and mutations inside the closure affect the outer scope.

let mut count = 0
let increment = fn() {
    count = count + 1
    count
}
say increment()     // 1
say increment()     // 2
say count           // 2

Capture at Definition Time

The closure captures a reference to the variable’s binding, not its current value. The variable is resolved at the time the closure is called, not when it is defined.

let mut x = 10
let get_x = fn() { x }
say get_x()         // 10

x = 20
say get_x()         // 20

Higher-Order Functions

Closures enable higher-order programming patterns. A higher-order function either takes a function as an argument or returns one.

Closures as Arguments

Many built-in functions accept closures:

let nums = [1, 2, 3, 4, 5]

let evens = filter(nums, fn(x) { x % 2 == 0 })
say evens       // [2, 4]

let doubled = map(nums, fn(x) { x * 2 })
say doubled     // [2, 4, 6, 8, 10]

let total = reduce(nums, 0, fn(acc, x) { acc + x })
say total       // 15

Returning Closures

Functions can return closures, creating function factories:

fn make_adder(n) {
    fn(x) { x + n }
}

let add5 = make_adder(5)
say add5(10)    // 15
say add5(20)    // 25

Closures in Method Syntax

Closures integrate naturally with method-style calls:

let names = ["Charlie", "Alice", "Bob"]
let sorted = names.sort(fn(a, b) { a < b })
say sorted      // ["Alice", "Bob", "Charlie"]

Multi-Statement Bodies

Closure bodies can contain multiple statements. The last expression is the return value.

let process = fn(items) {
    let filtered = filter(items, fn(x) { x > 0 })
    let doubled = map(filtered, fn(x) { x * 2 })
    doubled
}
say process([-1, 2, -3, 4])    // [4, 8]

Closures vs Named Functions

Closures and named functions (fn name(...) { } / define name(...) { }) differ in two ways:

1. Naming: Named functions are bound to a name in the current scope. Closures are anonymous and must be assigned to a variable explicitly.
2. Hoisting: Named functions are available throughout their defining scope. Closures are only available after the variable assignment that holds them.

Both named functions and closures capture their environment identically.

Recursive Closures

A closure can call itself recursively if it is assigned to a variable that is in scope at the time of the call:

let factorial = fn(n) {
    if n <= 1 { 1 }
    else { n * factorial(n - 1) }
}
say factorial(5)    // 120

Type Annotations

Closures do not currently support parameter or return type annotations. The types of parameters and the return value are inferred at runtime.

When Guards

A when expression performs multi-way branching on a scrutinee value using comparison operators. Each arm specifies a comparison operation applied to the scrutinee; the first matching arm’s result expression is returned.

Syntax

when expression {
    op value -> result,
    op value -> result,
    else -> result
}

The scrutinee is the expression after when. Each arm consists of a comparison operator, a value to compare against, the -> arrow, and a result expression. The optional else arm matches when no other arm does.

Basic Usage

let label = when age {
    < 13 -> "child",
    < 18 -> "teen",
    < 65 -> "adult",
    else -> "senior"
}
say label

The scrutinee age is evaluated once. Each arm’s operator and value are applied to the scrutinee in order. The first arm whose comparison returns true provides the result.

Comparison Operators in Arms

Arms support any comparison operator:

let status = when code {
    == 200 -> "ok",
    == 404 -> "not found",
    == 500 -> "server error",
    >= 400 -> "client error",
    else -> "unknown"
}

Evaluation Semantics

1. The scrutinee expression is evaluated exactly once.
2. Arms are tested top to bottom.
3. For each arm, the arm’s comparison operator is applied with the scrutinee as the left operand and the arm’s value as the right operand.
4. The first arm that produces true determines the result: its result expression is evaluated and returned.
5. If no arm matches and an else arm is present, the else result is returned.
6. If no arm matches and no else arm is present, the when expression evaluates to null.

When as an Expression

when produces a value and can be used anywhere an expression is expected:

say when score {
    >= 90 -> "A",
    >= 80 -> "B",
    >= 70 -> "C",
    else -> "F"
}

let discount = when items {
    > 100 -> 0.20,
    > 50 -> 0.10,
    > 10 -> 0.05,
    else -> 0.0
}

When as a Statement

when can also appear at the statement level:

when temperature {
    > 100 -> say "boiling",
    < 0 -> say "freezing",
    else -> say "normal"
}

Arm Result Expressions

Each arm’s result is a single expression. For multi-statement logic, use a block expression or call a function:

let result = when level {
    > 10 -> {
        let bonus = level * 2
        bonus + 100
    },
    else -> 0
}

The else Arm

The else arm is a catch-all that matches when no other arm does. It must be the last arm if present.

let kind = when x {
    > 0 -> "positive",
    < 0 -> "negative",
    else -> "zero"
}

If no else arm is provided and no arm matches, the when expression evaluates to null.

Differences from Match

when guards and match expressions serve different purposes:

See Match Expressions for structural pattern matching.

Match Expressions

A match expression performs structural pattern matching on a value. Each arm specifies a pattern; the first arm whose pattern matches the scrutinee has its body evaluated.

Syntax

match expression {
    pattern => body,
    pattern => body,
    ...
}

The scrutinee is the expression after match. Each arm consists of a pattern, the => arrow, and a body (one or more statements). Arms are separated by commas.

Patterns

Forge supports the following pattern forms:

Wildcard Pattern

The underscore _ matches any value and binds nothing.

match x {
    _ => say "matched anything"
}

Literal Pattern

A literal value matches if the scrutinee is equal to that value.

match color {
    "red" => say "stop",
    "green" => say "go",
    "yellow" => say "caution",
    _ => say "unknown"
}

Binding Pattern

A bare identifier binds the matched value to that name within the arm body.

match value {
    x => say "got: {x}"
}

Constructor Pattern

A constructor pattern matches an algebraic data type (ADT) variant and destructures its fields. The pattern names the variant and provides sub-patterns for each field.

type Shape {
    Circle(float)
    Rect(float, float)
    Point
}

let s = Circle(5.0)

match s {
    Circle(r) => say "circle with radius {r}",
    Rect(w, h) => say "rectangle {w} x {h}",
    Point => say "a point",
    _ => say "unknown shape"
}

Nested constructor patterns are supported:

type Expr {
    Num(int)
    Add(Expr, Expr)
}

match expr {
    Add(Num(a), Num(b)) => say "sum: {a + b}",
    Num(n) => say "number: {n}",
    _ => say "complex expression"
}

Evaluation Semantics

1. The scrutinee expression is evaluated exactly once.
2. Arms are tested top to bottom.
3. For each arm, the pattern is matched against the scrutinee:
   • Wildcard: Always matches.
   • Literal: Matches if the scrutinee equals the literal value.
   • Binding: Always matches; binds the scrutinee to the identifier.
   • Constructor: Matches if the scrutinee is an ADT value with the same variant name and the correct number of fields, and all sub-patterns recursively match.
4. The first matching arm’s body is evaluated. Bindings introduced by the pattern are in scope for the body.
5. If no arm matches, the match expression evaluates to null.

Match as an Expression

match produces a value and can be used in expression position:

let area = match shape {
    Circle(r) => 3.14159 * r * r,
    Rect(w, h) => w * h,
    _ => 0.0
}

Match as a Statement

match can appear at the statement level:

match event {
    Click(x, y) => handle_click(x, y),
    KeyPress(key) => handle_key(key),
    _ => {}
}

Multi-Statement Arm Bodies

Arm bodies can contain multiple statements. The last expression in the block is the value of the arm.

let result = match data {
    Some(value) => {
        let processed = transform(value)
        validate(processed)
        processed
    },
    None => default_value()
}

ADT Matching

Match is the primary mechanism for working with algebraic data types (see Algebraic Data Types).

type Result {
    Ok(any)
    Err(string)
}

fn handle(r) {
    match r {
        Ok(value) => say "success: {value}",
        Err(msg) => say "error: {msg}"
    }
}

Exhaustiveness

Forge does not currently enforce exhaustive matching. If no arm matches the scrutinee, the match expression evaluates to null. Use a wildcard _ arm as the final arm to ensure all cases are handled.

Differences from When Guards

See When Guards for operator-based branching.

Statements

A statement is a syntactic construct that performs an action. Unlike expressions, statements do not produce values (with the exception of expression statements, where an expression is evaluated for its side effects and the result is discarded).

A Forge program is a sequence of statements executed top to bottom.

Statement Categories

Declarations

Declarations introduce new names into the current scope.

• Variable declaration: let x = expr / set x to expr – binds a value to a name. See Variable Declaration.
• Function declaration: fn name(params) { body } / define name(params) { body } – binds a function to a name. See Function Declaration.
• Destructuring declaration: let {a, b} = obj / unpack {a, b} from obj – binds multiple names from a compound value. See Variable Declaration.

Assignments

Assignments change the value of an existing binding.

• Simple assignment: x = expr / change x to expr
• Compound assignment: x += expr, x -= expr, x *= expr, x /= expr
• Field assignment: obj.field = expr
• Index assignment: arr[i] = expr

See Assignment.

Control Flow

Control flow statements direct the order of execution.

• Conditional: if condition { body } with optional else/otherwise/nah clauses. See Control Flow.
• When guards: when expr { arms } – multi-way branch on a value. See When Guards.
• Match: match expr { arms } – structural pattern matching. See Match Expressions.

Loops

Loop statements execute a body repeatedly.

• For-in: for item in collection { body } / for each item in collection { body }
• While: while condition { body }
• Loop: loop { body } – infinite loop, exit with break
• Repeat: repeat N times { body } – counted loop

See Loops.

Jump Statements

Jump statements transfer control to a different point in the program.

• return: Exits the current function, optionally with a value.
• break: Exits the innermost loop.
• continue: Skips to the next iteration of the innermost loop.

See Return, Break, Continue.

Module Statements

Module statements manage code organization across files.

• import: import "file.fg" – executes another file and imports its definitions.

See Import and Export.

Expression Statements

Any expression can appear as a statement. The expression is evaluated and its result is discarded. This is how function calls with side effects are written.

say "hello"             // function call as statement
push(items, 42)         // side-effecting call

Statement Terminators

Forge does not require semicolons or other explicit statement terminators. Statements are separated by newlines. Multiple statements may appear on a single line if they are unambiguous to the parser.

let x = 10
let y = 20
say x + y

Blocks

A block is a sequence of statements enclosed in { and }. Blocks appear as the body of functions, loops, conditionals, and other compound statements. Blocks create a new scope: variables declared inside a block are not visible outside it.

let x = "outer"
{
    let x = "inner"
    say x           // "inner"
}
say x               // "outer"

Variable Declaration

Variable declarations introduce new bindings in the current scope. Forge supports both classic and natural syntax forms, with optional mutability and destructuring.

Immutable Variables

By default, variables are immutable. An immutable binding cannot be reassigned after initialization.

Classic Syntax

let name = "Alice"
let age = 30
let items = [1, 2, 3]

Natural Syntax

set name to "Alice"
set age to 30
set items to [1, 2, 3]

Both forms are semantically identical. The variable is bound to the result of evaluating the right-hand expression.

Mutable Variables

To allow a variable to be reassigned after its initial declaration, use the mut keyword.

Classic Syntax

let mut count = 0
count = count + 1       // allowed

Natural Syntax

set mut count to 0
change count to count + 1   // allowed

Attempting to reassign an immutable variable produces a runtime error:

let x = 10
x = 20          // runtime error: cannot reassign immutable variable 'x'

Type Annotations

Variable declarations may include an optional type annotation after the variable name:

let name: string = "Alice"
let age: int = 30
let ratio: float = 0.5

Type annotations are checked by the type checker when enabled. They do not affect runtime behavior in the interpreter.

Initializer Expressions

The right-hand side of a variable declaration is any valid expression:

let sum = 1 + 2 + 3
let greeting = "Hello, {name}!"
let data = fs.read("config.json")
let result = compute(x, y)

Every variable declaration requires an initializer. There is no uninitialized variable syntax.

Destructuring

Forge supports destructuring assignment for objects and arrays.

Object Destructuring

Classic Syntax

let person = { name: "Alice", age: 30, city: "NYC" }
let { name, age } = person
say name    // "Alice"
say age     // 30

Natural Syntax

let person = { name: "Alice", age: 30, city: "NYC" }
unpack { name, age } from person
say name    // "Alice"
say age     // 30

Object destructuring extracts the named fields from an object and binds them to variables with the same names.

Array Destructuring

let coords = [10, 20, 30]
let [x, y, z] = coords
say x   // 10
say y   // 20
say z   // 30

Rest Pattern

Array destructuring supports a rest pattern to capture remaining elements:

let items = [1, 2, 3, 4, 5]
let [first, ...rest] = items
say first   // 1
say rest    // [2, 3, 4, 5]

Scope

Variables are scoped to the block in which they are declared. A variable declared inside an if body, loop body, or function body is not accessible outside that block.

if true {
    let x = 42
    say x       // 42
}
// x is not accessible here

Inner scopes can shadow variables from outer scopes:

let x = "outer"
{
    let x = "inner"
    say x           // "inner"
}
say x               // "outer"

Multiple Declarations

Each let/set statement declares a single binding (or a destructuring pattern). To declare multiple variables, use separate statements:

let x = 1
let y = 2
let z = 3

Assignment

Assignment statements change the value of an existing mutable binding. The target must have been declared with mut (or let mut / set mut).

Simple Assignment

Classic Syntax

let mut x = 10
x = 20
say x       // 20

Natural Syntax

set mut x to 10
change x to 20
say x       // 20

Both forms evaluate the right-hand expression and store the result in the named variable.

Mutability Requirement

Only variables declared with mut can be reassigned. Attempting to assign to an immutable variable produces a runtime error:

let x = 10
x = 20          // runtime error: cannot reassign immutable variable 'x'

Compound Assignment

Compound assignment operators combine an arithmetic operation with assignment. The target must be mutable.

let mut count = 0
count += 1          // count is 1
count += 5          // count is 6
count *= 2          // count is 12
count -= 3          // count is 9
count /= 3          // count is 3

Compound assignment with += on strings performs concatenation:

let mut msg = "hello"
msg += " world"
say msg     // "hello world"

Field Assignment

Fields on objects and struct instances can be assigned using dot notation:

let mut user = { name: "Alice", age: 30 }
user.age = 31
say user.age    // 31

Nested field assignment is supported:

let mut config = { server: { port: 8080 } }
config.server.port = 3000
say config.server.port  // 3000

Index Assignment

Array elements and object keys can be assigned using bracket notation:

let mut items = [10, 20, 30]
items[1] = 99
say items       // [10, 99, 30]

let mut obj = { a: 1, b: 2 }
obj["a"] = 100
say obj.a       // 100

Assignment Is Not an Expression

In Forge, assignment is a statement, not an expression. Assignment does not produce a value and cannot be used in expression position:

// This is NOT valid:
// let y = (x = 5)

// Use separate statements:
let mut x = 0
x = 5
let y = x

Evaluation Order

In an assignment target = expression, the right-hand expression is evaluated first, then the result is stored in the target location.

For compound assignment target += expression, the current value of the target is read, the operation is performed with the right-hand expression, and the result is stored back.

Control Flow

Control flow statements direct the order of execution based on conditions.

If Statements

The if statement executes a block of code when a condition is truthy.

if temperature > 100 {
    say "boiling"
}

The condition is any expression. It is evaluated using Forge’s truthiness rules: false and null are falsy, everything else is truthy.

If-Else

An else clause provides an alternative block when the condition is falsy. Forge supports three equivalent keywords for the else clause:

Classic: else

if age >= 18 {
    say "adult"
} else {
    say "minor"
}

Natural: otherwise

if age >= 18 {
    say "adult"
} otherwise {
    say "minor"
}

Casual: nah

if age >= 18 {
    say "adult"
} nah {
    say "minor"
}

All three forms are semantically identical. The else block executes when the condition is falsy.

If-Else If Chains

Multiple conditions can be tested in sequence using else if (or otherwise if / nah if):

if score >= 90 {
    say "A"
} else if score >= 80 {
    say "B"
} else if score >= 70 {
    say "C"
} else {
    say "F"
}

Conditions are tested top to bottom. The first truthy condition’s block is executed. If no condition is truthy and an else clause is present, its block executes.

Nested If Statements

If statements can be nested arbitrarily:

if user != null {
    if user.role == "admin" {
        say "admin access"
    } else {
        say "regular access"
    }
} else {
    say "not logged in"
}

Block Scoping

Variables declared inside an if or else block are scoped to that block:

if true {
    let msg = "inside"
    say msg     // "inside"
}
// msg is not accessible here

No Ternary Operator

Forge does not have a ternary conditional operator (condition ? a : b). Use an if-else statement or a when expression instead:

// Using when as a conditional expression
let label = when age {
    >= 18 -> "adult",
    else -> "minor"
}

If as a Statement

if is always a statement in Forge. It does not produce a value that can be used in expression position. To select between values conditionally, use a when expression.

Truthiness in Conditions

The condition in an if statement follows Forge’s truthiness rules:

if 0 {
    say "zero is truthy"        // this executes
}

if "" {
    say "empty string is truthy"    // this executes
}

if null {
    say "unreachable"
} else {
    say "null is falsy"         // this executes
}

if false {
    say "unreachable"
} else {
    say "false is falsy"        // this executes
}

See Truthiness Rules for the complete specification.

Loops

Loop statements execute a body repeatedly. Forge provides several loop forms for different iteration patterns.

For-In Loops

The for-in loop iterates over elements of a collection.

let names = ["Alice", "Bob", "Charlie"]
for name in names {
    say "Hello, {name}"
}

For Each Variant

The for each form is equivalent to for-in:

for each name in names {
    say "Hello, {name}"
}

Iterating Over Arrays

let nums = [10, 20, 30]
for n in nums {
    say n
}
// Output: 10, 20, 30

Iterating Over Objects

When iterating over an object, the loop variable receives each key:

let user = { name: "Alice", age: 30 }
for key in user {
    say "{key}: {user[key]}"
}

Iterating with Index

Use enumerate or a two-variable for loop to access both index and value:

let items = ["a", "b", "c"]
for i, item in items {
    say "{i}: {item}"
}
// Output: 0: a, 1: b, 2: c

Iterating Over Ranges

The range function generates a sequence of integers:

for i in range(0, 5) {
    say i
}
// Output: 0, 1, 2, 3, 4

range(start, end) produces integers from start (inclusive) to end (exclusive).

While Loops

The while loop executes as long as its condition is truthy.

let mut count = 0
while count < 5 {
    say count
    count += 1
}
// Output: 0, 1, 2, 3, 4

The condition is evaluated before each iteration. If the condition is falsy on the first check, the body never executes.

Loop (Infinite)

The loop keyword creates an infinite loop. Use break to exit.

let mut n = 0
loop {
    if n >= 3 {
        break
    }
    say n
    n += 1
}
// Output: 0, 1, 2

Repeat N Times

The repeat loop executes a body a fixed number of times.

repeat 3 times {
    say "hello"
}
// Output: hello, hello, hello

The count expression is evaluated once before the loop begins. The body executes exactly that many times.

Break

The break statement exits the innermost enclosing loop immediately.

for i in range(0, 100) {
    if i == 5 {
        break
    }
    say i
}
// Output: 0, 1, 2, 3, 4

break can be used with for, while, loop, and repeat.

Continue

The continue statement skips the rest of the current iteration and proceeds to the next one.

for i in range(0, 5) {
    if i == 2 {
        continue
    }
    say i
}
// Output: 0, 1, 3, 4

Nested Loops

Loops can be nested. break and continue apply to the innermost loop only.

for i in range(0, 3) {
    for j in range(0, 3) {
        if j == 1 {
            break       // exits inner loop only
        }
        say "{i},{j}"
    }
}
// Output: 0,0  1,0  2,0

Loop Scope

Variables declared inside a loop body are scoped to each iteration:

for i in range(0, 3) {
    let msg = "iteration {i}"
    say msg
}
// msg is not accessible here

The loop variable itself (i in for i in ...) is scoped to the loop body.

Wait in Loops

The wait statement can be used inside loops to introduce delays:

repeat 3 times {
    say "tick"
    wait 1 second
}

Function Declaration

Function declarations introduce named, callable units of code. Forge supports both classic and natural syntax forms.

Basic Declaration

Classic Syntax

fn greet(name) {
    say "Hello, {name}!"
}

Natural Syntax

define greet(name) {
    say "Hello, {name}!"
}

Both forms are semantically identical. The function is bound to the given name in the current scope.

Parameters

Parameters are comma-separated identifiers enclosed in parentheses.

fn add(a, b) {
    a + b
}
say add(3, 4)   // 7

No Parameters

Functions with no parameters use empty parentheses:

fn hello() {
    say "hello"
}
hello()

Default Parameters

Parameters can have default values. Default values are used when the caller does not provide an argument for that position.

fn greet(name, greeting = "Hello") {
    say "{greeting}, {name}!"
}
greet("Alice")              // "Hello, Alice!"
greet("Bob", "Hi")          // "Hi, Bob!"

Default parameters must appear after all required parameters.

Variadic Parameters

Forge does not support variadic parameters (rest parameters). To accept a variable number of arguments, use an array parameter:

fn sum_all(numbers) {
    reduce(numbers, 0, fn(acc, n) { acc + n })
}
say sum_all([1, 2, 3, 4])  // 10

Return Type Annotation

An optional return type annotation may follow the parameter list:

fn square(n: int): int {
    n * n
}

Type annotations are checked by the type checker when enabled. They do not affect runtime behavior in the interpreter.

Return Values

Implicit Return

The last expression in a function body is its return value. This is the idiomatic way to return values in Forge.

fn double(x) {
    x * 2
}
say double(5)   // 10

Explicit Return

The return keyword exits the function immediately with a value:

fn abs(x) {
    if x < 0 {
        return -x
    }
    x
}

A bare return without a value returns null:

fn log_if_positive(x) {
    if x <= 0 {
        return
    }
    say "positive: {x}"
}

See Return, Break, Continue for details.

Function Scope

Functions create a new scope. Variables declared inside a function are not accessible outside it. Functions can access variables from their enclosing scope (closure behavior).

let multiplier = 10

fn scale(x) {
    x * multiplier      // accesses 'multiplier' from outer scope
}
say scale(5)    // 50

Recursion

Functions can call themselves recursively:

fn factorial(n) {
    if n <= 1 { return 1 }
    n * factorial(n - 1)
}
say factorial(5)    // 120

fn fib(n) {
    if n <= 1 { return n }
    fib(n - 1) + fib(n - 2)
}
say fib(10)     // 55

Async Functions

Async functions are declared with async fn (classic) or forge (natural):

async fn fetch_data(url) {
    let resp = await http.get(url)
    resp.body
}

// Natural syntax
forge fetch_data(url) {
    let resp = hold http.get(url)
    resp.body
}

Async functions return a future that must be awaited with await / hold. See Async Functions.

Nested Functions

Functions can be declared inside other functions:

fn outer() {
    fn inner() {
        say "inside"
    }
    inner()
}
outer()     // "inside"

Inner functions have access to the outer function’s scope.

Functions Are Values

Function declarations create values that can be stored in variables, passed as arguments, and returned from other functions:

fn add(a, b) { a + b }
fn sub(a, b) { a - b }

let ops = [add, sub]
say ops[0](10, 3)   // 13
say ops[1](10, 3)   // 7

Parameter Type Annotations

Parameters can include optional type annotations:

fn add(a: int, b: int): int {
    a + b
}

These annotations are informational for the type checker and do not enforce types at runtime in the interpreter.

Return, Break, Continue

Jump statements transfer control to a different point in the program, interrupting the normal top-to-bottom execution flow.

Return

The return statement exits the current function and optionally provides a return value.

Return with a Value

fn square(x) {
    return x * x
}
say square(5)   // 25

Return without a Value

A bare return returns null from the function:

fn maybe_log(x) {
    if x <= 0 {
        return          // returns null
    }
    say "value: {x}"
}

Implicit Return

The last expression in a function body is automatically used as the return value. Explicit return is only needed for early exit.

fn double(x) {
    x * 2           // implicit return
}
say double(5)   // 10

When using if-else as the last statement, the last expression in the executed branch becomes the return value:

fn abs(x) {
    if x < 0 {
        -x
    } else {
        x
    }
}
say abs(-3)     // 3

Return in Nested Blocks

return exits the enclosing function, not just the current block:

fn find_first_negative(items) {
    for item in items {
        if item < 0 {
            return item     // exits the function, not just the loop
        }
    }
    null
}
say find_first_negative([1, 2, -3, 4])  // -3

Return from Closures

A return inside a closure exits the closure, not the outer function:

fn process(items) {
    let results = map(items, fn(x) {
        if x < 0 {
            return 0        // exits the closure, not process()
        }
        x * 2
    })
    results
}
say process([1, -2, 3])    // [2, 0, 6]

Break

The break statement exits the innermost enclosing loop immediately. Execution continues with the first statement after the loop.

Break in For Loops

for i in range(0, 100) {
    if i >= 5 {
        break
    }
    say i
}
// Output: 0, 1, 2, 3, 4
say "done"

Break in While Loops

let mut n = 0
while true {
    if n >= 3 {
        break
    }
    say n
    n += 1
}
// Output: 0, 1, 2

Break in Loop

The break statement is the only way to exit a loop (infinite loop):

let mut count = 0
loop {
    count += 1
    if count > 5 {
        break
    }
}
say count   // 6

Break in Nested Loops

break only exits the innermost loop:

for i in range(0, 3) {
    for j in range(0, 10) {
        if j >= 2 {
            break       // exits inner loop only
        }
        say "{i},{j}"
    }
    // continues with next i
}

Break Outside a Loop

Using break outside of a loop produces a runtime error.

Continue

The continue statement skips the rest of the current loop iteration and proceeds to the next iteration.

Continue in For Loops

for i in range(0, 5) {
    if i == 2 {
        continue        // skip i == 2
    }
    say i
}
// Output: 0, 1, 3, 4

Continue in While Loops

let mut i = 0
while i < 5 {
    i += 1
    if i % 2 == 0 {
        continue        // skip even numbers
    }
    say i
}
// Output: 1, 3, 5

Continue in Nested Loops

Like break, continue applies to the innermost loop:

for i in range(0, 3) {
    for j in range(0, 3) {
        if j == 1 {
            continue    // skips j == 1 in inner loop
        }
        say "{i},{j}"
    }
}
// Output: 0,0  0,2  1,0  1,2  2,0  2,2

Continue Outside a Loop

Using continue outside of a loop produces a runtime error.

Summary

Import and Export

The import statement loads definitions from external Forge source files or references built-in modules.

Importing Files

To import all top-level definitions from another Forge source file:

import "utils.fg"

The import path is a string literal specifying the file to load. The interpreter resolves the path relative to the current working directory and checks the following locations in order:

1. {path} – the exact path as given
2. {path}.fg – with the .fg extension appended
3. forge_modules/{path}/main.fg – in the forge_modules directory

If no file is found at any of these locations, a runtime error is produced.

Import Semantics

When a file is imported, the following steps occur:

1. The source file is read and parsed.
2. A new interpreter instance is created.
3. The imported file is executed in the new interpreter.
4. Top-level definitions (fn and let bindings) are copied into the importing file’s scope.

Importantly, each import creates a fresh interpreter. Side effects in the imported file (such as printing) occur during import. The imported file does not share mutable state with the importing file.

// utils.fg
fn double(x) { x * 2 }
fn triple(x) { x * 3 }
let PI = 3.14159

// main.fg
import "utils.fg"
say double(5)       // 10
say triple(5)       // 15
say PI              // 3.14159

Selective Imports

To import specific names from a file, list them after the path:

import { double, PI } from "utils.fg"
say double(5)       // 10
say PI              // 3.14159
// triple is NOT imported

Only the listed names are copied into the current scope.

Built-in Modules

Forge’s standard library modules (math, fs, io, crypto, db, pg, env, json, regex, log, term, http, csv, exec, time) are automatically available without import. Attempting to import a built-in module name produces an error with guidance:

import "math"
// Error: 'math' is a built-in module — it's already available. Use it directly: math.function()

Built-in modules are accessed via dot notation:

say math.sqrt(16)       // 4.0
say math.pi             // 3.141592653589793
let data = fs.read("file.txt")

Module-Level Execution

When a file is imported, all of its top-level statements execute. This includes not just declarations but also expression statements and side effects:

// setup.fg
say "setting up..."         // prints during import
let config = { debug: true }

fn get_config() { config }

// main.fg
import "setup.fg"           // prints "setting up..."
let c = get_config()
say c.debug                 // true

Circular Imports

Forge does not detect or prevent circular imports. A circular import chain will cause infinite recursion and a stack overflow. It is the programmer’s responsibility to avoid circular dependencies.

No Namespacing

Imported definitions are placed directly into the importing file’s scope. There is no namespace or module prefix for file imports. If two imported files define the same name, the later import overwrites the earlier one.

import "a.fg"       // defines fn helper()
import "b.fg"       // also defines fn helper() -- overwrites a.fg's version

No Export Keyword

Forge does not have an explicit export keyword. All top-level fn and let bindings in a file are automatically available for import by other files.

Re-Imports

Importing the same file multiple times re-executes it each time. There is no import caching or module singleton behavior for file imports.

Type System

This chapter defines the type system of Forge. Forge is dynamically typed at runtime but provides structural mechanisms for organizing data and behavior: struct definitions, method attachment, interface contracts, composition via embedding, and structural satisfaction checking.

Overview

Forge’s type system is built on five pillars:

1. Struct definitions (thing/struct) — Define named record types with typed fields and optional defaults.
2. Method blocks (give/impl) — Attach instance and static methods to struct types after definition.
3. Interface contracts (power/interface) — Declare behavioral contracts that types may fulfill.
4. Composition (has) — Embed one struct inside another with automatic field and method delegation.
5. Structural satisfaction (satisfies) — Test whether a value’s type fulfills an interface at runtime, regardless of explicit declaration.

Dynamic Foundation

All Forge values are represented at runtime by the Value enum. There is no compile-time type erasure or monomorphization. Type annotations on struct fields and function parameters are documentation and future-proofing; the interpreter does not enforce them at assignment time in the current version.

The typeof builtin returns a string naming the runtime type:

typeof(42)        // "Int"
typeof("hello")   // "String"
typeof(true)      // "Bool"
typeof(null)      // "Null"
typeof([1, 2])    // "Array"
typeof({a: 1})    // "Object"

Struct instances are Object values with a __type__ field that records the struct name.

Type Identity

Every struct instance carries a __type__ field set to the struct’s name as a string. This field is automatically inserted during construction and is used by the runtime for method dispatch, interface satisfaction checking, and embedded-field delegation.

thing Point { x: Int, y: Int }
let p = Point { x: 1, y: 2 }
p.__type__    // "Point"
typeof(p)     // "Object"

The typeof builtin returns "Object" for all struct instances. The __type__ field distinguishes between different struct types at a finer granularity.

No Generics

Forge does not currently support generic types or parameterized type constructors. All collections (arrays, objects) are heterogeneous. Interface methods are checked by name and arity, not by parameter types.

Subsections

The following subsections define each type system feature in detail:

• Struct Definitions — Defining named record types.
• Method Blocks — Attaching methods to types.
• Interface Contracts — Declaring and implementing behavioral contracts.
• Composition — Embedding types and delegation.
• Structural Satisfaction — Runtime interface checking.
• Default Values — Default field values in struct definitions.
• Static Methods — Type-level methods without a receiver.

Struct Definitions

Structs are named record types that group related fields into a single value. Forge provides dual syntax for defining structs: thing (natural) and struct (classic).

Syntax

StructDef       = ("thing" | "struct") Identifier "{" FieldList "}"
FieldList       = Field ("," Field)* ","?
Field           = EmbedField | PlainField
PlainField      = Identifier (":" TypeAnnotation)? ("=" Expression)?
EmbedField      = "has" Identifier ":" TypeAnnotation
TypeAnnotation  = Identifier

Defining a Struct

The thing keyword (or its classic alias struct) introduces a new struct type. The struct name must be a valid identifier and by convention uses PascalCase.

thing Person {
    name: String,
    age: Int
}

Classic syntax:

struct Person {
    name: String,
    age: Int
}

Both forms are semantically identical. The parser produces the same StructDef AST node regardless of which keyword is used.

Fields

Each field has a name and an optional type annotation. Type annotations follow the field name after a colon. In the current implementation, type annotations are parsed and stored but not enforced at runtime.

thing Config {
    host: String,
    port: Int,
    debug: Bool
}

Fields without type annotations are permitted:

thing Pair {
    first,
    second
}

Default Values

Fields may specify a default value using = after the type annotation (or after the field name if no annotation is present). See Default Values for full details.

thing Config {
    host: String = "localhost",
    port: Int = 8080,
    debug: Bool = false
}

Construction

Struct instances are created using the struct name followed by a field initializer block. The result is an Object value with the specified fields plus an automatically inserted __type__ field.

thing Point { x: Int, y: Int }

let p = Point { x: 10, y: 20 }
// p is { __type__: "Point", x: 10, y: 20 }

Fields may be provided in any order. Fields with default values may be omitted; default values are applied first, then explicitly provided fields override them.

thing Config {
    host: String = "localhost",
    port: Int = 8080
}

let c = Config { port: 3000 }
// c is { __type__: "Config", host: "localhost", port: 3000 }

The __type__ Field

Every struct instance automatically receives a __type__ field set to the struct’s name as a String value. This field is inserted after all user-specified fields during construction. It is used by the runtime for:

• Method dispatch in give/impl blocks
• Interface satisfaction checking in satisfies
• Embedded field delegation via has

The __type__ field is a regular field and can be read like any other:

thing Dog { name: String }
let d = Dog { name: "Rex" }
say d.__type__    // "Dog"

Manually setting __type__ in the constructor is permitted but will be overwritten by the automatic insertion.

Registration

When a StructDef statement is executed, the interpreter:

1. Registers the struct name in the environment as a BuiltIn("struct:Name") sentinel value. This value is used to identify static method calls (Name.method()).
2. Records any embedded fields in the embedded_fields table for delegation.
3. Records any default values in the struct_defaults table, evaluating default expressions at definition time.

The struct name can subsequently be used as a constructor in StructInit expressions.

Field Access

Fields are accessed using dot notation:

thing Person { name: String, age: Int }
let p = Person { name: "Alice", age: 30 }

say p.name    // "Alice"
say p.age     // 30

If the field does not exist on the object directly, the runtime checks embedded sub-objects before reporting an error. See Composition.

Method Blocks

Method blocks attach functions to a struct type after its definition. Forge provides dual syntax: give (natural) and impl (classic). Methods are stored in the interpreter’s method tables and dispatched based on the instance’s __type__ field.

Syntax

MethodBlock      = GiveBlock | ImplBlock
GiveBlock        = "give" TypeName AbilityClause? "{" MethodDef* "}"
ImplBlock        = "impl" (TypeName | AbilityForType) "{" MethodDef* "}"
AbilityClause    = "the" "power" InterfaceName
AbilityForType   = InterfaceName "for" TypeName
MethodDef        = ("fn" | "define") Identifier "(" ParamList ")" Block
TypeName         = Identifier
InterfaceName    = Identifier

Instance Methods

An instance method is a method whose first parameter is named it. The it parameter receives the struct instance on which the method is called — it is Forge’s equivalent of self or this in other languages.

thing Person {
    name: String,
    age: Int
}

give Person {
    define greet(it) {
        say "Hello, I'm " + it.name
    }

    define birthday(it) {
        return it.age + 1
    }
}

Classic syntax:

impl Person {
    fn greet(it) {
        say "Hello, I'm " + it.name
    }
}

Both give and impl are semantically identical. The parser produces the same ImplBlock AST node.

Method Invocation

Instance methods are called using dot notation on a struct instance. The runtime automatically passes the instance as the it argument:

let p = Person { name: "Alice", age: 30 }
p.greet()       // prints "Hello, I'm Alice"
p.birthday()    // returns 31

When the interpreter encounters p.greet(), it:

1. Evaluates p to get the receiver object.
2. Reads p.__type__ to get the type name ("Person").
3. Looks up "greet" in method_tables["Person"].
4. Prepends p to the argument list as the it parameter.
5. Calls the resolved function with the full argument list.

Static Methods

A method without it as its first parameter is a static method. Static methods are called on the type name itself, not on instances. See Static Methods for full details.

give Person {
    define species() {
        return "Homo sapiens"
    }
}

Person.species()    // "Homo sapiens"

Additive Blocks

Multiple give/impl blocks for the same type are additive. Each block adds its methods to the existing method table without removing previously defined methods.

thing Car {
    make: String
}

give Car {
    define brand(it) {
        return it.make
    }
}

give Car {
    define honk(it) {
        say "Beep!"
    }
}

let c = Car { make: "Toyota" }
c.brand()    // "Toyota"
c.honk()     // prints "Beep!"

If a later block defines a method with the same name as an existing method, the later definition overwrites the earlier one in the method table.

Method Table Storage

The interpreter maintains two HashMap tables:

When a give/impl block is executed, each method is inserted into method_tables under the type name. Methods without an it parameter are additionally inserted into static_methods.

Method Resolution Order

When resolving obj.method(args) on a typed object:

1. Direct field — If the object has a field named method that is callable, it is invoked.
2. Method table — The runtime looks up method_tables[obj.__type__][method].
3. Embedded delegation — If not found, the runtime checks each embedded field’s type for the method in method_tables. See Composition.
4. Known builtins — Certain method names (e.g., map, filter, push) are recognized as builtin functions and dispatched accordingly.
5. Error — If no match is found, a runtime error is raised: no method 'method' on TypeName.

Mixed Syntax

Natural (define) and classic (fn) function syntax may be used interchangeably within give and impl blocks:

give Greeter {
    define hello(it) {
        say "hi from " + it.name
    }

    fn goodbye(it) {
        say "bye from " + it.name
    }
}

Interface Contracts

Interfaces define behavioral contracts — a set of method signatures that a type must implement. Forge provides dual syntax: power (natural) and interface (classic). Implementing an interface is verified at definition time when the give...the power or impl...for block is executed.

Syntax

InterfaceDef     = ("power" | "interface") Identifier "{" MethodSig* "}"
MethodSig        = ("fn" | "define") Identifier "(" ParamList ")" ("->" TypeAnnotation)?
ImplInterface    = "give" TypeName "the" "power" InterfaceName "{" MethodDef* "}"
                 | "impl" InterfaceName "for" TypeName "{" MethodDef* "}"

Defining an Interface

The power keyword (or its classic alias interface) introduces a named interface. An interface body contains method signatures — method names with parameter lists and optional return type annotations.

power Greetable {
    fn greet(it) -> String
}

Classic syntax:

interface Greetable {
    fn greet(it) -> String
}

Both forms produce the same InterfaceDef AST node.

Interface Registration

When an InterfaceDef statement is executed, the interpreter:

1. Builds an array of method specification objects. Each object contains:
   • name — the method name as a String.
   • param_count — the number of parameters as an Int.
   • return_type — the return type annotation as a String, if present.
2. Creates an interface metadata object with fields __kind__: "interface", name, and methods.
3. Registers the interface in the environment under both its name and __interface_Name__.

The interface object is a regular Object value and can be passed to functions like satisfies.

Implementing an Interface

To declare that a type fulfills an interface, use give...the power (natural) or impl...for (classic):

thing Cat {
    name: String
}

power Greetable {
    fn greet(it) -> String
}

give Cat the power Greetable {
    define greet(it) {
        return "Meow, I'm " + it.name
    }
}

Classic syntax:

interface Named {
    fn get_name(it) -> String
}

impl Named for Animal {
    fn get_name(it) {
        return it.name
    }
}

Validation at Definition Time

When a give...the power or impl...for block is executed, the runtime validates that every method required by the interface is present in the type’s method table (including methods added by the current block and any previous give/impl blocks).

The validation checks method presence by name. It does not verify parameter counts, parameter types, or return types.

If a required method is missing, a runtime error is raised:

'Cat' does not implement 'greet' required by power 'Greetable'

This error occurs at the point where the give...the power block is executed, not at a later call site.

Interface Without Explicit Implementation

A type may satisfy an interface without ever using give...the power or impl...for. Forge supports Go-style structural typing through the satisfies function. See Structural Satisfaction.

The give...the power syntax provides two benefits over implicit satisfaction:

1. Early validation — Errors are reported at the implementation site rather than at a distant call site.
2. Documentation — The code explicitly declares the relationship between a type and an interface.

Multiple Interfaces

A type may implement multiple interfaces through separate give...the power blocks:

power Speakable {
    fn speak(it) -> String
}

power Trainable {
    fn train(it, command: String)
    fn obey(it, command: String) -> Bool
}

thing Dog {
    name: String
}

give Dog the power Speakable {
    define speak(it) {
        return "Woof!"
    }
}

give Dog the power Trainable {
    define train(it, command) {
        say it.name + " is learning " + command
    }

    define obey(it, command) {
        return true
    }
}

Each give...the power block independently validates that its interface’s requirements are met. Methods from earlier blocks (including plain give blocks without an interface) count toward satisfaction.

Return Type Annotations

Return type annotations in interface method signatures are stored in the interface metadata but are not enforced at runtime. They serve as documentation:

power Hashable {
    fn hash(it) -> String
}

The -> String annotation is recorded in the method specification but the runtime does not check that hash actually returns a String.

Composition

Forge supports struct composition through the has keyword, which embeds one struct inside another. Embedded fields enable automatic delegation of both field access and method calls to the inner struct, providing a composition-based alternative to inheritance.

Syntax

EmbedField = "has" Identifier ":" TypeAnnotation

The has keyword appears in a struct field position and marks the field as embedded.

Defining Embedded Fields

Use has inside a struct definition to embed another type:

thing Address {
    street: String,
    city: String,
    zip: String
}

thing Employee {
    name: String,
    has addr: Address
}

The addr field is an embedded field of type Address. The has keyword tells the runtime to register this field for delegation.

Construction

Embedded fields are initialized like regular fields during construction:

let emp = Employee {
    name: "Alice",
    addr: Address {
        street: "123 Main St",
        city: "Springfield",
        zip: "62701"
    }
}

Field Delegation

When a field is accessed on a struct instance and the field is not found directly on the object, the runtime checks each embedded sub-object for the field. This enables transparent access to inner fields:

// Direct access (always works)
emp.addr.city      // "Springfield"

// Delegated access (through embedding)
emp.city           // "Springfield"
emp.street         // "123 Main St"

The delegation algorithm for obj.field:

1. Check if obj has a direct field named field. If found, return it.
2. Read obj.__type__ to get the type name.
3. Look up the type name in embedded_fields to get the list of (field_name, type_name) pairs.
4. For each embedded field, check if obj[field_name] is an object with the requested field. If found, return it.
5. If no embedded field contains the requested field, raise a runtime error.

Method Delegation

Method calls are also delegated to embedded types. If a method is not found in the outer type’s method table, the runtime searches each embedded type’s method table:

give Address {
    define full(it) {
        return it.street + ", " + it.city + " " + it.zip
    }
}

// Called on the embedded Address through Employee
emp.full()         // "123 Main St, Springfield 62701"

// Explicit path also works
emp.addr.full()    // "123 Main St, Springfield 62701"

The method delegation algorithm for obj.method(args):

1. Look up method in method_tables[obj.__type__]. If found, call it with obj prepended as it.
2. Look up embedded_fields[obj.__type__] to get the list of embedded fields.
3. For each (embed_field, embed_type) pair, look up method in method_tables[embed_type].
4. If found, extract obj[embed_field] as the receiver and call the method with the sub-object as it.
5. If no embedded type has the method, continue to builtin resolution or raise an error.

Multiple Embeddings

A struct may embed multiple fields:

thing Engine {
    horsepower: Int
}

thing Chassis {
    material: String
}

thing Car {
    make: String,
    has engine: Engine,
    has chassis: Chassis
}

give Engine {
    define rev(it) {
        say "Vroom! " + str(it.horsepower) + "hp"
    }
}

give Chassis {
    define describe(it) {
        return it.material + " chassis"
    }
}

let c = Car {
    make: "Toyota",
    engine: Engine { horsepower: 200 },
    chassis: Chassis { material: "Steel" }
}

c.rev()          // prints "Vroom! 200hp"
c.describe()     // "Steel chassis"
c.horsepower     // 200
c.material       // "Steel"

Embedded fields are searched in declaration order. If two embedded types provide the same field name, the first match wins.

Embedding and Interfaces

Delegated methods count toward interface satisfaction. If an embedded type’s method table contains a method required by an interface, the outer type satisfies that interface through delegation:

power Describable {
    fn describe(it) -> String
}

// Car satisfies Describable through its embedded Chassis
satisfies(c, Describable)    // true (via chassis.describe)

Storage

The interpreter maintains an embedded_fields table:

embedded_fields: HashMap<String, Vec<(String, String)>>

The key is the outer struct name. The value is a vector of (field_name, type_name) pairs, one for each has field in the struct definition. This table is populated when the StructDef statement is executed.

Structural Satisfaction

The satisfies function tests whether a value’s type fulfills an interface’s requirements at runtime, without requiring an explicit give...the power or impl...for declaration. This is Forge’s implementation of Go-style structural typing: if a type has the right methods, it satisfies the interface.

Syntax

satisfies(value, InterfaceObject) -> Bool

The satisfies function is a builtin that takes two arguments:

1. value — Any value, typically a struct instance (an object with a __type__ field).
2. InterfaceObject — An interface value (an object with __kind__: "interface" and a methods array).

It returns true if the value’s type has all methods required by the interface, false otherwise.

Basic Usage

thing Robot {
    name: String
}

power Speakable {
    fn speak(it) -> String
}

give Robot {
    define speak(it) {
        return "Beep boop, I am " + it.name
    }
}

let r = Robot { name: "R2D2" }
satisfies(r, Speakable)    // true

Note that Robot never explicitly declared give Robot the power Speakable. The satisfies check passes because Robot has a speak method in its method table.

Resolution Algorithm

The satisfies function checks interface satisfaction in two phases:

Phase 1: Structural Check

First, satisfies performs a structural check on the value itself. It examines whether the value (or the object’s fields) contains callable values matching each required method name. This handles objects that carry their methods as fields.

Phase 2: Method Table Check

If the structural check fails and the value is an object with a __type__ field, satisfies looks up the type name in the interpreter’s method_tables. For each method required by the interface, it checks whether the method table contains an entry with that name.

thing Printer {}

give Printer {
    define print_line(it, text) {
        say text
    }
}

power Printable {
    fn print_line(it, text: String)
}

let p = Printer {}
satisfies(p, Printable)    // true (found in method_tables)

Satisfaction Criteria

The check verifies method presence by name only. It does not verify:

• Parameter count or parameter types
• Return types
• Method body or behavior

A type satisfies an interface if and only if every method name listed in the interface’s methods array has a corresponding entry in the type’s method table.

Explicit vs. Structural

Forge supports both explicit and structural interface satisfaction:

Explicit implementation triggers immediate validation and produces clear error messages at the definition site. Structural satisfaction is more flexible but defers errors to the point where satisfies is called.

Both approaches can coexist. A type that explicitly implements an interface will also pass satisfies checks.

Examples

Satisfied Without Explicit Declaration

thing Duck {
    name: String
}

power Quackable {
    fn quack(it) -> String
}

give Duck {
    define quack(it) {
        return it.name + " says quack!"
    }
}

let d = Duck { name: "Donald" }
satisfies(d, Quackable)    // true — Duck has quack()

Not Satisfied

thing Rock {
    weight: Int
}

satisfies(Rock { weight: 5 }, Quackable)    // false — Rock has no quack()

Multiple Interface Methods

power Serializable {
    fn to_string(it) -> String
    fn to_json(it) -> String
}

thing Config {
    data: String
}

give Config {
    define to_string(it) { return it.data }
    // Missing to_json
}

let c = Config { data: "test" }
satisfies(c, Serializable)    // false — missing to_json

Return Value

satisfies always returns a Bool value. It never throws an error for non-matching types; it simply returns false. It only raises a runtime error if called with the wrong number of arguments.

Default Values

Struct fields may specify default values that are applied when the field is omitted during construction. Default expressions are evaluated at definition time and stored in the interpreter’s struct_defaults table.

Syntax

FieldWithDefault = Identifier (":" TypeAnnotation)? "=" Expression

The default value follows an = sign after the field name and optional type annotation.

Defining Defaults

thing Config {
    host: String = "localhost",
    port: Int = 8080,
    debug: Bool = false
}

A field may have a type annotation, a default, both, or neither:

Evaluation Timing

Default expressions are evaluated at definition time — when the thing/struct statement is executed, not when an instance is constructed. This means:

let counter = 0

thing Widget {
    id: Int = counter
}

change counter to 10

let w = Widget {}
say w.id    // 0, not 10 — default was captured at definition time

The default value is the result of evaluating the expression at the point where the struct is defined. Subsequent changes to variables referenced in the default expression do not affect the stored default.

Application During Construction

When a struct instance is constructed, defaults are applied first, then explicitly provided fields override them:

1. The interpreter retrieves the defaults from struct_defaults[StructName].
2. All default key-value pairs are inserted into the new object.
3. Explicitly provided fields in the constructor are evaluated and inserted, overwriting any defaults with the same key.
4. The __type__ field is inserted last.

thing Server {
    host: String = "0.0.0.0",
    port: Int = 3000,
    workers: Int = 4
}

// All defaults
let s1 = Server {}
// s1 = { host: "0.0.0.0", port: 3000, workers: 4, __type__: "Server" }

// Partial override
let s2 = Server { port: 8080 }
// s2 = { host: "0.0.0.0", port: 8080, workers: 4, __type__: "Server" }

// Full override
let s3 = Server { host: "127.0.0.1", port: 443, workers: 16 }
// s3 = { host: "127.0.0.1", port: 443, workers: 16, __type__: "Server" }

Default Expressions

Default values may be any valid expression, not just literals. They are evaluated in the current scope at definition time:

let default_name = "World"

thing Greeter {
    greeting: String = "Hello, " + default_name + "!"
}

let g = Greeter {}
say g.greeting    // "Hello, World!"

Function calls, arithmetic, string concatenation, and other expressions are all valid defaults.

Storage

The interpreter stores defaults in a struct_defaults table:

struct_defaults: HashMap<String, IndexMap<String, Value>>

The outer key is the struct name. The inner IndexMap maps field names to their default Value. Only fields with defaults are stored; fields without defaults are absent from the map.

Fields Without Defaults

Fields without defaults must be provided during construction. If a field without a default is omitted, the constructed object simply will not have that field — no error is raised at construction time, but accessing the missing field later will produce a runtime error.

Static Methods

Static methods are methods attached to a type that do not operate on an instance. They are defined in give/impl blocks without it as the first parameter and are called on the type name itself.

Syntax

Static methods are defined like instance methods but without it:

give TypeName {
    define method_name(params) {
        // body — no `it` parameter
    }
}

They are called on the type name:

TypeName.method_name(args)

Defining Static Methods

A method is classified as static when its first parameter is not named it. Any other parameter name (or no parameters at all) makes it a static method.

thing Person {
    name: String,
    age: Int
}

give Person {
    // Static method — no `it` parameter
    define species() {
        return "Homo sapiens"
    }

    // Static method — first param is not `it`
    define create(name, age) {
        return Person { name: name, age: age }
    }

    // Instance method — first param IS `it`
    define greet(it) {
        say "Hello, I'm " + it.name
    }
}

Invocation

Static methods are called using the type name with dot notation:

Person.species()               // "Homo sapiens"
let p = Person.create("Bob", 25)  // Person { name: "Bob", age: 25 }

The runtime resolves Person.method() by:

1. Evaluating Person — this yields the BuiltIn("struct:Person") sentinel value registered during struct definition.
2. Extracting the type name "Person" from the sentinel tag.
3. Looking up the method name in static_methods["Person"].
4. Calling the function with the provided arguments (no instance prepended).

Storage

Static methods are stored in the static_methods table:

static_methods: HashMap<String, IndexMap<String, Value>>

The key is the type name. The value is an IndexMap mapping method names to function values.

When a give/impl block is executed, each method is checked for the it parameter:

Static methods are stored in both tables. This means they appear in method_tables as well, which allows them to be found during interface satisfaction checks.

Factory Pattern

A common use of static methods is the factory pattern — creating instances with validation or transformation logic:

thing Color {
    r: Int,
    g: Int,
    b: Int
}

give Color {
    define from_hex(hex) {
        // Parse hex string to RGB values
        return Color { r: 0, g: 0, b: 0 }
    }

    define red() {
        return Color { r: 255, g: 0, b: 0 }
    }

    define display(it) {
        return "rgb(" + str(it.r) + ", " + str(it.g) + ", " + str(it.b) + ")"
    }
}

let c = Color.red()
say c.display()    // "rgb(255, 0, 0)"

Additive Blocks

Like instance methods, static methods from multiple give/impl blocks are additive:

give Math {
    define add(a, b) { return a + b }
}

give Math {
    define sub(a, b) { return a - b }
}

Math.add(1, 2)    // 3
Math.sub(5, 3)    // 2

Instance vs. Static Ambiguity

The classification is based solely on whether the first parameter is named it. A method named it with a different first parameter name is static:

give Config {
    // Static: first param is "key", not "it"
    define from_key(key) {
        return Config { value: key }
    }

    // Instance: first param is "it"
    define to_string(it) {
        return str(it.value)
    }
}

Error Handling

This chapter defines Forge’s error handling mechanisms. Forge uses a multi-layered approach: Result types for explicit error values, the ? operator for propagation, safe blocks for error suppression, must for crash-on-error semantics, and check for declarative validation.

Overview

Forge provides five complementary error handling mechanisms:

These mechanisms serve different use cases:

• Result + ? — For functions that can fail and callers that want to handle failures explicitly.
• safe — For optional operations where failure is acceptable and the value can be null.
• must — For operations that should never fail in correct code.
• check — For input validation with readable error messages.

Runtime Errors

All Forge runtime errors are represented by RuntimeError, which contains a message string and an optional propagated value. When an error is not caught, it terminates the program with an error message.

Errors can be caught with try/catch:

try {
    let x = 1 / 0
} catch e {
    say e.message    // "division by zero"
    say e.type       // "ArithmeticError"
}

The catch variable receives an object with message and type fields. Error types are inferred from the error message content:

Subsections

The following subsections define each error handling mechanism in detail:

• Result Type — Ok/Err values and inspection functions.
• Propagation — The ? operator.
• Safe and Must — Error suppression and crash-on-error.
• Check — Declarative validation.

Result Type

The Result type represents the outcome of an operation that may succeed or fail. A Result is either Ok(value) for success or Err(message) for failure. Results are first-class values that can be stored in variables, passed to functions, and returned from functions.

Syntax

ResultOk    = ("Ok" | "ok") "(" Expression ")"
ResultErr   = ("Err" | "err") "(" Expression ")"

Constructors

Forge provides two constructors for creating Result values. Both accept case-insensitive names:

let success = Ok(42)
let failure = Err("something went wrong")

// Lowercase variants are equivalent
let success2 = ok(42)
let failure2 = err("not found")

Ok wraps any value:

Ok(42)            // Result containing Int
Ok("hello")       // Result containing String
Ok([1, 2, 3])     // Result containing Array
Ok(null)          // Result containing null (Ok with no meaningful value)

Err wraps an error value (typically a string message):

Err("file not found")
Err("invalid input: expected number")

If Ok is called with no arguments, it wraps null. If Err is called with no arguments, it wraps the string "error".

Runtime Representation

Results are distinct variants in the Value enum:

• Value::ResultOk(Box<Value>) — wraps the success value.
• Value::ResultErr(Box<Value>) — wraps the error value.

The typeof builtin returns "Result" for both variants:

typeof(Ok(1))     // "Result"
typeof(Err("x"))  // "Result"

Display Format

Results are displayed as Ok(value) or Err(value):

say Ok(42)              // Ok(42)
say Err("not found")    // Err(not found)

In JSON serialization, Results produce { "Ok": value } or { "Err": value }.

Inspection Functions

Four builtin functions inspect and extract Result values:

is_ok(result)

Returns true if the value is Ok, false if Err. Raises a runtime error if the argument is not a Result.

is_ok(Ok(42))           // true
is_ok(Err("oops"))      // false

is_err(result)

Returns true if the value is Err, false if Ok. Raises a runtime error if the argument is not a Result.

is_err(Ok(42))          // false
is_err(Err("oops"))     // true

unwrap(result)

Extracts the inner value from Ok. If the value is Err, raises a runtime error with the message "unwrap() on Err: <error_value>".

unwrap(Ok(42))          // 42
unwrap(Err("oops"))     // runtime error: unwrap() on Err: oops

unwrap also works with Option values (Some/None):

unwrap(Some(42))        // 42
unwrap(None)            // runtime error: unwrap() called on None

unwrap_or(result, default)

Extracts the inner value from Ok. If the value is Err, returns the default value instead. Never raises an error for valid Result inputs.

unwrap_or(Ok(42), 0)       // 42
unwrap_or(Err("oops"), 0)  // 0

unwrap_or also works with Option values:

unwrap_or(Some(42), 0)     // 42
unwrap_or(None, 0)         // 0

Raises a runtime error if called with the wrong number of arguments or if the first argument is not a Result or Option.

Pattern Matching on Results

Results can be matched in match expressions using Ok and Err patterns:

let result = Ok(42)

match result {
    Ok(value) -> say "Got: " + str(value),
    Err(msg) -> say "Error: " + msg
}

Results in Functions

Functions commonly return Results to signal success or failure:

fn divide(a, b) {
    if b == 0 {
        return Err("division by zero")
    }
    return Ok(a / b)
}

let result = divide(10, 0)
if is_err(result) {
    say "Cannot divide: " + unwrap(Err("division by zero"))
}

Equality

Two Ok values are equal if their inner values are equal. Two Err values are equal if their inner values are equal. Ok and Err are never equal to each other:

Ok(42) == Ok(42)          // true
Err("x") == Err("x")     // true
Ok(42) == Err(42)         // false
Ok(1) == Ok(2)            // false

Error Propagation

The ? operator provides concise syntax for propagating errors up the call stack. When applied to a Result value, it unwraps Ok values and short-circuits on Err values by returning the error from the enclosing function.

Syntax

TryExpr = Expression "?"

The ? operator is a postfix unary operator applied to an expression that evaluates to a Result.

Semantics

The ? operator evaluates its operand and inspects the result:

• If the value is Ok(v), the expression evaluates to v (the inner value is unwrapped).
• If the value is Err(e), the enclosing function immediately returns Err(e).
• If the value is neither Ok nor Err, a runtime error is raised: `?` expects Result value (Ok(...) or Err(...)).

fn parse_number(s) {
    if s == "" {
        return Err("empty string")
    }
    return Ok(int(s))
}

fn double_parsed(s) {
    let n = parse_number(s)?    // unwraps Ok or returns Err
    return Ok(n * 2)
}

double_parsed("5")     // Ok(10)
double_parsed("")      // Err("empty string")

Propagation Mechanism

When ? encounters an Err value, it raises a RuntimeError with the propagated field set to the Err value. The runtime distinguishes propagated errors from ordinary runtime errors. When a propagated error reaches a function boundary, the function returns the propagated Err value rather than crashing the program.

The implementation:

1. Expr::Try(expr) evaluates expr.
2. If the result is ResultOk(value), returns value.
3. If the result is ResultErr(err), calls RuntimeError::propagate(ResultErr(err)), which creates a RuntimeError whose propagated field carries the original Err value.
4. The calling function’s error handler detects the propagated value and converts it back into a return value.

Chaining

The ? operator can be chained across multiple function calls:

fn read_config() {
    let text = read_file("config.json")?
    let parsed = json.parse(text)?
    return Ok(parsed)
}

Each ? either unwraps the Ok value for the next step or short-circuits the entire function with the first Err encountered.

Requirements

The ? operator requires that its operand evaluates to a Result value. Applying ? to a non-Result value (such as an Int, String, or null) raises a runtime error:

let x = 42?    // runtime error: `?` expects Result value (Ok(...) or Err(...))

Usage Patterns

Propagate and Transform

fn load_user(id) {
    let data = fetch_user_data(id)?
    let user = parse_user(data)?
    return Ok(user)
}

Propagate with Fallback

Combine ? with unwrap_or for partial error handling:

fn get_config_or_default() {
    let config = read_config()?            // propagate file errors
    let timeout = unwrap_or(config.timeout, 30)  // fallback for missing field
    return Ok(timeout)
}

Top-Level Handling

At the top level, propagated errors become runtime errors since there is no enclosing function to return from:

// If read_config returns Err, this crashes the program
let config = read_config()?

To handle errors at the top level, use is_ok/is_err checks, unwrap_or, or try/catch blocks instead of ?.

Safe and Must

safe and must provide two ends of the error handling spectrum: safe suppresses errors silently, while must crashes on error with a clear message.

Safe Blocks

Syntax

SafeBlock = "safe" "{" Statement* "}"

The safe keyword introduces a block whose errors are silently suppressed.

Semantics

A safe block executes its body statements. If any statement raises a runtime error, the error is caught and the block evaluates to null. If the block completes successfully, its result is returned normally.

safe {
    let data = json.parse("invalid json")
    say data
}
// No error — block silently returns null

Behavior

The safe block is a statement, not an expression. It does not produce a value that can be assigned directly. When used for its side effects, it simply prevents errors from propagating:

// Attempt to write a file; ignore errors
safe {
    fs.write("log.txt", "entry")
}

// Execution continues regardless
say "done"

Use Cases

• Optional side effects (logging, caching) where failure is acceptable.
• Defensive code around external operations (file I/O, network) that may fail intermittently.
• Quick prototyping where error handling is deferred.

Caution

safe blocks suppress all errors indiscriminately, including programming bugs, type errors, and logic errors. Overuse of safe can hide real problems. Prefer explicit error handling with Result/? for production code.

Must Expression

Syntax

MustExpr = "must" Expression

The must keyword is a prefix operator applied to an expression.

Semantics

must evaluates its operand and asserts that the result is a successful value:

• If the value is Ok(v), returns v (unwrapped).
• If the value is Err(e), raises a runtime error: "must failed: <e>".
• If the value is null, raises a runtime error: "must failed: got null".
• For any other value, returns it unchanged.

// Succeeds — unwraps Ok
let value = must Ok(42)       // 42

// Crashes — Err inside must
let value = must Err("oops")  // runtime error: must failed: oops

// Crashes — null inside must
let value = must null          // runtime error: must failed: got null

// Passes through — non-Result, non-null
let value = must 42            // 42

Comparison with unwrap

The key difference: must passes through non-Result, non-null values unchanged, while unwrap requires a Result or Option value. must is designed for contexts where the expression might return a Result, a plain value, or null.

Use Cases

• Asserting that a critical operation succeeds:

  let db = must db.open("app.db")
  

• Unwrapping configuration that should always be present:

  let key = must env.get("API_KEY")
  

• Failing fast on unexpected null values:

  let user = must find_user(id)
  

Combining Safe and Must

safe and must can be used together for fallback patterns:

// Try the primary source, fall back to default
safe {
    let config = must load_config("primary.json")
    apply_config(config)
}
// If must fails, safe catches it and continues

apply_config(default_config())

However, this pattern is generally better expressed with Result types:

let config = unwrap_or(load_config("primary.json"), default_config())
apply_config(config)

Check

The check statement provides declarative validation with clear error messages. It evaluates a condition and raises a runtime error if the check fails.

Syntax

CheckStmt     = "check" Expression CheckKind
CheckKind     = IsNotEmpty | Contains | Between | IsTrue
IsNotEmpty    = "is" "not" "empty"
Contains      = "contains" Expression
Between       = "is" "between" Expression "and" Expression
IsTrue        = (empty — implicit truth check)

Check Kinds

Forge supports four validation kinds, each producing a specific boolean test:

is not empty

Tests that a value is non-empty. The definition of “empty” depends on the type:

let name = "Alice"
check name is not empty    // passes

let empty = ""
check empty is not empty   // runtime error: check failed: "" did not pass validation

contains

Tests that a string contains a substring:

let email = "user@example.com"
check email contains "@"    // passes

let bad = "not-an-email"
check bad contains "@"      // runtime error: check failed

The contains check currently operates on strings only. Both the value and the needle must be strings; other type combinations return false.

is between … and

Tests that a numeric value falls within an inclusive range:

let age = 25
check age is between 0 and 150    // passes

let temp = -10
check temp is between 0 and 100   // runtime error: check failed

Both Int and Float values are supported, but the value and both bounds must be the same type. Mixed-type comparisons (e.g., Int value with Float bounds) return false.

Implicit Truth Check

When no check kind is specified, the value is tested for truthiness:

let valid = true
check valid    // passes

let invalid = false
check invalid  // runtime error: check failed

Error Messages

When a check fails, the runtime raises a RuntimeError with the message:

check failed: <value> did not pass validation

Where <value> is the string representation of the tested value.

Use Cases

Input Validation

fn create_user(name, age, email) {
    check name is not empty
    check age is between 0 and 150
    check email contains "@"

    return { name: name, age: age, email: email }
}

Preconditions

fn withdraw(account, amount) {
    check amount is between 1 and 10000
    check account.balance is between amount and 999999

    account.balance = account.balance - amount
}

Configuration Validation

let config = load_config()
check config.host is not empty
check config.port is between 1 and 65535

Comparison with Assert

check is designed for readable validation logic with automatic error descriptions. assert is a general-purpose assertion that requires the programmer to provide an error message.

Nesting in Safe Blocks

Check failures are runtime errors and can be caught by safe blocks or try/catch:

safe {
    check "" is not empty    // fails, but error is suppressed
}
say "continues"              // prints "continues"

try {
    check input is not empty
} catch e {
    say "Validation error: " + e.message
}

Concurrency

This chapter defines Forge’s concurrency primitives. Forge provides three mechanisms for concurrent execution: channels for message passing, spawn for task creation, and async/await (with natural syntax aliases forge/hold) for asynchronous functions.

Overview

Forge’s concurrency model is built on OS threads (via std::thread) with channels for communication:

Execution Model

Forge spawns concurrent tasks as OS threads. Each spawned task receives a clone of the current environment, enabling access to variables defined before the spawn point. Tasks do not share mutable state directly; communication should use channels.

The runtime uses std::thread::spawn for task creation and std::sync::mpsc::sync_channel for channels. This provides:

• True parallelism on multi-core systems.
• Thread-safe communication through bounded channels.
• Task handle values with condition-variable notification for await.

Task Handles

When spawn is used as an expression, it returns a TaskHandle value. Task handles are opaque values that can be passed to await (or hold) to block until the spawned task completes and retrieve its return value.

let handle = spawn { return 42 }
let result = await handle    // 42

Task handles use an Arc<(Mutex<Option<Value>>, Condvar)> internally:

• The Mutex<Option<Value>> holds the task’s return value (initially None).
• The Condvar is notified when the task writes its result.
• await blocks on the Condvar until the result is available, then extracts it.

Error Isolation

Errors in spawned tasks do not crash the parent task. If a spawned task encounters a runtime error, the error is printed to stderr and the task’s result is null:

spawn { let x = 1 / 0 }    // prints error to stderr, does not crash parent
say "still running"          // executes normally

Subsections

The following subsections define each concurrency mechanism in detail:

• Channels — Message passing between tasks.
• Spawn — Creating concurrent tasks.
• Async Functions — Defining asynchronous functions.
• Await — Waiting for async results.

Channels

Channels provide thread-safe message passing between concurrent tasks. A channel is a bounded, synchronous queue that allows one task to send values and another to receive them.

Creating a Channel

Syntax

channel()
channel(capacity)

The channel builtin creates a new channel and returns a Channel value. An optional integer argument specifies the buffer capacity (default: 32).

let ch = channel()        // buffered channel, capacity 32
let ch = channel(100)     // buffered channel, capacity 100
let ch = channel(1)       // minimal buffer, capacity 1

If a non-integer argument is provided, the default capacity of 32 is used. The minimum capacity is 1 (values less than 1 are clamped to 1).

Channel Value

A channel is represented at runtime as Value::Channel(Arc<ChannelInner>). The ChannelInner struct contains:

• tx: Mutex<Option<SyncSender<Value>>> — the sender half.
• rx: Mutex<Option<Receiver<Value>>> — the receiver half.
• capacity: usize — the buffer capacity.

Channels are reference-counted via Arc, so they can be safely shared between the parent task and spawned tasks through environment cloning.

Sending Values

send(channel, value)

The send builtin sends a value through a channel. It blocks if the channel buffer is full, waiting until a receiver consumes a value.

let ch = channel()
send(ch, 42)
send(ch, "hello")
send(ch, [1, 2, 3])

Any Forge value can be sent through a channel: integers, strings, arrays, objects, functions, Results, and other channels.

Arguments:

• channel — A Channel value (first argument).
• value — Any Value to send (second argument).

Returns: null on success.

Errors:

• "send(channel, value) requires 2 arguments" — Wrong argument count.
• "send() requires a channel as first argument" — First argument is not a channel.
• "channel closed" — The receiver has been dropped.

try_send(channel, value)

The try_send builtin attempts to send a value without blocking. Returns true if the value was sent, false if the channel is full or closed.

let ch = channel(1)
send(ch, "first")            // fills the buffer
let ok = try_send(ch, "second")  // false — buffer is full

Arguments: Same as send.

Returns: Bool — true if sent, false otherwise.

Errors:

• "try_send() requires (channel, value)" — Wrong argument count.
• "try_send() first argument must be a channel" — First argument is not a channel.

Receiving Values

receive(channel)

The receive builtin receives a value from a channel. It blocks until a value is available.

let ch = channel()
send(ch, 42)
let val = receive(ch)    // 42

If the channel is closed (all senders dropped) and the buffer is empty, receive returns null.

Arguments:

• channel — A Channel value.

Returns: The received Value, or null if the channel is closed.

Errors:

• "receive(channel) requires 1 argument" — No argument provided.
• "receive() requires a channel as first argument" — Argument is not a channel.

try_receive(channel)

The try_receive builtin attempts to receive a value without blocking. Returns Some(value) if a value was available, None if the channel is empty.

let ch = channel()
let result = try_receive(ch)    // None — nothing sent yet

send(ch, 42)
let result = try_receive(ch)    // Some(42)

Arguments:

• channel — A Channel value.

Returns: Some(value) if a value was received, None if the channel is empty or closed.

Errors:

• "try_receive() requires a channel" — No argument provided.
• "try_receive() argument must be a channel" — Argument is not a channel.

Producer-Consumer Pattern

Channels enable classic producer-consumer patterns:

let ch = channel()

// Producer
spawn {
    repeat 5 times {
        send(ch, it)
    }
}

// Consumer
repeat 5 times {
    let val = receive(ch)
    say "got: " + str(val)
}

Fan-Out Pattern

Multiple consumers can share a channel, though only one will receive each message:

let work = channel()
let results = channel()

// Producer
spawn {
    for item in tasks {
        send(work, item)
    }
}

// Workers
repeat 3 times {
    spawn {
        let item = receive(work)
        let result = process(item)
        send(results, result)
    }
}

Channel Lifetime

Channels remain open as long as at least one reference exists. When all references to a channel are dropped (through garbage collection or scope exit), the underlying SyncSender and Receiver are dropped, which closes the channel. Subsequent send calls on a closed channel return an error; receive calls return null.

Spawn

The spawn keyword creates a concurrent task that runs in a separate OS thread. It can be used as a statement (fire-and-forget) or as an expression (returning a task handle).

Syntax

SpawnStmt = "spawn" Block
SpawnExpr = "spawn" Block

When spawn appears as a statement, the result is discarded. When it appears as an expression (e.g., assigned to a variable), it returns a TaskHandle.

Statement Form (Fire-and-Forget)

When spawn is used as a statement, the block is executed concurrently and its result is discarded:

spawn {
    say "running in background"
}
say "continues immediately"

The parent does not wait for the spawned task to complete. The spawned block runs independently.

Expression Form (Task Handle)

When spawn is used as an expression, it returns a TaskHandle that can be awaited:

let handle = spawn {
    return 42
}

let result = await handle    // 42

The task handle is an opaque value that represents the running task. Its type name is "TaskHandle".

Execution Model

When spawn is executed:

1. The block’s statements are cloned.
2. A new Interpreter is created and its environment is cloned from the parent.
3. A shared result slot is created: Arc<(Mutex<Option<Value>>, Condvar)>.
4. A new OS thread is spawned via std::thread::spawn.
5. The thread executes the block. When it completes:
   • Signal::Return(v) or Signal::ImplicitReturn(v) stores v in the result slot.
   • Signal::None or other signals store null.
   • Errors print to stderr and store null.
6. The Condvar is notified, unblocking any await on the handle.
7. The TaskHandle value is returned to the parent.

Environment Cloning

The spawned task receives a clone of the parent’s environment at the point of the spawn call. This means:

• Variables defined before spawn are accessible in the spawned block.
• Modifications to the environment inside the spawned block do not affect the parent.
• Modifications in the parent after spawn do not affect the spawned block.

let x = 10
spawn {
    say x        // 10 — sees parent's x
    let x = 20   // shadows, does not affect parent
}
say x            // 10 — parent's x unchanged

Return Values

The spawned block may use return to provide a result. This value is stored in the task handle’s result slot:

let h = spawn {
    return "hello from spawn"
}
let msg = await h    // "hello from spawn"

If no return is used, the result is the last expression value (implicit return) or null:

let h = spawn {
    1 + 1
}
let result = await h    // may be 2 or null depending on block signal

Error Isolation

Errors in spawned tasks are isolated from the parent. A runtime error in the spawned block:

1. Prints the error message to stderr: spawn error: <message>.
2. Stores null in the result slot.
3. Does not crash or affect the parent task.

spawn {
    let x = 1 / 0    // error: division by zero
}
// Parent continues normally
say "still running"

When the handle is awaited, the result is null:

let h = spawn {
    return 1 / 0
}
let result = await h    // null (error was caught internally)

Multiple Spawns

Multiple tasks can be spawned and awaited:

let a = spawn { return 10 }
let b = spawn { return 20 }

let va = await a    // 10
let vb = await b    // 20
say va + vb         // 30

Tasks run concurrently in separate threads. The order of completion is non-deterministic.

Spawn with Channels

Spawn and channels work together for structured concurrency:

let ch = channel()

spawn {
    let result = expensive_computation()
    send(ch, result)
}

// Do other work...

let result = receive(ch)    // blocks until computation completes

Async Functions

Async functions are functions that execute asynchronously and must be awaited to retrieve their result. Forge provides dual syntax: async fn (classic) and forge (natural).

Syntax

AsyncFnDef    = ("async" "fn" | "forge") Identifier "(" ParamList ")" Block

Defining Async Functions

Classic syntax:

async fn fetch_data() {
    let resp = http.get("https://api.example.com/data")
    return resp
}

Natural syntax:

forge fetch_data() {
    let resp = http.get("https://api.example.com/data")
    return resp
}

Both forms are semantically identical. The parser produces the same FnDef AST node with is_async: true.

Semantics

An async function is defined with the is_async flag set to true in the AST. In the current implementation, async functions are stored as regular function values. The is_async flag is recorded in the AST but the interpreter treats async functions identically to synchronous functions during definition.

The distinction becomes relevant at the call site: async functions are expected to be called with await (or hold) to retrieve their result. Without await, the function executes synchronously and its return value is available immediately.

Registration

When an async function definition is executed, the function is registered in the environment as a Value::Function just like a synchronous function. The is_async flag from the AST does not alter the stored function value.

forge get_value() {
    return 42
}

// The function is callable like any other function
let result = get_value()       // 42 (runs synchronously)
let result = await get_value() // 42 (await passes through non-handle values)

Parameters and Return Values

Async functions support the same parameter syntax as regular functions, including default values and type annotations:

async fn fetch_user(id: Int, timeout: Int = 30) {
    let resp = http.get("https://api.example.com/users/" + str(id))
    return json.parse(resp.body)
}

Return values follow the same rules as synchronous functions. The return statement provides an explicit return value; without it, the function returns null or the last expression’s value.

Combining with Spawn

For true concurrent execution, combine async functions with spawn:

forge compute(n) {
    // Expensive computation
    return n * n
}

let handle = spawn { return compute(42) }
let result = await handle    // 1764

The spawn keyword is what creates actual concurrency (a new OS thread). The async/forge keyword marks intent but does not itself create a new thread.

Natural Syntax: forge

The forge keyword serves double duty as both the language name and the natural-syntax alias for async fn. In a function definition context, forge is parsed as an async function definition:

forge load_config() {
    let text = fs.read("config.json")
    return json.parse(text)
}

This reads naturally as “forge a load_config function” while being functionally equivalent to async fn load_config().

Await

The await keyword (or its natural alias hold) suspends the current execution until an asynchronous operation completes, then returns the result. It is primarily used with task handles from spawn.

Syntax

AwaitExpr = ("await" | "hold") Expression

Semantics

The await expression evaluates its operand and inspects the result:

TaskHandle

If the operand is a TaskHandle (returned by spawn), await blocks the current thread until the spawned task completes, then returns the task’s result value.

let h = spawn { return 42 }
let result = await h    // blocks until task completes, returns 42

The blocking mechanism uses a condition variable:

1. Lock the Mutex<Option<Value>> inside the task handle.
2. While the value is None, wait on the Condvar.
3. When notified (the spawned task stored its result), extract the value.
4. Return the extracted value, or null if the slot was empty.

Non-Handle Values (Pass-Through)

If the operand is not a TaskHandle, await returns the value unchanged. This provides backward compatibility and allows await to be used uniformly:

await 42         // 42
await "hello"    // "hello"
await null       // null
await Ok(10)     // Ok(10)

This pass-through behavior means await is always safe to call, even on values that are not async results.

Natural Syntax: hold

The hold keyword is the natural-syntax alias for await:

let h = spawn { return "data" }
let result = hold h    // "data"

hold and await are parsed to the same Expr::Await AST node and behave identically.

Awaiting Multiple Tasks

Multiple task handles can be awaited sequentially:

let a = spawn { return 10 }
let b = spawn { return 20 }
let c = spawn { return 30 }

let va = await a    // 10
let vb = await b    // 20
let vc = await c    // 30

say va + vb + vc    // 60

Each await blocks until its specific task completes. Tasks run concurrently, so the total time is approximately the duration of the slowest task, not the sum.

Awaiting Errored Tasks

If a spawned task encountered a runtime error, its result slot contains null. Awaiting such a handle returns null:

let h = spawn {
    return 1 / 0    // runtime error
}

let result = await h    // null

The error is printed to stderr by the spawned task. The parent receives null and must check for it if error detection is needed.

Await in Functions

await can be used inside regular and async functions:

fn parallel_sum(a, b) {
    let ha = spawn { return a * a }
    let hb = spawn { return b * b }
    return await ha + await hb
}

parallel_sum(3, 4)    // 25

Error Handling

The await expression can raise runtime errors in two cases:

• "await: task handle lock poisoned" — The Mutex guarding the result slot was poisoned (the spawned thread panicked while holding the lock).
• "await: condvar wait failed" — The condition variable wait failed.

Both are exceptional conditions that indicate a serious runtime problem.

Comparison with hold

There is no semantic difference. Use whichever style matches your code’s convention.

Standard Library Overview

Forge ships with 16 built-in modules containing over 230 functions. All modules are available without any import statement. There is no import math or require("fs") – every module is pre-loaded into the global scope.

Accessing Modules

Modules are accessed via dot notation:

let root = math.sqrt(144)       // 12.0
let data = fs.read("config.json")
let hash = crypto.sha256("hello")

Each module is a first-class object. You can assign it to a variable:

let m = math
say m.pi    // 3.141592653589793

Module Index

Execution Tier Support

All modules are fully supported in the interpreter (default execution mode). The bytecode VM (--vm) and JIT (--jit) support a subset of modules – primarily math, fs, io, and npc. For full module access, use the interpreter.

math

Mathematical operations and constants. All trigonometric functions use radians.

Constants

say math.pi    // 3.141592653589793
say math.e     // 2.718281828459045

Functions

math.sqrt(n) -> float

Returns the square root of n.

math.sqrt(144)   // 12.0
math.sqrt(2)     // 1.4142135623730951

math.pow(base, exp) -> int | float

Returns base raised to the power of exp. Returns int when both arguments are non-negative integers; returns float otherwise.

math.pow(2, 10)    // 1024
math.pow(2.0, 0.5) // 1.4142135623730951
math.pow(2, -1)    // 0.5

math.abs(n) -> int | float

Returns the absolute value of n. Preserves the input type.

math.abs(-42)    // 42
math.abs(-3.14)  // 3.14

math.max(a, b) -> int | float

Returns the greater of a and b.

math.max(10, 20)     // 20
math.max(3.14, 2.71) // 3.14

math.min(a, b) -> int | float

Returns the lesser of a and b.

math.min(10, 20)     // 10
math.min(3.14, 2.71) // 2.71

math.floor(n) -> int

Returns the largest integer less than or equal to n.

math.floor(3.7)   // 3
math.floor(-1.2)  // -2
math.floor(5)     // 5

math.ceil(n) -> int

Returns the smallest integer greater than or equal to n.

math.ceil(3.2)    // 4
math.ceil(-1.8)   // -1
math.ceil(5)      // 5

math.round(n) -> int

Returns the nearest integer to n, rounding half away from zero.

math.round(3.5)   // 4
math.round(3.4)   // 3
math.round(-2.5)  // -3

math.random() -> float

Returns a pseudo-random float between 0.0 and 1.0 (exclusive).

let r = math.random()  // e.g. 0.482371...

math.random_int(min, max) -> int

Returns a pseudo-random integer in the inclusive range [min, max]. Errors if min > max.

let die = math.random_int(1, 6)   // 1-6
let coin = math.random_int(0, 1)  // 0 or 1

math.sin(n) -> float

Returns the sine of n (in radians).

math.sin(0)          // 0.0
math.sin(math.pi/2)  // 1.0

math.cos(n) -> float

Returns the cosine of n (in radians).

math.cos(0)       // 1.0
math.cos(math.pi) // -1.0

math.tan(n) -> float

Returns the tangent of n (in radians).

math.tan(0)          // 0.0
math.tan(math.pi/4)  // ~1.0

math.log(n) -> float

Returns the natural logarithm (base e) of n.

math.log(1)       // 0.0
math.log(math.e)  // 1.0

math.clamp(value, min, max) -> int | float

Clamps value to the range [min, max].

math.clamp(5, 1, 10)    // 5
math.clamp(-5, 0, 10)   // 0
math.clamp(15, 0, 10)   // 10

fs

File system operations. All paths are strings. Functions that write to the file system return null on success.

Functions

fs.read(path) -> string

Reads the entire file at path and returns its contents as a string.

let content = fs.read("config.txt")
say content

fs.write(path, content) -> null

Writes content to the file at path, creating or overwriting the file.

fs.write("output.txt", "Hello, world!")

fs.append(path, content) -> null

Appends content to the file at path. Creates the file if it does not exist.

fs.append("log.txt", "New log entry\n")

fs.exists(path) -> bool

Returns true if a file or directory exists at path.

if fs.exists("config.json") {
    say "Config found"
}

fs.list(path) -> array

Returns an array of file and directory names in the directory at path. Names only, not full paths.

let files = fs.list("./src")
// ["main.fg", "utils.fg", "lib"]

fs.remove(path) -> null

Deletes a file or directory (recursively) at path.

fs.remove("temp.txt")
fs.remove("build/")     // removes directory and all contents

fs.mkdir(path) -> null

Creates the directory at path, including any necessary parent directories.

fs.mkdir("build/output/logs")

fs.copy(source, destination) -> int

Copies a file from source to destination. Returns the number of bytes copied.

let bytes = fs.copy("original.txt", "backup.txt")
say bytes  // e.g. 1024

fs.rename(old_path, new_path) -> null

Renames or moves a file or directory.

fs.rename("draft.txt", "final.txt")

fs.size(path) -> int

Returns the size of the file at path in bytes.

let s = fs.size("data.bin")
say s  // e.g. 4096

fs.ext(path) -> string

Returns the file extension without the leading dot. Returns an empty string if none.

fs.ext("photo.png")     // "png"
fs.ext("Makefile")      // ""

fs.read_json(path) -> any

Reads a JSON file and returns the parsed Forge value (object, array, etc.).

let config = fs.read_json("config.json")
say config.name

fs.write_json(path, value) -> null

Serializes value as pretty-printed JSON and writes it to path.

let data = { name: "forge", version: "0.3.3" }
fs.write_json("package.json", data)

fs.lines(path) -> array

Reads a file and returns an array of strings, one per line.

let lines = fs.lines("data.csv")
say len(lines)  // number of lines

fs.dirname(path) -> string

Returns the directory portion of path.

fs.dirname("/home/user/file.txt")  // "/home/user"

fs.basename(path) -> string

Returns the file name portion of path.

fs.basename("/home/user/file.txt")  // "file.txt"

fs.join_path(a, b) -> string

Joins two path segments with the platform path separator.

fs.join_path("/home", "user")  // "/home/user"

fs.is_dir(path) -> bool

Returns true if path is a directory.

fs.is_dir("/tmp")      // true
fs.is_dir("file.txt")  // false

fs.is_file(path) -> bool

Returns true if path is a regular file.

fs.is_file("main.fg")  // true
fs.is_file("/tmp")      // false

fs.temp_dir() -> string

Returns the path to the system temporary directory.

let tmp = fs.temp_dir()
say tmp  // e.g. "/tmp"

crypto

Hashing and encoding utilities. All functions accept and return strings.

Functions

crypto.sha256(input) -> string

Returns the SHA-256 hash of input as a lowercase hex string.

crypto.sha256("hello")
// "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"

crypto.md5(input) -> string

Returns the MD5 hash of input as a lowercase hex string.

crypto.md5("hello")
// "5d41402abc4b2a76b9719d911017c592"

Note: MD5 is cryptographically broken. Use crypto.sha256 for security-sensitive hashing. MD5 is provided for compatibility and checksums only.

crypto.base64_encode(input) -> string

Encodes input as a Base64 string using the standard alphabet.

crypto.base64_encode("hello world")
// "aGVsbG8gd29ybGQ="

crypto.base64_decode(input) -> string

Decodes a Base64 string back to its original form.

crypto.base64_decode("aGVsbG8gd29ybGQ=")
// "hello world"

crypto.hex_encode(input) -> string

Encodes input as a hexadecimal string.

crypto.hex_encode("AB")
// "4142"

crypto.hex_decode(input) -> string

Decodes a hexadecimal string back to its original form.

crypto.hex_decode("4142")
// "AB"

db

SQLite database operations. Forge embeds SQLite via the rusqlite crate. One connection is maintained per thread.

Functions

db.open(path) -> bool

Opens a SQLite database at path. Use ":memory:" for an in-memory database. Returns true on success.

db.open(":memory:")
db.open("app.db")

db.execute(sql, params?) -> null

Executes a SQL statement that does not return rows (CREATE, INSERT, UPDATE, DELETE). An optional second argument provides parameterized values as an array, using ? placeholders.

db.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)")

// Parameterized insert (recommended)
db.execute("INSERT INTO users VALUES (?, ?, ?)", [1, "Alice", "alice@example.com"])

// Batch execution (no params)
db.execute("INSERT INTO users VALUES (2, 'Bob', 'bob@example.com')")

db.query(sql, params?) -> array

Executes a SQL SELECT query and returns an array of objects. Each object maps column names to values. An optional second argument provides parameterized values.

let users = db.query("SELECT * FROM users")
// [{id: 1, name: "Alice", email: "alice@example.com"}, ...]

// Parameterized query
let result = db.query("SELECT * FROM users WHERE id = ?", [1])
say result[0].name  // "Alice"

db.close() -> null

Closes the current database connection.

db.close()

Full CRUD Example

// Open database
db.open(":memory:")

// Create table
db.execute("CREATE TABLE tasks (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    done INTEGER DEFAULT 0
)")

// Create
db.execute("INSERT INTO tasks (title) VALUES (?)", ["Buy groceries"])
db.execute("INSERT INTO tasks (title) VALUES (?)", ["Write documentation"])
db.execute("INSERT INTO tasks (title) VALUES (?)", ["Deploy v2"])

// Read
let all_tasks = db.query("SELECT * FROM tasks")
say all_tasks

let pending = db.query("SELECT * FROM tasks WHERE done = ?", [0])
say len(pending)  // 3

// Update
db.execute("UPDATE tasks SET done = ? WHERE id = ?", [1, 1])

// Delete
db.execute("DELETE FROM tasks WHERE id = ?", [3])

// Verify
let remaining = db.query("SELECT * FROM tasks")
say remaining

// Close
db.close()

Notes

• SQLite types map to Forge types: INTEGER -> int, REAL -> float, TEXT -> string, NULL -> null, BLOB -> string (as <blob N bytes>).
• Parameterized queries (using ? placeholders with an array) are the recommended approach to prevent SQL injection.

pg

PostgreSQL database operations. Requires a running PostgreSQL server. Uses tokio-postgres under the hood and requires the async runtime (interpreter mode).

Functions

pg.connect(connection_string) -> bool

Connects to a PostgreSQL database. Returns true on success. The connection string follows the standard PostgreSQL format.

pg.connect("host=localhost user=postgres password=secret dbname=myapp")

pg.query(sql) -> array

Executes a SQL SELECT query and returns an array of objects. Each object maps column names to values.

let users = pg.query("SELECT id, name, email FROM users")
for user in users {
    say user.name
}

pg.execute(sql) -> int

Executes a SQL statement that does not return rows. Returns the number of rows affected.

let count = pg.execute("UPDATE users SET active = true WHERE last_login > now() - interval '30 days'")
say count  // number of rows updated

pg.close() -> null

Closes the current PostgreSQL connection.

pg.close()

Example

pg.connect("host=localhost dbname=shop user=postgres")

pg.execute("CREATE TABLE IF NOT EXISTS products (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    price NUMERIC(10,2)
)")

pg.execute("INSERT INTO products (name, price) VALUES ('Widget', 9.99)")
pg.execute("INSERT INTO products (name, price) VALUES ('Gadget', 24.99)")

let products = pg.query("SELECT * FROM products ORDER BY price")
for p in products {
    say p.name + " - $" + str(p.price)
}

pg.close()

Notes

• PostgreSQL types map to Forge types: integer/bigint -> int, real/double precision/numeric -> float, text/varchar -> string, boolean -> bool, NULL -> null.
• The pg module requires the interpreter (default) execution mode. It is not available in the VM or JIT tiers.

json

JSON parsing and serialization.

Functions

json.parse(string) -> any

Parses a JSON string and returns the corresponding Forge value. Objects become Forge objects, arrays become Forge arrays, and JSON primitives map to their Forge equivalents.

let data = json.parse('{"name": "Forge", "version": 3}')
say data.name     // "Forge"
say data.version   // 3

let arr = json.parse("[1, 2, 3]")
say arr[0]  // 1

json.stringify(value) -> string

Serializes a Forge value into a compact JSON string (no extra whitespace).

let obj = { name: "Forge", tags: ["fast", "fun"] }
let s = json.stringify(obj)
say s  // {"name": "Forge", "tags": ["fast", "fun"]}

json.pretty(value, indent?) -> string

Serializes a Forge value into a pretty-printed JSON string. The optional indent parameter specifies the number of spaces per indentation level (default: 2).

let obj = { name: "Forge", version: 3 }
say json.pretty(obj)
// {
//   "name": "Forge",
//   "version": 3
// }

say json.pretty(obj, 4)
// {
//     "name": "Forge",
//     "version": 3
// }

Type Mapping

csv

CSV parsing and serialization. Uses comma-separated values with automatic type inference for fields.

Functions

csv.parse(string) -> array

Parses a CSV string into an array of objects. The first line is treated as headers. Values are automatically converted to int, float, or bool where possible; otherwise they remain strings.

let data = csv.parse("name,age,active\nAlice,30,true\nBob,25,false")
say data[0].name    // "Alice"
say data[0].age     // 30
say data[1].active  // false

csv.stringify(rows) -> string

Converts an array of objects into a CSV string. Headers are derived from the keys of the first object.

let rows = [
    { name: "Alice", age: 30 },
    { name: "Bob", age: 25 }
]
let output = csv.stringify(rows)
say output
// name,age
// Alice,30
// Bob,25

Values containing commas or quotes are automatically quoted.

csv.read(path) -> array

Reads a CSV file from disk and parses it into an array of objects. Equivalent to csv.parse(fs.read(path)).

let users = csv.read("users.csv")
for user in users {
    say user.name + ": " + str(user.email)
}

csv.write(path, rows) -> null

Serializes an array of objects as CSV and writes it to the file at path.

let data = [
    { product: "Widget", price: 9.99, qty: 100 },
    { product: "Gadget", price: 24.99, qty: 50 }
]
csv.write("inventory.csv", data)

regex

Regular expression operations. Uses Rust’s regex crate syntax.

Important: All regex functions take the text first, pattern second: regex.test(text, pattern). This is the opposite of many other languages.

Functions

regex.test(text, pattern) -> bool

Returns true if pattern matches anywhere in text.

regex.test("hello world", "world")     // true
regex.test("hello world", "^world")    // false
regex.test("abc123", "\\d+")           // true

regex.find(text, pattern) -> string | null

Returns the first match of pattern in text, or null if no match.

regex.find("order-4521-confirmed", "\\d+")  // "4521"
regex.find("no numbers here", "\\d+")       // null

regex.find_all(text, pattern) -> array

Returns an array of all non-overlapping matches of pattern in text.

regex.find_all("call 555-1234 or 555-5678", "\\d{3}-\\d{4}")
// ["555-1234", "555-5678"]

regex.find_all("aabbaab", "a+")
// ["aa", "aa"]

regex.replace(text, pattern, replacement) -> string

Replaces all occurrences of pattern in text with replacement.

regex.replace("hello world", "world", "Forge")
// "hello Forge"

regex.replace("2024-01-15", "(\\d{4})-(\\d{2})-(\\d{2})", "$2/$3/$1")
// "01/15/2024"

The replacement string supports capture group references ($1, $2, etc.).

regex.split(text, pattern) -> array

Splits text by occurrences of pattern and returns an array of substrings.

regex.split("one,,two,,,three", ",+")
// ["one", "two", "three"]

regex.split("hello   world  foo", "\\s+")
// ["hello", "world", "foo"]

env

Environment variable access.

Functions

env.get(key, default?) -> string | null

Returns the value of the environment variable key. Returns null if the variable is not set, or default if provided.

let home = env.get("HOME")
say home  // "/Users/alice"

let port = env.get("PORT", "8080")
say port  // "8080" if PORT is not set

env.set(key, value) -> null

Sets the environment variable key to value for the current process.

env.set("APP_MODE", "production")

env.has(key) -> bool

Returns true if the environment variable key is set.

if env.has("DATABASE_URL") {
    say "Database configured"
}

env.keys() -> array

Returns an array of all environment variable names.

let all_keys = env.keys()
say len(all_keys)

log

Structured logging with timestamps and severity levels. All log output is written to stderr with ANSI color formatting.

Functions

log.info(…args) -> null

Logs an informational message in green.

log.info("Server started on port", 8080)
// [14:30:15 INFO]  Server started on port 8080

log.warn(…args) -> null

Logs a warning message in yellow.

log.warn("Disk usage above 80%")
// [14:30:15 WARN]  Disk usage above 80%

log.error(…args) -> null

Logs an error message in red.

log.error("Failed to connect to database:", err)
// [14:30:15 ERROR] Failed to connect to database: connection refused

log.debug(…args) -> null

Logs a debug message in gray. Useful for development diagnostics.

log.debug("Request payload:", data)
// [14:30:15 DEBUG] Request payload: {name: "Alice"}

Notes

• All functions accept any number of arguments. Arguments are converted to strings and joined with spaces.
• Timestamps use the local time in HH:MM:SS format.
• Output goes to stderr, not stdout, so it does not interfere with piped output.

term

Terminal formatting, colors, and UI widgets. Color functions return styled strings; display functions print to stderr and return null.

Color Functions

Each color function wraps text in ANSI escape codes and returns the styled string.

term.red(text) -> string

term.green(text) -> string

term.blue(text) -> string

term.yellow(text) -> string

term.cyan(text) -> string

term.magenta(text) -> string

say term.red("Error!")
say term.green("Success!")
say term.blue("Info")

term.bold(text) -> string

term.dim(text) -> string

say term.bold("Important")
say term.dim("subtle note")

Display Functions

term.table(rows) -> null

Prints a formatted table from an array of objects. Column widths are auto-calculated. Headers come from the keys of the first object.

let data = [
    { name: "Alice", role: "Admin", active: true },
    { name: "Bob", role: "User", active: false }
]
term.table(data)
// name  | role  | active
// ------+-------+-------
// Alice | Admin | true
// Bob   | User  | false

term.hr(width?, char?) -> null

Prints a horizontal rule. Default width is 40, default character is "─".

term.hr()         // ────────────────────────────────────────
term.hr(20)       // ────────────────────
term.hr(20, "=")  // ====================

term.banner(text) -> null

Prints text in a double-line box.

term.banner("Forge v0.3.3")
// ╔════════════════╗
// ║  Forge v0.3.3  ║
// ╚════════════════╝

term.box(text) -> null

Prints text in a single-line box. Supports multi-line text.

term.box("Hello\nWorld")
// ┌───────┐
// │ Hello │
// │ World │
// └───────┘

term.bar(label, value, max?) -> null

Prints a progress bar. Default max is 100.

term.bar("CPU", 73, 100)
//   CPU [██████████████████████░░░░░░░░] 73%

term.sparkline(numbers) -> string

Returns a sparkline string from an array of numbers using Unicode block characters.

let spark = term.sparkline([1, 5, 3, 8, 2, 7, 4, 6])
say spark  // ▁▅▃█▂▇▃▆

term.gradient(text) -> string

Returns text with a rainbow gradient using 256-color ANSI codes.

say term.gradient("Hello, Forge!")

term.success(message) -> null

Prints a green success message with a checkmark.

term.success("Build complete")
//   ✅ Build complete