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,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)`