brolang/LANGUAGE.md

language features

This file is the compact current-state ledger. TODO.md remains the detailed roadmap and milestone history.

IMPLEMENTED

source, declarations, and packages

• newline-terminated statements and # comments
• immutable :: bindings, typed mutable = locals/globals, and _ sinks
• immutable package globals, mutable runtime globals, function-local mutable locals, and mutable local declarations initialized with undefined
• package-level functions, globals, native type declarations, and Name :: alias T
• directory packages with merged declarations
• file-local relative imports, import aliases, and qualified member access
• native top-level declarations beginning with _ are visible only within their source file; locals, fields, parameters, and C declarations are unaffected
• relative .h imports as synthetic C header package namespaces
• root main validation with trap executable recovery for missing or unusable entry points

scalar, aggregate, and pointer types

• exact-width integers, isize, usize, f32, f64, bool, void, anyopaque, and contextual int, float, and range constraints
• target-dependent C scalar primitives from c_char through c_longdouble, kept semantically distinct from native scalars
• contextual integer/float/character literals, backward type-demand inference through names and arithmetic, and compile-time folding for numeric constant expressions
• strict numeric conversion by default, widening where valid, C scalar coercions at C boundaries, and explicit scalar keyword casts such as i32(x) / c_float(x)
• arrays [N]T, inferred-count arrays [_]T, sentinel arrays [N;S]T, compile-time expression array counts, slices []T / [;S]T, single-item pointers @T, many-item pointers *T, and sentinel many-item pointers [*;S]T
• pointer mutability via mut, optional pointers as nullable pointers, pointer arithmetic for many-item pointers, postfix dereference ^, and trapping optional unwrap ?
• pointer-to-array .len, indexing, slicing, .ptr on slices and pointers-to-arrays, implicit address-taking for array-variable slices, and pointer/slice sentinel weakening
• ptr_cast(T, ptr) as a first-pass pointer-child retype that preserves optionality, pointer kind, mutability, and sentinel shape
• UTF-8 string literals as immutable pointers to static zero-terminated byte arrays, plus raw backtick multiline strings
• narrow immutable zero-terminated byte pointer/slice conversion to *c_char / ?*c_char without general u8/c_char interchange
• optionals with none, orelse, postfix ?, conditional unwraps, guarded unwraps, and left-to-right short-circuiting multi-unwraps
• nominal distinct types with exact backing construction, native enums with optional explicit integer backing, contextual enum literals, and imported C enums as target-backed integer aliases
• source-order native structs, opaque nominal records with Name :: opaque, complete c_struct { ... }, keyed record literals, native untagged unions, and native tagged unions union(Enum) / union(enum)
• void-payload tagged-union variants, anonymous struct payloads, contextual .variant, .variant{payload}, and .variant{field = value} construction
• native sum composition with A | B for unbacked enums and tagged unions, using program-global u16 variant ids
• fallible channel types T ! E, where E is a native enum/tagged union or supported sum composition

expressions and control flow

• checked integer + - * /, unary -, divide-by-zero traps, IEEE float arithmetic, comparisons, !, and, and or
• assignments and compound assignments += -= *= /= with single evaluation of complex lvalues
• field access through struct values and pointers, index/slice bounds contextually coerced to usize, and unsigned narrower index support
• boolean if / else if / else, braceless single-statement branches, and optional parenthesized conditions
• while loops with optional post-iteration update clauses
• for loops over ranges, arrays, slices, and pointers-to-arrays with copy captures, pointer captures |@item|, and optional usize index captures
• break, continue, labeled break :label, labeled continue :label, and labeled plain blocks
• bare block scopes and defer, including LIFO flushing on fall-through, return, break, and continue
• value blocks, value if, value loops, value match, yield, and labeled yield :label value
• match statements/expressions over enums, tagged unions, and scalars, including exhaustiveness checks, payload captures, pointer payload captures, multi-pattern arms, and scalar range patterns
• fallible try, fallback catch, and catch |e| { ... } handler blocks
• direct return match ... and yield match ... value-control-flow operands

functions, C interop, and linking

• demand-monomorphized Brolang and C-ABI functions
• integer comptime value parameters such as make_array func($N usize) [N]u8, specialized by value and omitted from the runtime ABI
• explicit comptime type parameters such as max func($T type, a, b T) T, specialized by type and omitted from the runtime ABI
• forced typed comptime expressions such as $sum(1, 2), $Point { x = 1, y = 2 }, and comptime value blocks such as ${ yield 4 }
• comptime execution for bodyful Brolang functions with mutable locals, loops, defer, match, try/catch, pointer/slice storage mutation, pointer captures, and calls through comptime-known function values
• bodyful c_func definitions and bodyless c_func declarations with exact external symbol names
• concrete-only C signatures, C variadic declarations/calls, and C default argument promotions
• native function pointer values and types with @func(...) R, fallible @func(...) R ! E, optional ?@func(...) R, and non-variadic native indirect calls
• Apple Silicon C ABI lowering for scalars, pointers, fixed-signature plain records/unions, small aggregates, homogeneous float aggregates, and indirect aggregate returns
• imported C typedefs, scalar constants, enum constants, fixed arrays, complete plain structs/unions, C void* as nullable anyopaque pointers, and pointers to opaque records
• imported external C object variables, including mutable variables and immutable object globals
• object-like scalar and plain record/union macro constants
• supported static inline C functions through generated external wrappers
• C function pointer types, imported nullable callback typedefs, concrete c_func callback values, and postfix calls through non-null function pointers
• brolang translate-c <header.h> for native .bro bindings from supported C declarations
• brolang --translate-c stdio.h for offline bindings from Zig-bundled standard C headers
• ordered linking of additional C sources, objects, archives, library paths, and libraries through compiler CLI options

standard packages

• std/mem allocator contract over byte allocation: Allocator with ?*mut anyopaque context plus alloc, realloc, and free; failed nonzero reallocation preserves the original allocation, while zero size frees it

compiler behavior

• error-tolerant compilation with diagnostics and runtime traps where recovery is possible
• lazy semantic checking of demanded function specializations
• static, eager runtime, mutable runtime, and deferred problematic globals with cycle diagnostics
• demand-driven LLVM declarations for referenced foreign functions
• replaceable dynamically loaded libclang C-import backend
• C-header import caching by canonical path, target, include paths, and defines

PLANNED / DEFERRED

• aggregate comptime parameters and stable aggregate specialization keys
• tuples and native Brolang variadic functions
• exporting Brolang functions to C and broader target-specific C ABI lowering
• non-plain C record layouts such as bitfields, packed records, flexible arrays, qualified fields, and C variadic record arguments
• typed heap allocation helpers, arenas, pools, build-mode heap policy, and escaping-allocation diagnostics
• broader Zig-style pointer/result casts beyond V1 ptr_cast(T, ptr)
• sum-type ABI/layout polish, including dynamic tag-width shrinking, all-void channel collapse, and cross-module global-id determinism
• backed/C enum composition and must-consume fallible linting
• result-to-argument type-demand propagation through function call boundaries
• distinct-type backing operators and reverse explicit conversions
• string concatenation operator