From 2a79010a57b9bc03e288c1507dc1ec0fb1a457b3 Mon Sep 17 00:00:00 2001 From: hl-valdemar Date: Wed, 10 Jun 2026 23:51:58 +0200 Subject: [PATCH] add a language document --- LANGUAGE.md | 61 ++++++++++++++++++++++++++++++++++++ README.md | 3 ++ TODO.md | 89 ++++++++++++++++++++++++++++++++--------------------- 3 files changed, 118 insertions(+), 35 deletions(-) create mode 100644 LANGUAGE.md diff --git a/LANGUAGE.md b/LANGUAGE.md new file mode 100644 index 0000000..718df8c --- /dev/null +++ b/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 diff --git a/README.md b/README.md index a1ac86f..8000d51 100644 --- a/README.md +++ b/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 diff --git a/TODO.md b/TODO.md index 3187711..0866eb6 100644 --- a/TODO.md +++ b/TODO.md @@ -4,38 +4,57 @@ # milestones -1. get c interop working: - - link with c / compile c code into binary alongside brolang code - - create bindings from c headers - - figure out how to represent variadic arguments - - proposal (from an older document): - ``` - # functions with variadic arguments - 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) - ``` - - notes on structs and tuples from same older document: - ``` - # structs carry only data, no methods, no behavior - Stuff :: struct { - first u32 - second float - third [5]i32 - } - - # tuples are just structs without field names (accessed via index: ``some_tuple.0``, ``some_tuple.1``, etc.) - # anonomous tuple type inferred from literal and type anchors? - some_tuple :: { 4, "hello" } - ``` - - find out how this should co-exist with the import system - - maybe c header files should just be treated as individual packages - - that is also typically how they're used in c projects as they define an interface to a module (or package) - - that means that bindings should be automatically generated by the compiler when the user imports a c header file: - - `import "relative/path/to/some_header.h"` - wraps the c header file in a brolang package called `some_header` - - `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 - - 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 - - this requires the ability to declare a "bare" function (as an interface) that is linked to the c implementation - ``` - # 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` - extern_c_sum :: c func(a, b int) int - ``` +1. manual c function interop + - separate calling convention, implementation, linkage, and link name + - allow bodyless `c func` declarations with exact external symbol names + - require concrete types in foreign signatures; inferred `int` is invalid + - emit LLVM `declare` for referenced foreign functions + - compile and link additional c sources, object files, and libraries through CLI options + - preserve bodyful, mangled, demand-monomorphized `c func` behavior + - verify end-to-end with an integer-only c function + +2. interop type foundation + - unsigned integers, floats, and target-dependent c scalar types + - 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 + - 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 + - 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 + - defer passing c structs by value until target ABI classification exists + +3. restricted c header imports + - 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