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