brolang/TODO.md

"quick" / "easy" fixes

• for global initialization cycles, report also starting and ending lines

milestones

1. interop type foundation (implemented)

   • unsigned integers, floats, and target-dependent c scalar types
   • atomic c_* primitive types remain distinct until target-aware lowering
   • c_func and pointer-only c_struct; c remains an ordinary identifier
   • keep binding mutability (:: / =) separate from element or pointee mutability (mut)
   • arrays and indexing
     • [N]T: array with N logical elements
     • [N;S]T: array with N logical elements followed by sentinel S
   • pointers
     • @T / @mut T: non-null single-item pointer without arithmetic
     • *T / *mut T: non-null many-item pointer with arithmetic
     • optional pointers represent nullable pointers (i.e. ?@T / ?@mut T, ?*T / ?*mut T)
   • slices and slicing
     • []T: pointer and length
     • [;S]T: pointer and length with a sentinel invariant
     • ordinary slices do not guarantee null termination
   • string literals as immutable sentinel slices backed by static arrays (superseded by milestone 3.5)
   • character literals
   • optionals with trapping unwrap and fallback operations
   • native structs with compiler-controlled layout
   • pointer-only c_struct support with target c layout
     • Some :: c_struct { ... }: defined c-layout struct
     • Some :: c_struct: opaque c-layout struct
     • passing c structs by value was deferred until milestone 4.1

2. restricted c header imports (implemented)

   • treat an imported header as a synthetic, file-local package namespace
     • native :: import "relative/path/to/header.h"
   • import functions, typedefs, scalar types, and pointers to opaque records
   • keep implementation linking separate from header imports
   • cache imports by canonical header path and target/include/define configuration
   • diagnose unsupported declarations when referenced
   • dynamically load libclang behind a replaceable c importer boundary

3. c variadic calls (implemented)

   • represent c variadics as a fixed parameter count plus a variadic flag
   • apply c default argument promotions at call sites
   • emit LLVM c-variadic declarations and calls
   • keep native brolang variadics and tuple design separate

3.5. sentinel pointers and c strings (implemented)

• add sentinel many-item pointers: [*;S]T
• represent string literals as immutable pointers to statically stored sentinel arrays: @[N;0]u8
• arrays expose .len but no .ptr; slices and pointers-to-arrays expose sentinel-preserving .ptr
• allow pointer-to-array .len, indexing, slicing, pointer decay, and slice construction without explicit dereference
• preserve or forget sentinel information through compatible pointer and slice coercions without copying arrays
• allow zero-terminated immutable byte pointer views to convert to immutable *c_char and [*;0]c_char
• keep u8 and c_char distinct to preserve target-dependent scalar c semantics
• reject general u8/c_char interchange, slice-to-pointer coercion, and conversion to mutable c character pointers

4. advanced c interop
   • by-value records and unions (implemented)
     • complete plain imported structs/unions and manual c_struct values
     • fixed C arrays inside imported records
     • keyed struct literals and exactly-one-field union literals
     • field reads/writes, storage, and fixed-signature calls/returns
     • aarch64-macos small aggregate, homogeneous float aggregate, and indirect ABI lowering
     • keep incomplete, bitfield, packed, flexible-array, qualified-field, and otherwise non-plain records pointer-only
     • keep C variadic record arguments unsupported
   • function pointers and callbacks (implemented)
     • imported C function pointer typedefs lower to nullable pointer types
     • manual ?*c_func(...) T callback type spelling
     • concrete c_func declarations/definitions can be passed as callback values
     • postfix calls through non-null function pointers, including callback?(...)
     • fixed and C-variadic callback ABI emission through LLVM indirect calls
   • external variables
   • macros and static inline functions
   • exporting brolang functions to c