222801d | plum

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

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

222801d — Peter John 2026-07-19T22:03:42+05:30

docs: document the currently-implemented language syntax in README

Files changed (2) hide show

README.md +318 -1
examples/basics.plum +2 -0

README.md CHANGED Viewed

@@ -11,4 +11,321 @@ node >= 23.1.0
 npm >= 10.9.0
 qbe >= 1.2
 clang >= 16.0.0
-```
+```
+## Language Syntax
+This section documents the syntax currently implemented by the [tree-sitter grammar](tooling/tree-sitter-plum/grammar.js), [`plum-checker`](plum-checker), and [`plum-wasm-codegen`](plum-wasm-codegen). Every construct below has a runnable, verified example in [`examples/`](examples) — the two test suites [`plum-checker/tests/examples_test.rs`](plum-checker/tests/examples_test.rs) and [`plum-wasm-codegen/tests/examples_test.rs`](plum-wasm-codegen/tests/examples_test.rs) parse, type-check, and (where noted) compile-and-execute every file in that directory, so this documentation can't silently drift out of sync with what actually works.
+> The [docs website](website/src/content/docs) describes a considerably more elaborate *future* syntax (`fn`, `record`, arrow return types, `{}` blocks, generic `[T]` params). That syntax isn't implemented yet — everything below is what the compiler accepts **today**.
+### Table of contents
+- [Layout and comments](#layout-and-comments)
+- [Naming conventions](#naming-conventions)
+- [Modules and imports](#modules-and-imports)
+- [Constants](#constants)
+- [Literals](#literals)
+- [Operators](#operators)
+- [Variables and assignment](#variables-and-assignment)
+- [Control flow](#control-flow)
+- [Functions](#functions)
+- [Types: records, traits, enums](#types-records-traits-enums)
+- [Generics](#generics)
+- [`self`, field access, and methods](#self-field-access-and-methods)
+- [Constructing values](#constructing-values)
+- [`match`](#match)
+- [String interpolation](#string-interpolation)
+- [Known gaps](#known-gaps)
+### Layout and comments
+Blocks are indentation-sensitive (2 spaces), like Python — there's no `{ }` for grouping statements. A `#` starts a line comment.
+```plum
+# this is a comment
+main() =
+  x = 1
+  if x > 0
+    x = x + 1
+```
+### Naming conventions
+The lexer enforces case by construct — using the wrong case for a position is a parse error, not just a style nit:
+| Token | Case | Used for |
+|---|---|---|
+| `type_identifier` | `PascalCase` | type/trait/enum names, generic bounds |
+| `fn_identifier` | `camelCase` | function/method names, `.field`/`.method()` member names |
+| `var_identifier` | `snake_case` | variables, params, fields (also accepts camelCase — see below) |
+| `const_identifier` | `SCREAMING_SNAKE_CASE` | top-level constants |
+| `mod_identifier` | `snake_case`, single word | `module` declarations only (no `/`) |
+`var_identifier`'s regex is deliberately a superset of `fn_identifier`'s (it allows both `_` and mixed case) so that a bare function call like `factorial(x)` — an all-lowercase, no-underscore name — isn't ambiguous between "a variable" and "a function" at the lexer level.
+### Modules and imports
+```plum
+module basics
+import std/io
+```
+`module` takes exactly one identifier (no path segments). `import` takes a `/`-separated path; there's no module resolution yet — it's parsed but not loaded.
+### Constants
+```plum
+MAX_RETRIES = 3
+PI = 3.14159
+GREETING = "hello"
+```
+Top-level only, `SCREAMING_SNAKE_CASE`, one expression.
+### Literals
+```plum
+dec = 42
+hex = 0xFF
+bin = 0b1010
+big = 1_000_000       # underscores allowed as digit separators
+flt = 3.14
+flt2 = 12.0f          # trailing f/F suffix
+exp = 6.022e23
+name = "plum"
+empty = ""
+escaped = "line one\nline two\ttabbed \"quoted\""
+yes = True
+no = False
+nothing = Nil
+```
+`True`/`False` are built into the type checker/codegen as `Bool`'s two variants — you don't need to declare `enum Bool` yourself to use them. `Nil` parses and type-checks, but codegen doesn't have a runtime representation for it yet (see [Known gaps](#known-gaps)).
+Full example: [`examples/basics.plum`](examples/basics.plum), [`examples/strings.plum`](examples/strings.plum).
+### Operators
+From tightest to loosest binding:
+| Precedence | Operators | Notes |
+|---|---|---|
+| highest | `.` | attribute access / method call |
+| | unary `+` `-` | |
+| | `*` `/` `%` | |
+| | `+` `-` | |
+| | `<<` `>>` | |
+| | `^` | |
+| | `&` | |
+| | `\|` | |
+| | `<` `<=` `==` `!=` `>=` `>` `<>` | comparisons |
+| | `!` | boolean not |
+| | `&&` | |
+| | `\|\|` | |
+| | `..` | range (e.g. `for i in 0..5`) |
+| lowest | `? :` | ternary |
+`!` binds **looser** than comparisons — `!a == b` means `!(a == b)`, not `(!a) == b`. Whenever you mix categories (especially with `!`), group explicitly rather than relying on memorized precedence:
+```plum
+grouped = {1 + 2} * {3 - 1}    # {expr} groups, like (expr) in most languages
+picked = cmp ? sum : bits
+negated = -sum
+inverted = !cmp
+```
+Note: this language uses `{ }` for grouping a sub-expression, not `( )` — parens are reserved for call/constructor argument lists.
+Full example: [`examples/basics.plum`](examples/basics.plum).
+### Variables and assignment
+```plum
+x = 1
+a, b = 1, 2          # multiple targets, positionally paired with multiple values
+```
+Assignment introduces a binding if `x` isn't already in scope, or updates it otherwise — there's no separate `let`/`var` keyword.
+### Control flow
+```plum
+if n < 0
+  return "negative"
+else if n == 0
+  return "zero"
+else
+  return "positive"
+while i > 0
+  i = i - 1
+for i in 0..limit
+  if i == 3
+    continue
+  if i == 8
+    break
+  total = total + i
+assert n > 0    # traps at runtime if false
+todo            # traps at runtime — marks a body as not yet implemented
+```
+`for x in <range>` only accepts a range expression (`a..b`) or another primary expression on the right — there's no iterator protocol yet.
+Full example: [`examples/control_flow.plum`](examples/control_flow.plum).
+### Functions
+```plum
+addInts(a: Int, b: Int) -> Int =
+  a + b
+greet() =                        # no return type => Unit
+  todo
+withDefault(a: Int, step: Int = 1) -> Int =
+  a + step
+sumAll(nums: ...Int) -> Int =    # variadic param
+  todo
+```
+The body always follows `=` on the next, indented line (`= expr` on the same line is grammatically accepted too, but every example and test in this repo uses the indented form — prefer it for consistency).
+Full example: [`examples/functions.plum`](examples/functions.plum).
+### Types: records, traits, enums
+```plum
+type Point =
+  x: Int
+  y: Int
+type Named(Stringable) =    # implements Stringable
+  name: Str
+trait Shape =
+  area() -> Float
+  perimeter() -> Float
+enum Color =
+  | Red
+  | Green
+  | Blue
+enum Option =
+  | Some(Int)              # variant with payload
+  | None
+```
+Full example: [`examples/types.plum`](examples/types.plum).
+### Generics
+Generic type parameters are single letters only: `a`, `b`, `c`, `d`.
+```plum
+type Box(a) =
+  value: a
+trait Comparable(a: Ord) =    # bounded generic param
+  compareTo(other: a) -> Int
+wrap(value: a) -> Bool =      # generic param type
+  True
+```
+Generic **arguments** (instantiating a generic type) accept either bracket or paren syntax: `List[Int]` and `List(Int)` both parse. There's no monomorphization/codegen for user-defined generics yet — they type-check permissively but don't compile to wasm.
+Full example: [`examples/types.plum`](examples/types.plum), [`examples/functions.plum`](examples/functions.plum).
+### `self`, field access, and methods
+A function declared as `name<Receiver>(...)` is a method on `Receiver`, with an implicit `self: Receiver`:
+```plum
+type Cat =
+  name: Str
+  age: Int
+getAge<Cat>() -> Int =
+  self.age
+birthday<Cat>() -> Int =
+  self.age + 1
+main() -> Int =
+  c = Cat(name: "Whiskers", age: 3)
+  a = c.getAge()        # method call
+  w = Wrapper(inner: c, tag: 1)
+  w.inner.age            # chained field access
+```
+Methods are dispatched by declared receiver type, not by name alone — two types can each define a method with the same name without colliding.
+Full example: [`examples/methods.plum`](examples/methods.plum).
+### Constructing values
+```plum
+Cat(name: "Whiskers", age: 3)
+```
+Construct a `type` value by calling its name with `field: value` pairs (any order; every field must be provided).
+### `match`
+```plum
+match n
+  0 =>
+    "zero"
+  1 =>
+    "one"
+  _ =>
+    "many"
+match b
+  True =>
+    1
+  False =>
+    0
+match opt
+  Some(v) =>
+    v
+  None =>
+    0
+```
+Case bodies are always an indented block — there's no `pattern => expr` one-liner form yet. Patterns can be: integer/float/string literals, a bare identifier (binds a new local to the subject's value), a bare capitalized tag (`True`, `False`, or any declared `enum` variant with no payload — compared, not bound), a constructor pattern (`Some(v)`, binding its argument), or `_` (wildcard). Multiple comma-separated subjects/patterns are accepted by the grammar but not yet lowered by codegen.
+Full example: [`examples/match.plum`](examples/match.plum).
+### String interpolation
+```plum
+greet(name: Str) -> Str =
+  "Hello, {name}!"
+```
+`{expr}` inside a string interpolates a single primary expression (a variable, literal, attribute access, etc). Parses and type-checks; codegen doesn't lower it yet (see below).
+Full example: [`examples/strings.plum`](examples/strings.plum).
+### Known gaps
+Some things parse and type-check but don't compile to wasm yet — `plum-wasm-codegen` reports a clear error rather than silently producing wrong code:
+- string interpolation (plain, non-interpolated string literals do compile)
+- `match` patterns other than integer literals, bindings, wildcard, and `True`/`False`; non-Bool enum-tag and constructor (`Some(v)`) patterns aren't lowered yet
+- multi-subject `match` (`match a, b`)
+- `Nil` as a value
+- user-defined generics (they type-check but aren't monomorphized)
+A few grammar rules (`try`, `closure`, the `except` external token) exist in `grammar.js` but aren't wired into any reachable rule yet, so they don't actually parse in context.

examples/basics.plum CHANGED Viewed

@@ -10,8 +10,10 @@ main() =
   dec = 42
   hex = 0xFF
   bin = 0b1010
+  big = 1_000_000
   flt = 3.14
   flt2 = 12.0f
+  exp = 6.022e23
   name = "plum"
   yes = True
   no = False