Docs for Finch 2.0: beginners, technicians, engineers (en, pl); READMEs; raylib example

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 08:54:25 +00:00 · 2026-10-08 19:20:46 +02:00 · 2026-10-08 19:20:46 +02:00 · 3e55da2645
commit 3e55da2645
parent c7ddd4d8b6
13 changed files with 2590 additions and 2140 deletions
--- a/README.md
+++ b/README.md
@ -25,19 +25,24 @@ fn main() {
 ## Why Finch

 - **Simple.** No semicolons, no headers, no preprocessor. Each thing has one way to do it.
- **Fast.** It compiles through LLVM's `-O2` pipeline to native code, with no runtime or garbage collector.
-  Recursive `fib(40)` runs in about 0.19 s (`clang -O2` on the same C: about 0.23 s).
- **Safer than C, where it is cheap.** No silent narrowing and no signed/unsigned mixing. Division by zero
-  and null `.value` stop with a clear runtime error instead of undefined behavior. Operator precedence
-  that does not bite (`x & 1 == 0` means what it says).
+- **Fast.** It compiles through LLVM's `-O2` pipeline to native code, with no garbage collector.
+  Recursive `fib(40)` runs in about 0.19 s (`clang -O2` on the same C: about 0.23 s); bounds-checked
+  array code matches C.
+- **Memory without the pain.** Lists, text and structs are values: assigning copies, and the end of a
+  block frees them. There is no `free` to forget, no use-after-free, and every test is clean under valgrind.
+- **Safer than C, where it is cheap.** No silent narrowing and no signed/unsigned mixing. Out-of-range
+  indexes, division by zero and null pointers stop with a clear runtime error instead of undefined behavior.
+  Operator precedence that does not bite (`x & 1 == 0` means what it says).
 - **Errors that talk like a person:**
  ```
  game.fn:3:13: error: 'y' must be i32, but this is int (use i32(...) to convert)
      3 |     i32 y = x
        |             ^
  ```
- **Any C library, directly.** `import "GLFW/glfw3.h"` + `link "glfw"`, and you can call it.
-  Headers are read by libclang, so there is nothing to declare by hand.
+- **Any C library, directly.** `import "raylib.h"` + `link "raylib"`, and you can call it, structs by value
+  and callbacks included. Headers are read by libclang, so there is nothing to declare by hand.
+- **Written in itself, too.** `boot/` is a Finch compiler written in Finch that compiles itself to a
+  byte-identical result.

 ## Quick start

@ -52,7 +57,8 @@ ninja -C build

 ./build/finch run examples/hello.fn
 ./build/finch build examples/tour.fn -o tour && ./tour
-tests/run.sh                        # 34 passed, 0 failed
+tests/run.sh                        # 58 passed, 0 failed
+tests/boot.sh                       # the compiler written in Finch builds itself
 ```

 ## Documentation
@ -70,14 +76,17 @@ Pick the guide that fits you:
 | | |
 |---|---|
 | Variables | `x := 5` (inferred) or `int x = 5` |
-| Types | `int` `float` `bool` `char` `str`, sized `i8`…`i64` `u8`…`u64` `f32` `f64`, pointers `ptr[T]` / `ptr` |
+| Types | `int` `float` `bool` `char` `str`, sized `i8`…`i64` `u8`…`u64` `f32` `f64`, arrays `[]T`, pointers `ptr[T]` |
 | Functions | `fn add(int a, int b) -> int { return a + b }` |
-| Control | `if` / `else if` / `else`, `while`, `for i in 0..10`, `break`, `continue` |
-| Pointers | `p := addr(x)`, `p.value = 5`, `null` |
-| Conversions | `int(3.9)`, `u8(x)`, `float(n)` (implicit only when nothing is lost) |
-| Operators | `+ - * / %`, `& \| ^ << >> ~`, `== != < <= > >=`, `&& \|\| !` |
-| C interop | `import "stdio.h"`, `link "glfw"` |
-| Output | `print(a, b, c)` prints anything, separated by spaces |
+| Structs | `struct Point { … }` with one field per line (`int x`, `int y = 0`); create with `Point(1, 2)` or `Point(x: 1)` |
+| Arrays | `nums := [1, 2, 3]`, `nums.push(4)`, `nums[0]`, `nums.len`, `for n in nums { }` |
+| Text | `"a" + "b"`, `str(42)`, `int("42")`, `s.split(",")`, `s.upper()`, `s[0]` |
+| Control | `if` / `else if` / `else`, `while`, `for i in 0..10`, `break`, `continue`, `defer` |
+| Memory | automatic for arrays, text and structs; `new(...)` / `free(...)` for your own heap structures |
+| Modules | `import shapes` → `shapes.area(b)` |
+| C interop | `import "stdio.h"`, `link "glfw"`, `link "mine.c"`, `addr(fn)` for callbacks |
+| I/O | `print(...)`, `input("? ")`, `read_file`, `write_file`, `shell` |
+| Tools | `finch run/build/ir`, `-g` for gdb, `-O0` |

 ## Examples

@ -85,32 +94,42 @@ Pick the guide that fits you:
 |---|---|
 | [`examples/hello.fn`](examples/hello.fn) | the smallest program |
 | [`examples/tour.fn`](examples/tour.fn) | variables, functions, conditions, loops |
+| [`examples/guess.fn`](examples/guess.fn) | a guessing game: input, loops, C's `rand` |
+| [`examples/todo.fn`](examples/todo.fn) | structs, arrays, strings and files |
+| [`examples/structs.fn`](examples/structs.fn) | structs, arrays of structs, a linked list with `new`/`free` |
 | [`examples/types.fn`](examples/types.fn) | sized numbers and pointers |
 | [`examples/c_import.fn`](examples/c_import.fn) | `printf`, `math.h`, `malloc`/`free`, `stderr` |
 | [`examples/window.fn`](examples/window.fn) | a GLFW + OpenGL window |
+| [`examples/raylib.fn`](examples/raylib.fn) | raylib with C structs by value |
 | [`examples/llvm.fn`](examples/llvm.fn) | Finch building LLVM IR through the LLVM-C API |
+| [`boot/`](boot/) | the Finch compiler, written in Finch |

 ## Roadmap

 - [x] Lexer, parser, LLVM codegen, O2 optimization
 - [x] Types incl. sized integers, pointers, conversions; functions; `if`/`while`/`for`
- [x] Readable compile errors; runtime checks (division, null)
+- [x] Readable compile errors; runtime checks (division, null, bounds)
 - [x] Bitwise operators with sane precedence
 - [x] C headers through libclang; `link` with pkg-config; link-error advice
- [ ] `struct` (and C structs by value)
- [ ] Arrays/slices with `.len` and bounds checks
- [ ] Memory: automatic free at the end of the owning block, `defer`, manual `free` when wanted
- [ ] Strings: `+`, `len`, `str(x)`; `input()`
- [ ] Finch modules (`import math`)
- [ ] Debug info (DWARF)
- [ ] Bootstrap: the Finch compiler written in Finch
+- [x] `struct`, including C structs by value (System V ABI) and callbacks
+- [x] Arrays with `.len`, bounds checks and methods; `for x in list`
+- [x] Memory: values freed at the end of their block, `defer`, `new`/`free`
+- [x] Strings: `+`, `.len`, indexing, methods, `str(x)`, `int(s)`; `input()`; files
+- [x] Finch modules (`import name`)
+- [x] Debug info (`-g`)
+- [x] Bootstrap: a Finch compiler written in Finch that builds itself
+- [ ] Methods on structs, maps, `match`
+- [ ] Error values instead of stopping the program
+- [ ] More platforms (ARM64, macOS)

 ## Layout

 ```
-src/        compiler: lexer, parser, AST, codegen, C import, driver (C++17, ~2.4k lines)
+src/        compiler: lexer, parser, AST, codegen, C import + ABI, driver (C++17, ~4.5k lines)
+runtime/    the small C runtime linked into every program
+boot/       the Finch compiler written in Finch (~3k lines)
 examples/   example programs
-tests/      run/ (golden output), fail/ (expected errors), run.sh
+tests/      run/ (golden output), fail/ (expected errors), run.sh, boot.sh
 docs/       en/ and pl/ guides for three audiences
 ```