add a language document

LANGUAGE.md

@@ -0,0 +1,61 @@
+# 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
+
+- `i8`, `i16`, `i32`, `i64`, `void`, and inferred integer-constrained `int`
+- contextual integer literals and constant folding of addition trees
+- checked signed integer addition
+- function calls, assignments, and returns
+
+### functions and packages
+
+- demand-monomorphized functions
+- bodyful `c func` definitions using the c calling convention
+- directory packages with merged declarations
+- file-local relative imports, aliases, and qualified member access
+
+### compiler behavior
+
+- error-tolerant compilation with runtime diagnostic traps
+- lazy semantic checking of demanded function specializations
+- static, eager runtime, and deferred problematic globals
+
+## PLANNED
+
+### foreign functions and linking
+
+- bodyless `c func` declarations with exact external symbol names
+- concrete-only foreign signatures
+- linking c sources, objects, and libraries
+- c variadic calls with default argument promotions
+- exporting brolang functions to c
+
+### scalar and compound types
+
+- unsigned integers, floats, characters, and target-dependent c scalar types
+- arrays `[N]T` and sentinel arrays `[N; S]T`
+- single-item pointers `@T` and many-item pointers `*T`
+- element and pointee mutability through `mut`, separate from binding mutability
+- slices `[]T` and sentinel slices `[; S]T`
+- string literals as immutable sentinel slices backed by static arrays
+- character literals
+- optionals with trapping `?` unwrap, `orelse` fallback, and nullable pointers
+- data-only native structs and target-layout `c struct` types
+- tuples and native variadic functions
+
+### c imports
+
+- c headers imported as synthetic package namespaces
+- typedefs, enums, opaque records, and external variables
+- function pointers, callbacks, macros, and static inline functions
+- target-specific by-value c record and union ABI lowering

README.md

@@ -45,6 +45,9 @@ Current prototype features:
 - Static, eager runtime, and deferred problematic globals
 - Runtime diagnostics followed by `llvm.trap`
 
+See [LANGUAGE.md](LANGUAGE.md) for the concise implemented and planned language
+feature ledger, and [TODO.md](TODO.md) for the implementation roadmap.
+
 Compiler exit statuses:
 
 - `0`: executable produced without source diagnostics

TODO.md

@@ -4,38 +4,57 @@
 
 # milestones
 
-1. get c interop working:
+1. manual c function interop
-  - link with c / compile c code into binary alongside brolang code
+   - separate calling convention, implementation, linkage, and link name
-  - create bindings from c headers
+   - allow bodyless `c func` declarations with exact external symbol names
-  - figure out how to represent variadic arguments
+   - require concrete types in foreign signatures; inferred `int` is invalid
-    - proposal (from an older document):
+   - emit LLVM `declare` for referenced foreign functions
-      ```
+   - compile and link additional c sources, object files, and libraries through CLI options
-      # functions with variadic arguments
+   - preserve bodyful, mangled, demand-monomorphized `c func` behavior
-      printf :: c func(fmt []u8, args ...) int  # `...` is essentially an anonomous tuple type used in function arguments. `...` collects remaining arguments in a type inferred tuple (infer from anchor)
+   - verify end-to-end with an integer-only c function
-      ```
+
-      - notes on structs and tuples from same older document:
+2. interop type foundation
-        ```
+   - unsigned integers, floats, and target-dependent c scalar types
-        # structs carry only data, no methods, no behavior
+   - keep binding mutability (`::` / `=`) separate from element or pointee mutability (`mut`)
-        Stuff :: struct {
+   - arrays and indexing
-            first u32
+     - `[N]T`: array with `N` logical elements
-            second float
+     - `[N;S]T`: array with `N` logical elements followed by sentinel `S`
-            third [5]i32
+   - pointers
-        }
+     - `@T` / `@mut T`: non-null single-item pointer without arithmetic
-        
+     - `*T` / `*mut T`: non-null many-item pointer with arithmetic
-        # tuples are just structs without field names (accessed via index: ``some_tuple.0``, ``some_tuple.1``, etc.)
+     - optional pointers represent nullable pointers
-        # anonomous tuple type inferred from literal and type anchors?
+   - slices and slicing
-        some_tuple :: { 4, "hello" }
+     - `[]T`: pointer and length
-        ```
+     - `[;S]T`: pointer and length with a sentinel invariant
-  - find out how this should co-exist with the import system
+     - ordinary slices do not guarantee null termination
-    - maybe c header files should just be treated as individual packages
+   - string literals as immutable sentinel slices backed by static arrays
-      - that is also typically how they're used in c projects as they define an interface to a module (or package)
+   - character literals
-      - that means that bindings should be automatically generated by the compiler when the user imports a c header file:
+   - optionals with trapping unwrap and fallback operations
-        - `import "relative/path/to/some_header.h"` - wraps the c header file in a brolang package called `some_header`
+   - native structs with compiler-controlled layout
-        - `other_header :: import "relative/path/to/some_header.h"` - wraps the c header file in a brolang package called `some_header` into `other_header` namespace
+   - pointer-only `c struct` support with target c layout
-        - implementation of the functions declared by the generated bindings is provided by the c implementation and requires the c implementation to be linked with the brolang binary
+     - `Some :: c struct { ... }`: defined c-layout struct
-      - this requires the ability to declare a "bare" function (as an interface) that is linked to the c implementation
+     - `Some :: c struct`: opaque c-layout struct
-        ```
+     - defer passing c structs by value until target ABI classification exists
-        # declare the bare extern function for c interop (notice only the signature is provided, not the implementation)
+
-        # this should only be allowed for extern functions, i.e. `c func`
+3. restricted c header imports
-        extern_c_sum :: c func(a, b int) int
+   - treat an imported header as a synthetic, file-local package namespace
-        ```
+     - `import "relative/path/to/header.h"`
+     - `other :: 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
+   - research libclang's c API behind a replaceable c importer boundary
+
+4. c variadic calls
+   - 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
+
+5. advanced c interop
+   - by-value records and unions
+   - function pointers and callbacks
+   - external variables
+   - macros and static inline functions
+   - exporting brolang functions to c