Introduction

Overview

Lattice is a general-purpose programming language built around a unique phase system inspired by states of matter. Variables exist in phases — mutable flux or immutable fix — and transition between them through explicit operations like freeze() and thaw(). This gives programmers fine-grained control over mutability at every stage of a program's execution.

Lattice is expression-based, dynamically typed with optional runtime type annotations, and supports first-class closures, structured concurrency with channels, pattern matching, and a comprehensive standard library of over 120 built-in functions.

Version

This specification describes Lattice version 0.3.1. The reference implementation is written in C and compiles source code to bytecode which runs on a stack-based virtual machine. A tree-walking interpreter is also available via the --tree-walk flag.

Notation Conventions

Throughout this specification, the following conventions are used:

• EBNF grammar is shown in shaded blocks. Non-terminals are written in italic, terminals in "quotes", and alternatives separated by |. Optional elements use [ ], repetition uses { }, and grouping uses ( ).
• Code examples are shown in syntax-highlighted blocks with the .lat file convention.
• Notes and warnings call out important behavioral details in colored callout boxes.

Grammar Notation

The grammar notation used in this specification follows extended Backus-Naur form (EBNF):

production    ::= name "::=" expression
expression    ::= alternative { "|" alternative }
alternative   ::= term { term }
term          ::= name                // non-terminal
               |  "literal"           // terminal string
               |  "[" expression "]"   // optional (0 or 1)
               |  "{" expression "}"   // repetition (0 or more)
               |  "(" expression ")"   // grouping

Execution Modes

Lattice supports two execution modes, controlled by a directive at the top of a source file:

• #mode casual (default) — The standard mode. Variables declared with let have their phase inferred. Unused variables do not trigger errors.
• #mode strict — Enables stricter checking. All phase transitions must be explicit. Additional warnings may be emitted.

// Enable strict mode at the top of the file
#mode strict

fn main() {
    flux x = 42     // Explicit mutable binding
    fix y = 100      // Explicit immutable binding
    freeze(x)        // Explicit phase transition
}

Program Structure

A Lattice program is a sequence of items and statements. Items include function declarations, struct definitions, enum definitions, trait declarations, impl blocks, and test blocks. Statements include bindings, assignments, expressions, and control flow.

program  ::= { item }
item     ::= function | struct | enum | trait | impl | test | statement

Lattice programs can optionally define a main() function as an entry point. If no main() function is defined, top-level statements are executed in order.

Interactive REPL

Lattice includes an interactive Read-Eval-Print Loop (REPL) for exploratory programming. Launch the REPL by running clat without arguments. The REPL maintains persistent state across lines — function, struct, and enum declarations remain available for the duration of the session.

Non-Unit and non-Nil expression results are automatically displayed with an => prefix.