Nex

Verification Model

2026-05-22T19:26:20.099529896Z

The Nex implementation runs two execution paths in parallel and treats their disagreement as a bug:

Tree-walking interpreter. The reference semantics. Used by nex run and nex test. Easy to read, easy to step through, easy to extend when adding a new language feature.
AOT compiler. LLVM IR text → clang -O1 → native binary. Used by nex compile. The path users ship.

Three layers of testing

Unit tests on every subsystem. Lexer, parser, three elaborator stages, interpreter, codegen, prelude. Over two thousand tests on JVM today; every commit runs the full suite on all three CLI targets (JVM, Scala.js, Scala Native). Backend-shelling tests (those that drive clang or the MLIR toolchain) run on JVM only; the cross-platform subset covers the parser, elaborator, and interpreter.
IR pattern checks. Codegen tests assert against expected LLVM IR fragments — both that the right instructions are emitted and that the fusion pass actually produced a single loop where it claimed to. This catches regressions where the IR drifts shape but still happens to execute correctly.
End-to-end interpreter/AOT parity. A shared corpus of programs (see NexProgramCorpus) is run twice — once through the interpreter, once through the AOT binary — and the two stdouts are compared byte-for-byte. A mutation-based fuzz harness (NexMutations) applies behaviour-preserving rewrites to each corpus program and reruns the comparison so silent miscompiles surface as parity failures. The AOT path emits reals via an iterative shortest-round-trip helper (%.<p>g + strtod for p = 1..17) plus a Java-Double.toString-style post-pass, so non-whole reals like 0.1 + 0.2 print as 0.30000000000000004 on both sides instead of %g‘s 6-significant-figure approximation.

Why this matters

Numerical code is unforgiving — silent codegen bugs corrupt computation in ways that look exactly like correct output until they don’t. Running a reference interpreter alongside a compiler and demanding byte-exact agreement turns a class of “did the optimizer break it?” bugs into immediate test failures.

The model came from sysl, where it has been load-bearing across seven backends. Nex inherits the same discipline.

Type System

2026-05-22T19:26:20.099529896Z

3.1 Primitive types

Type	Description	Size
`bool`	Boolean (`true` or `false`)	1 byte
`integer`	Signed integer	64 bits
`real`	IEEE 754 floating-point	64 bits
`complex`	Pair of `real` (re, im)	128 bits
`unit`	Single value `()`	0 bits
`string`	UTF-8 byte string	reference-typed

Sized variants (integer32, real32, complex32, etc.) are deferred.

3.2 Numeric promotion

The numeric types form a promotion lattice:

integer  →  real  →  complex

When an operator is applied to operands of different numeric types, the operand of the lower type is implicitly promoted. The result has the higher type.

1 + 2.0        // real, promotes 1 → 1.0, result 3.0
1.0 + 2.0i     // complex, promotes 1.0 → 1.0+0.0i, result 1.0+2.0i
1 + 2.0i       // complex, promotes 1 → 1.0 → 1.0+0.0i

Promotion is implicit in expression context. Conversion in the narrowing direction is never implicit — see chapter 4.

3.3 Array types

The array type [T] denotes a rank-1 array (vector) of elements of type T, with runtime-determined length. The array type [[T]] denotes a rank-2 array (matrix), with runtime-determined shape (rows × columns). T must be one of bool, integer, real, or complex.

[real]       // rank-1: vector of real
[integer]    // rank-1: vector of integer
[[real]]     // rank-2: matrix of real
[[complex]]  // rank-2: matrix of complex

Rank-2 arrays are rectangular — every row has the same number of columns. Constructing a jagged array (rows of differing lengths) traps at runtime. Storage is column-major, matching Fortran and the standard LAPACK/BLAS convention so that future FFI to those libraries is layout-compatible without transposing.

Higher-rank arrays ([[[T]]] and beyond) and statically-shaped arrays ([T; N], [T; M, N]) are deferred.

3.3.1 The `[byte]` buffer type

[byte] is a packed buffer of 8-bit values used for file I/O and image processing. It is a separate type from [T], not [byte] = [integer] with a narrower range. There is no scalar byte type — bytes only exist as elements of a buffer.

val b: [byte] = bytes(64)        // zero-filled buffer of length 64
val first = b[0]                 // first: integer (0..255)
b[1] = 128                       // traps if RHS is outside 0..255

Indexed read widens to integer in the range 0..255; indexed write requires the right-hand side to be an integer in the same range, otherwise it traps. The widening is unconditional — there is no implicit “is this within 0..255?” check on read, because by construction every stored byte already is.

[byte] is a storage type, not a computation type:

No element-wise arithmetic (b1 + b2 is a type error).
No broadcasting (b + 1 is a type error).
No views (b.view(lo..hi) is not supported; slicing copies).
No participation in fusion.

To do arithmetic on byte data, widen explicitly with to_integers(b), compute on the resulting [integer], and narrow back with to_bytes(a) (which traps if any element is outside 0..255). This widen-compute-narrow pattern is the recommended shape for sRGB / HDR / linear-light pixel math, where the computation lives in real or integer regardless.

Slicing b[lo..hi] (and the inclusive / open / strided variants from §4.14) returns a fresh [byte] copy. length(b) returns the buffer’s element count. Structural equality (==, !=) compares lengths first and then bytes.

3.4 Tuple types

A tuple type is a comma-separated list of types denoting a fixed-size heterogeneous product (n ≥ 2). Tuples are primarily used for multi-value return.

real, real
integer, [real], complex

Parentheses around a tuple type are optional grouping; they are required only when the surrounding context would otherwise parse the commas as something else (parameter declarations, type arguments, array element types). Both forms are equivalent:

def split(arr: [real]): real, real = ...           // paren-less return type
def split(arr: [real]): (real, real) = ...         // explicit grouping

In a parameter declaration the parens are mandatory because the outer parens of the parameter list use commas to separate parameters:

def join(left: (real, real), right: (real, real)) = ...    // two tuple parameters
def join(left: real, real, right: real, real) = ...        // ERROR: 4 parameters

3.5 Struct types

A struct type is declared with struct. Fields are declared one per line, with types:

struct Point
  x: real
  y: real
end

struct LineSegment
  start: Point
  finish: Point
  weight: real
end

Struct types are pure data — no methods, no inheritance, no constructors beyond the implicit field-list constructor. Struct values are constructed by naming the type followed by parenthesized arguments in declaration order:

val p = Point(3.0, 4.0)
val seg = LineSegment(Point(0.0, 0.0), Point(1.0, 1.0), 2.5)

Field access uses .:

val px = p.x
val end_x = seg.finish.x

3.6 Generic structs

A struct declaration may introduce one or more type parameters in square brackets after its name. Each type parameter stands for a type fixed at the use site; the field declarations may name the parameters, and the compiler generates a specialized clone of the struct for every distinct argument combination.

struct Box[T]
  value: T
end

struct Pair[A, B]
  fst: A
  snd: B
end

The bracket list follows the same shape as the one on a generic function (see §6.10): each entry is a bare [T] (admits any type) or a bounded [T: Kind] drawn from the same closed constraint set — Any, Numeric, Real, Float, Complex, Ord, Eq. A use site whose argument type isn’t admitted by the constraint is rejected at elaboration time.

Call-site inference. A generic struct is constructed exactly like a monomorphic one — the type arguments are not written. The compiler infers them by unifying each field’s declared type against the actual argument:

val p = Pair(1, "hi")          // A := integer, B := string
val q = Pair(1.0, 2.0)         // A := real,    B := real
val b = Box(42)                // T := integer

Explicit type arguments. A binding’s declared type may carry explicit arguments, which is useful when call-site inference cannot pin every parameter on its own — for instance, to pin a payload’s type ahead of the constructor or to disambiguate at a join point:

val p: Pair[integer, string] = Pair(1, "hi")

Specialization. Like generic functions, generic struct templates have no executable form on their own. Each unique combination of type arguments produces a specialized struct (e.g. Pair$integer$string, Pair$real$real) with the concrete fields already substituted. Two specializations of the same template with different arguments are independent types — a value of one cannot stand in for the other.

Combining with generic functions. A type parameter on a function can flow through to a generic struct constructor; the function’s specialization carries the right struct specialization with it:

def pack[T](x: T, y: T): Pair[T, T] = Pair(x, y)

val a = pack(1, 2)             // Pair$integer$integer
val b = pack(1.5, 2.5)         // Pair$real$real

The same constraint vocabulary applies — struct Sorted[T: Ord] is well-formed and lets the field operations rely on < / <= / > / >=.

3.7 Sum types

A sum type is declared with enum. Each line of the body declares a variant — either a bare name (a single value of the enum type) or a constructor that takes named, typed fields:

enum Color =
  Red
  Green
  Blue

enum Solver =
  Converged(x: real)
  Diverged
  MaxIters(iters: integer, last: real)

A variant’s field types are restricted to scalar types (integer, real, bool, string) in the current implementation. Aggregate fields (arrays, tuples, structs, complex, nested enums) are deferred.

Variant references are values directly when the variant is bare (Red, Diverged), or callable constructors when the variant has fields (Converged(3.14), MaxIters(100, 0.5)). Both forms yield a value whose static type is the enclosing enum:

val a: Color  = Green
val b: Solver = Converged(2.5)
val c: Solver = Diverged

Sum-type values are inspected with match (see §7.5). Printing a sum-type value renders bare variants as their name (Red) and fielded variants as Name(f0, f1, ...) (Converged(3.14)).

3.8 Generic enums

An enum declaration may introduce type parameters in square brackets, exactly like a generic struct. The parameters may appear in variant payload field types; bare variants carry no payload but still participate in the enum’s specialization.

enum Opt[T] =
  Some(value: T)
  None

enum Result[T, E] =
  Ok(value: T)
  Err(error: E)

The bracket list uses the same constraint vocabulary as §3.6 and §6.10: a bare [T] admits any type; a bound [T: Kind] restricts the parameter to the closed kind set.

Call-site inference. A variant constructor (Some(x), Ok(v)) infers its enum’s type arguments from its argument types:

val x = Some(42)               // Opt$integer
val r = Ok(3.14)               // E unpinned — see below

Bare-variant inference. A bare variant (None, no payload) carries no information to infer its enclosing enum’s type parameters from. Bare-variant references rely on push-down from a declared type on the surrounding binding:

val n: Opt[integer] = None     // T := integer via the annotation

A bare variant in a context with no declared type to push down (e.g. an if … then Some(1) else None with no outer annotation) is rejected the same way an unconstrained generic function call would be.

Partial-inference annotations. When only some of a multi-parameter enum’s type parameters can be pinned from a single use, the binding must carry an explicit type. Constructing Ok(7) on a Result[T, E] pins T from the argument but leaves E open:

val r: Result[integer, string] = Ok(7)

Without the annotation the compiler rejects the construction with a “cannot infer type for type parameter E“ diagnostic — the same shape Rust reports for an analogous case.

Match patterns. Patterns on a specialized enum reference the specialization’s variants. The scrutinee’s static type determines which specialization is matched; nested payload patterns bind values of the substituted field type:

val msg = x match
  Some(v) -> "got " + str(v)
  None    -> "nothing"

Specialization. Like generic structs, each unique combination of type arguments produces a specialized enum (Opt$integer, Opt$string, Result$integer$string, etc.) with its own per-variant constructors. Two specializations are independent types; a value of one cannot stand in for the other.

3.9 Function types

A function type (T1, T2, ..., Tn) -> R denotes a function taking arguments of the given types and returning R. A single-argument function may be written without parentheses:

real -> real
(real, real) -> real
([real], real -> real) -> [real]

A function type may include parameter modes (see chapter 6):

(mut [real]) -> unit

3.10 Type expressions

Type expressions are used in declarations (function signatures, struct field types, explicit annotations on bindings). They consist of:

Primitive type names (bool, integer, real, complex, unit, string)
Array type constructors ([T])
Tuple type constructors ((T1, ..., Tn))
Function type constructors ((T1, ..., Tn) -> R)
User-defined type names (referring to declared structs or enums)
Applied generic type names (Pair[integer, string], Opt[integer]) — see §3.6 and §3.8

Tour

2026-05-22T19:26:20.099529896Z

Comments

// Line comment.

/* Block comment. */

/* Block comments /* can nest */ — convenient for commenting out code. */

Layout: separators and line continuation

val a = 1; val b = 2        // multiple statements on one line, separated by ;

val long_expression =       // a line ending with an operator or open
  some_function(x, y)       // delimiter continues on the next (more-
    + another(z)            // indented) line; no backslash needed
    * yet_another(w)

; is rarely used; line continuation is common for expression-heavy numerical code.

Literals

Booleans, integers, reals

val flag    = true
val n       = 42
val big     = 1_000_000
val hex     = 0xFF              // 255
val bin     = 0b1010_1010       // 170
val oct     = 0o755             // 493
val pi_ish  = 3.14159
val sci     = 6.022e23
val sep     = 1_234.567_89

Strings and escapes

val hello   = "hello, world"
val multi   = "line one\nline two"
val tabbed  = "col1\tcol2"
val quoted  = "she said \"hi\""
val unicode = "\u{1F600}"           // 😀
val byte    = "\xC3\xA9"             // bytes for "é"

Interpolated strings (`s"..."`)

val name = "Ada"
val n = 42
val z = 3.0 + 4i

print(s"hello, $name")                  // hello, Ada
print(s"n = $n, n+1 = ${n + 1}")        // n = 42, n+1 = 43
print(s"|z| = ${z.abs()}")              // |z| = 5.0
print(s"first element = ${[10, 20][0]}")
print(s"literal dollar: $$")            // literal dollar: $

// $ident.field treats only $ident as the splice — .field is literal text.
// Use ${ident.field} to interpolate a field access:
print(s"$z.re")                         // (3.0 + 4.0i).re
print(s"${z.re}")                       // 3.0

Complex via the `i` constant

val a = i                   // (0.0 + 1.0i)  — imaginary unit
val b = 2i                  // (0.0 + 2.0i)  — juxtaposition: 2 * i
val c = 3 + 4i              // (3.0 + 4.0i)
val d = exp(pi * i)         // ~ (-1.0 + 0.0i)  (Euler's identity)

i is the prelude name; for i in 0..n shadows it normally. Pick a different index name (j, k, n, m) if you need both in the same scope.

Unit

val nothing = ()            // the single value of type `unit`

Bindings

val x = 10                  // immutable + has storage
var y = 20                  // mutable + has storage
y = 30                      // OK
y += 1                      // OK — compound assignment, same as y = y + 1
                            // (also: -=  *=  /=  %=)

val n: integer = 7          // explicit type annotation
var arr: [real] = [1.0, 2.0, 3.0]
val empty: [real] = []      // empty literal needs annotation

// `const` — compile-time constant; RHS must be a constant expression.
// May appear at any scope; compiler may inline at use sites.
const PI_OVER_2 = pi / 2
const TOL       = 1.0e-12
const MAX_ITER  = 1000

// `const` inside a function works too:
def newton(f: real -> real, x0: real) =
  const LOCAL_TOL = 1.0e-8
  // ...

// Calls to pure functions (prelude or user-defined) returning a scalar
// are constant expressions:
const SQRT_2 = sqrt(2.0)            // OK — sqrt is pure
const HYP    = hypot(3.0, 4.0)      // OK — 5.0

def square(x: real): real = x * x
const NINE   = square(3.0)          // OK — square is pure

// Calls that return non-scalars (arrays, tuples, structs) still need val:
val SAMPLES = linspace(0.0, 1.0, 100)

// Shadowing in a new scope is allowed:
val p = 1
if true then
  val p = 99                // OK: new scope shadows outer p
  print(p)                  // 99
end if
print(p)                    // 1

Block expressions

A multi-statement block is itself an expression — the value of the block is its final expression. Block expressions arise wherever an expression is expected: val RHS, function bodies, lambda bodies, branches of if.

val computed =
  val temp   = sqrt(2.0)
  val scaled = temp * 100.0
  scaled + 1.0             // value of the block is this final expression

// `if` branches are block expressions too:
val classified =
  if x > 0.0 then
    val msg = "positive"
    print(s"got $msg")
    msg
  else
    val msg = "non-positive"
    print(s"got $msg")
    msg

Arithmetic

7 + 3        // 10
7 - 3        // 4
7 * 3        // 21
7 / 3        // 2.333...  (real division — operands promoted)
7 div 3      // 2        (integer division — `div` keyword)
7 % 3        // 1        (modulo, integer)
2 ^ 10       // 1024     (exponentiation)
2.0 ^ 0.5    // 1.414...
-7           // unary minus

Numeric promotion

1 + 2.0      // integer 1 → real 1.0; result real 3.0
1.0 + 2i     // real → complex; result (1.0 + 2.0i)
1 + 2i       // integer → real → complex; result (1.0 + 2.0i)

Comparison and logical

5 < 10           // true
5 == 5           // true
5 != 5           // false

true and false   // false
true or false    // true
not true         // false

// Element-wise on arrays:
val v = [1, 2, 3, 4]
val mask = v < 3                          // [true, true, false, false]

// Chained comparisons read like the math — `0 <= i < n` desugars to
// `(0 <= i) and (i < n)` with the middle operand evaluated at most
// once and only when the previous compare held:
val i = 3
val n = 10
val in_range = 0 <= i < n                 // true

// Any number of comparisons may be chained; operators can be mixed.
val tight = 1 < i <= 3 < n                // true

Juxtaposition multiplication

val x = 5.0
val a = 2x                  // 2 * x = 10.0
val b = 2(x + 1)            // 2 * (x + 1) = 12.0
val c = 2pi                 // 2 * pi
val d = 3sin(pi/4)          // 3 * sin(pi/4)
val e = 2i                  // 2 * i

// Identifier-prefix is NOT juxtaposition — xy is one identifier.
val y = 4.0
val p = x * y               // explicit * required between identifiers

// Precedence: ^ > juxtaposition > * / // %
val q = 2x^3                // 2 * (x^3) = 250.0
val r = 1/2x                // 1 / (2 * x) = 0.1
val s = 2x * 3              // (2x) * 3 = 30.0

Arrays — rank-1

val v: [real] = [1.0, 2.0, 3.0]

length(v)              // 3
v[0]                   // 1.0
v[-1]                  // 3.0             — negative indices wrap from the end
v[1..3]                // [2.0, 3.0]      slice (owned copy)
v[0..=1]               // [1.0, 2.0]      inclusive slice
v[-2..]                // [2.0, 3.0]      open upper bound — fills with length(v)
v[..2]                 // [1.0, 2.0]      open lower bound — fills with 0
v[..]                  // [1.0, 2.0, 3.0] both ends open — whole-array copy

val w = [10.0, 20.0, 30.0, 40.0, 50.0, 60.0, 70.0, 80.0]
w[0..8 by 2]           // [10.0, 30.0, 50.0, 70.0]   — strided: every k-th element
w[1..8 by 3]           // [20.0, 50.0, 80.0]
w[.. by 2]             // [10.0, 30.0, 50.0, 70.0]   — stride combines with open bounds
w[-4.. by 2]           // [50.0, 70.0]                 and with negative bounds

// Element-wise arithmetic with broadcasting:
val a = [1.0, 2.0, 3.0]
val b = [4.0, 5.0, 6.0]
val c = 2a + b - 1.0   // [6.0, 9.0, 12.0]  — fuses to one loop

// View-style slicing — non-copying borrow into the source's buffer.
// Reads and writes alias the source; every rank-1 prelude function
// (sum, length, map, dot, ...) accepts a view transparently.
var src = [10, 20, 30, 40, 50]
val win = src.view(1..4)             // borrows src[1..4] — [20, 30, 40]
win[0] = 99                          // writes through: src is [10, 99, 30, 40, 50]
sum(win)                             // 99 + 30 + 40 = 169

// 3-arg form: strided view — borrow every k-th element of the window.
val big   = [10, 20, 30, 40, 50, 60, 70, 80]
val every2 = big.view(0..8, 2)       // [10, 30, 50, 70]
val every3 = big.view(1..8, 3)       // [20, 50, 80]
// View-of-view composes strides: this borrows every 4th of `big`.
every2.view(0..4, 2)                 // [10, 50]

Arrays — rank-2 (matrices)

val M: [[real]] = [[1.0, 2.0, 3.0],
                   [4.0, 5.0, 6.0]]        // 2×3

rows(M)                // 2
cols(M)                // 3
shape(M)               // (2, 3)
M[1, 2]                // 6.0               — element access
M[0]                   // [1.0, 2.0, 3.0]   — i-th row
M[:, 1]                // [2.0, 5.0]        — j-th column
M[0, 0..2]             // [1.0, 2.0]        — row 0, cols 0-1
M[0..2, 1..3]          // [[2.0, 3.0], [5.0, 6.0]]  — submatrix
M[1.., :]              // [[4.0, 5.0, 6.0]]         — open lo: rows 1..rows(M)
M[..2, ..2]            // [[1.0, 2.0], [4.0, 5.0]]  — open hi on both axes

// Element-wise on rank-2:
val N = [[10.0, 20.0, 30.0], [40.0, 50.0, 60.0]]
val P = M + N          // [[11.0, 22.0, 33.0], [44.0, 55.0, 66.0]]
val Q = 2M             // scalar broadcasts

// Matrix multiplication via @ (not element-wise):
val A = [[1.0, 2.0], [3.0, 4.0]]    // 2×2
val u = [5.0, 6.0]
val Au = A @ u                       // [17.0, 39.0]   matrix-vector
val AA = A @ A                       // [[7.0, 10.0], [15.0, 22.0]]  matrix-matrix
val d  = u @ u                       // 61.0           dot (rank-1 @ rank-1)

// Rank-2 view: borrow a contiguous row range. Row-major layout keeps
// the window contiguous, so no stride field is needed.
var grid = [[1, 2, 3], [4, 5, 6], [7, 8, 9], [10, 11, 12]]
val band = grid.view(1..3)           // rows 1..3 — a 2×3 view
band[0, 1] = 99                      // writes through: grid[1, 1] is now 99

// 3-arg form: sub-rectangle view — borrow a window in both axes. The
// visible rows have gaps in the underlying buffer; the descriptor
// carries a row-stride field so flat iteration (sum, map, transpose)
// still picks up the right elements.
val sub = grid.view(1..3, 0..2)      // [[4, 5], [99, 8]]    — 2×2 sub-matrix

`[byte]` buffers

A packed byte buffer for file I/O and image processing. Bytes are storage — indexing widens to an integer in 0..255, and writes outside that range trap.

val b = bytes(4)                // zero-filled buffer, length 4
b[0] = 0xFF                     // each cell holds 0..255
b[1] = 0x80
b[2] = 0x00
b[3] = 0x42

print(length(b))                // 4
print(b[0])                     // 255       — read widens to integer
print(b)                        // [0xFF, 0x80, 0x00, 0x42]

// Widen, compute, narrow:
val ints = to_integers(b)       // [255, 128, 0, 66]            : [integer]
val out  = to_bytes(ints)       // back to [byte] — traps if any > 255

// File I/O works on every backend (the prelude routes through
// the cross-platform runtime, so the same program runs on JVM,
// Node, and native).
write_bytes("hello.bin", b)
val read_back = read_bytes("hello.bin")
print(read_back == b)           // true

There is no scalar byte type — byte only exists as the element of a [byte] buffer, and arithmetic on bytes is always done by widening to integer. There is no element-wise arithmetic, broadcasting, or view form for [byte]; slicing copies. The full design is in the Specification, §3.3.1 and §10.9.

Slice assignment — Fortran-90 array sections

A slice expression on the left of = overwrites the corresponding sub-extent of a var array in place. The buffer is mutated, not reallocated.

var xs = [10, 20, 30, 40, 50]
xs[1..4] = [200, 300, 400]               // xs = [10, 200, 300, 400, 50]
xs[0..=2] = [1, 2, 3]                    // xs = [1, 2, 3, 400, 50]
xs[-2..]  = [99, 100]                    // open hi: xs = [1, 2, 3, 99, 100]

var ys = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
ys[0..10 by 2] = [1, 1, 1, 1, 1]         // strided: ys = [1,0,1,0,1,0,1,0,1,0]

var m = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
m[1, :]       = [40, 50, 60]             // replace row 1
m[:, 0]       = [-1, -4, -7]             // replace column 0
m[0..2, 0..2] = [[10, 20], [30, 40]]     // replace a 2×2 sub-matrix

The right-hand side must be shape-conforming with the slice; mismatches trap at runtime. See the Slice assignment section of the Expressions chapter for the full rules.

Tuples

val t = 1, 2.0, "three"                     // no parens needed

t.0                    // 1
t.1                    // 2.0
t.2                    // "three"

// Destructuring at binding — no parens needed
val a, b, c = t
val x, _ = 3.14, "ignored"

// Parens are only needed in contexts where commas mean something else,
// e.g. function arguments or array elements:
f(1, 2, 3)             // 3 separate arguments
f((1, 2, 3))           // 1 argument, the tuple
[(1, 2), (3, 4)]       // array of 2 tuples

Ranges

0..5                   // half-open: 0, 1, 2, 3, 4
0..=5                  // inclusive: 0, 1, 2, 3, 4, 5

for i in 0..3 do
  print(i)             // prints 0, 1, 2
end for

val nums = range(0, 10)         // materialize range to [integer]

Structs

struct Point
  x: real
  y: real
end

val p = Point(3.0, 4.0)
p.x                    // 3.0
p.y                    // 4.0

// Mutate via var binding:
var q = Point(0.0, 0.0)
q.x = 5.0              // OK because q is var
q = Point(1.0, 1.0)    // rebind whole value

Sum types and `match`

enum Shape =
  Circle(radius: real)
  Rect(width: real, height: real)
  Empty                                       // bare variant — no fields

def area(s: Shape) =
  s match
    Circle(r)  -> pi * r^2
    Rect(w, h) -> w * h
    Empty      -> 0.0

print(area(Circle(2.0)))     // 12.566370614359172
print(area(Rect(3.0, 4.0)))  // 12.0
print(area(Empty))           // 0.0

Bare variants like Empty are values; fielded variants like Circle(radius) are constructors. The scrutinee sits to the left of match and arms use Pattern -> body; an optional end match may close the block. match is exhaustive — every variant of the scrutinee’s enum must have an arm (or you opt out explicitly with _ ->); field patterns bind by declaration order, and _ discards.

Lambdas

val sq      = (x: real) -> x * x         // explicit param type
val sq2     = x -> x * x                  // type inferred from context
val sum_xy  = (x, y) -> x + y             // multi-arg
val biggy   = x ->                        // block-form
  val y = x * x
  y + 1

Functions

// Single-expression form
def double(x: real) = 2x

// Block-body form
def normalize(v: [real]) =
  val m = sqrt(dot(v, v))
  v / m

// Explicit return type (required for recursive functions)
def factorial(n: integer): integer =
  if n <= 1 then 1
  else n * factorial(n - 1)

// Mutual recursion
def is_even(n: integer): bool =
  if n == 0 then true else is_odd(n - 1)

def is_odd(n: integer): bool =
  if n == 0 then false else is_even(n - 1)

// Early return
def first_positive(v: [real]) =
  for x in v do
    if x > 0.0 then return x
  end for
  0.0           // fallback if nothing matched

// Unit-returning function
def greet(name: string) =
  print(s"hello, $name")
  ()

// Default parameter values + named arguments — defaults sit on the
// trailing positions; callers can pass `name = value` in any order
// for any parameter after the positional run.
def make_box(w: real, h: real = 1.0, depth: real = 1.0) =
  w, h, depth

make_box(3.0)                            // (3.0, 1.0, 1.0)
make_box(3.0, 5.0)                       // (3.0, 5.0, 1.0)
make_box(3.0, depth = 7.0)               // (3.0, 1.0, 7.0)
make_box(w = 2.0, depth = 4.0, h = 3.0)  // (2.0, 3.0, 4.0)

Parameter modes

// `read` mode is INFERRED when the body doesn't mutate the parameter.
// The function reads but never modifies v:
def sum_squares(v: [real]) =                  // inferred read
  var s = 0.0
  for x in v do s = s + x*x end for
  s

// `mut` mode is DECLARED when the body mutates the parameter:
def scale_in_place(v: mut [real], factor: real) =
  for i in 0..length(v) do
    v[i] = v[i] * factor
  end for

// A planned `@strict` attribute will disable auto-clone insertion in
// this function body — every clone must then be written explicitly
// with .clone(). For performance-critical paths where every allocation
// must be visible. (Parser-reserved today; deferred.)

Higher-order functions

def apply_twice(f: real -> real, x: real) = f(f(x))

apply_twice(x -> x + 1.0, 5.0)        // 7.0
apply_twice(sqrt, 16.0)               // 2.0

Closures

def make_adder(a: real) =
  x -> x + a

val add5  = make_adder(5.0)
val add10 = make_adder(10.0)

add5(3.0)            // 8.0
add10(3.0)           // 13.0

Generic functions

A def may carry type parameters in [...] right after the name. The caller never writes the type arguments — the compiler infers each T from the actuals at the call site and emits a specialized clone per distinct instantiation.

def id[T](x: T): T = x

def pickMax[T: Ord](a: T, b: T): T =
  if a < b then b else a

id(42)               // T := integer
id("hi")             // T := string
pickMax(3, 7)        // 7   — T := integer
pickMax(2.5, 1.5)    // 2.5 — T := real

A bare [T] admits any type; a bound [T: Kind] restricts T to a fixed admission list — Numeric (integer / real / complex), Real, Float, Complex, Ord (the types with <), Eq (the types with ==). The closed set is hard-wired in this milestone; user-defined constraints are deferred.

Concrete overloads win when they apply — a generic is consulted only when no concrete def of the same name fits the call:

def f(x: integer): integer = 100
def f[T](x: T): integer    = 200

f(1)        // 100 — concrete integer overload
f("hi")     // 200 — falls through to the generic

Generic structs and enums use the same constraint set and specialization model — see the Generic structs and Generic enums sections below.

Generic structs

A struct declaration may carry type parameters in [...] after the name. Field types reference the parameters; the compiler emits a specialized clone per distinct argument combination.

struct Box[T]
  value: T
end

struct Pair[A, B]
  fst: A
  snd: B
end

val b = Box(42)                // T := integer
val p = Pair(1, "hi")          // A := integer, B := string
val q = Pair(1.0, 2.0)         // A := real, B := real

The constraint vocabulary is the same closed set as generic functions (Numeric, Real, Float, Complex, Ord, Eq, or bare Any). When call-site inference can’t pin every parameter, write an explicit type on the binding:

val pp: Pair[integer, string] = Pair(1, "hi")

A type parameter on a function may thread through to a generic struct constructor — the function’s specialization carries the right struct specialization along:

def pack[T](x: T, y: T): Pair[T, T] = Pair(x, y)

val a = pack(1, 2)             // Pair$integer$integer
val b = pack(1.5, 2.5)         // Pair$real$real

Generic enums

An enum may also take type parameters. Variant payloads name them; bare variants carry no payload but still belong to the specialization.

enum Opt[T] =
  Some(value: T)
  None

enum Result[T, E] =
  Ok(value: T)
  Err(error: E)

val x  = Some(42)              // Opt$integer
val n: Opt[integer] = None     // bare variant — annotation pins T
val r: Result[integer, string] = Ok(7)   // pins E that the use can't infer

A bare variant (None) carries no information to infer its enum’s type parameters from — supply a declared type on the binding to push the parameter down. Multi-parameter enums where a single use pins only some parameters likewise need an explicit type (“cannot infer type for type parameter E“ if you forget). Matching on a specialized enum uses ordinary patterns:

val msg = x match
  Some(v) -> "got " + str(v)
  None    -> "nothing"

Control flow

// `if` is an expression:
val abs_x = if x < 0.0 then -x else x

// `if` with no else has type `unit`:
if verbose then
  print("doing the thing")
end if

// `for` over ranges or arrays, with optional tuple destructuring:
for i in 0..n do
  process(i)
end for

for k, x in enumerate([10.0, 20.0, 30.0]) do
  print(s"index $k = $x")
end for

// `while` loop:
var n = 100
while n > 1 do
  if n % 2 == 0 then n = n // 2
  else                   n = 3*n + 1
end while

Constants

pi          // 3.14159265358979...
e           // 2.71828...
inf         // +infinity
nan         // a quiet NaN
i           // (0.0 + 1.0i) — imaginary unit

Prelude — math

sqrt(2.0)              // 1.414...
exp(1.0)               // e
log(e)                 // 1.0
log2(8.0); log10(100.0)
sin(pi); cos(0.0); tan(pi/4)
asin(1.0); atan2(1.0, 1.0)
sinh(1.0); cosh(1.0); tanh(1.0)
abs(-5)                // 5
sign(-3.0)             // -1.0
floor(2.7); ceil(2.1); round(2.5); trunc(2.9)
min(3, 5); max(3, 5)

Prelude — rank-1 array operations

val v = [1.0, 2.0, 3.0, 4.0, 5.0]

sum(v)                                          // 15.0
product(v)                                      // 120.0
min(v); max(v)                                  // 1.0; 5.0
dot(v, v)                                       // 55.0
length(v)                                       // 5

v.map(x -> x * x)                               // [1.0, 4.0, 9.0, 16.0, 25.0]
v.reduce(0.0, (acc, x) -> acc + x)              // 15.0  (left fold)
v.filter(x -> x > 2.0)                          // [3.0, 4.0, 5.0]

enumerate(v)                                    // [(0,1.0), (1,2.0), ...]
zip(v, [10.0, 20.0, 30.0, 40.0, 50.0])          // [(1.0,10.0), ...]
range(0, 5)                                     // [0, 1, 2, 3, 4]

Prelude — rank-2 (matrix) operations

val M = [[1.0, 2.0],
         [3.0, 4.0],
         [5.0, 6.0]]                            // 3×2

rows(M); cols(M); shape(M)                      // 3; 2; (3, 2)
transpose(M)                                    // 2×3
diag([1.0, 2.0])                                // [[1.0, 0.0], [0.0, 2.0]]  — diagonal matrix
reshape([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], 2, 3)   // 2×3
flatten(M)                                      // [1.0, 3.0, 5.0, 2.0, 4.0, 6.0]  (column-major)

sum(M)                                          // 21.0  (all elements)
sum_axis(M, 0)                                  // [9.0, 12.0]  per-column
sum_axis(M, 1)                                  // [3.0, 7.0, 11.0]  per-row
M.map(x -> x + 1.0)                             // element-wise
matmul(transpose(M), M)                         // 2×2; same as transpose(M) @ M

Prelude — construction

zeros(5)                                        // [0, 0, 0, 0, 0]            — integer zeros
ones(3)                                         // [1, 1, 1]                  — integer ones
fill(4, 7.0)                                    // [7.0, 7.0, 7.0, 7.0]       — real, from x: real
fill(5, 0.0)                                    // [0.0, 0.0, 0.0, 0.0, 0.0]  — real zeros via fill
linspace(0.0, 1.0, 5)                           // [0.0, 0.25, 0.5, 0.75, 1.0]

zeros((2, 3))                                   // 2×3 integer zero matrix
ones((3, 3))                                    // 3×3 integer ones
fill((2, 2), 9)                                 // 2×2 of integer 9
fill((3, 2), 0.0)                               // 3×2 real zero matrix
identity(3)                                     // 3×3 integer identity matrix

Rank-2 construction takes a (rows, cols) tuple as the shape argument (single-integer arg = rank-1; tuple arg = rank-2). zeros/ones/identity currently return integer-element arrays — for real-typed initial buffers use fill(n, 0.0) / fill((r, c), 0.0) / linspace.

Prelude — I/O

print("hello")                                  // with newline
print()                                         // newline alone
print(s"x = $x")                                // plain interpolation
print(f"x = $x%5d, y = $y%.3f")                 // f-string with printf-style spec
val s = f"alpha = $a%8.4f"                      // value-position is fine too

f"..." accepts the same $ident / ${expr} interpolations as s"...", plus an optional Scala/printf-style spec right after each value: %[flags][width][.precision]conv with conv ∈ d f e g s x X o b. Flags - (left-align), 0 (zero-pad). See spec §10.6.

Prelude — conversions

to_real(42)                                     // 42.0
to_integer(3.7)                                 // 3 (truncates toward zero)
to_complex(5.0)                                 // (5.0 + 0.0i)

Testing

@test
def test_addition() =
  assert_eq(2 + 2, 4)

@test
def test_with_message() =
  assert(length([1.0, 2.0]) == 2, "expected length 2")

@test
def test_approx_real() =
  assert_approx(0.1 + 0.2, 0.3, 1e-10)

@test
def test_approx_complex() =
  // Checks `|a - b| <= tol` via hypot on the componentwise differences.
  assert_approx(1.0 + 2i, 1.000001 + 2.000001i, 1e-5)

@test
def test_approx_array() =
  // Element-wise rank-1 form: integer/real/complex elements are compared
  // per element with the same per-type distance as the scalar overloads.
  // A length mismatch traps.
  val xs = [1.0, 2.0, 3.0]
  val ys = [1.0 + 1e-12, 2.0 - 1e-12, 3.0 + 1e-12]
  assert_approx(xs, ys, 1e-9)

@test
def test_approx_array2() =
  // Same shape: rank-2 element-wise. Rows or cols mismatch traps.
  val A = [[1.0, 2.0], [3.0, 4.0]]
  val B = [[1.0 + 1e-12, 2.0 - 1e-12], [3.0, 4.0 + 1e-12]]
  assert_approx(A, B, 1e-9)

@test
def test_traps_on_bad_division() =
  assert_traps(() -> 1 div 0)

@test
def test_trap_message_contains_substring() =
  // The 2-arg form additionally checks that the trap's message
  // contains the expected substring — useful for asserting a specific
  // failure mode rather than "any trap fires".
  assert_traps(() -> 1 div 0, "division by zero")

A whole module can be marked test-only:

@test module mylib.deep_tests

import mylib.{public_fn}

// helper functions live alongside tests — both are stripped from production builds
def make_input(n: integer) = linspace(0.0, 1.0, n)

@test
def test_public_fn_monotonic() =
  val ys = make_input(100).map(public_fn)
  for i in 1..length(ys) do
    assert(ys[i] >= ys[i - 1])
  end for

Modules

Folder layout:

src/
  mylib/
    core.nex          ← module mylib
    util.nex          ← module mylib (same module, sibling file)
  main.nex

// in src/mylib/core.nex
module mylib

def public_fn(x: real) = x + 1.0

private def helper(x: real) = x * 2.0

// in src/mylib/util.nex
module mylib

// `helper` is visible because we're in the same module folder
def public_use_of_helper(x: real) = helper(x) + 1.0

// in src/main.nex
import mylib.{public_fn, public_use_of_helper}
import mylib.{public_fn as pf}      // rename on import

def main() =
  print(public_fn(3.0))             // 4.0
  print(pf(3.0))                    // 4.0
  // helper is NOT visible here — it's private to mylib

Literate Nex

A file with the .lnex extension is Markdown: column-0 prose, code indented one level (tab or four-plus spaces). The compiler strips the prose to blank lines (so error positions still match) and dedents the code before lexing. A module may freely mix .nex and .lnex files.

A short paragraph above the function explains why it exists.

    def square(x: real): real = x * x

A second paragraph between code blocks renders normally in
documentation and is invisible to the compiler.

    def main() =
      print(square(2.5))

See spec §2.9 for fenced-block handling and corner cases.

Dedicated @test Modules

2026-05-22T19:26:20.099529896Z

When tests need a lot of helpers, fixtures, or table-driven data, put them in a sibling @test module. The whole module is stripped from non-test builds.

@test module stats.distribution_tests

import stats.{mean, variance, stddev, skewness}

// --- support code (not tests, but available to tests in this module) ---

def constant_dataset(n: integer, c: real) = fill(n, c)

def linear_dataset(n: integer) = linspace(0.0, to_real(n - 1), n)

val constant_cases = [
  (constant_dataset(10,    0.0),   0.0),
  (constant_dataset(100,   3.14),  3.14),
  (constant_dataset(1000, -7.5),  -7.5)
]

// --- tests ---

@test
def test_mean_recovers_constants() =
  for sample, c in constant_cases do
    assert_approx(mean(sample), c, 1e-12)
  end for

@test
def test_stddev_of_any_constant_is_zero() =
  for sample, _ in constant_cases do
    assert_approx(stddev(sample), 0.0, 1e-12)
  end for

@test
def test_skewness_of_symmetric_linear_dataset_is_zero() =
  // 0..n-1 is symmetric around (n-1)/2
  assert_approx(skewness(linear_dataset(11)), 0.0, 1e-12)

This style is appropriate when:

The tests need lots of shared setup
You want fixture data computed once and shared across tests
The support code is itself testing-specific and would be noise in the regular module

The cost of a @test module: it can only see public members of the modules it imports. If you need to test private helpers, use inline @test functions in the same module instead (as in the Multi-File Modules example).

Supported Targets

2026-05-22T19:26:20.099529896Z

AOT path (native binaries via `nex compile`)

Mac arm64 — verified end-to-end on every commit. The clang -O1 invocation produces a Mach-O binary; CI runs it and diffs the stdout against the interpreter.

Other Unix targets (Linux x86_64, Linux arm64) should work given a working clang -O1, but they are not yet exercised by CI.

CLI builds

The Nex compiler is cross-compiled to three targets via Scala 3, and the full unit-test suite (over two thousand tests on JVM today) passes identically on all three on every commit. (Backend-shelling tests — those that drive clang or the MLIR toolchain — only run on JVM; the cross-platform tests cover the parser, elaborator, and interpreter.) Filesystem operations route through the path library so the module loader runs the same code on JVM filesystems, Node’s fs, and Native via java.nio.file.

JVM — primary development target. The full CLI (tokens, parse, elaborate, run, test, compile) lives here; the JVM is the only target that exercises the AOT path because it shells out to clang.
Scala.js (Node) — the interpreter and module loader work the same as JVM. nex run / nex test are functional; no compile subcommand because there’s no clang to shell out to.
Scala Native — same story as Scala.js. nex run / nex test work; no AOT path.

Planned

GPU / accelerator targets — deferred.
Linux x86_64 / arm64 — likely to be folded into CI once a runner is available; no language work required.
WebAssembly — possible via a future LLVM IR → wasm backend; no concrete plan yet.

Sum Types and Match

2026-05-22T19:26:20.099529896Z

A solver loop typically has three distinct outcomes: it converged on a value, the iterates diverged, or it ran out of iterations without converging. Modeling the result as a flat structure ((success: bool, x: real, iters: integer)) loses information: the meaning of x depends on success, and the meaning of iters depends on both. A sum type makes the three cases — and the data each one carries — explicit.

The driver below is Newton’s method for $f(x) = 0$,

\[x_{n+1} \;=\; x_n - \frac{f(x_n)}{f'(x_n)},\]

reporting Converged(x) once $\lvert f(x_n) \rvert < \text{tol}$, Diverged if $f'(x_n)$ approaches zero (the update step blows up), and MaxIters(iters, last) if the loop exhausts its budget without either condition firing. The example function is $f(x) = x^2 - 2$, $f'(x) = 2x$, so a converging run lands on $\sqrt{2}$.

The solver

enum Solver =
  Converged(x: real)
  Diverged
  MaxIters(iters: integer, last: real)

def newton(f: real -> real, fp: real -> real, x0: real, tol: real, max_iters: integer): Solver =
  var x = x0
  for i in 0..max_iters do
    val fx = f(x)
    if abs(fx) < tol then return Converged(x)
    val d = fp(x)
    if abs(d) < 1.0e-15 then return Diverged
    x = x - fx / d
  end for
  MaxIters(max_iters, x)

def f(x: real) : real = x^2 - 2.0
def fp(x: real): real = 2.0 * x

Each return site builds a value of the enum type. Converged(x) calls the fielded constructor (one real field); Diverged is a bare variant, so the name itself is the value; MaxIters(...) constructs the two-field variant. All three are typed Solver, so the function’s declared return type is satisfied uniformly.

Inspecting the outcome with `match`

def describe(s: Solver): string =
  s match
    Converged(x)         -> s"converged at x=${x}"
    Diverged             -> "diverged"
    MaxIters(iters, x)   -> s"ran ${iters} iters, last x=${x}"

def main() =
  print(describe(newton(f, fp, 1.0,    1.0e-12, 50)))
  print(describe(newton(f, fp, 0.0,    1.0e-12, 50)))     // fp(0)=0 → Diverged
  print(describe(newton(f, fp, 1.0e9,  1.0e-12, 3)))      // 3 iters too few

Output:

converged at x=1.4142135623730951
diverged
ran 3 iters, last x=125000000.0

Three properties to notice:

Exhaustiveness. Every variant of Solver has its own arm. Drop one and the compiler refuses to build the program — there is no quiet “default fell through” path. A wildcard case _ => arm is allowed when only some variants matter, but you opt in by writing it.
Field binding. Converged(x) extracts the real field into a name visible inside the arm body. MaxIters(iters, x) binds two fields in declaration order, available throughout the arm body. Use _ for any field you don’t need (case Continue(_) => ...).
One result type. Every arm body must evaluate to the same type — here, string. The whole match expression is itself a string, so it can flow into print, into a binding, or into another expression.

When to reach for a sum type

A sum type fits when a value has a bounded set of named cases, each with its own associated data:

Solver outcomes (Converged | Diverged | MaxIters)
Parsed tokens (Number(real) | Identifier(string) | LParen | RParen | ...)
Tree shapes (Leaf(real) | Branch(real, real) — once nested variant fields ship)
Operation results that distinguish “succeeded with x” from “failed because of y”

If the cases all carry the same shape and only differ in a small tag, a struct with an integer/string tag field is simpler. If the cases are unbounded or grow at runtime (user-defined plugins, dynamic types), a sum type isn’t the right tool — that’s where traits / interfaces would fit, both of which are deferred from the current language.

Three Ways to Express the Same Computation

2026-05-22T19:26:20.099529896Z

// 1) Functional: fresh array, fusion-friendly. The expression `v / mag`
//    lowers to a single fused loop with no intermediate.
def normalize(v: [real]) =
  val mag = sqrt(sum(v * v))
  if mag == 0.0 then v
  else v / mag

// 2) Explicit-loop with a local `var`: same machine code as (1), useful
//    when the loop body is more complex than a single element-wise
//    expression can capture. `out` is unique inside the function, so
//    indexed writes are in-place; the return value moves the buffer out.
def normalize_loop(v: [real]) =
  val n = length(v)
  val mag = sqrt(sum(v * v))
  if mag == 0.0 then v
  else
    var out = fill(n, 0.0)
    for i in 0..n do
      out[i] = v[i] / mag
    end for
    out

// 3) Slice assignment: overwrite a sub-extent of an existing var array
//    in place. The assignment mutates the underlying buffer in the
//    binding's own scope — no clone, no reallocation, no new identity.

def main() =
  // 1) Functional:
  val a = [3.0, 4.0]
  val b = normalize(a)
  print(b)                          // [0.6, 0.8]

  // 2) Explicit loop — same answer, same machine code (per design promise):
  val c = normalize_loop([3.0, 4.0])
  print(c)                          // [0.6, 0.8]

  // 3) Slice assignment: replace the first two elements in place.
  //    This is the idiom for partial in-place updates on a var array.
  var d = [9.0, 9.0, 9.0, 9.0]
  d[..2] = [0.6, 0.8]               // open lo: writes positions 0 and 1
  print(d)                          // [0.6, 0.8, 9.0, 9.0]

Sum of Sinusoids

2026-05-22T19:26:20.099529896Z

A pure sinusoid has the form $y(t) = A \sin(2\pi f t + \varphi)$ — amplitude $A$, frequency $f$ (cycles per unit of $t$), and phase $\varphi$. Adding several sinusoids with integer-multiple frequencies builds a periodic waveform; the wave below sums three such components on $[0, 1]$:

\[w(t) \;=\; 3\sin(2\pi t) \;+\; 2\cos(4\pi t) \;-\; \sin(6\pi t).\]

The second example evaluates a partial Fourier sine series at a single $t$,

\[s(t) \;=\; \sum_{k=1}^{n} c_k \sin(2\pi k t),\]

where coeffs[k-1] holds $c_k$. Both functions exploit juxtaposition multiplication so the source reads like the math: 3sin(2pi*t), 2cos(4pi*t).

// Three-term wave: w(t) = 3 sin(2π t) + 2 cos(4π t) - sin(6π t)
def wave(t: real) =
  3sin(2pi*t) + 2cos(4pi*t) - sin(6pi*t)

// Partial Fourier sum: s(t) = Σ_{k=1..n} coeffs[k-1] · sin(2π k t)
def fourier_sample(coeffs: [real], t: real) =
  val n = length(coeffs)
  var result = 0.0
  for k in 0..n do
    result += coeffs[k] * sin(2pi * to_real(k + 1) * t)
  end for
  result

def main() =
  val ts = linspace(0.0, 1.0, 100)
  val ys = ts.map(wave)

  print(s"wave(0.25) = ${wave(0.25)}")
  print(s"max sample = ${max(ys)}")
  print(s"min sample = ${min(ys)}")

  val coeffs = [1.0, 0.5, 0.25, 0.125]
  print(s"fourier(0.1) = ${fourier_sample(coeffs, 0.1)}")

Standard Library / Prelude

2026-05-22T19:26:20.099529896Z

The prelude is implicitly imported in every module. It contains the names available without any import statement.

The scalar math layer (the libm transcendentals plus their complex extensions) lives as ordinary Nex source in the sysroot’s prelude/ directory and is auto-imported at every program’s elaboration. The compiler still seeds a handful of names whose dispatch depends on return-type information (abs, sign, min, max, conj, arg) plus the array prelude and I/O — those will migrate to source as the relevant overload-resolution rules generalize. The split is invisible to users; either way the names are in scope.

10.1 Constants

Name	Type	Value
`pi`	`real`	π = 3.14159265358979…
`e`	`real`	Euler’s number = 2.71828…
`inf`	`real`	positive infinity
`nan`	`real`	a quiet NaN
`i`	`complex`	imaginary unit = `(0.0, 1.0)` (shadowable; see the Lexical chapter)

The boolean literals true and false (see the Lexical chapter) are globally available as keywords, not prelude names.

10.2 Mathematical functions on scalars

sqrt, cbrt, abs, sign
exp, log, log2, log10
sin, cos, tan, asin, acos, atan, atan2
sinh, cosh, tanh, asinh, acosh, atanh
hypot
floor, ceil, round, trunc
min, max

Each is overloaded over numeric types as appropriate. sqrt, exp, log, log2, log10, sin, cos, tan apply to both real and complex (the complex variants are source-level Nex defs in the prelude that compose the real-libm primitives — overload resolution picks the right one by argument type at the call site).

hypot(x, y) returns the Euclidean norm $\sqrt{x^2 + y^2}$ without the intermediate overflow that a naive sqrt(x*x + y*y) would suffer for large $\lvert x \rvert$ or $\lvert y \rvert$. sign(x) is the signum function: $-1$, $0$, or $+1$ for negative, zero, and positive real $x$ respectively.

10.3 Complex-specific operations

The real and imaginary parts of a complex value are accessed as fields with .:

z.re        // real part        (type: real)
z.im        // imaginary part   (type: real)

Other complex operations:

conj(z: complex): complex     // complex conjugate
arg(z: complex): real         // argument (angle, in radians)
abs(z: complex): real         // magnitude

Equivalent method-style: z.conj(), z.arg(), z.abs() (see the method-like notation rules in the Expressions chapter).

Construction of complex values uses the prelude constant i (§10.1) together with arithmetic, supported by juxtaposition multiplication (see the Expressions chapter):

3 + 4i             // (3.0 + 4.0i)
2.5i               // (0.0 + 2.5i)
exp(pi * i)        // ≈ (-1.0 + 0.0i) — Euler's identity
exp(2pi * i)       // ≈ (1.0 + 0.0i)  — full rotation

10.4 Array operations

Rank-1 operations:

length(a: [T]): integer
sum(a: [T]): T                          // T must be numeric
product(a: [T]): T                      // T must be numeric
min(a: [T]): T                          // T must be ordered numeric
max(a: [T]): T                          // T must be ordered numeric
dot(a: [T], b: [T]): T                  // inner product; T numeric
map(a: [T], f: T -> U): [U]
flatMap(a: [T], f: T -> [U]): [U]              // concat results
reduce(a: [T], init: U, f: (U, T) -> U): U
filter(a: [T], pred: T -> bool): [T]
range(lo: integer, hi: integer): [integer]    // materialize range
enumerate(a: [T]): [(integer, T)]
zip(a: [T], b: [U]): [(T, U)]

Definitions. Indices run $i = 0, \ldots, n-1$ where $n = $ length(a).

sum(a) $= \sum_i a_i$ and product(a) $= \prod_i a_i$.
min(a) $= \min_i a_i$ and max(a) $= \max_i a_i$.
dot(a, b) $= \sum_i a_i\, b_i$ — length(a) must equal length(b); mismatch traps.
map(a, f)[i] $= f(a_i)$.
filter(a, p) keeps each $a_i$ for which $p(a_i)$ is true, preserving the original order.
reduce(a, z, f) $= f(\ldots f(f(z, a_0), a_1) \ldots, a_{n-1})$ — left fold seeded with $z$.
range(lo, hi) $= [lo,\; lo+1, \ldots, hi-1]$ — exclusive upper; empty if $hi \le lo$.
enumerate(a)[i] $= (i, a_i)$ and zip(a, b)[i] $= (a_i, b_i)$ — zip truncates to $\min(\text{length}(a), \text{length}(b))$.

Calling convention. All the higher-order array functions (map / flatMap / reduce / filter) and the rank-1 accessors (length / sum / product / dot / enumerate / zip) are typically called via method-call sugar (§4.9). The two forms are equivalent — the dot form just sugars arr.name(...) into name(arr, ...):

// Preferred — reads as a pipeline:
xs.map(x -> x * x).filter(y -> y > 10).sum()

// Same call shape, free-function form:
sum(filter(map(xs, x -> x * x), y -> y > 10))

Either compiles to the same AST; the dot form is the documented convention for chains.

Rank-2 operations:

rows(m: [[T]]): integer                 // number of rows
cols(m: [[T]]): integer                 // number of columns
shape(m: [[T]]): (integer, integer)     // (rows, cols)

transpose(m: [[T]]): [[T]]              // m × n → n × m
matmul(a: [[T]], b: [[T]]): [[T]]       // also available via the @ operator
diag(d: [T]): [[T]]                     // n×n diagonal matrix with d on the diagonal

reshape(a: [T], m: integer, n: integer): [[T]]   // length(a) must equal m * n
flatten(m: [[T]]): [T]                  // column-major flatten

sum(m: [[T]]): T                        // sum over all elements
sum_axis(m: [[T]], axis: integer): [T]  // axis=0 → per-column; axis=1 → per-row
map(m: [[T]], f: T -> U): [[U]]         // element-wise

Definitions. For a matrix $M$ with row index $i = 0, \ldots, r-1$ and column index $j = 0, \ldots, c-1$ where $(r, c) = $ shape(M):

transpose(M)[i, j] $= M_{j i}$ — an $r \times c$ matrix becomes $c \times r$.
matmul(A, B)[i, j] $= \sum_k A_{i k}\, B_{k j}$ — also written A @ B; cols(A) must equal rows(B).
diag(d)[i, j] $= d_i$ if $i = j$, else $0$ — an $n \times n$ matrix from a length-$n$ vector.
sum(M) $= \sum_{i, j} M_{i j}$ — total over every element.
sum_axis(M, 0)[j] $= \sum_i M_{i j}$ — column sums; result length cols(M).
sum_axis(M, 1)[i] $= \sum_j M_{i j}$ — row sums; result length rows(M).
map(M, f)[i, j] $= f(M_{i j})$ — element-wise; shape preserved.
flatten(M)[k] $= M_{k \bmod r,\; k \div r}$ and reshape(a, r, c)[i, j] $= a[j \cdot r + i]$ — both follow the column-major storage convention from §3.3.

These are built-in: the compiler knows their types and lowers them with fusion-aware codegen. The user-facing surfaces for the same shape are generic functions (§6.10) and generic structs / enums (§3.6, §3.8).

10.5 Construction

Rank-1:

zeros(n: integer): [integer]
ones(n: integer): [integer]
fill(n: integer, x: T): [T]
linspace(lo: real, hi: real, n: integer): [real]

Rank-2:

zeros(shape: (integer, integer)): [[integer]]
ones(shape: (integer, integer)): [[integer]]
fill(shape: (integer, integer), x: T): [[T]]
identity(n: integer): [[integer]]       // n × n identity matrix

zeros, ones, and fill dispatch on shape: a single integer argument produces rank-1, a (integer, integer) tuple produces rank-2.

zeros(5)                 // rank-1: [0, 0, 0, 0, 0]
zeros((2, 3))            // rank-2: [[0, 0, 0], [0, 0, 0]]
fill(4, 7.0)             // rank-1: [7.0, 7.0, 7.0, 7.0]
fill((3, 2), 0.0)        // rank-2 reals
identity(3)              // rank-2 integer identity matrix

zeros, ones, and identity currently return integer element type. When you need a real-typed buffer, use fill(n, 0.0), fill(n, 1.0), or linspace; for a real identity, multiply by 1.0 (identity(n) * 1.0) or fill manually. A future refinement is expected once overload-by-return-type lands.

View-style slicing. Alongside the copying slice a[lo..hi] (spec §4.14), a rank-1 array exposes a non-copying view form:

val a = [10, 20, 30, 40, 50]
val v = a.view(1..4)        // borrows a[1..4] — [20, 30, 40]
v[0] = 99                   // writes through: a is now [10, 99, 30, 40, 50]
print(length(v))            // 3
print(sum(v))               // 99 + 30 + 40 = 169

a.view(r) returns a non-copying borrow into a covering the index range r (exclusive lo..hi or inclusive lo..=hi; negative bounds wrap from the end). Reads through the view see the source’s current contents; writes (v[i] = x) update the source. Every [T] prelude function (sum, length, map, dot, …) accepts a view transparently. An out-of-bounds range traps.

A 3-arg form a.view(lo..hi, k) borrows every k-th element of the window:

val big    = [10, 20, 30, 40, 50, 60, 70, 80]
val every2 = big.view(0..8, 2)      // [10, 30, 50, 70]
val every3 = big.view(1..8, 3)      // [20, 50, 80]

k must be a positive integer; non-positive strides trap. View-of-view composes strides — every2.view(0..4, 2) borrows every 4th element of big — and the contiguous 2-arg form is the special case k = 1.

A rank-2 matrix exposes the same view form for a contiguous row range:

val m = [[1, 2, 3], [4, 5, 6], [7, 8, 9], [10, 11, 12]]
val v = m.view(1..3)        // rows 1..3 — a 2×3 view
v[0, 1] = 99                // writes through: m[1, 1] is now 99
print(rows(v))              // 2
print(transpose(v))         // works on a view

Row-major layout makes any row range contiguous in memory, so a row-range view shares the same flat descriptor mechanism as rank-1 — rows, cols, shape, transpose, sum, sum_axis, element indexing, and row indexing all accept a row-range view without copying.

A 3-arg form m.view(rRange, cRange) borrows a non-contiguous sub-matrix:

val sub = m.view(1..3, 0..2)        // [[4, 5], [7, 8]]   — 2×2 window
sub[0, 1] = 99                      // writes through: m[1, 1] is now 99
transpose(sub)                      // rank-2 ops work over the gap

The visible rows have gaps in the underlying buffer; the descriptor carries an explicit row-stride field so flat iteration (sum, map, transpose, matmul, …) decomposes the linear index back into (r, c) and picks up the right elements across the gap. The rank-1 and rank-2 3-arg forms disambiguate on the 3rd argument’s shape — an integer is a stride (rank-1), a range is a column window (rank-2).

Spec §4.14 — a[lo..hi] allocates a fresh array and copies elements in. a.view(...) is the alternative for places where copying is wasteful: in-place algorithms (FFT, row pivoting), passing windows to reduction kernels, or working on a sub-range without changing the source.

10.6 I/O

print(x: T)                  // print value with newline
print()                      // print newline alone

For string composition, Nex provides two interpolated string forms (see also the Lexical chapter):

s"..." — plain interpolation. $ident and ${expr} are replaced by the default printed form of the value (whole reals as n.0, strings unquoted, structs as Name { ... }, etc.).
```
val x = 42
print(s"x = $x")            // x = 42
print(s"sum = ${x + 1}")    // sum = 43
```
f"..." — formatted interpolation. Same as s"...", but each $ident or ${expr} may be followed by a printf-style format spec %[flags][width][.precision]conversion. Conversion characters: d (integer), f e g (real, fixed / scientific / shortest), s (string), x X o b (integer in hex / upper-hex / octal / binary). Flags: - left-align, 0 zero-pad. The spec follows immediately after the value with no space.
```
val n  = 42
val pi = 3.14159
print(f"|$n%5d|")           // |   42|
print(f"|$n%-5d|")          // |42   |
print(f"|$n%05d|")          // |00042|
print(f"$pi%.3f")           // 3.142
print(f"$pi%10.3f")         //      3.142
print(f"hex = $n%x")        // hex = 2a
print(f"bin = $n%08b")      // bin = 00101010
```
Inside an f"..." literal, % in plain text is literal (no %% escape needed — 100% sure works). $$ still emits a literal $.

The conversion-vs-value-type compatibility is checked at runtime: f"$str%d" traps because %d expects an integer. %s accepts any value and uses the default printed form.

10.7 Type conversions

Explicit conversion functions (narrowing or non-promoting):

to_real(x: integer): real
to_integer(x: real): integer         // truncates toward zero
to_complex(x: real): complex
to_bytes(a: [integer]): [byte]       // traps if any element is outside 0..255
to_integers(b: [byte]): [integer]    // widens; always safe

The pair to_bytes / to_integers is the bridge between [byte] storage and the integer arithmetic surface — bytes are not first-class numbers and must be widened before any computation. See §3.3.1.

10.9 The `[byte]` buffer

Construction and length:

bytes(n: integer): [byte]            // zero-filled, length n
length(b: [byte]): integer           // element count

File I/O — both routes route through the cross-platform runtime, so the same program reads and writes on JVM, JS, and native targets:

read_bytes(path: string): [byte]
write_bytes(path: string, data: [byte]): unit

These two are the only file-I/O entry points the prelude offers in v0; the existing text-file helpers (readFile / writeFile) live in the host runtime and are not surfaced to Nex code yet.

10.8 Assertions

For use in test functions (see the Functions chapter) and test modules (see the Modules chapter):

assert(cond: bool)
assert(cond: bool, msg: string)
assert_eq(actual: T, expected: T)
assert_approx(actual: real,      expected: real,      tol: real)
assert_approx(actual: complex,   expected: complex,   tol: real)
assert_approx(actual: [T],       expected: [T],       tol: real)
assert_approx(actual: [[T]],     expected: [[T]],     tol: real)
assert_traps(thunk: () -> T)
assert_traps(thunk: () -> T, expected_substring: string)

All assertions trap on failure with a message naming the assertion type and (where applicable) the user-supplied msg. The test runner catches the trap and reports the failure without halting the rest of the test suite.

Prefer assert_approx over assert_eq for real and complex values — exact floating-point equality is almost always incorrect. The check is the absolute-distance predicate $\lvert a - b \rvert \le \text{tol}$, where the metric depends on the operand type: $\lvert a - b \rvert$ for real, and the Euclidean distance $\lvert a - b \rvert = \sqrt{(a_r - b_r)^2 + (a_i - b_i)^2}$ for complex. The array overloads run element-wise on rank-1 and rank-2 arrays of integer, real, or complex; integers lift to real, complex elements use the same Euclidean distance, and a shape mismatch (length for rank-1, rows or cols for rank-2) traps.

assert_traps takes a zero-argument closure and passes if invoking it traps; it fails if the thunk returns normally. The 2-arg form additionally checks that the trap message contains expected_substring — useful for asserting a specific failure mode rather than “any trap fires”.

Power Iteration

2026-05-22T19:26:20.099529896Z

Power iteration finds the eigenvector $v_*$ associated with the eigenvalue of largest magnitude (the dominant eigenvalue $\lambda_*$) of a square matrix $A$. Starting from an arbitrary nonzero $v_0$, repeated multiplication by $A$ amplifies the component along $v_*$ faster than every other component; renormalizing each step keeps the vector bounded:

\[v_{k+1} = \frac{A v_k}{\lVert A v_k \rVert_2}.\]

Once $v_k$ has converged in direction, the Rayleigh quotient recovers the eigenvalue:

\[\lambda \;=\; \frac{v^\top A v}{v^\top v}.\]

The denominator is $1$ here because we renormalize $v$ each step, so the code below evaluates the numerator $v^\top (A v)$ directly with dot.

// Power iteration: finds the dominant eigenvalue/eigenvector of a square matrix.
// Returns (eigenvalue, eigenvector).
def power_iteration(A: [[real]], iters: integer) =
  val n = rows(A)
  var v = fill(n, 1.0)               // initial guess — real-typed so subsequent
                                     // reassignments stay [real]; `ones(n)` would
                                     // give [integer] and the rebind would trip
                                     // the type check.
  var lambda = 0.0

  for k in 0..iters do
    val Av = A @ v                   // matrix-vector multiply (rank-1 result)
    val norm = sqrt(dot(Av, Av))
    v = Av / norm                    // element-wise scalar division
    lambda = dot(v, A @ v)           // Rayleigh quotient
  end for

  lambda, v

def main() =
  // Symmetric matrix with eigenvalues 5 and 1
  val A = [[3.0, 2.0],
           [2.0, 3.0]]

  val lambda, v = power_iteration(A, 50)

  print(s"dominant eigenvalue ~ $lambda")
  print(s"corresponding eigenvector ~ $v")

@test
def test_power_iteration_finds_correct_eigenvalue() =
  val A = [[3.0, 2.0], [2.0, 3.0]]
  val lambda, _ = power_iteration(A, 100)
  assert_approx(lambda, 5.0, 1e-6)

Numerical Methods

2026-05-22T19:26:20.099529896Z

Newton’s method for square roots

Newton’s method for $f(x) = 0$ refines a guess by

\[x_{n+1} \;=\; x_n - \frac{f(x_n)}{f'(x_n)}.\]

Applied to $f(x) = x_n^2 - x$ (whose root in $x_n$ is $\sqrt{x}$), the recurrence collapses to the classical Heron / Babylonian average

\[x_{n+1} \;=\; \tfrac{1}{2}\!\left(x_n + \tfrac{x}{x_n}\right),\]

which converges quadratically — each step roughly doubles the number of correct digits.

def newton_sqrt(x: real, tol: real) =
  var guess = x / 2.0
  var delta = guess
  while abs(delta) > tol do
    val next = (guess + x / guess) / 2.0
    delta = next - guess
    guess = next
  end while
  guess

def main() =
  print(newton_sqrt(2.0,    1.0e-12))    // 1.41421356...
  print(newton_sqrt(1000.0, 1.0e-9))     // 31.6227766...

RK4 — one step of a vector ODE solver

For the vector ODE $\dot y = f(t, y)$, the classical Runge-Kutta-4 step from $(t_n, y_n)$ to $(t_{n+1}, y_{n+1}) = (t_n + h, \, y_{n+1})$ samples the slope at four points,

\[\begin{aligned} k_1 &= f(t_n, \; y_n) \\ k_2 &= f(t_n + h/2, \; y_n + (h/2)\, k_1) \\ k_3 &= f(t_n + h/2, \; y_n + (h/2)\, k_2) \\ k_4 &= f(t_n + h, \; y_n + h\, k_3), \end{aligned}\]

and combines them with Simpson-like weights,

\[y_{n+1} \;=\; y_n + \tfrac{h}{6}\,(k_1 + 2k_2 + 2k_3 + k_4).\]

The method is fourth-order accurate: the local truncation error is $O(h^5)$ and the global error over a fixed interval is $O(h^4)$. The example below applies it to the simple harmonic oscillator $\ddot p = -p$, written as the first-order system $\dot p = v$, $\dot v = -p$.

// One Runge-Kutta 4 step for dy/dt = f(t, y), where y is a vector.
def rk4_step(f: (real, [real]) -> [real], t: real, y: [real], h: real) =
  val k1 = f(t,       y)
  val k2 = f(t + h/2, y + h/2 * k1)
  val k3 = f(t + h/2, y + h/2 * k2)
  val k4 = f(t + h,   y + h   * k3)

  // The whole expression fuses to a single loop:
  y + h/6 * (k1 + 2k2 + 2k3 + k4)

// Simple harmonic oscillator: dy/dt = (velocity, -position)
def harmonic(t: real, y: [real]) =
  [y[1], -y[0]]

def main() =
  var y = [1.0, 0.0]              // start: position 1, velocity 0
  var t = 0.0
  val h = 0.01
  val steps = 1000

  for k in 0..steps do
    y = rk4_step(harmonic, t, y, h)
    t = t + h
  end for

  print(s"after $steps steps: position=${y[0]}, velocity=${y[1]}")

Modules

2026-05-22T19:26:20.099529896Z

9.1 Folder-as-module

In Nex, a module is a directory. All .nex files within the directory belong to the same module. Subdirectories are submodules.

Given a project root, the module path is the directory path relative to the root, with / replaced by .:

src/
  linalg/
    dense/
      type.nex        ← all three files are part of module
      arith.nex       ← linalg.dense
      decompose.nex
    sparse/
      matrix.nex      ← module linalg.sparse
  main.nex            ← module (root)

Files in the same module share visibility: any binding in one file is visible to all other files in the same module, unless declared private (see §9.4).

9.2 Module declaration

A file may optionally declare its module at the top:

module linalg.dense

def add(a: Matrix, b: Matrix) = ...

If the declaration is present, it must match the directory path. If absent, the module is determined by the directory path alone. Declaration is recommended for clarity in large codebases but never required.

9.3 Imports

Imports use the import keyword. Selective imports list the names to import; as introduces a local alias:

import math.{sqrt, abs}
import linalg.dense.{Matrix, lu_decompose as lu}
import io.console as con

Whole-module imports (import math) are not allowed — selective import is required. This prevents namespace pollution and makes dependencies explicit.

Imports must appear at the top of a file, after the optional module declaration.

9.4 Visibility

The default visibility of all module-level declarations (functions, structs, constants) is public — visible to importing modules.

The private keyword restricts a declaration to the declaring module (the whole folder, including sibling files):

module geometry

def distance(p1: Point, p2: Point) = ...    // public
private def helper(x: real) = ...           // private to geometry

Private declarations are visible to all sibling files within the same module folder but invisible to importing modules.

9.5 No `.mod` binary headers

Nex does not use precompiled interface files (Fortran’s .mod files, C++ modules’ BMIs, etc.). The build system compiles from source in topological order based on the import graph.

9.6 Test modules

An entire module may be marked as test-only by placing @test before the module declaration. The module’s contents — both test functions and support code — are stripped from non-test builds.

@test module stats.deep_tests

import stats.{mean, variance, stddev}

// Support code — not a test, available to tests in this module.
def make_constant_sample(n: integer, c: real) = fill(n, c)

val constant_cases = [
  (make_constant_sample(10,    0.0),  0.0),
  (make_constant_sample(100,   3.14), 3.14),
  (make_constant_sample(1000, -7.5), -7.5)
]

@test
def test_mean_recovers_constants() =
  for sample, c in constant_cases do
    assert_approx(mean(sample), c, 1e-12)
  end for

Test modules can import freely from regular modules but see only the public surface — private members of the imported modules are not visible. If a test needs an internal helper, place the @test function in the same module as the code (see the Functions chapter) rather than in a separate test module.

A test module may itself be a folder containing multiple files; each file declares @test module foo.bar.tests at the top.

Multi-File Modules

2026-05-22T19:26:20.099529896Z

Folder layout:

src/
  stats/
    moments.nex          ← module stats
    distribution.nex
    summary.nex
  main.nex

src/stats/moments.nex:

module stats

def mean(xs: [real]) = sum(xs) / to_real(length(xs))

def variance(xs: [real]) = central_moment(xs, 2)

def stddev(xs: [real]) = sqrt(variance(xs))

// Private to the `stats` module; other files in stats/ can call it
// but importers cannot. The explicit `: real` return type lets sibling
// callers like `variance` see a concrete element type even when the
// body's last expression composes generic prelude HOFs.
private def central_moment(xs: [real], k: integer): real =
  val m = mean(xs)
  val n = to_real(length(xs))
  xs.map(x -> (x - m)^k).sum() / n

// Inline tests sit next to the code they exercise.
// They see private members because they're in the same module.

@test
def test_mean_of_constants() =
  assert_approx(mean([5.0, 5.0, 5.0]), 5.0, 1e-12)

@test
def test_stddev_of_constants_is_zero() =
  assert_approx(stddev(fill(100, 7.0)), 0.0, 1e-12)

@test
def test_central_moment_visible_to_test_in_module() =
  // central_moment is private — only visible because we're in `stats`
  assert_approx(central_moment([1.0, 2.0, 3.0], 1), 0.0, 1e-12)

src/stats/distribution.nex:

module stats

def skewness(xs: [real]) =
  central_moment(xs, 3) / stddev(xs)^3

def kurtosis(xs: [real]) =
  central_moment(xs, 4) / variance(xs)^2 - 3.0

src/stats/summary.nex:

module stats

struct Summary
  count: integer
  mean_val: real
  stddev_val: real
  min_val: real
  max_val: real
end

def summarize(xs: [real]) =
  Summary(length(xs), mean(xs), stddev(xs), min(xs), max(xs))

src/main.nex:

import stats.{Summary, summarize, skewness}

def main() =
  val data = linspace(0.0, 10.0, 100)
  val s = summarize(data)
  print(s"n=${s.count}  mean=${s.mean_val}  sd=${s.stddev_val}")
  print(s"range=[${s.min_val}, ${s.max_val}]")
  print(s"skewness=${skewness(data)}")

Mode System and Memory Management

2026-05-22T19:26:20.099529896Z

This chapter describes the design that makes Nex’s array semantics safe and analyzable. Most of it is invisible to users in everyday code — the compiler handles the bookkeeping. This chapter describes what the compiler is doing on the user’s behalf.

8.1 The two array regimes

Arrays in Nex fall into two regimes based on the binding kind that owns them:

val arrays: immutable contents, freely shareable. Multiple bindings may refer to the same underlying buffer because no mutation is possible.
var arrays: mutable contents, uniquely owned. Only one binding may refer to a given buffer at any program point. Aliasing is prohibited by the type system.

This split is the foundation of Nex’s fusion guarantees: the compiler can rewrite array expressions without proving non-aliasing analyses because the type system has already ensured no aliasing exists for mutable arrays.

8.2 Uniqueness for `var` arrays

A var binding to an array is a unique owner. The compiler enforces:

After a var binding’s value is moved (passed to a mut parameter, returned, or assigned to another var binding), the original binding is invalid and may not be used.
A var binding may not be assigned the same array as another live var binding.

These rules ensure that for any var array, there is exactly one live binding referring to it at every program point.

8.3 Auto-clone insertion

The compiler automatically inserts clones wherever needed to satisfy the uniqueness rule. Users do not write .clone() in normal code. The clone insertion follows these rules:

If a var array is used after its value has been moved, the compiler inserts a clone of the original buffer at the point of the move so the later use sees an independent buffer.
If a val array is passed to a mut parameter, the compiler inserts a clone so the function receives a fresh mutable buffer.
The clone-placement optimization pass picks the optimal point for each clone (e.g., clones the earlier use so the later use can be a move), and elides clones that are provably unnecessary.

A planned @strict function attribute will disable auto-clone insertion within a function body — every clone must then be written explicitly as .clone(), and missing clones become compile errors. This mode is intended for library authors and performance-critical code where every allocation must be visible. The attribute is reserved at the parser level today; the enforcement pass is deferred.

8.4 Read-mode parameters need no clones

Because read-mode parameters (the default) do not mutate or take ownership of their argument, calls to read-mode functions never require clones — even when the caller passes a var array:

def sum(v: [real]) = ...               // read mode

var a = [1.0, 2.0, 3.0]
val s1 = sum(a)            // ok: read mode, a still valid
val s2 = sum(a)            // ok: a still valid
a[0] = 10.0                // ok: a is mutable, never moved

8.5 Memory management: ARC

The current implementation uses automatic reference counting (ARC) for all heap-allocated values (arrays, strings, structs containing those). Each heap-allocated value carries a reference count; increments occur when ownership is shared, decrements occur when a reference goes out of scope, and the value is freed when the count reaches zero.

ARC requires no garbage collector runtime, has no pause-style overhead, and is straightforward to implement. The per-operation cost (atomic increments and decrements) is acceptable for current workloads; performance-critical paths can be revisited later.

8.6 Future: RAII for `var` arrays

The memory management for var arrays will be upgraded from ARC to RAII (deterministic deallocation at scope exit). Because uniqueness guarantees a single owner, RAII can free a var array immediately when its binding goes out of scope, with no refcount overhead. This change is invisible to user code — only the runtime characteristic changes. val arrays continue to use ARC.

Mandelbrot Set

2026-05-22T19:26:20.099529896Z

For each complex parameter $c$, the Mandelbrot set studies the iteration

\[z_0 = 0, \qquad z_{n+1} = z_n^2 + c.\]

The point $c$ belongs to the set if the sequence $\{z_n\}$ stays bounded; otherwise it escapes to infinity. A simple sufficient escape test is $\lvert z_n \rvert > 2$ — once the orbit leaves the disk of radius 2, it never returns. The renderer records the first $n$ at which that happens (the escape time) and maps it to an ASCII gradient; pixels that never escape after max_iter are drawn solid.

def escape_iters(c: complex, max_iter: integer) =
  var z = 0i
  var k = 0
  while k < max_iter and z.abs() <= 2.0 do
    z = z*z + c
    k += 1
  end while
  k

// Compute one row of escape-times as a rank-1 vector. The whole row
// is built independently of the result matrix and then written into
// it via slice assignment — `result[py, :] = row` — in one statement.
def row_at(py: integer, width: integer, height: integer, max_iter: integer) =
  var row = fill(width, 0)
  for px in 0..width do
    val x = -2.0 + 3.0 * to_real(px) / to_real(width)
    val y = -1.5 + 3.0 * to_real(py) / to_real(height)
    row[px] = escape_iters(x + y*i, max_iter)
  end for
  row

def mandelbrot(width: integer, height: integer, max_iter: integer) =
  var result = fill((height, width), 0)
  for py in 0..height do
    // Slice assignment replaces the entire py-th row of the image in
    // place. No per-pixel writes to `result`, no temporary copy.
    result[py, :] = row_at(py, width, height, max_iter)
  end for
  result

def main() =
  val img = mandelbrot(80, 24, 50)
  for py in 0..24 do
    // `print` always appends a newline, so we assemble one row of
    // pixels as a string and print it once per row.
    var line = ""
    for px in 0..80 do
      val n = img[py, px]
      val ch =
        if n == 50 then "#"
        elif n > 25 then ":"
        elif n > 10 then "."
        else " "
      line += ch
    end for
    print(line)
  end for

Two slice idioms in one program:

Whole-row write — result[py, :] = row replaces the entire py-th row of result in place, with no per-pixel result[py, px] = ... writes and no temporary copy of the row buffer.
Single-row read — img[py] (single integer on a rank-2) reads the py-th row as a freshly-owned rank-1, used implicitly above via the explicit img[py, px] element access. You could also lift that with val row = img[py]; for px in ... do ... row[px].

Lexical Syntax

2026-05-22T19:26:20.099529896Z

2.1 Source encoding

Source files are UTF-8 encoded. Files use the .nex extension. Literate sources (Markdown wrappers; see §2.9) use .lnex and are transparently preprocessed before lexing — every rule below applies to the dedented code inside a .lnex file just as it does to a .nex file.

2.2 Identifiers

Identifiers begin with an ASCII letter or underscore and may contain ASCII letters, digits, and underscores:

identifier  ::=  (letter | '_') (letter | digit | '_')*
letter      ::=  'a'..'z' | 'A'..'Z'
digit       ::=  '0'..'9'

Unicode identifiers are deferred.

2.3 Keywords

Reserved words (cannot be used as identifiers):

and       as        const     def       div       do
else      end       false     for       if        import
in        match     module    mut       not       or
private   return    struct    then      true      val
var       while

Words reserved for future use:

class     extends   given     implicit  package
pub       trait     type      where     yield

2.4 Literals

Boolean literals: true, false.

Integer literals: decimal, hexadecimal (0x prefix), binary (0b prefix), or octal (0o prefix). Underscores allowed as digit separators.

42
1_000_000
0xFF
0b1010_1010
0o755

Integer literals have type integer.

Real literals: decimal with required fractional part or exponent.

3.14
1.0
2.5e-3
6.022e23
1_234.567_89

Real literals have type real.

Complex values are constructed from real values using the prelude constant i (the imaginary unit, equal to (0.0, 1.0)) together with arithmetic operators. Combined with juxtaposition multiplication (chapter 4), this produces math-flavored notation without a dedicated complex-literal form:

i                           // imaginary unit: (0.0 + 1.0i)
2.0i                        // (0.0 + 2.0i)  — juxtaposition: 2.0 * i
3.0 + 4.5i                  // (3.0 + 4.5i)
exp(pi * i)                 // (-1.0 + 0.0i) — Euler's identity

Complex values have type complex (chapter 3). Nex does not provide a dedicated complex-literal token — 2i, 3 + 4i, etc. are ordinary expressions parsed under the rules in chapter 4.

(The prelude name i shadows freely: a for i in 0..n loop variable hides the imaginary unit within the loop body. If you need both in the same scope, pick a different index name — by mathematical convention, j, k, m, or n.)

String literals: double-quoted, with backslash escapes (\n, \t, \r, \\, \", \x41, \u{1F600}).

"hello, world"
"line one\nline two"

String literals have type string.

Interpolated string literals: prefixed with s. Values are spliced into the string at marker positions:

s"hello, $name"                    // identifier substitution
s"x + y = ${x + y}"                // arbitrary expression in ${}
s"|z| = ${z.abs()}"                // method/field access in ${}
s"first = ${arr[0]}"               // indexing in ${}
s"price: $$$amount"                // literal $ via doubling

Rules:

$identifier substitutes the value of the named binding.
${expression} substitutes the result of an arbitrary expression.
$$ produces a literal $.
The form $ident.field parses as ${ident}.field — only the bare identifier is interpolated, and .field is literal text. To interpolate a field access, write ${ident.field}. The same rule applies to […] and (…) following an interpolated identifier.

Each interpolated value is converted to its string form (the same conversion print uses). Interpolated strings have type string.

Format-string interpolation with precision specifiers (f"x = $x%.3f") is deferred.

Unit literal: (). The single value of type unit.

2.5 Comments

Line comments begin with // and extend to the end of the line. Block comments are /* ... */ and may nest.

// this is a line comment

/* this is
   a block comment */

/* block /* nested */ comments work */

2.6 Indentation and structure

Nex uses indentation-based syntax in the Scala 3 family. Indentation introduces a block; dedentation closes it. Blocks are introduced after = (in def and val/var bindings), after then / else (in if), after do (in for / while), and after -> in block-form lambdas.

Indentation may use spaces or tabs but must be consistent within a file. The recommended convention is two spaces.

def normalize(v: [real]) =
  val mag = sqrt(sum(v * v))
  if mag == 0.0 then
    v
  else
    v / mag

2.7 End markers

Any indented block may be terminated by an optional end marker for clarity. The marker may be bare (end) or named with the construct it closes:

def normalize(v: [real]) =
  val mag = sqrt(sum(v * v))
  if mag == 0.0 then
    v
  else
    v / mag
  end if
end def

End markers are particularly useful for long blocks where the closing dedent would otherwise be far from the opening keyword. They are never required and never alter semantics.

2.8 Statement separators

A statement ends at the end of a line, unless the line ends with an operator or open delimiter, in which case the statement continues on the next (more-indented) line. Multiple statements on one line may be separated by ;.

val x = 1; val y = 2

val long_expression =
  some_function(a, b)
    + another_function(c, d)
    * yet_another(e)

2.9 Literate Nex

A file with the .lnex extension is a literate source: Markdown prose interleaved with indented code blocks. The compiler preprocesses the file before lexing, so the rest of the language sees ordinary Nex source.

The preprocessing rules are:

Prose lines start at column 0 and are stripped — replaced by blank lines so that error positions still refer to the original .lnex line numbers. Markdown headings, paragraphs, lists, links, inline math ( $..$ ), and display math ($$..$$) all fall under this rule.
Code lines start with a tab or at least four spaces. Exactly one indentation level is stripped (the leading tab, or four leading spaces) and the dedented body is fed to the lexer. Any further indentation survives — Nex’s own indent-sensitive blocks work normally inside a literate file.
Fenced blocks (```) are non-Nex content (ASCII diagrams, sample output, hex dumps) and are stripped entirely. The fence delimiters and everything between them become blank lines.
Lines with 1-3 leading spaces are treated as prose (Markdown list-item continuations).

Example:

# Greeting

This file demonstrates literate Nex. The compiler ignores the prose
and reads only the indented blocks below.

    def main() =
        val name = "world"
        print(name)

A module may freely mix .nex and .lnex files; the directory’s contents are taken as the union, and the rules of §9 apply unchanged.

Introduction

2026-05-22T19:26:20.099529896Z

Implementation language: Scala 3. Target: AOT compilation via LLVM IR text → clang -O1 (Mac arm64 verified end-to-end on every commit). A reference tree-walking interpreter runs alongside; the two paths are required to produce byte-for-byte identical output (modulo a documented %g 6-significant-figure divergence on irrational reals).

1.1 What Nex is

Nex is a statically-typed, expression-oriented, array-first numerical programming language. It is designed for the kind of code that Fortran is still used for today: numerical simulation, scientific computing, computational mathematics, signal processing — workloads where array operations dominate, IEEE 754 behavior matters, and AOT-compiled performance is non-negotiable.

The language combines:

Array-first semantics with element-wise operations as the default
Value semantics throughout — no shared mutable state, no object identity
Uniqueness types for mutable arrays, inferred and managed by the compiler
Fusion-aware compilation — array expressions compile to fused loops with no temporaries
Modern syntax in the Scala 3 family: indentation-based, expression-oriented, optional end markers
Built-in complex numbers, in the Fortran tradition

1.2 Audience

The primary audience is the Fortran-using community: HPC, computational science, numerical libraries. Secondary audiences are anyone who currently reaches for Julia or NumPy for numerical work and would prefer an AOT-compiled, statically-typed alternative with cleaner syntax.

1.3 Goals and non-goals

Goals:

Mathematical clarity in source code
Predictable, AOT-compiled performance
Fusion of array operations as a semantic guarantee, not an optimization
Strong static typing without ceremony
Clean module system that supports growing codebases

Non-goals:

Web programming, systems programming, application programming
Object-oriented design (no classes, no inheritance, no methods in the OO sense)
General-purpose dynamic dispatch
Pervasive metaprogramming

1.4 Scope

The language as currently specified is the minimum coherent slice that can run real numerical programs. It includes: scalar types, rank-1 and rank-2 arrays (vectors and matrices) with slice assignment, expression-oriented control flow, multi-file folder modules, the mode system, ARC-based memory management, a source-form standard prelude (the scalar transcendentals and their complex extensions live in prelude/*.nex and are auto-imported), built-in unit testing, and both a reference interpreter and an AOT compiler.

Excluded for now: user-defined generics, sized numeric variants (real32, integer32, etc.), rank-3+ arrays / a shape language, structs with methods, sum types / pattern matching, operator definitions, modules with submodule interface/implementation split, FFI, parallel-for, and a package manager. See chapter 11 for the full deferred list.

Install

2026-05-22T19:26:20.099529896Z

Prerequisites

JVM 17 or newer. Needed to run the CLI itself. Any distribution works (Temurin, GraalVM, Zulu, Oracle).
sbt 1.9 or newer. Used as the build and runner front-end. Install via SDKMAN (sdk install sbt) or Homebrew (brew install sbt).
clang on $PATH. Required only by nex compile (the AOT path). The interpreter (nex run, nex test) doesn’t need it. macOS ships clang via the Xcode Command Line Tools (xcode-select --install); Linux distros bundle clang in their package manager (apt install clang, dnf install clang, etc.).

Verify each is installed:

java   -version   # 17+
sbt    --version  # 1.9+
clang  --version  # any recent

Get the source

There is no published binary yet. Clone the repository and build from source:

git clone https://github.com/edadma/nex.git
cd nex
sbt nexJVM/compile     # first build pulls dependencies; subsequent runs are fast

The first sbt invocation downloads dependencies (several minutes). After that the build is incremental and quick.

Supported targets

The AOT compile path is verified end-to-end on Mac arm64. Linux x86_64 and Linux aarch64 should work — the codegen emits portable LLVM IR and shells out to whatever clang finds — but neither is exercised on every commit. Report any platform-specific issues.

The interpreter (nex run, nex test) runs anywhere the JVM does, including Windows. The same code path also builds for Scala.js (Node) and Scala Native — every commit runs the cross-platform unit-test suite on all three targets — so embedding the interpreter in a browser playground or a static binary is straightforward when the need arises.

Next step

Once the build succeeds: run your first program.

Writing a PPM image with `[byte]`

2026-05-22T19:26:20.099529896Z

The [byte] type is Nex’s storage form for binary file I/O. To show it end to end, we build a tiny 64 × 32 image of a smooth red→blue gradient, pack it into the P6 binary PPM container, and write the result to disk. PPM is convenient here because the on-disk layout is essentially one ASCII header followed by raw RGB triples — exactly the shape [byte] is for.

A P6 file is

P6
<width> <height>
255
<width * height * 3 bytes of RGB pixel data>

with a single newline after each line of the header and no terminator between header and pixel block.

For a fixed 64 × 32 image the header is exactly 13 bytes: P6\n64 32\n255\n. We build it as a literal [byte] and concatenate the pixel block onto it.

def main() =
  val w = 64
  val h = 32

  // P6\n 6 4   3 2 \n 2 5 5 \n  — 13 ASCII bytes.
  val header_ints = [80, 54, 10, 54, 52, 32, 51, 50, 10, 50, 53, 53, 10]
  val header_len = length(header_ints)
  val pixel_count = w * h
  val buf = bytes(header_len + pixel_count * 3)

  for i in 0..header_len do
    buf[i] = header_ints[i]
  end for

  // Horizontal red→blue gradient with a fixed green channel. The
  // per-pixel index in the buffer is header_len + (y * w + x) * 3.
  for y in 0..h do
    for x in 0..w do
      val base = header_len + (y * w + x) * 3
      val t = to_real(x) / to_real(w - 1)
      buf[base + 0] = to_integer(255.0 * (1.0 - t))   // red
      buf[base + 1] = 32                              // green
      buf[base + 2] = to_integer(255.0 * t)           // blue
    end for
  end for

  write_bytes("gradient.ppm", buf)
  print(s"wrote ${length(buf)} bytes")

The program prints wrote 6157 bytes (header + 64 × 32 × 3 pixels) and leaves a real gradient.ppm on disk that any PPM viewer can open. The same source runs through nex run on the interpreter on JVM, Node, and native, and through nex compile on the LLVM AOT backend — write_bytes routes through the cross-platform runtime so the file appears in the same place on every backend, and the [byte] descriptor + ARC helpers in the AOT runtime produce a byte-identical PPM file to the interpreter’s.

A real image-processing pipeline would normally widen the byte buffer to [integer] (or to [real] for HDR / sRGB / linear-light math) with to_integers, do the computation, and narrow back to [byte] with to_bytes before writing. [byte] exists for the storage layer; it deliberately does not participate in element-wise arithmetic or fusion. See the Specification, §3.3.1.

Higher-Order Functions and Closures

2026-05-22T19:26:20.099529896Z

For a sample $x_0, \ldots, x_{n-1}$, the mean and the population standard deviation are

\[\bar{x} \;=\; \frac{1}{n}\sum_{i=0}^{n-1} x_i, \qquad \sigma \;=\; \sqrt{\,\frac{1}{n}\sum_{i=0}^{n-1} (x_i - \bar{x})^2\,}.\]

The Nex realization reads as one expression per formula. The lambda inside .map captures mean from the enclosing scope — that’s the closure — and the intermediate array .map would otherwise produce fuses into the .sum reduction, so the whole variance computation runs in a single pass over xs.

def main() =
  val xs = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0]

  val n = to_real(length(xs))
  val mean = sum(xs) / n

  // The explicit `: real` annotation pins the binding's type — the
  // elaborator does not yet infer return types through `.map(lambda).sum()`
  // chains, so the downstream `sqrt(variance)` overload-resolution needs
  // the hint.
  val variance: real = xs.map(x -> (x - mean)^2).sum() / n
  val stddev = sqrt(variance)

  print(s"mean = $mean, stddev = $stddev")

Hello, world

2026-05-22T19:26:20.099529896Z

Hello, world

def main() =
  print("Hello, Nex!")

A function and a calculation

def hypotenuse(a: real, b: real) = sqrt(a^2 + b^2)

def main() =
  print(s"hypotenuse(3, 4) = ${hypotenuse(3.0, 4.0)}")

Functions

2026-05-22T19:26:20.099529896Z

6.1 Function declarations

A function is declared with def. The simplest form is single-expression:

def square(x: real) = x * x

def hypotenuse(a: real, b: real) = sqrt(a * a + b * b)

The block form uses an indented body after =:

def normalize(v: [real]) =
  val mag = sqrt(sum(v * v))
  if mag == 0.0 then v
  else v / mag

6.2 Return types

Return types are inferred by default. An explicit return type may be given after the parameter list:

def square(x: real): real = x * x

Explicit return types are required for recursive functions:

def factorial(n: integer): integer =
  if n <= 1 then 1
  else n * factorial(n - 1)

6.3 Parameters

Each parameter is declared with name: type. An optional = default clause supplies a value to use when the caller omits the argument (see §6.5).

6.4 Parameter modes

Function parameters that hold arrays (or struct types containing arrays) have a mode that determines how the parameter is passed and what the function may do with it.

Two modes exist:

read mode (default, inferred): the function reads the parameter; it does not mutate, take ownership of, or store it. Read mode is inferred from the function body — if the body never mutates the parameter, never passes it to a mut parameter elsewhere, and never returns or stores it in a var binding, the parameter is read mode.
mut mode (declared explicitly with mut): the function takes ownership of the parameter and may mutate it. Required if the body does any of the actions ruled out by read mode.

def sum(v: [real]) = ...                   // read mode (inferred)
def fill(v: mut [real], x: real) = ...     // mut mode (declared)

Mode mismatches at call sites:

Passing a val array to a mut parameter requires a clone (compiler inserts it automatically; see chapter 8).
Passing a var array to a mut parameter moves ownership — the caller cannot use the array after the call unless the function returns it.
Passing any array to a read parameter never moves or mutates it.

Modes apply only to array and struct types. Scalar parameters (integer, real, bool, complex, unit) are always pass-by-value.

6.5 Default values and named arguments

A parameter may carry a default expression in its declaration:

def greet(name: string, greeting: string = "Hello") =
  print(s"${greeting}, ${name}!")

def scale(x: real, factor: real = 2.0, offset: real = 0.0) =
  factor * x + offset

Default-valued parameters must form a contiguous trailing run — once one parameter has a default, every later parameter must also have one. This guarantees that a positional caller can simply drop trailing arguments.

greet("World")                 // "Hello, World!" — greeting defaulted
scale(10.0)                    //  20.0 — factor + offset defaulted
scale(10.0, 3.0)               //  30.0 — offset defaulted

Named arguments at the call site identify a parameter by name with name = expr. Named arguments may appear in any order, may skip over middle parameters that have defaults, and must come after any positional arguments:

greet(name = "Nex")                            // "Hello, Nex!"
greet(greeting = "Hi", name = "Foo")           // "Hi, Foo!"
scale(10.0, offset = 5.0)                      //  25.0 — factor defaulted
scale(10.0, factor = 7.0, offset = 2.0)        //  72.0

Resolution rule (compile-time):

All positional arguments fill leading parameter positions in order.
Each named argument fills the parameter slot matching its name.
Any unfilled slot uses that parameter’s declared default; an unfilled slot whose parameter has no default is a compile error.
Supplying the same parameter twice (positional + named, or named twice) is a compile error.

The default expression is captured untouched at declaration time and re-evaluated at every call site that uses it (Scala / JavaScript semantics, not Python’s evaluate-once). A default like id: integer = next_id() calls next_id() fresh on each call.

Restrictions. Defaults and named arguments are only supported when the callee is a single, non-overloaded def referenced by name. Overload sets (multiple defs sharing a name) require fully-positional calls. Computed callees (lambda values, function-typed parameters, returned closures) likewise require positional arguments. Method-call syntax (receiver.f(args)) does not yet support named arguments — use the function-call form f(receiver, ...) if you need them.

6.6 Closures

Function values may be created with lambda syntax (chapter 4) and passed as arguments or returned from functions:

def make_adder(a: real) =
  x -> x + a

val add5 = make_adder(5.0)
add5(3.0)                    // 8.0

Closures capture lexical bindings. Capture of val bindings is unrestricted. Capture of var array bindings moves the binding into the closure (uniqueness preserved).

6.7 Higher-order functions

Functions are first-class values. They may be passed as arguments and returned from other functions:

def apply(f: real -> real, x: real) = f(x)
apply(square, 3.0)           // 9.0
apply(x -> x + 1.0, 3.0)     // 4.0

6.8 Recursion

Direct and mutual recursion are supported. Mutually-recursive functions must appear in the same module; forward declarations are not required.

6.9 `return`

The return expression terminates the enclosing function with the given value (or () if omitted). It is useful for early exit:

def first_negative(v: [real]) =
  for x in v do
    if x < 0.0 then return x
  end for
  0.0

A function’s final expression provides its return value implicitly without return.

6.10 Generic functions

A def may introduce one or more type parameters in square brackets after its name. Each type parameter stands for a type fixed at the call site; the body of the function is type-checked against the parameter, and the compiler generates a specialized clone for every distinct type the function is called with.

def id[T](x: T): T = x

def pickMax[T: Ord](a: T, b: T): T =
  if a < b then b else a

def first[T, U](a: T, b: U): T = a

The bracketed list may be a mix of bounded and unbounded entries: [T] is shorthand for [T: Any], and [T: Float, U: Numeric, V] is a three-parameter list with two bounds.

Kind constraints. A bare [T] allows any type. A bound [T: Kind] restricts T to a fixed list of admissible types, picked from the closed set below. Stage 1 of the generics feature does not allow user-defined constraints — the set is hard-wired.

Constraint	Admitted types
`Any`	every type (the default for `[T]`)
`Numeric`	`integer`, `real`, `complex`
`Real`	`integer`, `real`
`Float`	`real` (kept distinct from `Real` so split-precision additions extend it cleanly)
`Complex`	`complex`
`Ord`	`integer`, `real` (the types that support `<` / `<=` / `>` / `>=`)
`Eq`	`integer`, `real`, `bool`, `string`, `complex` (the types with structural `==` / `!=`)

A call site whose argument type isn’t admitted by the constraint is rejected at elaboration time.

Call-site inference. The caller never writes the type arguments — the compiler infers them by unifying each formal parameter against its actual:

val a = pickMax(3, 7)         // T := integer; result type integer
val b = pickMax(2.5, 1.5)     // T := real; result type real
val c = first(1, "hi")        // T := integer, U := string; result integer

When the same type parameter appears in multiple formal positions, all the corresponding actuals must unify to a single type. For Numeric-constrained variables the unifier widens through the numeric tower (so f[T: Numeric](x: T, y: T) called as f(1, 2.0) widens to real); for non-numeric constraints, mismatched actuals are a hard error.

Overload resolution. A name may simultaneously bind a generic def and one or more concrete overloads. Concrete overloads win when they apply — a generic candidate is consulted only when no concrete overload accepts the call site’s argument types:

def f(x: integer): integer = 100
def f[T](x: T): integer     = 200

f(1)        // 100 — concrete integer overload
f("hi")     // 200 — falls through to the generic

Within the concrete bucket the existing numeric-promotion ranking still picks the closest match (Functions §6.5 already covers this). Two generic candidates both applicable to the same call is an unambiguity error — the user must add a concrete overload or further constrain one of the generics.

Specialization. Generic templates have no executable form on their own. The compiler walks every reachable call site, deduces the type arguments, and emits a specialized clone with the parameter substituted. The clones (named pickMax$real, id$string, etc.) are what backends actually compile and what the linker sees. A generic that is never called produces no code — there is no abstract “generic dispatcher” floating around at runtime.

Specialization recurses: a generic body that itself calls a generic produces a chain of specializations, with the outer call’s type arguments threaded through to the inner call.

Generic structs and enums. The same constraint set, call-site inference, and specialization model extend to user-declared struct and enum types. See §3.6 and §3.8 for declaration syntax and the rules around bare-variant inference.

Limitations. User-defined trait/type-class constraints are deferred — the constraint set is the closed list above. Lambda bodies that thread a kind variable through to a nested generic call are supported; arrays and aggregates parameterized by a kind variable inherit the limitations of the current array-element-type rules.

6.11 `@intrinsic` declarations

A bodyless def annotated with @intrinsic("opId") declares a function whose implementation is supplied by the compiler — typically a libm bridge or a runtime helper — rather than by Nex source. The opId string names the lowering: @intrinsic("libm.sqrt") lowers to a direct call to the host’s libm sqrt primitive.

@intrinsic("libm.sqrt")
def sqrt(x: real): real

This is how the standard prelude bridges the real-libm transcendentals (see the Prelude chapter); user code generally has no reason to write @intrinsic directly. The attribute is the only sanctioned escape hatch — any other bodyless def is a parse error.

6.12 Test functions

A function declared with the @test attribute is a unit test: it takes no arguments, returns unit, and is discovered automatically by the test runner.

@test
def test_addition_is_commutative() =
  assert_eq(2 + 3, 3 + 2)

@test
def test_normalize_produces_unit_vector() =
  val v = [3.0, 4.0]
  val u = normalize(v)
  assert_approx(sum(u * u), 1.0, 1e-12)

Test functions are stripped from non-test builds — they do not appear in production binaries.

Tests in a regular module can see every binding in that module, including private ones. This makes it natural to test internal helpers without widening their public surface.

A test passes by returning normally and fails by trapping. The prelude provides assertion functions (see the Prelude chapter) that trap with structured failure information the test runner catches and reports.

Your First Program

2026-05-22T19:26:20.099529896Z

Write a program

Create a file hello.nex anywhere on your filesystem:

def main() =
  print("Hello, Nex!")
  val k = 10
  for i in 1..=5 do
    print(i * k)

Two top-level pieces: a def main() that’s the program’s entry point, and a for loop that prints 10, 20, … 50. Everything in the body uses two-space indentation; there are no braces or semicolons. 1..=5 is an inclusive range; 1..5 would stop at 4.

Run it

From the nex repository root, invoke the interpreter via sbt:

sbt "nexJVM/runMain io.github.edadma.nex.run run /path/to/hello.nex"

Output:

Hello, Nex!
10
20
30
40
50

run parses, elaborates (type-checks), and executes the program with the tree-walking interpreter. It’s the fastest edit/run cycle for development — no native binary involved.

What else `run` accepts

The same invocation works on any of the examples in the repository:

sbt "nexJVM/runMain io.github.edadma.nex.run run examples/fft/main.nex"

If your program imports other modules (multi-file projects), point run at the entry file and the import graph is discovered from its directory upward — see the Modules chapter in the spec for layout rules.

Next step

Now compile that same program to a native binary.

FFT

2026-05-22T19:26:20.099529896Z

A recursive discrete Fourier transform that showcases Nex’s complex number support, per-element array-literal coercion, strided slices for the even/odd split, and open-bound slice assignment for stitching the two output halves. Works for any power-of-2 length; the recursion bottoms out at the trivial one-point transform.

The DFT of length $N$ is

\[X_k = \sum_{n=0}^{N-1} x_n \, e^{-2\pi i\, k n / N}, \qquad k = 0, 1, \ldots, N-1.\]

A direct evaluation is $\Theta(N^2)$. Cooley-Tukey splits the sum by even / odd index — $E_k$ is the DFT of the even-indexed samples, $O_k$ the DFT of the odd-indexed ones — and reuses each half twice:

\[X_k = E_k + W_N^{\,k}\, O_k, \qquad X_{k+N/2} = E_k - W_N^{\,k}\, O_k,\]

for $k \in [0, N/2)$, where $W_N = e^{-2\pi i / N}$ is the principal $N$-th root of unity. Each recursive level halves the problem, giving $\Theta(N \log N)$ overall.

def fft(x: [complex]): [complex] =
  val n = length(x)
  if n == 1 then return x

  // Split into even/odd-indexed sub-arrays via strided slices.
  val ef = fft(x[..n by 2])     // even-indexed: 0, 2, 4, ...
  val of = fft(x[1..n by 2])    // odd-indexed:  1, 3, 5, ...

  val half = n div 2

  // Build the twiddled odd half as a vector first: t[k] = W_N^k · O[k].
  var t = fill(half, 0.0 + 0i)
  for k in 0..half do
    val angle = -2.0 * pi * to_real(k) / to_real(n)
    t[k] = (cos(angle) + sin(angle) * i) * of[k]

  // Stitch the two output halves into `y` with element-wise array ops
  // (`ef + t`, `ef - t` on `[complex]`) plus a slice assignment per
  // half — no per-index `y[k] = ...; y[k + half] = ...` shuffle.
  var y = fill(n, 0.0 + 0i)
  y[..half] = ef + t                    // open lo: same as 0..half
  y[half..] = ef - t                    // open hi: same as half..n
  y

def main() =
  // The `: [complex]` annotation pushes the element type into each
  // literal, so the real values 0.0 / 1.0 coerce per-element via
  // `to_complex(...)`.
  val x: [complex] = [
    1.0, 1.0, 1.0, 1.0,
    0.0, 0.0, 0.0, 0.0
  ]
  val y = fft(x)
  val n = length(y)
  print("FFT of [1, 1, 1, 1, 0, 0, 0, 0]:")
  for k in 0..n do
    print(y[k])

Output (the DC term $X_0$ is the sum of inputs; real input gives the Hermitian symmetry $X_k = \overline{X_{N-k}}$ for $k > 0$):

FFT of [1, 1, 1, 1, 0, 0, 0, 0]:
4.0+0.0i
1.0-2.414213562373095i
0.0+0.0i
1.0-0.4142135623730949i
0.0+0.0i
0.9999999999999999+0.4142135623730949i
0.0+0.0i
0.9999999999999997+2.414213562373095i

The full source lives at examples/fft/main.nex. Change x to any power-of-2 length and the same code transforms it.

Expressions

2026-05-22T19:26:20.099529896Z

Nex is expression-oriented: nearly every syntactic construct is an expression with a type and a value.

4.1 Literal expressions

Each literal form (chapter 2) is an expression of the corresponding type.

4.2 Variable references

A bare identifier refers to a binding in scope. The expression has the type of the binding.

4.3 Operators and precedence

Operators, in order from highest to lowest precedence:

Level	Operators	Associativity	Description
1	`.`	left	field / method access
2	`f(...)`, `a[...]`	left	application, indexing
3	unary `-`, `not`	right	unary minus, logical not
4	`^`	right	exponentiation
5	juxtaposition (`2x`, `2(e)`, `2pi`)	left	implicit multiplication (§4.4)
6	`*`, `/`, `div`, `%`, `@`	left	multiplication, division, integer division, modulo, matrix multiply
7	`+`, `-`	left	addition, subtraction
8	`..`, `..=`	left	range constructors
9	`==`, `!=`, `<`, `<=`, `>`, `>=`	non-associative	comparison
10	`and`	left	logical and
11	`or`	left	logical or
12	`->`	right	function / lambda
13	`,`	right	tuple constructor (§4.16)

User-defined operators are deferred.

Comma binds looser than every other operator on a single line. That means if cond then a else b, c parses as (if cond then a else b), c — a 2-tuple. To put the comma inside an else branch, either parenthesize (if cond then (a, c) else (b, c)) or use the indented block form, whose last expression accepts a paren-less tuple naturally:

if cond then
  a, c
else
  b, c

The same single-line vs. block-form distinction applies to lambda bodies (f = (x) -> (x, -x) vs. a block body whose last item is x, -x) and to match arm bodies. See §4.17.

4.4 Arithmetic operators

The arithmetic operators +, -, *, /, ^, %, div apply to numeric operands with the following semantics:

+, -, * — work on integer, real, complex. Promote per §3.2.
/ — real division. Both operands promoted to at least real. integer / integer produces real.
div — integer division (keyword, not a symbol — // is reserved for line comments). Both operands must be integer. Truncates toward zero. Example: 7 div 3 == 2.
% — modulo. Both operands must be integer. Result has sign of dividend.
^ — exponentiation. real ^ real → real, complex ^ complex → complex, integer ^ integer → integer (only for non-negative exponent; negative exponent traps).
unary - — negation. Works on any numeric type.

Integer arithmetic traps on overflow. Real arithmetic follows IEEE 754 (NaN, infinities propagate; no traps from arithmetic itself).

Juxtaposition multiplication. A numeric literal (integer or real) immediately followed by an identifier or an opening parenthesis — with or without intervening whitespace — denotes implicit multiplication. This makes mathematical notation read naturally:

2x                  // 2 * x
2(x + 1)            // 2 * (x + 1)
2pi                 // 2 * pi
3sin(t)             // 3 * sin(t)
2i                  // 2 * i    = (0.0 + 2.0i)

The rule applies only when the left operand is a numeric literal — not when it is an identifier and not when it is a parenthesized expression. Therefore:

xy is the identifier xy, not x * y.
(x)(y) is a function call (x applied to y), not multiplication.
To multiply two identifier or parenthesized expressions, write * explicitly.

Per the precedence table (§4.3), juxtaposition binds tighter than *, /, div, and %, but looser than ^. This matches how the math reads:

2x^3 is 2 * (x^3) — ^ binds tighter than juxtaposition
1/2x is 1 / (2 * x) — juxtaposition binds tighter than /
2x * 3 is (2 * x) * 3 — juxtaposition binds tighter than *

The juxtaposition rule subsumes Nex’s complex-number construction: 2i, 3 + 4i, and (a + b)i are all ordinary expressions under this rule, with i being a prelude constant of type complex (see the Prelude chapter).

4.5 Element-wise array operators

When an arithmetic operator is applied with one or both operands being an array, the operation is element-wise. The rules are:

[T] op [T] — element-wise on rank-1, requires same length, returns [T]
[[T]] op [[T]] — element-wise on rank-2, requires same shape, returns [[T]]
arr op T and T op arr — broadcasts the scalar over the array (any rank), returns an array of the same shape and rank

Shape mismatch (length for rank-1; shape for rank-2) is a runtime trap.

val a = [1.0, 2.0, 3.0]
val b = [4.0, 5.0, 6.0]
val c = a + b                            // [5.0, 7.0, 9.0]
val d = a * 2.0                          // [2.0, 4.0, 6.0]
val e = 2a + b                           // [6.0, 9.0, 12.0]   (juxtaposition)

val M = [[1.0, 2.0], [3.0, 4.0]]         // 2×2
val N = [[10.0, 20.0], [30.0, 40.0]]
val P = M + N                            // [[11.0, 22.0], [33.0, 44.0]]
val Q = 2M                               // [[2.0, 4.0], [6.0, 8.0]]

Element-wise expressions are guaranteed to fuse: 2a + b and its rank-2 equivalents lower to a single loop nest with no intermediate arrays allocated.

Matrix multiplication uses the @ operator (not element-wise). It is defined between rank-1 and rank-2 arrays as follows:

[[T]] @ [[T]]    shapes (m, k) @ (k, n)  →  (m, n)     matrix-matrix
[[T]] @ [T]      shape  (m, k) @ k       →  m          matrix-vector
[T]  @ [[T]]     shape  k     @ (k, n)   →  n          vector-matrix
[T]  @ [T]       shape  k     @ k        →  T          dot product

Inner-dimension mismatch traps.

val A = [[1.0, 2.0], [3.0, 4.0]]         // 2×2
val v = [5.0, 6.0]
val Av = A @ v                           // [17.0, 39.0]   (rank-1)
val AA = A @ A                           // [[7.0, 10.0], [15.0, 22.0]]
val d  = v @ v                           // 61.0           (scalar = dot)

4.6 Comparison operators

The operators ==, !=, <, <=, >, >= produce bool. Comparison is defined for:

bool == bool, bool != bool only
All ordered numeric comparisons between numeric types after promotion
complex == complex and complex != complex (no ordered comparison on complex)
Element-wise array comparison: [T] op [T] → [bool] (same broadcast rules as §4.5)
string == string, string != string (no ordered comparison on string)

Chained comparisons

Two or more comparison operators in a row form a chained comparison:

0 <= i < n
lo < x <= hi
a < b < c <= d

a OP1 b OP2 c ... OPn z is equivalent to

(a OP1 b) and (b OP2 c) and ... and (y OPn z)

with the additional guarantee that every inner operand is evaluated at most once and only if every earlier comparison succeeded. Concretely, 0 < f() < 10 calls f() exactly once when 0 < f() is true, and not at all when it is false. The operators may be mixed freely — 0 <= i < n and a < b == c are both well-formed — and any number of comparisons may be chained.

Each pairwise comparison must independently satisfy the type rules above; in particular a chain that mixes ordered and equality operators on values for which the relevant pairwise comparison isn’t defined is rejected by the type checker.

4.7 Logical operators

and, or, not work on bool (or [bool] element-wise). and and or are short-circuiting on scalar bool.

4.8 Function calls

f(a, b, c)
sqrt(2.0)
map(arr, x -> x * 2.0)

If f has type (T1, T2, ..., Tn) -> R, the call has type R. Arguments are evaluated left-to-right.

4.9 Method-like notation

The expression e.name(args...) is sugar for name(e, args...) when e.name does not refer to a struct field. The compiler resolves e.name as follows:

If e‘s type is a struct with a field named name, treat as field access.
Otherwise, if a function name is in scope whose first parameter matches the type of e, treat as name(e, args...).
Otherwise, error.

This allows the natural chaining style:

arr.map(x -> x * 2.0).sum()       // equivalent to sum(map(arr, x -> x * 2.0))

4.10 Conditionals

An if expression has the form:

if cond then expr1 else expr2

It is an expression whose type is the common type of expr1 and expr2.

then is required for an inline body and optional when the body starts on a new indented line. Multi-line form (with or without then):

// `then` optional when body is indented:
if cond
  expr1
else
  expr2

// `then` still works for the multi-line form too:
if cond then
  expr1
else
  expr2

For chained conditionals — both else if and elif (single-token shorthand) are accepted, with identical semantics:

if cond1
  expr1
else if cond2
  expr2
else
  expr3

// Same shape with `elif`:
if cond1
  expr1
elif cond2
  expr2
else
  expr3

An if without an else is an expression of type unit. Both branches in that case must also have type unit:

if cond
  print(x)         // type unit

4.11 Lambdas

Lambda expressions use ->:

x -> x * x
(x, y) -> x + y
(x: real) -> x * 2.0          // optional parameter type annotation

Single-parameter lambdas may omit parentheses. Multi-parameter lambdas require them. Parameter types are inferred from context where possible; otherwise must be annotated.

Block-form lambdas:

x ->
  val y = x * x
  y + 1

Lambdas capture surrounding lexical bindings. Captured val bindings are captured by value (or by shared reference, per ARC). Captured var bindings are captured uniquely — only one closure may capture a given var binding, and the binding is moved into the closure (see chapter 8).

4.12 Ranges

The range expressions:

lo..hi — half-open: [lo, hi)
lo..=hi — closed: [lo, hi]

Operands are integer. The result is a range, a built-in iterable type used in for loops and convertible to [integer].

0..n              // 0, 1, ..., n-1
0..=n             // 0, 1, ..., n

Materialization to [integer] is lazy — a range used in a for loop iterates without allocating an array.

4.13 Array literals and construction

Rank-1 literals use square brackets:

[1.0, 2.0, 3.0]              // [real]
[1, 2, 3]                    // [integer]
[true, false, true]          // [bool]
[1.0 + 2.0i, 3.0 + 4.0i]     // [complex]

All elements must have the same type. Empty rank-1 literals require a type annotation:

val empty: [real] = []

Rank-2 literals are nested. Each inner array is a row of the resulting matrix:

val m = [[1.0, 2.0, 3.0],
         [4.0, 5.0, 6.0]]              // [[real]], 2×3 matrix

val grid = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]    // [[integer]], 3×3

Inner arrays must all have the same length (rectangularity); a jagged literal traps at runtime.

Arrays may also be constructed from ranges via the range function (rank-1) and from the standard-library constructors zeros, ones, fill, identity, linspace (see the Prelude chapter).

4.14 Indexing and slicing

Array indexing is 0-based. Out-of-bounds indexing traps.

Negative indices count from the end of the axis: a[-1] is the last element, a[-2] is the second-to-last, and so on. The wrap is i + length for i < 0; the bounds check then runs against the wrapped value, so a[-10] on a 3-element array still traps. Negative indices apply to both axes of a rank-2 index (m[-1, -1] is the bottom-right element), to the single-index row form (m[-1] is the last row), AND to slice and axis-range bounds (a[-3..length(a)] is the last 3 elements; m[:, -1] is the last column).

Rank-1 indexing with a single integer:

val a = [10.0, 20.0, 30.0]
a[0]    // 10.0
a[2]    // 30.0
a[-1]   // 30.0
a[-3]   // 10.0

Rank-1 slicing with a range expression returns a freshly owned array (copying elements):

a[0..2]       // [10.0, 20.0]
a[1..=2]      // [20.0, 30.0]

Open-ended slice bounds omit either side; the missing bound fills from the array’s runtime extent (0 for the lower side, length(a) for the upper). Each side is independent and combines with negative indices and the inclusive form:

a[2..]        // [30.0]        — lo given, hi defaults to length(a)
a[..2]        // [10.0, 20.0]  — hi given, lo defaults to 0
a[..]         // full copy     — both ends default
a[-3..]       // last 3 elements
a[..-1]       // all but the last
a[..=-1]      // inclusive — full array

The open forms are only legal inside an index list; using .. or ..= outside a slice context (e.g. as a value on the right of =) is a parse error.

Strided slices sample every k-th element from the selected window via a trailing by k:

a[0..10 by 2]    // every other element from indices 0..9 (exclusive)
a[1..10 by 3]    // 1, 4, 7
a[0..=9 by 2]    // inclusive — same as the first form on a length-10 array
a[..10 by 2]     // combines with open bounds
a[-5.. by 2]     // combines with negative bounds

The stride must be a positive integer; a stride of 0 or any negative value traps. Negative strides (reverse iteration) are deferred. Strided rank-2 axis ranges (m[lo..hi by k, :]) are deferred.

Strided forms are also valid assignment targets (spec §4.15): the RHS supplies one element per selected position. Length mismatch and non-positive stride trap the same way they do on read:

var a = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
a[0..10 by 2] = [1, 1, 1, 1, 1]            // every-other slot
//  a == [1, 0, 1, 0, 1, 0, 1, 0, 1, 0]

var b = [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]
b[1..10 by 3] = [200, 500, 800]
//  b == [10, 200, 30, 40, 500, 60, 70, 800, 90, 100]

Rank-2 indexing uses two integer indices separated by a comma:

val m = [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]
m[0, 0]       // 1.0
m[1, 2]       // 6.0

The single-index form m[i] returns the i-th row as a freshly-owned rank-1 array:

m[0]          // [1.0, 2.0, 3.0]
m[1]          // [4.0, 5.0, 6.0]

Rank-2 slicing uses : to mean “all of this axis” and range expressions for sub-extents. Result rank depends on what’s collapsed: an integer along an axis collapses it; : or a range preserves it.

m[:, 1]              // column 1 (rank-1)        → [2.0, 5.0]
m[0, 0..2]           // row 0, cols 0-1 (rank-1) → [1.0, 2.0]
m[0..2, 1..3]        // sub-matrix (rank-2)
m[:, :]              // full copy (rank-2)

All slice forms return freshly-owned arrays. View-style slicing (returning a borrow into the source array without copying) is deferred.

4.15 Slice assignment

Slice forms (the same shapes documented in §4.14) are also valid on the left of =. This is the Fortran-90 array-section assignment idiom: a single statement overwrites an entire sub-extent of a var array in place.

var xs = [10, 20, 30, 40, 50]
xs[1..4]  = [200, 300, 400]                // xs = [10, 200, 300, 400, 50]
xs[0..=2] = [1, 2, 3]                      // xs = [1, 2, 3, 400, 50]

var m = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
m[1, :]       = [40, 50, 60]               // replace row 1
m[:, 0]       = [-1, -4, -7]               // replace column 0
m[0..2, 0..2] = [[10, 20], [30, 40]]       // replace a 2×2 sub-matrix

Shape conformance. The right-hand side must match the slice’s shape:

A rank-1 slice (a[lo..hi], a[lo..=hi]) expects a rank-1 array of the same length.
A rank-2 slice with both axes preserved (m[r1..r2, c1..c2], m[:, :]) expects a rank-2 array of matching shape.
A rank-2 slice with one axis collapsed (m[i, c1..c2], m[:, j], m[i, :]) expects a rank-1 array of matching length.

Length / shape mismatches trap at runtime, as does any out-of-bounds slice bound.

In-place mutation. The underlying buffer is rewritten — the var binding does not acquire a new identity. The assignment is observable through every binding that aliases the same underlying array, and no clone fires from this construct alone.

When to reach for slice assignment. Three common cases:

Replacing a contiguous prefix / suffix / middle of a rank-1 buffer, where you’d otherwise write an indexed loop.
Writing one row, column, or sub-block of a rank-2 matrix that you’ve computed independently — result[py, :] = row_vector is the working idiom (see the Mandelbrot example).
Avoiding a mut parameter for “replace this region with that data” APIs, since slice assignment mutates a binding directly in its own scope without the auto-clone interaction that follows passing a var array to a mut parameter (§8.3).

Strided slice forms (xs[lo..hi by k] = rhs) are deferred.

4.16 Struct construction and access

val p = Point(3.0, 4.0)
val x = p.x                  // 3.0

Struct field reassignment is allowed only on var bindings (see chapter 5):

var p = Point(3.0, 4.0)
p.x = 10.0                   // ok

4.17 Tuple construction and access

Tuples are constructed by comma-separated expressions (length ≥ 2). Parentheses are not required:

val t = 1, 2.0, "three"      // type: integer, real, string
val pair = 3.0, 4.0           // type: real, real

Parentheses are optional grouping; both forms are equivalent:

val t = (1, 2.0, "three")

Parentheses become required when the surrounding context already uses commas for another purpose:

f(1, 2, 3)                   // 3 arguments
f((1, 2, 3))                 // 1 argument, the tuple (1, 2, 3)

[1, 2, 3]                    // [integer] of 3 elements
[(1, 2), (3, 4)]             // [(integer, integer)] of 2 tuples

Tuple elements are accessed by 0-based numeric field:

t.0      // 1
t.1      // 2.0
t.2      // "three"

Tuple destructuring in val / var bindings — no parens needed unless type-annotated:

val a, b, c = t                          // bind components
val x, _ = 3.14, "ignored"               // _ discards
val (a, b): (integer, real) = 1, 2.0     // parens required when annotating types

Single-element tuples do not exist; 1 is just 1. The empty tuple () is already the unit literal (chapter 2) — there is no zero-arity tuple distinct from unit.

Tuples as block results. Inside an indented block — a def body, a val/var/const binding RHS that uses block form, a then / else / do body, a match arm body, or a lambda body that uses block form — the block’s last item may be a paren-less tuple:

def make_box(w: real, h: real, d: real) =
  w, h, d                            // returns a 3-tuple

def first_positive(xs: [real]) =
  for x in xs do
    if x > 0.0 then return x, true    // returns a 2-tuple
  end for
  0.0, false                          // fallback 2-tuple

return is a statement, so its value also accepts a paren-less tuple (return a, b, c returns the 3-tuple (a, b, c)).

4.18 Block expressions

A sequence of statements followed by a final expression is itself an expression with the type and value of the final expression. The block form arises from indentation:

val x =
  val y = compute()
  val z = transform(y)
  z + 1                      // type of the block is the type of z + 1

If the final form is a statement (e.g., assignment), the block has type unit.

Deferred

2026-05-22T19:26:20.099529896Z

The features deferred from the current language are split into two tiers by scope:

Near-term additions — small, additive, non-breaking. Planned as natural follow-ups without redesigning anything in the core.
Long-term work — major features, possibly breaking, requiring substantive design and implementation effort.

11.1 Near-term additions

(All previously-listed near-term items are now shipped.)

11.2 Long-term work

Type system:

Sized numeric variants (integer8, integer32, real32, complex32)
Higher-rank arrays (rank-3 and beyond) and a static-shape language ([real; M, N])
Pattern matching beyond enums (literal patterns, guards, range patterns) — current match shape is defined in §7.5
Traits / type classes (Stage 3 of the generics roadmap)
Type aliases

Syntax / expressions:

User-defined operators (with precedence inheritance)
Operator definitions on existing types

Memory / runtime:

RAII for var arrays (currently ARC)
Cycle detection for ARC
Parallel-for / parallel reductions
SIMD intrinsics

Modules / build:

Module interface/implementation split (Fortran-2008-style submodules)
Package manager
Conditional compilation
FFI / C ABI compatibility
Calling external Fortran / BLAS / LAPACK

Standard library:

geometry3 stdlib module — quaternions plus the other 3D-rotation representations (rotation matrices, axis–angle, Euler angles) and the conversions between them. Quaternions are not planned as a built-in primitive: they don’t extend the integer → real → complex promotion lattice cleanly (complex has no canonical embedding into quaternions — which of i / j / k?), their multiplication is non-commutative (which breaks the element-wise / broadcast story for *), and the workloads that need them (3D graphics, robotics, attitude estimation) sit outside the Fortran / numerical-array audience the language is shaped around. The library home is the right one once generics (def foo[T](...)) and structs with methods both ship — until then, users who need a Q4 can roll a 4-field struct and write the ops by hand.

Backend:

GPU / accelerator targets

Tooling:

Language server / IDE integration
Debugger
Profiler
Documentation generator

Control Flow

2026-05-22T19:26:20.099529896Z

7.1 `if` / `else`

See the Expressions chapter. if is an expression.

then is required for an inline body and optional when the body starts on a new indented line:

// Inline — `then` required:
val sign = if x > 0 then 1 else if x < 0 then -1 else 0

// Block body — `then` optional:
if cond
  do_something()
  do_more()
else
  fallback()

7.2 `for` loops

The for loop iterates over an iterable. Iterables are ranges and arrays:

// `do` required when the body is inline:
for k in 0..n do process(k)

// `do` optional when the body starts on a new indented line:
for k in 0..n
  process(k)
end for

for x in arr
  print(x)
end for

The end for marker is optional in both forms.

A for loop is an expression of type unit.

Tuple destructuring in the loop variable — no parens needed:

for k, x in enumerate(arr)
  print(k, x)

7.3 `while` loops

while follows the same rule as for: do required for inline bodies, optional when the body starts on a new indented line.

while cond
  body
end while

// Inline form:
while keep_going do step()

A while loop is an expression of type unit.

7.4 Block scoping

Each control-flow body introduces a new scope. Bindings declared in a body are not visible outside it.

7.5 `match` expressions

match inspects a sum-type value (§3.7) and dispatches on its variant. The scrutinee sits to the left of match; arms follow on indented lines, each pattern -> body:

enum Solver =
  Converged(x: real)
  Diverged
  MaxIters(iters: integer, last: real)

def describe(s: Solver): real =
  s match
    Converged(x)      -> x
    Diverged          -> -1.0
    MaxIters(n, last) -> last

A match is an expression — all arm bodies must yield the same type, and the match itself evaluates to that type.

Optional end match. The block can be closed with an end match marker. The marker is purely visual; the parser doesn’t enforce it, and the same indented Dedent boundary closes the block whether or not it appears:

c match
  Red   -> "stop"
  Green -> "go"
  Blue  -> "wait"
end match

Patterns.

Variant — matches a bare variant by name.
Variant(p1, p2, ...) — matches a fielded variant and recursively binds each sub-pattern to the corresponding field.
name — matches anything and binds the scrutinee to name. Acts as a catch-all when used as a top-level pattern.
_ — matches anything without binding. Same role as name but without introducing a name in scope.

When used inside a variant pattern, sub-patterns are restricted to plain bindings or _ — nested variant patterns are deferred until variant fields can carry aggregate types.

Exhaustiveness. Every variant of the scrutinee’s enum must be covered, either by an explicit Variant(...) -> arm or by a catch-all (_ -> or name ->). The compiler rejects a match that leaves variants uncovered:

enum Color = Red; Green; Blue

def isRed(c: Color): bool =
  c match
    Red -> true
    _   -> false             // catch-all closes the set

Duplicate arms (two arms covering the same variant) and arms after a catch-all are also rejected. A non-exhaustive match without a catch-all is a compile error, not a runtime trap.

Restrictions. The scrutinee must have an enum type — match on integers, reals, strings, structs, etc. is not supported. Guards (Variant(x) if x > 0 -> ...) are deferred.

Complex Numbers and the Quadratic Formula

2026-05-22T19:26:20.099529896Z

Complex numbers

A complex number $z = a + bi$ has modulus $\lvert z \rvert = \sqrt{a^2 + b^2}$ and argument $\arg(z) = \operatorname{atan2}(b, a)$, related by the polar form $z = \lvert z \rvert \, e^{i\arg(z)}$ — i.e. Euler’s formula $e^{i\theta} = \cos\theta + i\sin\theta$. The prelude exposes both the field-style accessors .re / .im and the polar-form helpers abs(z) / arg(z).

def main() =
  val z1 = 1.0 + 2i             // (1.0 + 2.0i)
  val z2 = 3.0 - 1i             // (3.0 - 1.0i)

  print(s"z1 + z2 = ${z1 + z2}")
  print(s"z1 * z2 = ${z1 * z2}")
  print(s"|z1| = ${z1.abs()}, arg(z1) = ${z1.arg()}")
  print(s"z1.re = ${z1.re}, z1.im = ${z1.im}")

Quadratic formula

The roots of $a x^2 + b x + c = 0$ are

\[x \;=\; \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}.\]

The sign of the discriminant $\Delta = b^2 - 4ac$ decides whether the roots are real ($\Delta \ge 0$) or a complex-conjugate pair ($\Delta < 0$). The function below returns both roots as complex regardless, so callers see a single result type.

// Solve ax² + bx + c = 0; returns a pair of complex roots.
// Each indented if-branch is a block; the block's last expression is
// a paren-less tuple — no wrapping parens are needed here.
def solve_quadratic(a: real, b: real, c: real) =
  val disc = b^2 - 4a*c
  if disc >= 0.0 then
    val sd = sqrt(disc)
    (-b + sd) / (2a) + 0i, (-b - sd) / (2a) + 0i
  else
    val real_part = -b / (2a)
    val imag_part = sqrt(-disc) / (2a)
    real_part + imag_part*i, real_part - imag_part*i
  end if

def main() =
  val r1, r2 = solve_quadratic(1.0, -3.0, 2.0)      // x² - 3x + 2 = 0
  print(s"real roots: $r1, $r2")

  val c1, c2 = solve_quadratic(1.0, 0.0, 1.0)       // x² + 1 = 0
  print(s"complex roots: $c1, $c2")

Notice the math-flavored juxtaposition: 4a*c, (2a). The imag_part*i uses explicit * because imag_part is an identifier (no juxtaposition between two identifiers).

Compile to a Native Binary

2026-05-22T19:26:20.099529896Z

Compile

The compile subcommand emits LLVM IR text and shells out to clang -O1 to produce a native binary:

sbt "nexJVM/runMain io.github.edadma.nex.run compile /path/to/hello.nex"

The resulting binary lands next to the source, with the .nex extension stripped:

/path/to/hello

Run it directly — no JVM, no sbt, no dependencies beyond the system C runtime:

/path/to/hello

Output is identical to what the interpreter produced.

Verify parity

The intended way to use Nex during development is to write code, run it under the interpreter for the fast edit/run cycle, then occasionally compile to native to confirm the AOT path produces the same output. Every commit to the compiler runs the full unit-test suite (over two thousand tests on JVM today) plus an interpreter-vs-AOT parity sweep that compares the two paths byte-for-byte on a shared corpus. The compiled binary’s real-number printing matches Java’s Double.toString — non-whole reals like 0.1 + 0.2 print as 0.30000000000000004, magnitudes like 1e20 print as 1.0E20, and runtime traps (assertions, array-index OOB, division by zero, slice OOB) all carry the same human-readable messages as the interpreter, written to stderr as trap: <msg>\n with exit code 1, so assert_traps(fn, substring) matches the same trap text on both sides and a shell pipeline that captures stderr sees identical bytes from either path.

When you’d reach for which

Use run while writing code. Sub-second turnaround. Same output as the binary for everything you care about.
Use compile when shipping, benchmarking, or producing a self-contained executable to share. The native binary is roughly an order of magnitude faster on most numerical workloads (no interpreter dispatch overhead, real LLVM optimization at -O1).
Use test to discover and run every @test-annotated function in a project — see the Tooling chapter for details and the Test modules example for the convention.

Next step

You’re done with the getting-started path. From here:

Examples — a feature tour plus a dozen complete programs from hello-world through a recursive FFT.
Specification — the chapter-by-chapter language reference.
Tooling — CLI details, verification model, supported targets.

CLI

2026-05-22T19:26:20.099529896Z

Subcommands

nex tokens    <file>                # lex; print the token stream
nex parse     <file>                # lex + parse; print the AST
nex elaborate <file>                # parse + name resolution; print the typed AST
nex run       <file>                # parse, elaborate, execute via the tree-walking interpreter
nex test      <file>                # discover and run every @test function reachable from <file>'s project root
nex compile [--backend B] <file>    # emit IR and invoke a backend toolchain to produce a native binary

<file> is always a single .nex source. For test and compile, the directory containing <file> is the project root — the import graph is discovered from there.

--backend (only for compile) selects the codegen pipeline:

llvm (default) — emits LLVM IR text and invokes clang -O1. Covers the full language surface.
mlir — emits MLIR via linalg / arith / scf / tensor / func dialects and runs mlir-opt → mlir-translate → clang -O1. Experimental and growing on the strangler-fig pattern: scalar arithmetic (+ - * / div % ^, unary -), comparisons (scalar and array-element-wise, returning [bool]) + bool + and / or / not, min / max / abs, the libm transcendentals (sqrt / exp / log / sin / cos / …), the explicit conversions to_real / to_integer, array literals + length + indexing, array-array element-wise binops (matching element types, or mixed integer / real promoting up the lattice), scalar–array broadcasts (arithmetic and comparison), and the @ operator (matmul, matvec, dot) all parity-check against the interpreter. Control flow lowers via the scf dialect — scalar if-expressions, statement-position if / if/else (lowered to a no-result scf.if with optional else region), while cond do ... loops, and for loops in both forms (for i in lo..hi do ... over an integer range, for x in xs do ... over a rank-1 array) are wired up. Mutable scalar var bindings lower to memref.alloca slots so a counter-style var n = 0; while ... do n = n + 1 works end-to-end. Mutable tensor var bindings rebind through fresh SSA via tensor.insert / tensor.insert_slice / scf.for accumulators, covering whole-tensor reassign, scalar index-assign at rank-1 and rank-2 (negative-index wrap + OOB trap), rank-1 slice-assign (open bounds, inclusive, stride > 1), and rank-2 row/column replace (m[i, :] = rhs / m[:, j] = rhs); auto-clone insertions (spec §8.3) become emit-inner identities because SSA tensor semantics already diverge the bindings on the first mutation. Rank-1 and rank-2 slicing (xs[2..5], m[:, 1], m[0..2, 1..3], etc.) routes through tensor.extract_slice for both literal and runtime bounds, including the strided forms (xs[0..n by 2], m[..r by k, c]) — the rank-reducing form drops a dimension whenever an axis collapses to a scalar index. Rank-1 filter(arr, pred) and flatMap(arr, x -> [...]) lower to two-pass tensor.empty + tensor.insert builders so the output shape is sized exactly. Index-style traps match the interpreter: negative-index wrap on TIndex, plus out-of-bounds traps on both indexing and slice bounds. The MLIR C runtime now carries the same setjmp/longjmp trap-catching infrastructure the LLVM backend has had since milestone 1 — a thread-local nex_trap_buf plus a nex_trap_with(msg) shim that longjmps when an assert_traps is on the stack and aborts to stderr otherwise — so assert lowers to scf.if !cond { call nex_assert_failed } with the message extracted from the optional nex_str at compile time, assert_traps(fn, sub?) lowers to a nex_assert_traps call that pulls (fn_addr, env_addr) out of the closure descriptor via the existing nex_closure_fn / nex_closure_env helpers (with the thunk cast to int64_t (*)(int64_t) so unit / int / pointer return types all flow), and integer div/%, real /, and int-div-int-to-real / get an scf.if-guarded nex_trap_int_div_zero check before the divide. assert_traps cases that close over an array value inside the closure are still deferred until the tensor-capture closure ABI lands, and assert_approx (rank-1, rank-2, and complex variants) is also deferred pending dedicated emitters. User-defined def functions lower to func.func @nex_user_<name>_<id> at module level — scalar (i64 / f64 / i1) and string parameters and return types are supported, plus tensor params / tensor returns (including tensor-returning if-expressions) and unit-returning defs (def scale(v: mut [real], k: real) = ...); recursion, mutual recursion, forward references, and prelude consts (pi / e) referenced from inside a user def all flow naturally because module-level ops in MLIR are order-independent. Value-returning defs with early return inside a loop or branch are desugared to an equivalent if-expression chain before codegen, so return doesn’t need a dedicated MLIR shape. mut scalar parameters lower to memref<T> ref slots — the callee binds the param as a varSlot, reads and assignments flow through memref.load / memref.store on the same memref the caller’s slot uses, and the call site forwards its slot register directly so writes are visible on both sides without a copy. mut rank-1 and rank-2 tensor parameters take a different shape: they are admitted as plain tensor<...> by-value rather than boxed through memref<tensor<...>>, and the callee seeds them into its var-tensor map so the same index-assign / slice-assign machinery covers writes inside the function body. The elaborator’s NexLifetime auto-clone pass (spec §8.3) wraps the call-site arg in a TClone whenever the caller’s var is read after the mut call, so visible-aliasing cases are diverged at the language level before MLIR ever sees them. Compound assignment (+= -= *= /= %=) rides the existing var-slot and index-assign machinery for free, because the elaborator already desugars n += k to TAssign(n, n + k) before the backend sees it. Top-level const X = ... inits flow through the same emitter as ordinary expressions, so const X = sqrt(2.0) and recursive-fact / cos(pi/2) style initializers compile without a dedicated shape. Closures lower end-to-end: each TLambda whose signature and captures fit i64-shaped LLVM-compatible slots becomes a synthetic top-level llvm.func @nex_lambda_<N>(%env, args...); free-var captures are classified ByVal (immutable) or ByRef (the source is a var), and any var referenced inside any lambda is “boxed” out of its parent’s memref.alloca into a heap cell so the box outlives the parent frame and mutations through either side stay visible. Closure construction sites build a heap descriptor {fn_ptr, env_ptr} via llvm.mlir.addressof + llvm.ptrtoint, the closure type lowers as an opaque i64, and indirect call extracts (fn, env) from the descriptor and dispatches through llvm.call. Top-level defs reached in value position (passed to a HOF, bound to a val, returned) lower to a closure descriptor with a synthetic thunk function pointer and a null env, so a top-level def can be passed wherever a closure is expected. Arrays of closures work ([f, g, h] and for f in fs do f(x)), and map(xs, f) accepts a val- or arg-bound closure value rather than only an inline lambda — the rank-1 driver extracts (fn, env) once outside the scf.for and dispatches per-iteration. if-expressions can return string values (if cond then "yes" else "no") since the i64 string-descriptor encoding matches the closure-style boundary type the scf.if regions already use. User-defined generic functions (Spec §6.10) flow through to MLIR transparently: NexMonomorphize runs in the elaborator before any backend sees the typed IR, so identity / numeric-constrained / ord-constrained / two-type-param / generic-lambda / overload-resolved call sites all reach codegen as concrete monomorphized defs without any MLIR-side dispatch logic. Structs and tuples lower to !llvm.struct<(...)> from the LLVM dialect — the pass pipeline already runs convert-func-to-llvm, so LLVM-dialect types flow through func-boundary signatures unchanged. Struct construction is an llvm.mlir.undef of the struct type folded with llvm.insertvalue per declared slot (int → real promoted at the slot boundary); field reads emit llvm.extractvalue at the declared field index; nested-field writes (o.i.v = 99) walk the TField chain back to its TVarRef root, recursively extractvalue along the path, perform the leaf insertvalue, then insertvalue the updated sub-struct back out, with the final SSA rebound at the var. var-bound structs and tuples track per-var SSA registers parallel to the var-tensor scheme, so auto-clone falls out for free: var c = b copies the SSA register but the first write through either binding produces a fresh value, leaving the other binding unaffected. Tuples are the positional twin (no field names); TTupleProj lowers to extractvalue and the print(tuple) / s"$tup" paths share an emitTupleToString formatter. Tuple-returning and struct-returning if-expressions flow through the typed-if scaffold via parallel MTuple / MStruct arms. Scalar complex values lower as !llvm.struct<(f64, f64)> from the same LLVM-dialect path — a pack/unpack helper pair feeds per-component lowerings for + - * / (with a zero-denominator trap on /), equality and unary minus, the field projections .re and .im, the to_complex conversion, the modulus |z|, complex-arm if-expressions, and print / s"..." formatting; a branchless sign(x) built-in is along for the ride and unlocks the prelude’s source-defined complex extensions for sqrt / exp / log / sin / cos / tan, which lower through the same monomorphized-def machinery as any other prelude function. User-defined generic structs (Spec §3.6) flip transparently for the same monomorphization reason — Box[T], Pair[A, B], nested generic structs, generic-into-generic-fn, ord-constrained generic struct, explicit-annotation construction, and generic-struct field write all reach codegen as concrete MStruct(...) lowerings. String values are represented as opaque i64 descriptor pointers — literals share a module-level memref.global pool, the runtime ships refcounted concat / eq / from_i64 / from_bool / from_double helpers, and refcount discipline (–1 immortal for literals, +1 heap for concat / value-to-string results, dec on every consume site) mirrors LLVM exactly; print("..."), string == / != / +, s"..." interpolation with integer / bool / real, and f"..." format-spec values (%d / %f / %e / %g / %x / %X / %o / %b with width / 0 / - flags and .precision) all parity-check against the interpreter, and the real-value branch uses a shortest-round-trip helper that matches Java’s Double.toString byte-for-byte. The array builders range / zeros / ones / linspace plus transpose round out the rank-1 / rank-2 surface. The corpus opts cases in one at a time via a per-case mlir = true flag in NexProgramCorpus — see NexCorpusMlirParityTests for what’s currently covered. User-defined enums (Spec §3.7 / §3.8) lower as tagged unions !llvm.struct<(i32, !llvm.array<N x i64>)> where N is the max field count across variants and each field occupies one i64 payload slot — int as identity, real ↔ i64 via llvm.bitcast, bool ↔ i64 via llvm.zext / llvm.trunc, string as the i64 descriptor it already is. match walks arms in source order as a chain of scf.if -> (T) (or no-result scf.if for unit-typed arms), each variant pattern testing arith.cmpi eq %tag, idx and binding sub-pattern fields by llvm.extractvalue [1, i] + per-type decode; var- and wildcard-patterns terminate as the default arm. A per-enum func.func @nex_enum_str_<Name> flushed after @main powers print(enum) and s"${enum}". Generic enums (Opt[T], Result[T, E], ord-constrained generic enum) flip transparently for the same monomorphization reason generic structs already do. Aggregate field types inside a variant (struct- or tensor-typed fields) stay rejected at codegen — a separate lowering sub-project. Arrays of structs are also deferred (a separate struct-element tensor sub-project). The elaborator’s NexFusion pass is now wired into the LLVM compile path (so 2 * a + b lowers to a single fused loop on the default backend), but is intentionally not run before MLIR codegen yet — the MLIR TFusedLoop lowering only covers rank-1 fused loops with statically-known lengths, so any program reaching MLIR with fused IR (a broadcast inside a def, any rank-2 fusion) would raise the “not yet supported” diagnostic. Picking those up is a strangler-fig follow-up. Anything outside the opted-in surface raises a compile-time “not yet supported” diagnostic.

Locating the source prelude

The scalar transcendentals plus their complex extensions live in a prelude/*.nex directory and are auto-imported on every elaboration (see §10 of the spec). The CLI locates that directory at startup; the precedence order is:

--prelude-path <dir> — an explicit CLI flag (highest priority).
NEX_HOME environment variable — looks at $NEX_HOME/lib/prelude/.
-Dnex.prelude.path=<dir> JVM system property. build.sbt sets this automatically so sbt run and sbt test use the in-repo prelude/ with no extra wiring.
Walk up from the current working directory — at each ancestor, check for a prelude/ sibling and then lib/prelude/.

If none of the four locate a directory, the compiler falls back to the compiler-built-in name table and proceeds silently. This was the design during the Stage 1/2 migration and remains the fallback today for environments without a sysroot.

Running the CLI from sbt

There is no shipped binary yet; the canonical entry point is sbt’s runMain:

sbt "nexJVM/runMain io.github.edadma.nex.run <subcommand> <file>"

Examples:

sbt "nexJVM/runMain io.github.edadma.nex.run run     examples/fft/main.nex"
sbt "nexJVM/runMain io.github.edadma.nex.run compile examples/fft/main.nex"
./examples/fft/main

run is also a published @main entry point on the JVM JAR — once packaged, java -jar nex.jar <subcommand> <file> does the same thing.

Requirements

JVM 17+ to invoke the CLI.
clang on $PATH for the compile subcommand. The compiler writes LLVM IR text to a temp file and shells out to clang -O1 to produce a native binary.
No other native dependencies.

What each subcommand prints

tokens — one token per line, with source position.
parse — the untyped AST as a pretty-printed tree.
elaborate — the elaborated (typed, name-resolved, lowered) AST. Useful for debugging type inference or fusion-pass output.
run — the program’s stdout (whatever it prints); exit status reflects whether a trap occurred.
test — one line per discovered test, with a pass/fail marker; a summary at the bottom; non-zero exit on any failure.
compile — diagnostics during code generation, then either a native binary at <file-without-extension> or a non-zero exit on error.

Bindings

2026-05-22T19:26:20.099529896Z

Nex has three binding kinds: const, val, and var. All three may appear at any scope (module level or inside a function/block). They differ in what they bind:

Keyword	Mutability	Storage	Evaluated
`const`	Immutable	None (may be inlined)	Compile time
`val`	Immutable	Has storage	Runtime, at point of declaration
`var`	Mutable	Has storage	Runtime, at point of declaration

5.1 `val` bindings

A val binding introduces an immutable binding to a value. The bound name cannot be reassigned, and (for array and struct types) the bound value’s contents cannot be mutated through this binding. The right-hand side may be any expression, evaluated once at the point of declaration (module load, function entry, or block entry).

val x = 42
val data = [1.0, 2.0, 3.0]
val mag = sqrt(sum(v * v))          // RHS may include function calls

Type annotation is optional and inferred from the initializer when omitted:

val x: integer = 42
val data: [real] = [1.0, 2.0, 3.0]
val empty: [real] = []              // empty literals require an annotation

For val arrays: contents are immutable, the buffer may be freely shared, no uniqueness constraint applies (see chapter 8).

5.2 `var` bindings

A var binding introduces a mutable binding. For scalar types, the binding may be reassigned. For array types and struct types, the contents may also be mutated (via a[i] = ... or s.field = ...). The right-hand side may be any expression.

var n = 0
n = n + 1                    // ok

var data = [1.0, 2.0, 3.0]
data[0] = 10.0               // ok: mutate contents
data = [4.0, 5.0]            // ok: rebind

var p = Point(0.0, 0.0)
p.x = 5.0                    // ok

Module-level vars are permitted (for caches, RNG state, configuration set at startup) but should be used sparingly — most program state belongs in function-local bindings or in consts.

var arrays are subject to the uniqueness rule (chapter 8).

Compound assignment. The four arithmetic ops + - * / and the integer % op pair with = to form +=, -=, *=, /=, %=. Each is desugar-equivalent to evaluating the binop against the current value of the l-value and assigning the result back:

n += 5         // identical to: n = n + 5
n -= 1
acc *= 2.0
x /= 2.0
n %= 10

a[i] += 1      // index target
b.v *= 3       // field target

The l-value must be a var, a field of a var, or an index into a var array (the same set of forms = already accepts). The right-hand side is parsed as a full expression — n += 2 * 3 + 4 is n = n + (2 * 3 + 4). Compound assignment is a statement form: it only appears at block-item position, never inside an expression. There is no ^=, no div=, and no boolean / bitwise compound (and=, or=).

5.3 `const` bindings

A const binding introduces a compile-time constant. The right-hand side must be a constant expression — evaluable entirely at compile time. The compiler may inline the value at use sites; there is no guaranteed storage location.

const PI       = 3.14159265358979
const TAU      = 2 * PI            // arithmetic on consts is constant
const MAX_ITER = 1000
const ENABLED  = true

A constant expression is one of:

A numeric or boolean literal
An application of +, -, *, /, div, %, ^, juxtaposition, not, and, or, or comparison operators to constant expressions
A reference to another const binding
A reference to a prelude constant (pi, e, inf, nan, i)
Unary - of a constant expression
A call to a pure function (prelude or user-defined) whose every argument is itself a constant expression and whose return type is scalar (integer, real, bool, or complex)

A function is pure when it has no observable side effects: no I/O, no mutation of var bindings, and every function it calls is itself pure. Prelude math functions (sqrt, sin, cos, abs, hypot, min, max, floor, ceil, round, trunc, the conversions, the complex helpers, …) are pure; print and the assert_* family are impure (they emit output or trap).

const SQRT_2  = sqrt(2.0)            // OK — sqrt is pure
const HYP     = hypot(3.0, 4.0)      // OK — 5.0
const TWO_PI  = 2 * pi                // OK — arithmetic on prelude const

def square(x: real): real = x * x
const NINE    = square(3.0)          // OK — square is pure

const BAD     = print(1)              // ERROR — print is impure

Two practical restrictions:

The return type of a forward-referenced user function (one declared after the const) must be written explicitly. Otherwise the const’s static type can’t be resolved before the function’s body is type-inferred. Move the def above the const or add a declared return type.
The call result must be a scalar — [T], tuples, structs, and strings escape the inline-friendly model. A pure helper that returns an array can still be used inside a normal val binding.

For runtime-computed module-level values that aren’t compile-time constants (a call that needs an array argument, a struct construction, an if), use val:

val SAMPLES = linspace(0.0, 1.0, 100)   // construction → must be val

Prefer const over val whenever the value is a true compile-time fact (mathematical constants, physical constants, configuration flags, fixed tolerances). It signals intent and lets the compiler inline at use sites.

5.4 Scoping

Bindings are lexically scoped. A binding is visible from its declaration to the end of the enclosing block.

5.5 Shadowing

A new binding may shadow an earlier binding with the same name in an enclosing scope. Shadowing within the same block is not permitted.

val x = 1
def foo() =
  val x = 2                  // ok: shadows outer x in foo's scope
  ...

val x = 1
val x = 2                    // error: redeclaration in same scope

Arrays and Structs

2026-05-22T19:26:20.099529896Z

Element-wise array operations (the fusion sweet spot)

For arrays $a$ and $b$ of the same length, an element-wise expression like

\[r_i \;=\; 2 a_i + b_i - 1 \qquad i = 0, \ldots, n-1\]

compiles to a single loop — no temporary array for 2a, no separate + b, no separate - 1.0. The whole expression is the fusion unit.

def main() =
  val a = [1.0, 2.0, 3.0, 4.0, 5.0]
  val b = [10.0, 20.0, 30.0, 40.0, 50.0]

  // Fuses to a single loop, no intermediate arrays:
  //   for i in 0..5: result[i] = 2 * a[i] + b[i] - 1.0
  val result = 2a + b - 1.0

  print(result)         // [11.0, 23.0, 35.0, 47.0, 59.0]

A struct and a function over it

A Point is a record of two reals, and distance is the Euclidean norm of the difference,

\[d(p_1, p_2) \;=\; \sqrt{(x_1 - x_2)^2 + (y_1 - y_2)^2}.\]

The function reads back as one line per term in the formula.

struct Point
  x: real
  y: real
end

def distance(p1: Point, p2: Point) =
  val dx = p1.x - p2.x
  val dy = p1.y - p2.y
  sqrt(dx^2 + dy^2)

def main() =
  val origin = Point(0.0, 0.0)
  val p = Point(3.0, 4.0)
  print(distance(origin, p))        // 5.0

Appendix B: Open Design Questions

2026-05-22T19:26:20.099529896Z

The original draft’s question list has been mostly settled during implementation. Items that remain open:

Whether unused val bindings produce a warning (currently silent — the compiler does not warn).

Resolved

The following items from the original draft have been resolved by the implementation:

Shape-mismatch traps include source location. Element-wise rank-1 and rank-2 operations trap with a message such as element-wise '+': shape mismatch plus the source position of the operator. Rank-1 length mismatches in dot and similar prelude functions include both lengths.
for x in arr iterates by value. Each loop iteration binds x to a copy of the next element. This matches the value-semantics design of the language and avoids a “borrow that escapes the loop” footgun.
String formatting via f-strings. Scala-style f"..." (sibling of s"...") covers width, precision, alignment, padding, hex / octal / binary conversions, and the %%/$$ escapes — replacing the earlier deferred format() builtin. See spec §10.6.

Appendix A: Naming Conventions

2026-05-22T19:26:20.099529896Z

The following naming conventions are recommended but not enforced:

Module and file names: lowercase, underscore-separated (linalg, dense_matrix)
Type names (structs): UpperCamelCase (Point, LineSegment, Matrix)
Function and binding names: lowercase, underscore-separated (compute_norm, dense_solve)
Constants: UPPER_SNAKE_CASE (PI, MAX_ITERATIONS)

Nex

Verification Model

Three layers of testing

Why this matters

Type System

3.1 Primitive types

3.2 Numeric promotion

3.3 Array types

3.3.1 The [byte] buffer type

3.4 Tuple types

3.5 Struct types

3.6 Generic structs

3.7 Sum types

3.8 Generic enums

3.9 Function types

3.10 Type expressions

Tour

Comments

Layout: separators and line continuation

Literals

Booleans, integers, reals

Strings and escapes

Interpolated strings (s"...")

Complex via the i constant

Unit

Bindings

Block expressions

Arithmetic

Numeric promotion

Comparison and logical

Juxtaposition multiplication

Arrays — rank-1

Arrays — rank-2 (matrices)

[byte] buffers

Slice assignment — Fortran-90 array sections

Tuples

Ranges

Structs

Sum types and match

Lambdas

Functions

Parameter modes

Higher-order functions

Closures

Generic functions

Generic structs

Generic enums

Control flow

Constants

Prelude — math

Prelude — rank-1 array operations

Prelude — rank-2 (matrix) operations

Prelude — construction

Prelude — I/O

Prelude — conversions

Testing

Modules

Literate Nex

Dedicated @test Modules

Supported Targets

AOT path (native binaries via nex compile)

CLI builds

Planned

Sum Types and Match

The solver

Inspecting the outcome with match

When to reach for a sum type

Three Ways to Express the Same Computation

Sum of Sinusoids

Standard Library / Prelude

10.1 Constants

10.2 Mathematical functions on scalars

10.3 Complex-specific operations

10.4 Array operations

10.5 Construction

10.6 I/O

10.7 Type conversions

10.9 The [byte] buffer

10.8 Assertions

Power Iteration

3.3.1 The `[byte]` buffer type

Interpolated strings (`s"..."`)

Complex via the `i` constant

`[byte]` buffers

Sum types and `match`

AOT path (native binaries via `nex compile`)

Inspecting the outcome with `match`

10.9 The `[byte]` buffer

9.5 No `.mod` binary headers

8.2 Uniqueness for `var` arrays

8.6 Future: RAII for `var` arrays

6.9 `return`

6.11 `@intrinsic` declarations

What else `run` accepts