feat: Std::String, Std::Map, Result/Option, ? operator, sizeof fix, docs

Add standard library modules: - Std::String: strlen, strcmp, concat, copy, starts_with wrappers - Std::Map: linear-probing hash map with String keys, int values Add error handling: - Result and Option algebraic enum examples - ? try operator for automatic error propagation in HIR lowering Compiler bugfixes: - Fix sizeof() for user-defined structs (new hSizeOf HIR node) - Fix HIR type lowering for char8, bool8, int8, uint8, etc. - Fix let statement lowering for pointer types (*char8 → int* bug) - Fix PrintInt ABI mismatch (int64_t → int in io.c) - Fix Makefile test bug (_test_tmp_pkg already exists) Documentation: - Rewrite README.md with features, examples, project structure - Add docs/LanguageRef.md — complete language reference - Add docs/Stdlib.md — standard library documentation - Add docs/BuildAndTest.md — build and test guide New examples: strings, map, result_option, try_operator (13 total)
2026-05-31 10:15:44 +03:00
parent e328af6eee
commit 7ee6a73ea4
22 changed files with 1475 additions and 55 deletions
@@ -0,0 +1,190 @@
+# Build and Test Guide
+
+This guide covers building the Bux bootstrap compiler, creating projects, and running tests.
+
+---
+
+## Prerequisites
+
+- **Nim** (1.6+) — for building the bootstrap compiler
+- **C compiler** (`gcc`, `clang`, or `cc`) — for the C backend
+- **Make**
+
+On Debian/Ubuntu:
+```bash
+sudo apt-get install nim gcc make
+```
+
+On macOS:
+```bash
+brew install nim gcc make
+```
+
+---
+
+## Building the Compiler
+
+```bash
+# Release build
+make build
+
+# Development build (no optimizations, faster compile)
+make dev
+```
+
+The output is a single binary: `buxc`.
+
+---
+
+## Creating a Project
+
+```bash
+# Create a new package in a new directory
+./buxc new myproject
+cd myproject
+```
+
+This generates:
+```
+myproject/
+├── bux.toml
+└── src/
+    └── Main.bux
+```
+
+### bux.toml
+
+```toml
+[Package]
+Name    = "myproject"
+Version = "0.1.0"
+Type    = "bin"
+
+[Build]
+Output = "Bin"
+```
+
+---
+
+## Building and Running
+
+```bash
+# Type-check without building
+./buxc check
+
+# Build
+./buxc build
+
+# Build and run
+./buxc run
+
+# Clean build artifacts
+./buxc clean
+```
+
+Build output goes to `build/` by default.
+
+---
+
+## Running Tests
+
+### Compiler Tests
+```bash
+make test
+```
+
+This runs:
+- Lexer unit tests
+- Parser unit tests
+- Semantic analysis unit tests
+- HIR lowering unit tests
+- Integration tests (`buxc new`, `buxc --version`)
+
+### Example Programs
+```bash
+make test-examples
+```
+
+Compiles and runs all programs in `examples/`.
+
+### Individual Example
+```bash
+mkdir -p examples_pkg/hello/src
+cp examples/hello.bux examples_pkg/hello/src/Main.bux
+# Create bux.toml manually or use `buxc new`
+cd examples_pkg/hello && ../../buxc run
+```
+
+---
+
+## Project Layout
+
+```
+bux/
+├── src/              # Bootstrap compiler source (Nim)
+│   ├── main.nim      # Entry point
+│   ├── cli.nim       # CLI commands
+│   ├── lexer.nim     # Tokenizer
+│   ├── parser.nim    # Parser
+│   ├── sema.nim      # Semantic analysis
+│   ├── hir.nim       # High-level IR
+│   ├── hir_lower.nim # AST → HIR lowering
+│   ├── c_backend.nim # HIR → C code generation
+│   └── ...
+├── stdlib/           # Standard library
+│   ├── Std/
+│   │   ├── Io.bux
+│   │   ├── Array.bux
+│   │   ├── String.bux
+│   │   └── Map.bux
+│   ├── runtime.c     # C runtime shim
+│   └── io.c          # C I/O functions
+├── examples/         # Example programs
+├── tests/            # Unit tests (Nim)
+├── docs/             # Documentation
+└── Makefile
+```
+
+---
+
+## Debugging
+
+### Verbose Output
+```bash
+./buxc build -v
+```
+
+### Inspecting Generated C
+```bash
+./buxc build
+cat build/main.c
+```
+
+### Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `stdlib directory not found` | `buxc` can't find `stdlib/` | Run from project root or set correct path |
+| `duplicate symbol 'bux_alloc'` | Multiple stdlib modules declare same extern | Only declare in one module |
+| `C compilation failed` | Generated C has errors | Check `build/main.c` for issues |
+
+---
+
+## Adding a New Example
+
+1. Create `examples/myexample.bux`
+2. Add `myexample` to `EXAMPLES` in `Makefile`
+3. Run `make test-examples`
+
+---
+
+## Development Workflow
+
+```bash
+# After making changes to the compiler:
+make build
+make test
+
+# If tests pass, run examples:
+make test-examples
+```
@@ -0,0 +1,413 @@
+# Bux Language Reference
+
+This document describes the Bux programming language as implemented by the bootstrap compiler.
+
+---
+
+## Table of Contents
+
+1. [Lexical Structure](#lexical-structure)
+2. [Types](#types)
+3. [Variables](#variables)
+4. [Functions](#functions)
+5. [Control Flow](#control-flow)
+6. [Structs](#structs)
+7. [Enums](#enums)
+8. [Pattern Matching](#pattern-matching)
+9. [Methods and Interfaces](#methods-and-interfaces)
+10. [Generics](#generics)
+11. [Error Handling](#error-handling)
+12. [Modules and Imports](#modules-and-imports)
+13. [Operators](#operators)
+
+---
+
+## Lexical Structure
+
+### Comments
+```bux
+// Single-line comment
+
+/*
+   Multi-line comment
+   /* Nested comments are supported */
+*/
+```
+
+### Identifiers
+Identifiers start with a letter or underscore, followed by letters, digits, or underscores.
+
+### Keywords
+```
+func, let, var, const, type, struct, enum, union, interface, extend
+module, import, pub, extern, if, else, while, do, loop, for, in
+break, continue, return, match, as, is, null, self, super, sizeof
+```
+
+### String Literals
+```bux
+"Hello"           // String (UTF-8)
+c8"Hello"         // *char8 (C string)
+c16"Hello"        // *char16
+c32"Hello"        // *char32
+```
+
+### Number Literals
+```bux
+42        // int
+3.14      // float64
+0x2A      // hex
+0o52      // octal
+0b101010  // binary
+32i8      // int8 literal
+1000u64   // uint64 literal
+```
+
+---
+
+## Types
+
+### Primitive Types
+
+| Type | Description |
+|------|-------------|
+| `int8`, `int16`, `int32`, `int64`, `int` | Signed integers |
+| `uint8`, `uint16`, `uint32`, `uint64`, `uint` | Unsigned integers |
+| `float32`, `float64` | Floating-point |
+| `bool`, `bool8`, `bool16`, `bool32` | Booleans |
+| `char8`, `char16`, `char32` | Characters |
+| `String` | C-compatible string (`const char*`) |
+
+### Composite Types
+
+```bux
+*T              // Pointer to T
+T[]             // Slice (unsized)
+T[N]            // Fixed-size array
+(T1, T2, T3)    // Tuple
+func(T1) -> T2  // Function type
+```
+
+### Structs
+```bux
+struct Point {
+    x: int;
+    y: int;
+}
+```
+
+### Enums
+```bux
+enum Color {
+    Red,
+    Green,
+    Blue
+}
+
+// Algebraic enum (tagged union)
+enum Result {
+    Ok(int),
+    Err(String)
+}
+```
+
+### Unions
+```bux
+union Bits {
+    asByte: uint8;
+    asInt: int32;
+}
+```
+
+---
+
+## Variables
+
+```bux
+let x: int = 42;       // Immutable
+var y: int = 10;       // Mutable
+y = 20;                // OK
+
+const MAX: int = 100;  // Compile-time constant
+```
+
+---
+
+## Functions
+
+```bux
+func Add(a: int, b: int) -> int {
+    return a + b;
+}
+
+// Extern C function
+extern func printf(fmt: *char8, ...);
+
+// Generic function
+func Min<T>(a: T, b: T) -> T {
+    if a < b {
+        return a;
+    }
+    return b;
+}
+```
+
+---
+
+## Control Flow
+
+### If / Else
+```bux
+if x > 0 {
+    PrintLine("positive");
+} else if x < 0 {
+    PrintLine("negative");
+} else {
+    PrintLine("zero");
+}
+```
+
+### Loops
+```bux
+while i < 10 {
+    i = i + 1;
+}
+
+do {
+    i = i + 1;
+} while i < 10;
+
+loop {
+    // Infinite loop
+    break;
+}
+
+for i in 0..10 {
+    // Range 0 to 9 (exclusive)
+}
+
+for i in 0..=10 {
+    // Range 0 to 10 (inclusive)
+}
+```
+
+### Break / Continue with Labels
+```bux
+outer: loop {
+    loop {
+        break outer;
+    }
+}
+```
+
+---
+
+## Structs
+
+```bux
+struct Rectangle {
+    width: int;
+    height: int;
+}
+
+func Main() -> int {
+    let rect: Rectangle = Rectangle { width: 10, height: 5 };
+    PrintInt(rect.width);
+    return 0;
+}
+```
+
+---
+
+## Enums
+
+### Simple Enums
+```bux
+enum Color { Red, Green, Blue }
+
+let c: Color = Color::Red;
+if c == Color::Red {
+    PrintLine("red");
+}
+```
+
+### Algebraic Enums
+```bux
+enum Result {
+    Ok(int),
+    Err(String)
+}
+
+func Main() -> int {
+    let r: Result = Result { tag: Result_Ok };
+    r.data.Ok_0 = 42;
+
+    if r.tag == Result_Ok {
+        PrintInt(r.data.Ok_0);
+    }
+    return 0;
+}
+```
+
+---
+
+## Pattern Matching
+
+```bux
+match opt {
+    Option::Some(value) => PrintInt(value),
+    Option::None => PrintLine("none")
+}
+```
+
+Supported patterns:
+- Wildcard: `_`
+- Literal: `42`, `"hello"`, `true`
+- Identifier: `name`
+- Range: `1..9`, `1..=9`
+- Enum destructuring: `Shape::Circle(r)`
+- Struct destructuring: `Point { x: 0, y: 0 }`
+- Tuple: `(a, b, c)`
+- Guard: `t if t < 0`
+
+---
+
+## Methods and Interfaces
+
+```bux
+struct Rectangle {
+    width: int;
+    height: int;
+}
+
+interface Drawable {
+    func Draw(self: Rectangle);
+}
+
+extend Rectangle for Drawable {
+    func Draw(self: Rectangle) {
+        PrintLine("Drawing rectangle");
+    }
+}
+
+// Or extend with standalone methods
+extend Rectangle {
+    func Area(self: Rectangle) -> int {
+        return self.width * self.height;
+    }
+}
+```
+
+---
+
+## Generics
+
+Generic functions are monomorphized at compile time:
+
+```bux
+func Swap<T>(a: *T, b: *T) {
+    let tmp: T = *a;
+    *a = *b;
+    *b = tmp;
+}
+
+func Main() -> int {
+    let x: int = 1;
+    let y: int = 2;
+    Swap<int>(&x, &y);
+    return 0;
+}
+```
+
+---
+
+## Error Handling
+
+### Result and Option Types
+```bux
+enum Result {
+    Ok(int),
+    Err(String)
+}
+
+enum Option {
+    Some(int),
+    None
+}
+```
+
+### The `?` Operator
+The `?` operator automatically propagates errors:
+
+```bux
+func Divide(a: int, b: int) -> Result {
+    if b == 0 {
+        return Result_NewErr("division by zero");
+    }
+    return Result_NewOk(a / b);
+}
+
+func Compute() -> Result {
+    let x: int = Divide(10, 2)?;  // If Err, returns immediately
+    let y: int = Divide(x, 5)?;
+    return Result_NewOk(y);
+}
+```
+
+`?` can be used on `Result` and `Option` types in any expression context.
+
+---
+
+## Modules and Imports
+
+```bux
+// Single import
+import Std::Io::PrintLine;
+
+// Multiple imports
+import Std::Io::{PrintLine, PrintInt};
+
+// Wildcard import
+import Std::Io::*;
+
+// Module declaration
+module MyModule;
+
+pub func PublicFunc() -> int {
+    return 42;
+}
+
+func PrivateFunc() -> int {
+    return 0;
+}
+```
+
+---
+
+## Operators
+
+### Arithmetic
+`+`, `-`, `*`, `/`, `%`, `**` (power)
+
+### Comparison
+`==`, `!=`, `<`, `<=`, `>`, `>=`
+
+### Logical
+`&&`, `||`, `!`
+
+### Bitwise
+`&`, `|`, `^`, `~`, `<<`, `>>`
+
+### Assignment
+`=`, `+=`, `-=`, `*=`, `/=`, `%=`, `&=`, `|=`, `^=`, `<<=`, `>>=`
+
+### Other
+- `as` — Cast: `expr as Type`
+- `is` — Type test: `expr is Type`
+- `?` — Try / error propagation: `expr?`
+- `&` — Address-of: `&var`
+- `*` — Dereference: `*ptr`
+- `::` — Path separator: `Module::Name`
+- `..` — Range (exclusive): `0..10`
+- `..=` — Range (inclusive): `0..=10`
+- `sizeof` — Size of type: `sizeof(Type)`
@@ -0,0 +1,176 @@
+# Bux Standard Library
+
+The Bux standard library provides core functionality for systems programming. It is intentionally minimal for the bootstrap phase and will grow as the language matures.
+
+---
+
+## Std::Io
+
+Basic input/output operations wrapping C stdio.
+
+### Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `PrintLine` | `func PrintLine(s: String)` | Print string with newline |
+| `Print` | `func Print(s: String)` | Print string without newline |
+| `PrintInt` | `func PrintInt(n: int)` | Print integer |
+| `PrintFloat` | `func PrintFloat(f: float64)` | Print float |
+| `PrintBool` | `func PrintBool(b: bool)` | Print boolean |
+| `ReadLine` | `func ReadLine() -> String` | Read line from stdin |
+
+### Example
+```bux
+import Std::Io::{PrintLine, PrintInt};
+
+func Main() -> int {
+    PrintLine("Hello, World!");
+    PrintInt(42);
+    return 0;
+}
+```
+
+---
+
+## Std::Array
+
+Dynamic array of integers (currently hardcoded for `int`).
+
+### Types
+
+```bux
+struct Array {
+    data: *int,
+    len: uint,
+    cap: uint,
+}
+```
+
+### Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `Array_New` | `func Array_New(cap: uint) -> Array` | Create new array with capacity |
+| `Array_Push` | `func Array_Push(arr: *Array, value: int)` | Append element |
+| `Array_Get` | `func Array_Get(arr: *Array, index: uint) -> int` | Get element at index |
+| `Array_Len` | `func Array_Len(arr: *Array) -> uint` | Get length |
+| `Array_Free` | `func Array_Free(arr: *Array)` | Free memory |
+
+### Example
+```bux
+import Std::Array::{Array, Array_New, Array_Push, Array_Get};
+
+func Main() -> int {
+    let arr: Array = Array_New(4);
+    Array_Push(&arr, 10);
+    Array_Push(&arr, 20);
+    PrintInt(Array_Get(&arr, 0));  // 10
+    Array_Free(&arr);
+    return 0;
+}
+```
+
+---
+
+## Std::String
+
+String manipulation utilities for the built-in `String` type (`const char*` in C).
+
+### Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `String_Len` | `func String_Len(s: String) -> uint` | Length of string (wraps `strlen`) |
+| `String_Eq` | `func String_Eq(a: String, b: String) -> bool` | Compare strings for equality |
+| `String_Concat` | `func String_Concat(a: String, b: String) -> String` | Concatenate two strings (allocates) |
+| `String_Copy` | `func String_Copy(s: String) -> String` | Copy string (allocates) |
+| `String_StartsWith` | `func String_StartsWith(s: String, prefix: String) -> bool` | Check prefix |
+
+### Example
+```bux
+import Std::String::{String_Len, String_Concat, String_Eq};
+
+func Main() -> int {
+    let hello: String = "Hello";
+    let world: String = "World";
+    let greeting: String = String_Concat(hello, ", ");
+    let full: String = String_Concat(greeting, world);
+    PrintLine(full);  // "Hello, World"
+    return 0;
+}
+```
+
+---
+
+## Std::Map
+
+Hash map with `String` keys and `int` values using linear probing.
+
+### Types
+
+```bux
+struct MapEntry {
+    key: String,
+    value: int,
+    occupied: bool,
+}
+
+struct Map {
+    entries: *MapEntry,
+    cap: uint,
+    len: uint,
+}
+```
+
+### Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `Map_New` | `func Map_New(cap: uint) -> Map` | Create new map with given capacity |
+| `Map_Set` | `func Map_Set(m: *Map, key: String, value: int)` | Insert or update key |
+| `Map_Get` | `func Map_Get(m: *Map, key: String) -> int` | Get value by key (0 if missing) |
+| `Map_Has` | `func Map_Has(m: *Map, key: String) -> bool` | Check if key exists |
+| `Map_Len` | `func Map_Len(m: *Map) -> uint` | Number of entries |
+| `Map_Free` | `func Map_Free(m: *Map)` | Free memory |
+
+### Example
+```bux
+import Std::Map::{Map, Map_New, Map_Set, Map_Get, Map_Has};
+
+func Main() -> int {
+    let m: Map = Map_New(16);
+    Map_Set(&m, "one", 1);
+    Map_Set(&m, "two", 2);
+    PrintInt(Map_Get(&m, "one"));   // 1
+    PrintInt(Map_Get(&m, "three")); // 0
+    Map_Free(&m);
+    return 0;
+}
+```
+
+---
+
+## Runtime Functions
+
+These C functions are provided by `runtime.c` and are available via `extern` declarations.
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `bux_alloc` | `func bux_alloc(size: uint) -> *void` | Allocate memory (wraps `malloc`) |
+| `bux_realloc` | `func bux_realloc(ptr: *void, size: uint) -> *void` | Reallocate memory |
+| `bux_free` | `func bux_free(ptr: *void)` | Free memory |
+| `bux_bounds_check` | `func bux_bounds_check(index: uint, len: uint)` | Panic on out-of-bounds |
+
+---
+
+## Future Modules
+
+Planned for future phases:
+
+- `Std::Result` — Generic `Result<T, E>` with `?` operator support
+- `Std::Option` — Generic `Option<T>`
+- `Std::Math` — `Sqrt`, `Pow`, `Min`, `Max`, `Abs`
+- `Std::Os` — `Args`, `Env`, `Exit`, `Cwd`
+- `Std::Fmt` — String formatting with interpolation
+- `Std::Iter` — Iterator trait and combinators
+- `Std::Task` / `Std::Channel` — Lightweight concurrency