36d9946 | plum | pyrossh

git clone https://git.pyrossh.dev/plum

A statically typed, imperative programming language inspired by rust, python

36d9946 — Peter John 2026-11-01T22:44:09+05:30

docs: README restructure - one owner per example/rule, types sections reordered

Files changed (1) hide show

README.md +58 -79

README.md CHANGED Viewed

@@ -18,8 +18,13 @@ import std/Seq
 error ParseError = BadNum | Negative       # a named error set
-struct Circle(r: Float)                    # small copy-semantics value type
+struct Circle(r: Float) =                  # small copy-semantics value type
+  fun area(self) -> Float =                # a method
+    self.r * self.r * 3.14
-record Rect(w: Float, h: Float)            # reference type
+record Rect(w: Float, h: Float) =          # reference type
+  fun area(self) -> Float =
+    self.w * self.h
 enum Shape =                               # a union: a Circle or a Rect
   | Circle
@@ -27,12 +32,7 @@ enum Shape =                               # a union: a Circle or a Rect
   SIDES_MAX = 4                            # associated constant: Shape.SIDES_MAX
-  fun area(self) -> Float =                # a method
-    match self
-      Circle(r) => r * r * 3.14
-      Rect(w, h) => w * h
-struct Vec2(x: Float, y: Float) =          # small copy-semantics value type
+struct Vec2(x: Float, y: Float) =
   ZERO = Vec2(x: 0.0, y: 0.0)              # Vec2.ZERO
   fun add(self, o: Vec2) -> Vec2 =         # `a + b` calls a.add(b)
@@ -76,9 +76,9 @@ test "glance"
 | declare with a type | `s: Shape := Circle(r: 2.0)` (only with `:=`, a value is required) |
 | a block | indent by 2 spaces, no braces |
 | group an expression | `{1 + 2} * 3` (braces; parentheses are for calls) |
-| a conditional expression | `if c then a else b` (there is no `?:` ternary) |
+| a conditional expression | `if c then a else b` (no `c ? a : b` ternary) |
 | loop | `while c`, `for x := range src`, `for i := range n` |
-| a union of types | `enum Shape = Circle \| Rectangle` |
+| a union of types | `enum Shape = Circle \| Rect` |
 | a small value type | `struct Vec2(x: Float, y: Float)` |
 | a record (reference type) | `record User(name: Str, age: Int)` |
 | a method / static / constant | `fun area(self)` / `fun origin()` / `NAME = expr` inside the type body |
@@ -329,11 +329,11 @@ fun draw(shape: Shape) =
     drawOther(shape)
 ```
-A bare member name narrows the value inside the branch, so the member's own fields and methods are available:
+A bare member name narrows the value inside the branch (see [Enums](#enums)):
 ```plum
 fun width(s: Shape) -> Float =
-  if Rectangle := s
+  if Rect := s
     s.w
   else
     0.0
@@ -389,24 +389,51 @@ fun sumAll(nums: ...Int) -> Int = # variadic param
   total
 ```
-A function without a return type returns `Unit`; the last expression of a body is its value. A call can name its arguments only for constructors (`Cat(name: "Whiskers", age: 3)`); functions take positional arguments.
+A function without a return type returns `Unit`; the last expression of a body is its value. Functions take positional arguments; only constructors can name them (see [Constructing values](#constructing-values)).
 ## Types: struct, record and enum
-`enum` is a union: a value that is one of several member types. `struct` and `record` are product types with named fields. A `struct` is a value type and a `record` is a reference type (see [`struct` and `record`](#struct-and-record)).
+`struct` and `record` are product types with named fields (a value type and a reference type); an `enum` is a union of member types. The other declaration forms are `error Name = A | B` ([Error handling](#error-handling)) and `primitive Name =` ([Constants, statics and `primitive`](#constants-statics-and-primitive)).
+### `struct` and `record`
+`struct` declares a small, copy-semantics value type (a vector, a color, a rectangle) that is flattened into wasm locals instead of being heap-allocated. `record` declares a reference type. Both are declared with named fields:
+```plum
+struct Vec2(x: Float, y: Float)
+struct Body(pos: Vec2, size: Vec2)  # a field may be another struct
+record User(name: Str, age: Int)
+```
+The header ends with `=` only when an indented body follows (methods, constants: see [Methods](#methods-self-and-field-access) and [Constants](#constants-statics-and-primitive)); `struct Vec2(x: Float, y: Float)` with no body has no `=`.
-The other declaration forms are `error Name = A | B` ([Error handling](#error-handling)) and `primitive Name =` ([Constants, statics and `primitive`](#constants-statics-and-primitive)).
+```plum
+a := Vec2(x: 1.0, y: 2.0)
+b := a
+b.x = 9.0          # a.x is still 1.0: a struct is copied
+u := User(name: "ann", age: 3)
+u2 := u
+u2.age = 4         # u.age is now 4: a record is a heap object, shared on assignment
+```
+A `struct` has no generics; its fields are only `Int`, `Float`, `Bool` or other structs, and a struct can't contain itself. Values are copied on assignment and when passed, and are boxed inside `T?` and other generic slots. <!-- arrays-of-structs note --> A `record` may have any field types and may be generic (`record Pair[K, V](key: K, val: V)`). Methods and `match` work as for any enum. See [`plum-examples/values.plum`](plum-examples/values.plum).
 ### Enums
-An `enum` lists the types it can hold. A member is a declared `struct` or `record`, a built-in (`Int`, `Float`, `Bool`, `Byte`), a std type (`Str`, `List[Json]`, `Map[Str, Json]`), or a bare name that is not a declared type, which becomes a payload-less tag. A short list fits on one line; a longer one, or one with methods, goes on indented `|` lines:
+An `enum` lists the types it can hold. A member is a declared `struct` or `record`, a built-in (`Int`, `Float`, `Bool`, `Byte`), a std type (`Str`, `List[Json]`, `Map[Str, Json]`), or a bare name that is not a declared type, which becomes a payload-less tag. A short list fits on one line; a longer one, or one with methods, goes on indented `|` lines. Every member other than a tag is an existing type, and the enum adds no new constructor for it:
 ```plum
-struct Circle(r: Float)
+struct Circle(r: Float) =
+  fun area(self) -> Float =
+    self.r * self.r * 3.14
-record Rectangle(w: Float, h: Float)
+record Rect(w: Float, h: Float) =
+  fun area(self) -> Float =
+    self.w * self.h
-enum Shape = Circle | Rectangle
+enum Shape = Circle | Rect
 enum Color =
   | Red
@@ -422,14 +449,12 @@ enum Json =
   | Map[Str, Json]
 ```
-Every member other than a tag is an existing type, and the enum adds no new constructor for it.
 A member converts to its enum wherever the enum is expected: an argument, a `return`, a tail expression, `push`, a `T?` or a `!T` slot. Nothing is written at the call site:
 ```plum
 fun make(big: Bool) -> Shape =
   if big
-    Rectangle(w: 10.0, h: 10.0)
+    Rect(w: 10.0, h: 10.0)
   else
     Circle(r: 1.0)
@@ -440,7 +465,7 @@ fun use() -> Str =
   label(2.5)
 ```
-A pattern names a member to take the value apart (`Circle(r)`) or, written as just the member's name, to narrow the subject to that type. In an arm that names `Float`, the subject is a `Float`; the narrowed subject must be a local, a parameter or `self`:
+A pattern names a member to take the value apart (`Circle(r)`) or, written as just the member's name, to narrow the subject to that type, so the member's own fields and methods are available (`if Rect := s`, then `s.w`). In an arm that names `Float`, the subject is a `Float`; the narrowed subject must be a local, a parameter or `self`:
 ```plum
 fun show(j: Json) -> Str =
@@ -453,13 +478,15 @@ fun show(j: Json) -> Str =
     Map => "map"
 ```
-A method that every member defines is callable on the enum itself, and the call goes to the member's own method (auto-dispatch):
+A method that every member defines is callable on the enum itself, and the call goes to the member's own method (auto-dispatch). The enum can also define the method itself with a `match self` body, one per operation:
 ```plum
 fun areaOf(s: Shape) -> Float =
   s.area()
 ```
+See [`plum-examples/shapes.plum`](plum-examples/shapes.plum) and [`plum-examples/types.plum`](plum-examples/types.plum).
 One type can be a member of several enums. A `Circle` is a `Shape` and also a `Round`, and converts to whichever the context asks for:
 ```plum
@@ -468,7 +495,7 @@ enum Round = Circle | Oval
 record Oval(a: Float)
 ```
-A method call on a member value falls back to the enum when the member has no such method and exactly one enum it belongs to defines it (`Circle(r: 1.5).area()` calls `Shape.area`); if two enums define it, the call is an error until you convert the value first.
+A method call on a member value falls back to the enum when the member has no such method and exactly one enum it belongs to defines it (`circle.perimeter()` calls `Shape.perimeter` when only the enum defines it); if two enums define it, the call is an error until you convert the value first.
 A discriminant enum gives every tag a shared number:
@@ -499,11 +526,11 @@ fun main() -> Int =
   a + w.inner.age # chained field access
 ```
-A field of a `struct` or `record` is read with `.field`. On a union it is read after narrowing (`if Rectangle := s`, then `s.w`).
+A field of a `struct` or `record` is read with `.field`. On a union it is read after narrowing (see [Enums](#enums)).
 ### Constructing values
-Construct a `struct` or `record` by calling its name with `field: value` pairs (any order; every field required), or positionally:
+Construct a `struct` or `record` by calling its name with `field: value` pairs (any order; every field required), or positionally. This is the only call that can name its arguments:
 ```plum
 cat := Cat(name: "Whiskers", age: 3)
@@ -528,7 +555,7 @@ match n
 match shape
   Circle(r) => r
-  Rectangle(w, h) => w * h
+  Rect(w, h) => w * h
 match book
   FantasyBook(title, _, hasMythicalCreatures) when hasMythicalCreatures =>
@@ -538,52 +565,6 @@ match book
 Patterns can be literals, a bare identifier (binds), a bare capitalized name (a member or tag of an enum, or an error name when matching an error value, also written `error.Name`; compared), a constructor pattern (`Circle(r)`, binding its fields, possibly nested), a bare member name (`Float`, which narrows the subject to that type, see [Enums](#enums)), or `_` (wildcard). `match a, b, ...` supports multiple subjects, and a case can carry a `when <expr>` guard. A `match` over an enum must be exhaustive. See [`plum-examples/match.plum`](plum-examples/match.plum), [`plum-examples/dop_visitor.plum`](plum-examples/dop_visitor.plum) and [`plum-examples/oop_visitor.plum`](plum-examples/oop_visitor.plum).
-Mixed kinds of value live in one enum with a `match self` method per operation:
-```plum
-struct Circle(r: Float)
-record Rect(w: Float, h: Float)
-enum Shape =
-  | Circle
-  | Rect
-  fun area(self) -> Float =
-    match self
-      Circle(r) => r * r * 3.0
-      Rect(w, h) => w * h
-```
-See [`plum-examples/shapes.plum`](plum-examples/shapes.plum) and [`plum-examples/types.plum`](plum-examples/types.plum).
-### `struct` and `record`
-`struct` declares a small, copy-semantics value type (a vector, a color, a rectangle) that is flattened into wasm locals instead of being heap-allocated. `record` declares a reference type. Both are declared with named fields:
-```plum
-struct Vec2(x: Float, y: Float) =
-  fun add(self, o: Vec2) -> Vec2 =
-    Vec2(x: self.x + o.x, y: self.y + o.y)
-struct Rect(pos: Vec2, size: Vec2)  # a field may be another struct
-record User(name: Str, age: Int)
-```
-The header ends with `=` only when an indented body follows: `struct Vec2(x: Float, y: Float)` with no body has no `=`.
-```plum
-a := Vec2(x: 1.0, y: 2.0)
-b := a
-b.x = 9.0          # a.x is still 1.0: a struct is copied
-u := User(name: "ann", age: 3)
-u2 := u
-u2.age = 4         # u.age is now 4: a record is a heap object, shared on assignment
-```
-A `struct` has no generics; its fields are only `Int`, `Float`, `Bool` or other structs, and a struct can't contain itself. Values are copied on assignment and when passed, and are boxed only inside generic containers (`List[Vec2]`, `Vec2?`). A `record` may have any field types and may be generic (`record Pair[K, V](key: K, val: V)`). Methods and `match` work as for any enum. See [`plum-examples/values.plum`](plum-examples/values.plum).
 ## Generics
 ```plum
@@ -679,7 +660,7 @@ primitive Byte =                  # in plum-std/Byte.plum
     Int(self)
 ```
-The std library uses namespaces where free functions clearly belong together: `Math.sqrt(x)`, `Math.sin(x)`, ... (`import std/Math`). `Time.now()`, `Uuid.v4()`, `Uuid.fromStr(s)`, `Random.float()` and `Random.intBelow(n)` are statics of their types. See [`plum-examples/constants.plum`](plum-examples/constants.plum) and [`plum-examples/numbers.plum`](plum-examples/numbers.plum).
+The std library uses namespaces where free functions clearly belong together: `Math` (see [Standard library highlights](#standard-library-highlights)). `Time.now()`, `Uuid.v4()`, `Uuid.fromStr(s)`, `Random.float()` and `Random.intBelow(n)` are statics of their types. See [`plum-examples/constants.plum`](plum-examples/constants.plum) and [`plum-examples/numbers.plum`](plum-examples/numbers.plum).
 ## Closures
@@ -832,14 +813,12 @@ fun find(n: Int) -> Person? =
 | Form | Meaning |
 |---|---|
 | `opt ?: default` | the value, or `default` when `opt` is null. The default may diverge: `opt ?: return null`, `opt ?: return error.Absent`, `opt ?: crash "msg"` |
-| `if x := opt` + block | runs the block with `x: T` bound when present (an optional `else` block runs on null). Also inline: `if x := opt then f(x) else 0` |
+| `if x := opt` + block | runs the block with `x: T` bound when present (an optional `else` block runs on null). Also inline: `if x := opt then f(x) else 0`. Patterns beyond a plain name: see [Pattern `if`](#pattern-if) |
 | `while x := opt` + block | loops while the expression is non-null, re-evaluated each iteration: `while job := queue.next()` |
 | `opt!` | the value, or crashes with `<callee> returned null at file:line:col` |
 | `opt == null`, `opt != null` | presence test (either order) |
 | `opt?.field`, `opt?.method()` | maps over a present value; null passes through (see [Safe navigation](#safe-navigation-)) |
-`if` also takes patterns beyond a plain name (`if Circle(r) := shape`), and optional bindings work in `else if` chains: see [Pattern `if`](#pattern-if).
 `?:` binds looser than comparison, arithmetic and `||`, tighter than `if`/`catch`, and is right-associative, so `a ?: b ?: c` is `a ?: {b ?: c}`. `catch` is for error unions and `?:` for optionals; using the wrong one is a type error (`catch is for errors; use ?:`, `?: is for optionals; use catch`).
 ```plum
@@ -1032,7 +1011,7 @@ hello, world!
 - **`Map[K, V]`** (`import std/Map`) — `Map("a" => 1, "b" => 2)` builds a `Map[Str, Int]`; `Map[K, V]()` is empty. `k => v` is sugar for `Pair(k, v)` in any call's argument list, and a key can be any expression (`Map(n + 1 => x)`). A later duplicate key wins, as with `set`. See [`plum-examples/maps.plum`](plum-examples/maps.plum)
 - **`Set[T]`**, **`Deque[T]`**, **`Heap[T]`** — a set over `Map`'s bucketed hash table, a ring-buffer double-ended queue and a key-ordered min-heap
 - **`Seq[T]`** (`import std/Seq`) — the adapters and terminals of the `for` chains
-- **`Json`**, **`Base64`**, **`Uuid`**, **`Time`**, **`Random`** — parsing, encoding, ids, wall-clock time and a seeded deterministic generator (`Random.float()` and `Random.intBelow(n)` use the wall clock)
+- **`Json`**, **`Base64`**, **`Uuid`**, **`Time`**, **`Random`** — parsing, encoding, ids, wall-clock time and a seeded deterministic generator (the `Random` statics use the wall clock)
 - **`Os`**, **`Http`** — printing and the file system; HTTP requests through the host
 - **`Testing`** (`import std/Testing`) — assertion helpers for `test` blocks