# Dino language spec (draft) Goal: Go-like simplicity, C++/Rust speed, no GC, no low-level syntax. Targets: game dev, CLI tools, desktop apps. ## Decisions - **Methods**: declared inside the struct body. Fields are accessed directly (`self` available for the whole value). No receiver, no `mut` keyword: the compiler infers whether a method mutates. - **Variables**: `var x = 1` creates a changeable variable (type inferred; `var x: int = 1` with a type). `x = 2` changes it. `const X = 1` is fixed. - **Types are written after a colon**, everywhere: `var x: int = 1`, `func area(w: float, h: float): float`, `struct User { name: string, age: int }`, enum data `Circle(r: float)`, generic bounds `[T: Ordered]`, several results `func f(): (int, error)`. Names in a row share a type: `(a, b: int)`, `x, y: float`. Without a colon the compiler explains what to add. - **Sized numbers**: `i8 i16 i32 u8 u16 u32 u64 f32`; `i64` is `int` and `f64` is `float` (same type). A number literal takes the type asked for (`var x: u8 = 200`, `b + 1`, `[1, 2]` as `[]u8`) and a literal that doesn't fit is an error. Different number types never mix: convert with `u8(x)`, `f32(x)`, `int(x)`, ... Integers wrap around on overflow; float to integer stops at the nearest end (NaN is 0). Dividing by zero panics. Unsigned values can't be negated. `f32` prints the shortest text that reads back the same. - **Sharing**: `shared T` (reference counted), `weak T` (non-owning). Everything else is plain ownership, inferred by the compiler. - **Errors**: Go-style `(value, error)` returns, with `?` to propagate. - **Missing values**: `T?` with `nil`. Compiler requires a nil check before use. - **Strings**: interpolation with `"Hello {name}"`; literal brace is `\{`. - **Visibility**: private by default, `pub` makes it public. - **Loops**: `for` only: `for i in 0..10`, `for x in items`, `for cond { }`, `for { }` (infinite), with `step` for strides. No C-style three-part loop. - **Numbers**: `int` (64-bit) and `float` (64-bit) for everyday code; sized types `i8 i16 i32 i64 u8 u16 u32 u64 f32 f64` when exact control is needed. `var a = 42` is `int`, `var b = 3.14` is `float`. - **print**: `print(a, b, c)` writes values separated by spaces, then a newline. - **Conversions**: no implicit int/float mixing, except that an integer literal fits a float (`var x: float = 1`, `x * 2`). Use `int(x)` / `float(x)`. - **Integer overflow** wraps around; `/` and `%` by zero panic (exit code 2). - **Evaluation order** is left to right, always (arguments, `&&`/`||` short-circuit). - **Top-level `const`** may not call functions; uses are replaced by the value. - **Structs are values**: `var b = a` copies; passing to a function copies. Methods go inside the struct and see fields directly; `self` is the whole value. Inside a method, a name resolves as: local/parameter, then field, then method of the same struct (call it bare: `update(dt)`), then global function/const. - **Mutation is inferred**: a method that assigns to a field (or calls a mutating method on `self`) is mutating. Mutating methods can't be called on a `const` or on a temporary like `make().update()`. - **Struct literals**: positional `Vec2{1, 2}` needs every field; named `Player{name: "A"}` may leave fields out (they start at zero: 0, 0.0, false, ""). Initializers run in the order written. - **Printing a struct** shows `Vec2{x: 1.0, y: 2.0}`. `==` on structs is not allowed yet; compare fields. - **Lists** `[]T`: `[1, 2, 3]`, `var xs: []int` (empty), `xs[i]`, `xs[i] = v`, `xs.len()`, `xs.push(v)`, `xs.pop()`, `xs[1..3]` (a copy), `for x in xs`, `for i, x in xs`. Lists are values: `var b = a` and passing to a function copy. A function that never changes a list parameter gets it without a copy (the compiler works this out); returning a local list moves it. Looping walks the list as it was when the loop started. `print` shows `[1, 2]`. Out-of-range index/slice and `pop()` on an empty list panic (exit code 2). `s.len()` on a string is its length in bytes. - **Enums** carry data per case: `enum Shape { Circle(r float) Rect(w, h float) Point }`, with methods inside, like structs. Build a value with the qualified name: `Shape.Circle(2.0)`, `Shape.Point`. Enums are values (copied like structs); a case may hold lists. The zero value is the first case. Printing shows `Shape.Circle(2.0)`. `==` works on enums whose cases carry no data. An enum can't contain itself directly, but may hold a list of itself. - **match** is exhaustive: missing cases are a compile error (the message lists them); `_` covers the rest. Works on enums, int, bool, string. Patterns: `Circle(r)`, `Rect(w, _)`, `Point`, `Shape.Point`, literals, `_`, or a lowercase name that takes the whole value. A capitalized name that isn't a case is an error (never a silent catch-all). Nested patterns come later. As a statement, arms may be blocks (and may `break`/`continue`/`return`). As a value (`var x = match ...`, `return match ...`), every arm is a single expression, or a lone `return`/`break`/`continue`. Arms of a value `match` must have the same type. - **Errors**: `error` is a built-in type: nil (no error) or a message. Make one with `error("msg {x}")`; print it or use it in `"{err}"` (nil prints `nil`). A function may return several values: `func f(): (int, error)`; take them with `var n, err = f()` (`_` throws one away). `return v, nil` or the shorthand `return error("x")` (zero values are filled in). The error ignored by a bare `f()` statement is a compile error. `call()?` passes the error up: on error the enclosing function returns it (zero values for the rest), otherwise `?` gives the value. Needs a function whose last result is `error`; works on `(T, error)` and `error` calls. `func main(): error` is allowed: an error prints `error: msg` to stderr, exit code 1. - **Optionals**: `T?` holds a `T` or `nil`. A `T` converts to `T?` implicitly. Compare with `x == nil` / `x != nil`. To use the value, check first: the compiler knows `x` is set inside `if x != nil { }`, after `if x == nil { return }` (or break/continue), and on the right of `x != nil &&` / `x == nil ||`. Assigning to `x` forgets that. (Reads are also checked at runtime, so it can never go wrong.) Not yet: `T?` as a struct field / enum data / list element, `??`, `x!`, `match` on nil, `?` on optionals. - **Last use moves**: `var b = a` copies `a`, unless `a` is never used again (and no loop is in the way): then `b` takes the value and nothing is copied (`src/moves.rs`). - **Generic functions**: `func max[T: Ordered](a, b: T): T`. The types are worked out from the arguments (`max(3, 9)`, `first(["a"])`; bare number literals become `int`, or `float` if any is a float); there is no `max[int](...)` yet. Each set of types gets its own compiled copy, so generics cost nothing at runtime. Rules after the colon: `Ordered` (numbers and strings) and `Number`; no rule means anything goes, and a mistake then shows up when the copy is checked (the message names the types). A generic function that is never used is not checked. A generic function needs a parameter that mentions its type. - **Interfaces** are rules for generics, Go-style: no `implements`. A type follows an interface just by having its methods with the same parameters and result: `interface Shape { area(): float name(): string }`, then `func show[T: Shape](s: T)` (also `struct Gallery[T: Shape]`, `[T: m.Shape]` from another file). A type that doesn't gets a message naming the missing or different method. Generic code may call the methods the interface lists even if they are private in another file. - **Interface values**: an interface is also a type: `var s: Shape = Circle{2.0}`, `[]Shape`, `func f(s: Shape)`, struct fields, results. A struct or enum value with the right methods converts automatically (the value is copied into the interface value), and `s.area()` calls the method of whatever is inside. Interface values are values like any other: `var t = s` copies the inside, and a method that changes the value (`s.scale(2.0)`) changes only that variable's copy. `nil` is the empty interface value (`s == nil`); calling a method on it panics (exit code 2). A list can mix types: `var xs: []Shape = [Circle{1.0}, Rect{2.0, 3.0}]`. Printing shows the value inside. Not yet: turning an interface value back into its type, one interface value used as another interface, interfaces with type parameters. Interfaces can't take type parameters yet. - **Generic structs and enums**: `struct Stack[T] { items: []T func push_item(x: T) { items.push(x) } }`, `enum Maybe[T] { Some(value: T) None }`. Use them with the types written out: `Stack[int]{}`, `var s: Stack[string]`, `Pair[string, float]{"pi", 3.14}`, `Maybe[int].Some(3)`, `func f(): Maybe[int]`, and from another file `m.Stack[int]{}`. The types are never guessed (`Stack{}` is an error). Like functions, each list of types becomes its own type (`Stack[int]` prints with its types), rules `[T: Number]` work, and they may contain themselves through lists (`kids: []Tree[T]`). A capitalized name followed by `[types]` and then `{` or `.` is read as a generic type, anything else as indexing. A generic type that is never used is not checked. - **Shared values**: `var tex = shared Texture{...}` makes one value with a counter. `var b = a`, passing it, putting it in a list or a struct field all give another owner (no copy of the value); the value is freed when the last owner goes. Use it like the thing inside: `tex.name`, `tex.touch()`, `tex.uses = 1`, `match light { ... }`. A change through any owner is seen by all. Only structs and enums can be shared for now. Written as a type: `shared Texture`. A shared value is not copied by `var b = a`, so two owners really are one value. - **Weak pointers**: `weak win` gives a non-owning pointer to a shared value (type `weak Window`; `weak Window?` means the same). It doesn't keep the value alive, so a window and its buttons can point at each other without leaking (the button's side is `weak`). `w == nil` / `w != nil` tell whether the value is still there; using a weak pointer whose value is gone (or that was never set) panics with a clear message (exit code 2). A weak pointer starts as `nil` (`Button{label: "x"}`) and can be assigned `nil`. To use the value as an owner, `w.upgrade()` gives a `shared T?`: the shared value (now with one more owner, so it stays alive while you hold it) or `nil` if it is gone. Not yet: `==` between shared values (identity), shared lists/strings/numbers. - **Function values and closures**: the type is `func(int, string): bool` (no `: result` means nothing is returned). Write one as `func(x: int): int { return x + 1 }`, or short as `x => x + 1` / `(a, b) => a + b` where the types are known from the place it is used (a parameter, a typed variable, a return, a struct field) or, for a generic function, from its other arguments (`map(nums, x => x * 2)`). A top-level function is a value too: `apply(double, 4)`. Call a function value like a function: `f(3)`, `b.on_click(name)`, `make()(3)`. A closure **copies** the variables it uses when it is made and keeps its own copies (so it can count: `n += 1` inside changes only its copy, which persists between calls). Copying a closure (`var g = f`, passing it) copies its state too. Calling a function value counts as changing it, like a method that changes `self`. A function value that was never set panics when called (exit code 2). Not yet: closures with block bodies in short form, methods as values, several results from a function value, `==` on functions. - **Memory**: no GC, nothing to write. Every value has exactly one owner and is freed when its owner's block ends (also on early `return`, `break`, `continue` and `?`). Lists, structs, enums, optionals, errors and strings all follow this. Assigning or passing a variable copies it (`var b = a`); a fresh value (a call result, a literal) or a returned local moves without copying. Strings are immutable and counted, so copying one only bumps a counter; literals are never freed. A parameter that the function doesn't change is passed by address, so passing lists around costs nothing. Every test program runs under the address sanitizer, so a leak, double free or use after free fails the test. - **Imports**: `import os` (built-in) or `import utils` (the file `utils.dino` next to the main file; `import tools.fs` is `tools/fs.dino`, used as `fs.name`). Use things as `utils.double(2)`, `utils.Vec2{1.0, 2.0}`, `utils.Shape.Circle(1.0)`, `utils.SCALE`, and `utils.Vec2` in types. Only `pub` functions, consts, types, methods and fields can be used from another file (fields are private too unless written `pub x: int`). Each file has its own imports and its own names, so two files may both define `f`. Import cycles and missing files are errors; errors point at the file they are in. Names of module types print with the module (`utils.Vec2{...}`). Importing a C library (`import c "x.h"`) is not supported yet. - **Built-in modules**: `os` (`read_file write_file append_file exists exit env read_line`, and the value `args`), `math` (`sqrt pow floor ceil round trunc sin cos tan asin acos atan atan2 exp log log10 hypot min max abs PI E`), `time` (`now sleep`). Text has methods: `upper lower trim split lines fields replace repeat contains starts_with ends_with index_of to_int to_float`; `[]string` has `join`. - **Maps** `map[K, V]`: `{"a": 1}` (types guessed), `map[string, int]{}` or `var m: map[string, int] = {}` (empty). Keys: int/whole-number types, string, bool. Values: anything except `T?`. `m[k] = v` adds or replaces, `m[k]` panics if the key is missing, `m[k] += 1` treats a missing key as zero, methods `has get get_or remove keys values len`, `for k, v in m` / `for k in m`. Entries keep insertion order (hash index + ordered arrays; `remove` is O(n)). Maps are values (`var b = a` copies). Not yet: `==`, generic `map[K,V]` params. - **Docs**: `docs/` holds learner notes in markdown; a test compiles and runs every example in them. - **Characters** `char`: one Unicode character, `'a'` `'\n'` `'é'` (escapes `\n \t \r \0 \\ \' \"`). Compare with `== != < > <= >=`, `match` on them (`'+' => ...`), use as map keys; no arithmetic (`int(c)`, `char(n)`). `string(x)` (or `"{c}"`) makes text. `for c in s` / `for i, c in s` walk characters (`i` = byte position, invalid UTF-8 comes out as U+FFFD). `s[i]` is the character starting at byte `i` (panics out of range or in the middle of a character); strings can't be assigned to. Methods `is_digit is_letter is_alnum is_space is_upper is_lower upper lower` (ASCII plus Latin-1 letters). Not yet: `s.chars()`, `[]char`→string. - **Formatter** `dino fmt [--check] ..` (`src/fmt.rs`): text based, so comments and blank lines survive. 4-space indent, spaces around binary operators and after `,` `:`, tight `Point{...}` / map literals and `[]T`, at most one blank line, trailing `//` comments of neighbouring lines aligned. It never moves line breaks (a one-line block stays one line), indents continuation lines (after an operator, or inside open brackets) one level, and verifies that the token stream is unchanged before writing. `examples/` must stay formatted (a test checks). - **Editor support** (`editors/`): `dino lsp` is a language server (`src/lsp.rs`, own JSON in `src/json.rs`, no dependencies): full-text sync, error diagnostics from the real checker (imports read from disk or from open buffers; errors in other files shown at the top of the importing file; UTF-16 columns), whole-file formatting. `editors/vscode` (extension + TextMate grammar), `editors/vim` (syntax), `editors/README.md` (Neovim, Helix, others). Not yet: hover, go to definition, completion, rename; the compiler reports only the first error. - **String slicing**: `s[a..b]`, `s[a..]`, `s[..b]` (byte positions, bounds checked; panics with "the length is N"). - **Running**: `dino run file.dino a b c` passes `a b c` to the program (`os.args`). - **Example**: `examples/calc/` is a multi-file calculator (tokenizer, parser, evaluator, shared scope); `session.txt` / `session.out` are checked by a test. ## Open questions - Braces vs indentation (currently braces, no semicolons) - Concurrency details ## Status Working: functions, int/float/bool/string, var/const, if/else, for (infinite, while, range with step, over lists), break/continue, string interpolation, print, structs with methods (value semantics, inferred mutation), lists (value semantics, bounds checked), enums with data + exhaustive match, errors (`error`, multi-value returns, `?`), optionals (`T?`, `nil`, narrowing), `dino run`. Not yet: nested match patterns, `==` on lists/structs, top-level const lists. These give a clear "not supported yet" error. Known gaps: memory is only freed on normal exits (a panic just ends the program).