From e805af6ef640325b60b26d3ea4e89dd7ec7d74e0 Mon Sep 17 00:00:00 2001 From: dimgigov Date: Wed, 15 Jul 2026 16:16:54 +0300 Subject: [PATCH] docs: sync README and plans with v0.5.x features Document multi-instance closures, tuples, Iter HOF, diagnostics, and updated test targets. Refresh QUALITY_PLAN diagnosis and next-day backlog. --- README.md | 76 ++++++++++++++++++++++++++++++++++++++------ docs/BuildAndTest.md | 8 +++++ docs/QUALITY_PLAN.md | 23 +++++++------- docs/ROADMAP.md | 3 +- 4 files changed, 89 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index c4a0aaf..c9571b6 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,15 @@ ![Bux Language](bux-lang-01.jpeg) -> **Status:** v0.5.0 — Bootstrap compiler (`buxc`, Nim) and self-hosted compiler (`buxc2`, Bux) both compile `.bux` → C → native binary. -> **Selfhost loop:** `buxc2` compiles itself → binary-identical `buxc3` ✅ Deterministic C codegen + ELF verified. +> **Status:** v0.5.x — Bootstrap (`buxc`, Nim) and self-hosted (`buxc2`, Bux) both compile `.bux` → C → native binary. +> **Selfhost loop:** deterministic C codegen + ELF verified. > **Gradual Ownership:** `@[Checked]` borrow checker, `@[Release]` zero-cost mode, `borrow &mut` expressions. +> **Closures:** multi-instance capturing closures via fat function pointers (`BuxFn { code, env }`) in both compilers. +> **Tuples:** `(T, U)` types and `.0`/`.1` field access (bootstrap + selfhost). > **Green Threads:** M:N scheduler with channels (Go-style goroutines without GC). -> **All 26 examples pass.** Compiler successfully parses all 3 real-world apps (`apps/boko-framework`, `apps/jwt-pitbul`, `apps/nexus`). +> **Examples:** 40+ programs pass (`make test-examples`). Apps: `boko-framework`, `jwt-pitbul`, `nexus`, `simpledb`. -Bux is a fast, compiled, strongly-typed systems programming language. Features a C backend for native code generation, raw multi-line strings, gradual ownership (opt-in borrow checking), async/await, generics, algebraic enums, and a package manager. +Bux is a fast, compiled, strongly-typed systems programming language. Features a C backend for native code generation, raw multi-line strings, gradual ownership (opt-in borrow checking), multi-instance closures, async/await, generics, algebraic enums, and a package manager. --- @@ -185,22 +187,55 @@ func Main() -> int { } ``` +### Multi-instance closures +```bux +func MakeAdder(base: int) -> func(int) -> int { + return |a: int| -> int { return a + base; }; +} + +func Main() -> int { + let a10 = MakeAdder(10); + let a20 = MakeAdder(20); + // Independent capture environments + PrintInt(a10(1)); // 11 + PrintInt(a20(1)); // 21 + return 0; +} +``` + +### Iter map / filter / fold +```bux +import Std::Iter::{Array_Iter, Iter_MapInt, Iter_FilterInt, Iter_FoldInt}; + +func Main() -> int { + var nums: Array = Array_New(4); + Array_Push(&nums, 1); + Array_Push(&nums, 2); + Array_Push(&nums, 3); + let it = Array_Iter(&nums); + let doubled = Iter_MapInt(&it, |x: int| -> int { return x * 2; }); + return 0; +} +``` + --- ## Features | Feature | Status | |---------|--------| -| **Types** | Primitives, pointers, slices, tuples, structs, enums, unions | +| **Types** | Primitives, pointers, slices, tuples `(T,U)` + `.0`/`.1`, structs, enums, unions | | **Generics** | Generic functions (monomorphization) | | **Algebraic Enums** | Enums with data (`Result`, `Option`) | | **Pattern Matching** | `match` with guards | | **Methods** | `extend` blocks for struct methods | | **Interfaces** | `interface` + `extend` for trait-like behavior | -| **Error Handling** | `Result`, `Option`, and the `?` operator | -| **Standard Library** | `Io`, `Array`, `String`, `Map`, `Fs`, `Mem`, `Set`, `Path`, `Math`, `Task`, `Channel`, `Sync`, `Os`, `Time`, `Process` | +| **Error Handling** | `Result`/`Option`, `?`, `Expect`/`UnwrapOr`/`Or` helpers | +| **Closures** | Capture-less + capturing; **multi-instance** fat pointers (`BuxFn`) | +| **Function pointers** | `func(T) -> R` as fat values; named funcs via adapters | +| **Standard Library** | `Io`, `Array`, `String`, `Map`, `Set`, `Iter` (map/filter/fold), `Fs`, `Mem`, `Path`, `Math`, `Task`, `Channel`, `Sync`, `Os`, `Time`, `Process`, `Test`, … | | **Backend** | LIR → C transpiler (clean 3-address code, then gcc/clang) | -| **Strings** | Raw multi-line backtick strings (`...`), C-string interop | +| **Strings** | Raw multi-line backticks, `f"..."` interp (bootstrap), `ReplaceAll` / `IsBlank` / `Repeat` | | **Gradual Ownership** | `@[Checked]` + `@[Release]` + `@[Shared]` + `borrow &mut` / `borrow &` | | **Drop Trait** | Auto-drop for `@[Drop]` types (Array, Map, user-defined structs) | | **Green Threads** | M:N scheduler (ucontext + SIGVTALRM), work-stealing queues | @@ -210,7 +245,8 @@ func Main() -> int { | **Trait Bounds** | `func Max(a: T, b: T) -> T` | | **Package Manager** | `bux add`, `bux install`, `bux.lock`, path + git deps | | **Cross-Compilation** | `--target ` via clang (e.g. `aarch64-linux-gnu`) | -| **Tooling** | `bux new`, `bux build`, `bux run`, `bux test`, `bux check` | +| **Diagnostics** | Rust-style snippets, multi-char underlines, `= help:` hints | +| **Tooling** | `bux new/build/run/test/check/fmt`, LSP (`tools/lsp_server.nim` + `buxc check`) | --- @@ -255,12 +291,34 @@ bux/ --- +## Documentation + +| Doc | Description | +|-----|-------------| +| [`docs/LanguageRef.md`](docs/LanguageRef.md) | Language reference | +| [`docs/Stdlib.md`](docs/Stdlib.md) | Standard library API | +| [`docs/BuildAndTest.md`](docs/BuildAndTest.md) | Build, test, and tooling | +| [`docs/QUALITY_PLAN.md`](docs/QUALITY_PLAN.md) | Roadmap toward a “good” v1.0 | +| [`docs/ROADMAP.md`](docs/ROADMAP.md) | Feature status (constructs) | +| [`PLAN.md`](PLAN.md) | Long-form phase plan | + +--- + ## Build & Test ```bash # Build bootstrap compiler (Nim → C) make build +# Run all example programs +make test-examples + +# Golden diagnostic tests (Rust-style error format) +make test-errors + +# Full unit + example suite +make test + # Build self-hosted compiler (Bux → C → native) make selfhost diff --git a/docs/BuildAndTest.md b/docs/BuildAndTest.md index a27decc..be92294 100644 --- a/docs/BuildAndTest.md +++ b/docs/BuildAndTest.md @@ -129,12 +129,20 @@ Use `--target ` to cross-compile for a different platform. Bux generates ## Running Tests +### Example suite +```bash +make test-examples # all examples/ programs (40+) +make test-errors # golden Rust-style diagnostic output +``` + ### Compiler Tests ```bash make test ``` This runs: +- Example suite (`test-examples`) +- Error diagnostic goldens (`test-errors`) - Lexer unit tests - Parser unit tests - Semantic analysis unit tests diff --git a/docs/QUALITY_PLAN.md b/docs/QUALITY_PLAN.md index 599a105..deee9dc 100644 --- a/docs/QUALITY_PLAN.md +++ b/docs/QUALITY_PLAN.md @@ -1,7 +1,7 @@ # Bux — План към „добър“ език (v0.5 → v1.0) -> **Дата:** 2026-07-15 -> **Текущо:** v0.5.0 — selfhost loop, gradual ownership, green threads, 26+ examples ✅ +> **Дата:** 2026-07-15 (обновено вечерта) +> **Текущо:** v0.5.x — selfhost loop, gradual ownership, green threads, **40+ examples** ✅ > **Цел:** Език, с който се пишат реални проекти комфортно, безопасно (по избор) и с надежден toolchain. --- @@ -12,14 +12,14 @@ |------|-----------|--------| | Frontend (lex/parse) | Пълен Pratt parser, recovery | ★★★★☆ | | Sema / generics | Monomorphization, trait bounds basic | ★★★★☆ | -| HIR → C | Работи; tuples/func-ptr half-baked в bootstrap | ★★★☆☆ | -| Selfhost (`src/`) | ~12k LOC, binary-identical loop | ★★★★★ | +| HIR → C | Tuples + fat `func` ABI в bootstrap **и** selfhost | ★★★★☆ | +| Selfhost (`src/`) | ~12k LOC, binary-identical loop, closures+tuples | ★★★★★ | | Gradual ownership | `@[Checked]`, `&`/`&mut`, move, Drop | ★★★☆☆ (basic) | | Concurrency | M:N tasks + channels + async | ★★★★☆ | -| Stdlib | 25+ модула, но колекциите са минимални | ★★★☆☆ | -| Tooling | `new/build/run/test/fmt`, LSP prototype, VSCode | ★★☆☆☆ | +| Stdlib | Array/Map/Set/String/Iter HOF разширени | ★★★★☆ | +| Tooling | `test-errors`, LSP diagnostics via `buxc check` | ★★★☆☆ | | Ecosystem / registry | path+git deps; няма централен registry | ★☆☆☆☆ | -| Документация | Има, но drift (PLAN vs README версии) | ★★★☆☆ | +| Документация | README + QUALITY_PLAN синхронизирани (2026-07-15) | ★★★★☆ | **Силна ниша:** gradual ownership (C-скорост на писане + opt-in Rust-safety). **Слабо място:** ergonomics на stdlib + maturity на tooling + пълнота на borrow checker. @@ -40,7 +40,7 @@ ## Фази -### A — Ergonomics & Stdlib (P0, сега) 🔄 +### A — Ergonomics & Stdlib (P0) ✅ (core done) | # | Задача | Защо | Статус | |---|--------|------|--------| @@ -57,10 +57,11 @@ |---|--------|------|--------| | B.1 | Proper tuple types в C backend | `(T,U)` → `Tuple_T_U` struct + `.0`/`.1` | ✅ bootstrap + selfhost | | B.2 | Function pointer types | `func(T)->U` fat ABI | ✅ bootstrap + selfhost | -| B.3 | Match expression до край в C (не `return "0"`) | Expression-context match | -| B.4 | Closures: multi-instance + loop/return в body | Реални higher-order callbacks | +| B.3 | Match expression до край в C (не `return "0"`) | Expression-context match | ⏳ | +| B.4 | Closures multi-instance | Fat `BuxFn` + heap env | ✅ bootstrap + selfhost | +| B.4b | Closures: loop/return edge cases in body | По-сложни body control-flow | ⏳ | | B.5 | По-добри diagnostics (snippet + hint) | DX #1 за нови потребители | ✅ | -| B.6 | Bootstrap ↔ selfhost feature parity | Operator overloading, string interp и в selfhost | +| B.6 | Bootstrap ↔ selfhost feature parity | Tuples/closures done; string interp / ops still bootstrap-heavy | 🔄 | ### C — Gradual Ownership 2.0 (P1) diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 783d612..d46c5c1 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,6 +1,7 @@ # Bux Language Roadmap — New Constructs -> **Updated:** 2026-06-09 | **Status:** In Progress +> **Updated:** 2026-07-15 | **Status:** In Progress +> Recent: multi-instance closures (fat `BuxFn`), tuples in selfhost, Iter map/filter/fold, Rust-style diagnostics. This document tracks planned language constructs beyond Phase 8 strategy.