flan/docs/overview.md

Overview — superseded

This was the first brainstorm. It is kept for history and is no longer accurate. Read instead:

• plan.org — the design, the build sequence, and the open decisions
• spec-memory.md — ownership, containers, places, generics, function values
• spec-conditions.md — conditions and restarts, operational semantics
• sand.flan — the first acceptance program
• syntax-sketch.flan — the syntax, annotated with the decisions above

What changed since

This document said	Now
"C-like with Roc syntax"	S-expressions, Clojure's brackets; C's value model
"Start with interpreter, output C later"	Frontend → typed IR → LLVM IR as text → clang. An interpreter is acceptable for milestone 2 only
"lists, slice, fixed-length array, matrices"	Four container types, distinct ownership: [n T], [T], (Vec T), (Map K V) — see spec-memory.md
arr[4], arr[1..] index syntax	(at a i), (as-slice a lo hi) — no infix, no bracket indexing
const by default?	Locals are assignable places; parameters are not; const qualifies slices and pointers
Rust-style iterator chains ending in .collect()	->> threading over slices; every collecting operation allocates from an explicit allocator, usually the frame arena
Ptr a	Kept, as (Ptr a). Cross-references use (Handle a) instead
option/result in the stdlib	Kept, and layered with conditions — see plan.org "Error handling, layered"

Original text

Concepts:

- Primitives
  - u8, i32, f32, bool, char
  - lists, slice, fixed-length array builtin, matrices
- Control flow
  - for, while, break
- Structs & tuples
- Let bindings
- `Ptr a`
- Pattern matching
- ADTs
- Mutability
  - const by default?
- Functions
- Array syntax
  - ranges `arr[1..]`, `arr[..3]`
  - index `arr[4]`
- Stdlib
  - string
  - vec/dynarray
  - hashtable
  - option/result

C-like with Roc syntax.
Start with interpreter. Output C later down the track