while loops

TODO.md

@@ -95,9 +95,12 @@
     - new `Optional_Is_Some` / `Optional_Value` IR opcodes (the `Unwrap` presence-test + extract, minus the trap)
   - conditional unwrapping with guard clause:  `if val |v : v >= 10| { ... } else { ... }` - unwrap `val` into `v` if it is not `none`
   - multi-unwrap (see section below)
-  - while loops (operates on boolean conditions). examples:
+  - while loops (implemented; operates on boolean conditions). examples:
     - `while condition { ... }` - iterate while the condition is true
-    - `while condition : i += 1 { ... }` - iterate while the condition is true and execute `i += 1` (continue expression) after each iteration
+    - `while condition : i = i + 1 { ... }` - execute the update after each completed iteration
+    - the condition and update may be parenthesized independently for visual clarity
+    - update targets must already be declared and mutable; loops do not introduce implicit induction variables
+    - compound assignment (`+=`) remains deferred
   - ranges (see section below)
   - for loops (operates on iterable sequences). examples:
     - `for items |item| { ... }` - capture just the `item` value in the array/slice (uses copy semantics, i.e. gets a `T`)
@@ -109,8 +112,11 @@
     - `for 0..(len) |i| { ... }` or equivalently `for 0..=(len - 1) |i| { ... }` - calculating range bounds, expressions must be parenthesized
   - for all conditionals/guards, parentheses are optional but allowed for visual clarity
 
-6. compound assignment
+6. compound assignment: `+=`, `-=`, `*=`, `/=`
 
+7. enums (native and c interop) (see below)
+
+8. distinct types (see below)
 
 ## A word on multi-unwrap
 
@@ -175,3 +181,59 @@ Ranges represent a sequence of values, commonly used in for loops, and is itself
 ```
   
 This rule keeps the grammar simple and forces clarity at the call site — no precedence rules to remember. Also, being a value type, ranges can be assigned to variables and passed around like any other value.
+
+# A word on distinct types
+
+Distinct types are considered distinct from their backing type. They do not implicitly coerce to their backing type.
+
+```
+# distinct type
+UserID :: distinct u32
+
+# instantiate distinct type
+my_id UserId :: UserID(42) # value must be of to backing type
+```
+
+# A word on enums
+
+```
+# standard enums
+Animal :: enum {
+    dog
+    cat
+    bird
+    lizard
+}
+
+# enums with backing type
+Nat :: enum(u8) { # in this case, a maximum of 256 values are possible
+    one # default: implicitly starts from value 0
+    two
+    three
+    four
+    five
+}
+
+# enums with backing type with explicit associated values
+# note: must not be jumbled (i.e. `first_val = 1` must come before `other_val = 2`), but is allowed to be discontiguous (i.e. `one = 1` can be followed by `three = 3` without `two = 2` in between)
+Nat :: enum(u8) {
+    one = 1
+    two = 2
+    three = 3
+    # no four
+    five = 5
+}
+
+# enums with backing type with semi-implicit associated values
+Nat :: enum(u8) {
+    one = 1 # starts from value 1
+    two     # implicitly gets value 2
+    three   # etc...
+    four
+    five
+}
+
+# using enums
+dog_tag1 Animal :: Animal.dog
+dog_tag2 Animal :: .dog # type inferred
+```