nomen-lang 0.0.19 → 0.2.0

package/NOMEN_AGENTS.md

@@ -36,22 +36,50 @@ The rules below trip up newcomers and LLMs. Follow them.
 
 Nomen infers types from initializers and return values. Don't spell them out
 unless the inference would be wrong or the annotation materially aids a public
-API.
+API. This includes generic instantiations — an initializer like
+`split_lines(text)` already says `List<Line>`.
 
 ```nomen
-const x = 5              // good — inferred int
-const int x = 5          // avoid
-const msg = "hi"         // good
-var items = [1, 2, 3]    // good — int[]
+const x = 5                        // good — inferred int
+const int x = 5                    // avoid
+const lines = split_lines(text)     // good — inferred List<Line>
+const List<Line> lines = split_lines(text)  // avoid
+const msg = "hi"                   // good
+var items = [1, 2, 3]              // good — int[]
 ```
 
 Annotate when you need a wider type (`int64` rather than `int`), when there is
 no initializer, or on a `pub` API where the type is the contract.
 
-### No `else if` — use `switch` or separate `if`s
+### Loop updates go in the header
 
-Nomen forbids `else if` and `else { if { … } }` chains. Use a `switch` for
-related conditions, or pull each condition into its own top-level `if`.
+`for` and `while` take a post-statement after the condition, C-`for` style.
+Don't bury the update as the last statement of the body.
+
+```nomen
+while i < n; i += 1 { ... }   // good — update in the header
+while i < n { ...; i += 1 }   // avoid
+```
+
+Only hoist an update that runs on every iteration — if a `continue` (or early
+`return` that isn't meant to advance) must skip it, keep it in the body.
+
+### No `else if` — use `switch`
+
+Nomen forbids `else if` and `else { if { … } }` chains. Consecutive sibling
+`if`s on mutually exclusive conditions are the same smell (and a `did_x` flag
+set only to gate the next `if` is a giveaway): fold them into a `switch`,
+which evaluates cases in order and runs the first true one.
+
+```nomen
+switch {
+	case moved { ... }
+	case is_ins { ... }
+	else { ... }
+}
+```
+
+Independent conditions that can all fire stay as separate `if`s.
 
 ### Constraints are compile-time assertions
 
@@ -72,7 +100,7 @@ func safe = (string[] s, int i: i >= 0 && i < s.length, out string) {
 | -------- | ---------------------------------------------- |
 | `ref T`  | mutable borrow; caller must also write `ref`   |
 | `view T` | read-only borrow                               |
-| `mov T`  | transfer ownership; caller writes `mov`        |
+| `move T` | transfer ownership; caller writes `move`       |
 | `out T`  | output parameter, assigned inside the function |
 
 `const` values cannot be passed to `ref` — rebind the caller as `var` first.
@@ -106,15 +134,27 @@ const y = x + 1     // Error: 'x' is null
 
 ```nomen
 import System                  // standard library
-import System/Test             // submodule
-import System/Collections/List // specific module
+import System::Test            // submodule
+import System::Controls::Geometry // a single module file
 ```
 
+Import paths must mirror the library's file layout — a typo'd path
+(`import System::Contrls`) is a compile error.
+
+Files in the same folder are one module — they already see each other's
+declarations, so never import a sibling. Only cross-namespace references
+(subfolders, libraries) need an import.
+
 ### No exceptions
 
 Failures are signalled via return values — nullable results, status structs,
 or boolean + out-parameter pairs. There is no `throw`/`try`/`catch`.
 
+`Result<T, E>` is declared `must_use`: a call returning it must bind or match
+the value (`var _ = f.close()` to discard deliberately; a bare `f.close()`
+statement is a compile error). Any enum or bitset can opt into this with the
+`must_use` modifier.
+
 ## Tests
 
 A test is any `pub func <name> = (ref Tester t)` in a `*.test.nm` file.
@@ -123,7 +163,7 @@ benchmarks.
 
 ```nomen
 import System
-import System/Test
+import System::Test
 
 func add = (int a, int b, out int) => a + b
 
@@ -153,6 +193,10 @@ var int? maybe = null                // nullable
 ref int ptr                          // reference to an int
 ```
 
+Keywords (`out`, `in`, `match`, `if`, `of`, `as`, `swap`, …) are reserved and
+cannot be used as variable, parameter, field, type, or case names. Function
+names are exempt since calls go through `.name(...)` (e.g. `Regex.match`).
+
 ### Functions
 
 ```nomen
@@ -177,6 +221,7 @@ switch x {
 for i of 0 .. 10 { ... }       // exclusive range
 for item of array { ... }
 while cond { ... }
+while cond; update { ... }     // post-statement (e.g. while i < n; i += 1)
 ```
 
 ### Structs and classes

package/core/System/Array.nm

@@ -114,13 +114,13 @@ pub struct Array<T>: Viewable {
 		```
 		#arch: c
 		T* _data = (T*)((char*)self + sizeof(*self));
-		// T_NEEDS_STRDUP is 1 when T is string: the slot must own a heap copy
-		// (free the outgoing string, strdup the incoming one) so auto_free can
-		// soundly free every slot at scope exit and reassigning a slot doesn't
-		// leak the previous value. 0 for all other T (plain assignment).
+		// T_NEEDS_STRDUP is 1 when T is string (a fat value whose backing
+		// bytes must be heap-copied per slot — otherwise the slot would share
+		// the incoming pointer and auto_free would double-free it). 0 for all
+		// other T (plain assignment).
 		#if T_NEEDS_STRDUP
-			free(_data[index]);
-			_data[index] = (T)strdup(value);
+			free(_data[index].ptr);
+			_data[index] = nomen_str_dup(value);
 		#else
 			_data[index] = value;
 		#endif
@@ -258,12 +258,12 @@ pub struct Array<T>: Viewable {
 		((long*)_result)[1] = count;
 		T* _data = (T*)((char*)_result + _header);
 		for (long i = 0; i < count; i++) {
-			// T_NEEDS_STRDUP is 1 when T is string (a `char*` pointer whose
-			// backing bytes must be heap-copied per slot — otherwise all n
-			// slots would share one pointer and auto_free would n-free it).
-			// For all other T it is 0 and the plain assignment runs.
+			// T_NEEDS_STRDUP is 1 when T is string (a fat value whose backing
+			// bytes must be heap-copied per slot — otherwise all n slots would
+			// share one pointer and auto_free would n-free it). For all other
+			// T it is 0 and the plain assignment runs.
 			#if T_NEEDS_STRDUP
-				_data[i] = (T)strdup(value);
+				_data[i] = nomen_str_dup(value);
 			#else
 				_data[i] = value;
 			#endif

package/core/System/Buffer.nm

@@ -445,11 +445,11 @@ pub struct Buffer<T> {
 	}
 
 	// Move a value out of a T_SIZE-sized slot: return it and zero the slot so the
-	// buffer no longer holds a (possibly owning) copy. Declared `mov out T` so
+	// buffer no longer holds a (possibly owning) copy. Declared `move out T` so
 	// the result is treated as OWNED by the borrow checker — the slot is
 	// relinquished, so the caller is the sole remaining owner. The value
 	// counterpart of ClassBuffer.move_int — used by List.pop for any value T.
-	inline func move_T = (ref self, int i: i >= 0 && i < self.cap, mov out T) {
+	inline func move_T = (ref self, int i: i >= 0 && i < self.cap, move out T) {
 		```
 		#arch: c
 		T* _slots = (T*)(unsigned long long)self->data;

package/core/System/Channel.nm

@@ -1,9 +1,18 @@
 // Channel — thread-safe single-direction queue for passing values between
 // tasks. Unbounded, FIFO, blocking receive.
 //
-// Stores uint64 values (Nomen values are pointer-sized on every target we
-// care about). A typed Channel<T> wrapper can come later — the storage story
-// is identical, only the call-site types change.
+// The queue node's payload is two words wide: every message carries a
+// (value, len) pair. `send`/`receive` move uint64 values (len stays 0);
+// `send_string`/`receive_string` move fat strings without truncating the len
+// half. A typed Channel<T> wrapper can come later — the storage story is
+// identical, only the call-site types change.
+//
+// String payloads are copied in and moved out: `send_string` duplicates the
+// value into the node (the sender keeps its own string), and
+// `receive_string` moves that copy out to the receiver (zeroing the node's
+// payload). A message that is never received is freed by #destroy's drain.
+// This keeps literals (rodata), heap strings freed at the sender's scope
+// exit, and messages crossing task boundaries all sound.
 //
 // Default stance in Nomen is "no shared mutable state" — channels are the
 // preferred way for tasks to communicate. See ASYNC.md.
@@ -24,6 +33,7 @@ pub class Channel: Sendable {
 		#include <pthread.h>
 		struct nomen_channel_node {
 			unsigned long long value;
+			unsigned long long len;
 			struct nomen_channel_node *next;
 		};
 		```
@@ -58,6 +68,7 @@ pub class Channel: Sendable {
 		#arch: c
 		struct nomen_channel_node *n = (struct nomen_channel_node *)malloc(sizeof(struct nomen_channel_node));
 		n->value = value;
+		n->len = 0;
 		n->next = NULL;
 		pthread_mutex_lock((pthread_mutex_t *)self->mu);
 		if (self->tail) {
@@ -73,18 +84,19 @@ pub class Channel: Sendable {
 		#arch: aarch64
 		// x19 = self (set by prologue), x1 = value
 		str x1, [sp, #-16]!       // save value on stack
-		mov x0, #16
+		mov x0, #24               // node = { value, len, next }
 		bl _malloc                // x0 = node
 		ldr x1, [sp], #16         // restore value
 		str x1, [x0, #0]          // node->value = value
-		str xzr, [x0, #8]         // node->next = NULL
+		str xzr, [x0, #8]         // node->len = 0
+		str xzr, [x0, #16]        // node->next = NULL
 		str x0, [sp, #-16]!       // save node on stack
 		ldr x0, [x19, #8]         // self->mu
 		bl _pthread_mutex_lock
 		ldr x2, [sp], #16         // restore node
 		ldr x1, [x19, #32]        // tail
 		cbz x1, .Lchannel_send_empty
-		str x2, [x1, #8]          // tail->next = node
+		str x2, [x1, #16]         // tail->next = node
 		b .Lchannel_send_enqueued
 		.Lchannel_send_empty:
 		str x2, [x19, #24]        // head = node
@@ -97,6 +109,67 @@ pub class Channel: Sendable {
 		```
 	}
 
+	// Pass a fat string through the channel. The value is DUPLICATED into the
+	// queue node — the sender keeps ownership of what it passed — so the
+	// message survives the sender's scope exit intact (true len, embedded
+	// NULs and all). Receive it with receive_string.
+	pub func send_string = (self, string value) {
+		```
+		#arch: c
+		struct nomen_channel_node *n = (struct nomen_channel_node *)malloc(sizeof(struct nomen_channel_node));
+		nomen_string _v = value.ptr ? nomen_str_dup(value) : (nomen_string){0, 0};
+		n->value = (unsigned long long)_v.ptr;
+		n->len = (unsigned long long)_v.len;
+		n->next = NULL;
+		pthread_mutex_lock((pthread_mutex_t *)self->mu);
+		if (self->tail) {
+			((struct nomen_channel_node *)self->tail)->next = n;
+		} else {
+			self->head = (unsigned long long)n;
+		}
+		self->tail = (unsigned long long)n;
+		pthread_cond_signal((pthread_cond_t *)self->not_empty_cv);
+		pthread_mutex_unlock((pthread_mutex_t *)self->mu);
+		```
+		```
+		#arch: aarch64
+		// x19 = self (set by prologue), x1 = value.ptr, x2 = value.len
+		stp x1, x2, [sp, #-32]!   // [sp]=ptr [sp+8]=len [sp+16]=node scratch
+		mov x0, #24               // node = { value, len, next }
+		bl _malloc                // x0 = node
+		str x0, [sp, #16]         // save node across the strdup call
+		ldr x1, [sp, #0]          // value.ptr
+		cbz x1, .Lchannel_send_str_zero
+		mov x0, x1
+		bl _strdup                // x0 = owned copy (node owns its buffer)
+		b .Lchannel_send_str_have
+		.Lchannel_send_str_zero:
+		mov x0, #0
+		.Lchannel_send_str_have:
+		ldr x2, [sp, #16]         // node
+		str x0, [x2, #0]          // node->value = copied ptr
+		ldr x1, [sp, #8]          // value.len
+		str x1, [x2, #8]          // node->len = len
+		str xzr, [x2, #16]        // node->next = NULL
+		ldr x0, [x19, #8]         // self->mu
+		bl _pthread_mutex_lock
+		ldr x2, [sp, #16]         // restore node
+		ldr x1, [x19, #32]        // tail
+		cbz x1, .Lchannel_send_str_empty
+		str x2, [x1, #16]         // tail->next = node
+		b .Lchannel_send_str_enqueued
+		.Lchannel_send_str_empty:
+		str x2, [x19, #24]        // head = node
+		.Lchannel_send_str_enqueued:
+		str x2, [x19, #32]        // tail = node
+		ldr x0, [x19, #16]        // not_empty_cv
+		bl _pthread_cond_signal
+		ldr x0, [x19, #8]         // self->mu
+		bl _pthread_mutex_unlock
+		add sp, sp, #32
+		```
+	}
+
 	pub func receive = (self, out uint64) {
 		```
 		#arch: c
@@ -126,7 +199,7 @@ pub class Channel: Sendable {
 		b .Lchannel_receive_wait
 		.Lchannel_receive_got:
 		// x1 = node
-		ldr x2, [x1, #8]          // node->next
+		ldr x2, [x1, #16]         // node->next
 		str x2, [x19, #24]        // head = node->next
 		cbnz x2, .Lchannel_receive_not_empty
 		str xzr, [x19, #32]       // tail = 0
@@ -141,14 +214,69 @@ pub class Channel: Sendable {
 		```
 	}
 
+	// Block until a message is available, then return it as an OWNED string
+	// (the node's copy is moved out — the payload leaves the channel, and a
+	// second receive of the same message is not possible). The fat (ptr, len)
+	// pair survives intact. Pair with send_string.
+	pub func receive_string = (self, move out string) {
+		```
+		#arch: c
+		pthread_mutex_lock((pthread_mutex_t *)self->mu);
+		while (!self->head) {
+			pthread_cond_wait((pthread_cond_t *)self->not_empty_cv, (pthread_mutex_t *)self->mu);
+		}
+		struct nomen_channel_node *n = (struct nomen_channel_node *)self->head;
+		self->head = (unsigned long long)n->next;
+		if (!self->head) self->tail = 0;
+		nomen_string v = { (char *)n->value, (long)n->len };
+		n->value = 0;
+		n->len = 0;
+		free(n);
+		pthread_mutex_unlock((pthread_mutex_t *)self->mu);
+		return v;
+		```
+		```
+		#arch: aarch64
+		// x19 = self (set by prologue); returns the fat pair in x0/x1
+		ldr x0, [x19, #8]         // self->mu
+		bl _pthread_mutex_lock
+		.Lchannel_receive_str_wait:
+		ldr x1, [x19, #24]        // head
+		cbnz x1, .Lchannel_receive_str_got
+		ldr x0, [x19, #16]        // not_empty_cv
+		ldr x1, [x19, #8]         // mu
+		bl _pthread_cond_wait
+		b .Lchannel_receive_str_wait
+		.Lchannel_receive_str_got:
+		// x1 = node
+		ldr x2, [x1, #16]         // node->next
+		str x2, [x19, #24]        // head = node->next
+		cbnz x2, .Lchannel_receive_str_not_empty
+		str xzr, [x19, #32]       // tail = 0
+		.Lchannel_receive_str_not_empty:
+		ldr x0, [x1, #0]          // value.ptr
+		ldr x2, [x1, #8]          // value.len
+		stp x0, x2, [sp, #-16]!   // push pair
+		str xzr, [x1, #0]         // payload moves out of the node
+		str xzr, [x1, #8]
+		mov x0, x1                // x0 = node (for free)
+		bl _free
+		ldr x0, [x19, #8]         // self->mu
+		bl _pthread_mutex_unlock
+		ldp x0, x1, [sp], #16     // pop pair → x0/x1 (return)
+		```
+	}
+
 	pub func #destroy = () {
 		```
 		#arch: c
 		if (self->mu) {
-			// Drain any pending nodes.
+			// Drain any pending nodes. A string payload that was never
+			// received still owns its buffer — free it with the node.
 			struct nomen_channel_node *n = (struct nomen_channel_node *)self->head;
 			while (n) {
 				struct nomen_channel_node *next = n->next;
+				if (n->value) free((void *)n->value);
 				free(n);
 				n = next;
 			}
@@ -167,14 +295,20 @@ pub class Channel: Sendable {
 		// x19 = self (set by prologue)
 		ldr x0, [x19, #8]         // self->mu
 		cbz x0, .Lchannel_destroy_done
-		// Drain nodes
+		// Drain nodes (freeing any unconsumed string payload)
 		ldr x1, [x19, #24]        // head
 		.Lchannel_destroy_drain:
 		cbz x1, .Lchannel_destroy_drained
-		ldr x2, [x1, #8]          // next (before free clobbers it)
-		str x2, [sp, #-16]!       // save next on stack
+		ldr x2, [x1, #16]         // next (before calls clobber x1)
+		stp x1, x2, [sp, #-16]!   // save node + next
+		ldr x0, [x1, #0]          // payload ptr
+		cbz x0, .Lchannel_destroy_no_payload
+		bl _free
+		.Lchannel_destroy_no_payload:
+		ldr x0, [sp, #0]          // node
 		bl _free
-		ldr x1, [sp], #16         // restore next
+		ldr x1, [sp, #8]          // next
+		add sp, sp, #16
 		b .Lchannel_destroy_drain
 		.Lchannel_destroy_drained:
 		// Destroy mutex and condvar

package/core/System/ClassBuffer.nm

@@ -175,14 +175,14 @@ pub struct ClassBuffer<T> {
 	}
 
 	// Move a class pointer out of a slot: return it and zero the slot so the
-	// buffer no longer references it. Declared `mov out T` so the borrow
+	// buffer no longer references it. Declared `move out T` so the borrow
 	// checker treats the result as OWNED — the slot is relinquished, so the
 	// caller is the sole remaining owner. This is the owning-extract primitive
 	// (parallel to List.pop); use it (not load_T) when transferring ownership
 	// out of a ClassBuffer slot, or moving a value into a fresh owning
 	// container — load_T returns a BORROW (the slot is unchanged) and storing
 	// it elsewhere would create shared ownership (double-free at destroy).
-	inline func move_T = (ref self, int i: i >= 0 && i < self.cap, mov out T) {
+	inline func move_T = (ref self, int i: i >= 0 && i < self.cap, move out T) {
 		```
 		#arch: c
 		long *slots = (long*)(unsigned long long)self->data;

package/core/System/Console.nm

@@ -9,12 +9,12 @@ pub struct Console {
 		```
 		```
 		#arch: aarch64
-		sub sp, sp, #16
-		mov x1, x0
-		str x1, [sp]
+		// Fat-string ABI: line = (x0 ptr, x1 len); printf needs the fmt in
+		// x0 and the NUL-terminated ptr half in x1.
+		mov x2, x0
 		adr x0, .Lfmt_console_s
+		mov x1, x2
 		bl _printf
-		add sp, sp, #16
 		b .Lend_Console_write
 		.Lfmt_console_s: .asciz "%s"
 		.p2align 2
@@ -29,12 +29,11 @@ pub struct Console {
 		```
 		```
 		#arch: aarch64
-		sub sp, sp, #16
-		mov x1, x0
-		str x1, [sp]
+		// Fat-string ABI: line = (x0 ptr, x1 len).
+		mov x2, x0
 		adr x0, .Lfmt_console_snl
+		mov x1, x2
 		bl _printf
-		add sp, sp, #16
 		b .Lend_Console_write_line
 		.Lfmt_console_snl: .asciz "%s\n"
 		.p2align 2
@@ -42,7 +41,9 @@ pub struct Console {
 		```
 	}
 
-	pub func read_line = (out string) {
+	// Read one line from stdin (newline stripped). The raw body mallocs the
+	// buffer — `move out string` transfers ownership to the caller.
+	pub func read_line = (move out string) {
 		```
 		#arch: c
 		int cap = 16;
@@ -58,7 +59,9 @@ pub struct Console {
 			c = getchar();
 		}
 		buf[len] = 0;
-		return buf;
+		// Fat-string ABI: return the (ptr, len) pair — len is already
+		// counted, no strlen.
+		return (nomen_string){ buf, len };
 		```
 		```
 		#arch: aarch64
@@ -121,42 +124,45 @@ pub struct Console {
 		```
 	}
 
-	pub func platform = (out string) {
+	// The platform name ("macos" / "ios" / …). The raw body strdups a static
+	// string — `move out string` transfers the owned copy to the caller.
+	pub func platform = (move out string) {
 		```
 		#arch: c
 		#platform: macos
-		return strdup("macos");
+		return (nomen_string){ strdup("macos"), 5 };
 		```
 		```
 		#arch: c
 		#platform: ios
-		return strdup("ios");
+		return (nomen_string){ strdup("ios"), 3 };
 		```
 		```
 		#arch: c
 		#platform: linux
-		return strdup("linux");
+		return (nomen_string){ strdup("linux"), 5 };
 		```
 		```
 		#arch: c
 		#platform: android
-		return strdup("android");
+		return (nomen_string){ strdup("android"), 7 };
 		```
 		```
 		#arch: c
 		#platform: windows
-		return strdup("windows");
+		return (nomen_string){ strdup("windows"), 7 };
 		```
 		```
 		#arch: c
 		#platform: web
-		return strdup("web");
+		return (nomen_string){ strdup("web"), 3 };
 		```
 		```
 		#arch: aarch64
 		#platform: macos
 		adr x0, .Lconsole_plat_macos
 		bl _strdup
+		mov x1, #5
 		b .return_Console_platform
 		.Lconsole_plat_macos: .asciz "macos"
 		.p2align 2
@@ -166,6 +172,7 @@ pub struct Console {
 		#platform: ios
 		adr x0, .Lconsole_plat_ios
 		bl _strdup
+		mov x1, #3
 		b .return_Console_platform
 		.Lconsole_plat_ios: .asciz "ios"
 		.p2align 2
@@ -175,6 +182,7 @@ pub struct Console {
 		#platform: linux
 		adr x0, .Lconsole_plat_linux
 		bl _strdup
+		mov x1, #5
 		b .return_Console_platform
 		.Lconsole_plat_linux: .asciz "linux"
 		.p2align 2
@@ -184,6 +192,7 @@ pub struct Console {
 		#platform: android
 		adr x0, .Lconsole_plat_android
 		bl _strdup
+		mov x1, #7
 		b .return_Console_platform
 		.Lconsole_plat_android: .asciz "android"
 		.p2align 2
@@ -193,6 +202,7 @@ pub struct Console {
 		#platform: windows
 		adr x0, .Lconsole_plat_windows
 		bl _strdup
+		mov x1, #7
 		b .return_Console_platform
 		.Lconsole_plat_windows: .asciz "windows"
 		.p2align 2
@@ -202,6 +212,7 @@ pub struct Console {
 		#platform: web
 		adr x0, .Lconsole_plat_web
 		bl _strdup
+		mov x1, #3
 		b .return_Console_platform
 		.Lconsole_plat_web: .asciz "web"
 		.p2align 2