brolang/LANGUAGE.md

language features

IMPLEMENTED

source and declarations

• newline-terminated statements and # comments
• immutable :: bindings, mutable function-local = bindings, and _ sinks
• immutable and mutable locals
• package-level globals and functions
• interned identifiers

types and expressions

• exact-width i8 through i64, u8 through u64, f32, f64, isize, usize, bool, void, and inferred integer-constrained int
• target-dependent atomic C primitives from c_char through c_longdouble
• C primitives remain semantically distinct from exact-width Brolang primitives until target lowering
• contextual integer and character literals and constant folding of arithmetic and negation trees
• strict numeric conversions, binary + - * / with checked integer overflow and divide-by-zero traps (floats follow IEEE), and unary negation
• boolean literals, comparisons, unary !, and short-circuiting and / or
• arrays [N]T, sentinel arrays [N;S]T, single-item pointers @T, many-item pointers *T, sentinel many-item pointers [*;S]T, pointer offsets, slices, and explicit slicing
• immutable UTF-8 string literals typed as pointers to static sentinel arrays: @[N;0]u8
• pointer-to-array .len, indexing, and slicing without explicit dereference
• arrays expose .len but not .ptr; slices and pointers-to-arrays expose .ptr and preserve sentinel information when available
• information-preserving and information-forgetting pointer-to-array decay and sentinel slice/pointer weakening; array values never implicitly decay
• narrow immutable zero-terminated byte pointer conversion to *c_char and [*;0]c_char, without general u8/c_char interchange
• optionals with trapping postfix ?, orelse, and nullable pointer representation
• conditional optional unwrapping with immutable guard/then-block bindings, guarded captures, and left-to-right short-circuiting multi-unwrap: if first and second |a, b : guard| { ... }
• source-order native structs, defined or opaque c_struct, and keyed record literals
• complete plain imported C structs and unions as runtime values; incomplete or unsupported-layout records remain pointer-only
• C function pointer types as pointer-sized runtime values, including manual *c_func(...) T spelling and nullable imported callback typedefs
• postfix pointer dereference, general writable locations, function calls, assignments, compound assignment (+= -= *= /=) with single-evaluation lvalues, and returns
• first-class exclusive and inclusive integer ranges: start..end and start..=end
• boolean if statements and while loops with optional post-iteration assignment/expression clauses
• for loops over ranges, arrays, slices, and pointers-to-arrays, with copy, pointer, and optional usize index captures
• |@item| pointer captures inherit pointee mutability from the iterable; arrays require an explicit pointer such as &items

functions and packages

• demand-monomorphized functions
• bodyful c_func definitions using the c calling convention
• bodyless c_func declarations with exact, globally unique external symbol names
• concrete-only foreign signatures
• Apple Silicon C ABI scalar, pointer, and fixed-signature plain record/union lowering, including narrow integer extension attributes
• directory packages with merged declarations
• file-local relative imports, aliases, and qualified member access
• relative .h imports as synthetic package namespaces
• transitive external C function prototypes, typedef chains, C scalars, fixed arrays, complete plain records/unions, and pointers to opaque C records
• imported external C object variables, including writable globals and immutable arrays
• object-like scalar and plain record/union C macro constants
• supported static inline C functions through generated external wrappers
• bodyless manual and imported C variadic declarations with target-aware default argument promotions
• passing concrete c_func declarations/definitions as C callback values and calling non-null C function pointers with postfix call syntax
• reference-time diagnostics for unsupported imported C declarations

compiler behavior

• error-tolerant compilation with runtime diagnostic traps
• lazy semantic checking of demanded function specializations
• demand-driven LLVM declarations for referenced foreign functions
• ordered linking of additional c sources, objects, and libraries
• replaceable dynamically loaded libclang C-import backend
• per-compilation C-header import caching by canonical path, target, ordered include paths, and ordered defines
• static, eager runtime, and deferred problematic globals

PLANNED

foreign functions and linking

• exporting brolang functions to c
• additional target-specific C ABI lowering

scalar and compound types

• tuples and native variadic functions
• C enums and non-plain C record layouts