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, 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 literals and constant folding of addition and negation trees
• strict numeric conversions, checked integer addition, and unary negation
• arrays [N]T, sentinel arrays [N;S]T, indexing, pointers, pointer offsets, slices, and explicit slicing
• immutable UTF-8 sentinel-slice strings and Unicode code-point character literals
• optionals with trapping postfix ?, orelse, and nullable pointer representation
• source-order native structs, keyed literals, and defined or opaque pointer-only c_struct
• postfix pointer dereference, explicit .ptr/.len, general writable locations, function calls, assignments, and returns

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 and pointer 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, and pointers to opaque C records
• 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

• c variadic calls with default argument promotions
• exporting brolang functions to c

scalar and compound types

• tuples and native variadic functions
• C unions, C enums, and by-value C record ABI lowering

advanced c imports

• C enums, external variables, function pointers, callbacks, macros, and static inline functions
• target-specific by-value C record and union ABI lowering