Merge branch 'main' into main

11 files changed, 579 insertions, 0 deletions

diff --git a/docs/lex.md b/docs/lex.md
new file mode 100644
index 0000000..1cd70fd
--- /dev/null
+++ b/docs/lex.md
@@ -0,0 +1,130 @@
+# Lexical Structure
+
+## Source Text
+
+Zen-C source code is encoded in UTF-8.
+
+## Grammar Notation
+
+The lexical grammar is defined using a notation similar to EBNF.
+- `Rule ::= Production`: Defines a rule.
+- `[ ... ]`: Character class.
+- `*`: Zero or more repetitions.
+- `+`: One or more repetitions.
+- `?`: Zero or one occurrence.
+- `|`: Alternation.
+- `"..."` or `'...'`: Literal string/character.
+- `~`: Negation (e.g., `~[\n]` means any character except newline).
+
+## Whitespace and Comments
+
+Whitespace separates tokens but is otherwise ignored. Comments are treated as whitespace.
+
+```text
+Whitespace ::= [ \t\n\r]+
+Comment    ::= LineComment | BlockComment
+
+LineComment  ::= "//" ~[\n]*
+BlockComment ::= "/*" (BlockComment | ~("*/"))* "*/"
+```
+
+## Identifiers
+
+Identifiers name entities such as variables, functions, and types.
+
+```text
+Identifier      ::= IdentifierStart IdentifierPart*
+IdentifierStart ::= [a-zA-Z_]
+IdentifierPart  ::= [a-zA-Z0-9_]
+```
+
+## Literals
+
+### Integer Literals
+
+Integers can be decimal, hexadecimal, or binary.
+
+```text
+IntegerLiteral ::= ( DecimalInt | HexInt | BinaryInt ) IntegerSuffix?
+
+DecimalInt ::= [0-9]+
+HexInt     ::= "0x" [0-9a-fA-F]+
+BinaryInt  ::= "0b" [01]+
+
+IntegerSuffix ::= "u" | "L" | "u64" | ... 
+```
+*Note: The lexer technically consumes any alphanumeric sequence following a number as a suffix.*
+
+### Floating Point Literals
+
+```text
+FloatLiteral ::= [0-9]+ "." [0-9]* FloatSuffix?
+               | [0-9]+ FloatSuffix
+
+FloatSuffix ::= "f"
+```
+
+### String Literals
+
+```text
+StringLiteral ::= '"' StringChar* '"'
+StringChar    ::= ~["\\] | EscapeSequence
+EscapeSequence ::= "\\" ( ["\\/bfnrt] | "u" HexDigit{4} )
+```
+
+### F-Strings
+
+```text
+FStringLiteral ::= 'f"' StringChar* '"'
+```
+
+
+### Character Literals
+
+```text
+CharLiteral ::= "'" ( ~['\\] | EscapeSequence ) "'"
+```
+
+## Keywords
+
+```text
+Keyword ::= Declaration | Control | Special | BoolLiteral | NullLiteral | LogicOp
+
+Declaration ::= "let" | "def" | "fn" | "struct" | "enum" | "union" | "alias"
+              | "trait" | "impl" | "use" | "module" | "import" | "opaque"
+
+Control     ::= "if" | "else" | "match" | "for" | "while" | "loop" 
+              | "return" | "break" | "continue" | "guard" | "unless" 
+              | "defer" | "async" | "await" | "try" | "catch" | "goto"
+
+Special     ::= "asm" | "assert" | "test" | "sizeof" | "embed" | "comptime" 
+              | "autofree" | "volatile" | "launch" | "ref" | "static" | "const"
+
+BoolLiteral ::= "true" | "false"
+NullLiteral ::= "null"
+
+CReserved   ::= "auto" | "case" | "char" | "default" | "do" | "double" 
+              | "extern" | "float" | "inline" | "int" | "long" | "register" 
+              | "restrict" | "short" | "signed" | "switch" | "typedef" 
+              | "unsigned" | "void" | "_Atomic" | "_Bool" | "_Complex" 
+              | "_Generic" | "_Imaginary" | "_lmaginary" | "_Noreturn" 
+              | "_Static_assert" | "_Thread_local"
+
+LogicOp     ::= "and" | "or"
+```
+
+## Operators and Punctuation
+
+```text
+Operator ::= "+"  | "-"  | "*"  | "/"  | "%"
+           | "&&" | "||" | "!"  | "++" | "--"
+           | "&"  | "|"  | "^"  | "~"  | "<<" | ">>"
+           | "==" | "!=" | "<"  | ">"  | "<=" | ">="
+           | "="  | "+=" | "-=" | "*=" | "/=" | "%="
+           | "&=" | "|=" | "^=" | "<<=" | ">>="
+           | ".." | "..=" | "..<" | "..."
+           | "."  | "?." | "??" | "??=" | "->" | "=>" 
+           | "::" | "|>" | "?"
+           | "("  | ")"  | "{"  | "}"  | "["  | "]"
+           | ","  | ":"  | ";"  | "@"
+```
diff --git a/docs/std/README.md b/docs/std/README.md
index 6125a4e..3cbf8f8 100644
--- a/docs/std/README.md
+++ b/docs/std/README.md
@@ -3,10 +3,17 @@
 - [Env (Environment)](./env.md) - Process environment variables.
 - [File System (FS)](./fs.md) - File I/O and directory operations.
 - [IO](./io.md) - Standard Input/Output.
+- [JSON](./json.md) - JSON parsing and serialization.
 - [Map](./map.md) - Hash map implementation.
+- [Networking (Net)](./net.md) - TCP networking.
 - [Option](./option.md) - Optional values (Some/None).
 - [Path](./path.md) - File path manipulation.
+- [Process](./process.md) - Process execution and management.
 - [Result](./result.md) - Error handling (Ok/Err).
 - [Queue](./queue.md) - FIFO queue (Ring Buffer).
+- [Set](./set.md) - Hash set implementation.
+- [Stack](./stack.md) - LIFO stack.
 - [String](./string.md) - Growable, heap-allocated string type.
+- [Thread (Concurrency)](./thread.md) - Multithreading and synchronization.
+- [Time](./time.md) - Time measurement and sleep.
 - [Vector (Vec)](./vec.md) - A growable dynamic array.
diff --git a/docs/std/json.md b/docs/std/json.md
new file mode 100644
index 0000000..ce35d64
--- /dev/null
+++ b/docs/std/json.md
@@ -0,0 +1,83 @@
+# JSON (`std/json.zc`)
+
+The `std/json` module provides a DOM-style JSON parser and builder.
+
+## Usage
+
+```zc
+import "std/json.zc"
+```
+
+## Types
+
+### Struct `JsonValue`
+
+Represents a node in a JSON document.
+
+#### Creation Methods
+
+- **`fn null() -> JsonValue`**, **`fn null_ptr() -> JsonValue*`**
+- **`fn bool(b: bool) -> JsonValue`**, **`fn bool_ptr(b: bool) -> JsonValue*`**
+- **`fn number(n: double) -> JsonValue`**, **`fn number_ptr(n: double) -> JsonValue*`**
+- **`fn string(s: char*) -> JsonValue`**, **`fn string_ptr(s: char*) -> JsonValue*`**
+- **`fn array() -> JsonValue`**, **`fn array_ptr() -> JsonValue*`**
+- **`fn object() -> JsonValue`**, **`fn object_ptr() -> JsonValue*`**
+
+#### Parsing
+
+- **`fn parse(json: char*) -> Result<JsonValue*>`**
+  Parses a JSON string into a heap-allocated `JsonValue` tree.
+
+#### Accessors
+
+- **`fn is_null(self) -> bool`**, **`is_bool`**, **`is_number`**, **`is_string`**, **`is_array`**, **`is_object`**
+  Check the type of the value.
+
+- **`fn as_string(self) -> Option<char*>`**
+  Returns `Some(string)` if the value is a string, `None` otherwise.
+- **`fn as_int(self) -> Option<int>`**
+- **`fn as_float(self) -> Option<double>`**
+- **`fn as_bool(self) -> Option<bool>`**
+
+#### Object/Array Operations
+
+- **`fn push(self, val: JsonValue)`**
+  Appends a value to an array.
+- **`fn set(self, key: char*, val: JsonValue)`**
+  Sets a key-value pair in an object.
+
+- **`fn get(self, key: char*) -> Option<JsonValue*>`**
+  Retrieves a value from an object by key.
+- **`fn at(self, index: usize) -> Option<JsonValue*>`**
+  Retrieves a value from an array by index.
+
+#### Serialization
+
+- **`fn to_string(self) -> String`**
+  Serializes the JSON value to a string representation.
+  
+- **`fn stringify(self, buf: String*)`**
+  Internal recursive serialization method that appends to a string buffer.
+  
+**Example:**
+```zc
+let obj = JsonValue::object();
+obj.set("name", JsonValue::string("Alice"));
+obj.set("age", JsonValue::number(30.0));
+
+let json_str = obj.to_string();
+println "{json_str.c_str()}";  // {"name":"Alice","age":30}
+json_str.free();
+obj.free();
+```
+
+**Features:**
+- Proper escaping of special characters: `\"`, `\\`, `\n`, `\t`, `\r`, `\b`, `\f`
+- Numbers formatted with `%.15g` for precision
+- Recursive serialization for nested objects and arrays
+- Round-trip compatible with `parse()`
+
+#### Memory Management
+
+- **`fn free(self)`**
+  Recursively frees the JSON value and all its children.
diff --git a/docs/std/net.md b/docs/std/net.md
new file mode 100644
index 0000000..392c901
--- /dev/null
+++ b/docs/std/net.md
@@ -0,0 +1,44 @@
+# Networking (`std/net.zc`)
+
+The `std/net` module provides basic TCP networking capabilities.
+
+## Usage
+
+```zc
+import "std/net.zc"
+```
+
+## Types
+
+### Type `TcpListener`
+
+Represents a TCP socket listening for incoming connections.
+
+#### Methods
+
+- **`fn bind(host: char*, port: int) -> Result<TcpListener>`**
+  Creates a new listener bound to the specified host and port.
+
+- **`fn accept(self) -> Result<TcpStream>`**
+  Blocks waiting for a new connection. Returns a `TcpStream` for the connected client.
+
+- **`fn close(self)`**
+  Closes the listening socket.
+
+### Type `TcpStream`
+
+Represents a TCP connection stream.
+
+#### Methods
+
+- **`fn connect(host: char*, port: int) -> Result<TcpStream>`**
+  Connects to a remote host.
+
+- **`fn read(self, buf: char*, len: usize) -> Result<usize>`**
+  Reads up to `len` bytes into `buf`. Returns the number of bytes read.
+
+- **`fn write(self, buf: char*, len: usize) -> Result<usize>`**
+  Writes `len` bytes from `buf` to the stream. Returns the number of bytes written.
+
+- **`fn close(self)`**
+  Closes the connection.
diff --git a/docs/std/process.md b/docs/std/process.md
new file mode 100644
index 0000000..31485ee
--- /dev/null
+++ b/docs/std/process.md
@@ -0,0 +1,57 @@
+# Standard Library: Process (`std/process.zc`)
+
+The process module allows you to spawn and interact with child processes.
+
+## Usage
+
+```zc
+import "std/process.zc"
+
+fn main() {
+    let output = Command::new("echo")
+        .arg("hello")
+        .output();
+        
+    if (output.exit_code == 0) {
+        output.stdout.print();
+        // Or access raw C string: output.stdout.c_str()
+    }
+}
+```
+
+## Structs
+
+### Command
+
+A builder for spawning a process.
+
+```zc
+struct Command {
+    program: String;
+    args: Vec<String>;
+}
+```
+
+#### Methods
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| **new** | `Command::new(program: char*) -> Command` | Creates a new Command for the given program. |
+| **arg** | `arg(self, arg: char*) -> Command*` | Adds an argument to the command. Returns the command pointer for chaining. |
+| **output** | `output(self) -> Output` | Executes the command as a child process, waiting for it to finish and collecting all of its stdout. |
+| **status** | `status(self) -> int` | Executes the command as a child process and returns the exit status code. Does not capture output (output goes to stdout/stderr). |
+
+### Output
+
+The output of a finished process.
+
+```zc
+struct Output {
+    stdout: String;
+    exit_code: int;
+}
+```
+
+#### Methods
+
+`Output` implements `Drop` to automatically free the captured `stdout` string.
diff --git a/docs/std/set.md b/docs/std/set.md
new file mode 100644
index 0000000..0d62a66
--- /dev/null
+++ b/docs/std/set.md
@@ -0,0 +1,38 @@
+# Set (`std/set.zc`)
+
+The `std/set` module provides a Generic Hash Set `Set<T>`.
+
+## Usage
+
+```zc
+import "std/set.zc"
+```
+
+## Types
+
+### Struct `Set<T>`
+
+A set of unique elements.
+
+#### Methods
+
+- **`fn new() -> Set<T>`**
+  Creates a new empty set.
+
+- **`fn add(self, val: T) -> bool`**
+  Adds a value to the set. Returns `true` if the value was added, `false` if it was already present.
+
+- **`fn contains(self, val: T) -> bool`**
+  Returns `true` if the set contains the value.
+
+- **`fn remove(self, val: T) -> bool`**
+  Removes a value from the set. Returns `true` if present and removed.
+
+- **`fn length(self) -> usize`**
+  Returns the number of elements in the set.
+
+- **`fn is_empty(self) -> bool`**
+  Returns `true` if the set is empty.
+
+- **`fn clear(self)`**
+  Removes all elements from the set.
diff --git a/docs/std/slice.md b/docs/std/slice.md
new file mode 100644
index 0000000..f029995
--- /dev/null
+++ b/docs/std/slice.md
@@ -0,0 +1,93 @@
+# Standard Library: Slice (`std/slice.zc`)
+
+`Slice<T>` is a lightweight, non-owning view into a contiguous sequence of elements. It's particularly useful for working with fixed-size arrays and enabling iteration.
+
+## Usage
+
+```zc
+import "std/slice.zc"
+
+fn main() {
+    let arr: int[5] = [1, 2, 3, 4, 5];
+    
+    // Direct iteration (auto-imports std/slice.zc)
+    for val in arr {
+        println "{val}";
+    }
+    
+    // Manual slice creation
+    let slice = Slice<int>::from_array((int*)(&arr), 5);
+    for val in slice {
+        println "{val}";
+    }
+}
+```
+
+## Structure
+
+```zc
+struct Slice<T> {
+    data: T*;
+    len: usize;
+}
+```
+
+## Methods
+
+### Construction
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| **from_array** | `Slice<T>::from_array(arr: T*, len: usize) -> Slice<T>` | Creates a slice view over an array. |
+| **new** | `Slice<T>::new(data: T*, len: usize) -> Slice<T>` | Alias for `from_array` (backwards compat). |
+
+### Iteration
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| **iterator** | `iterator(self) -> SliceIter<T>` | Returns an iterator for `for-in` loops. |
+
+`SliceIter<T>` implements the iterator protocol with a `next() -> Option<T>` method.
+
+### Access & Query
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| **length** | `length(self) -> usize` | Returns the number of elements. |
+| **is_empty** | `is_empty(self) -> bool` | Returns true if length is 0. |
+| **get** | `get(self, idx: usize) -> Option<T>` | Returns the element at index, or None if out of bounds. |
+| **at** | `at(self, idx: usize) -> Option<T>` | Alias for `get`. |
+
+## Examples
+
+### Iterating over fixed-size arrays
+
+```zc
+// std/slice.zc is auto-imported when using for-in on arrays
+let numbers: int[3] = [10, 20, 30];
+
+for n in numbers {
+    println "Number: {n}";
+}
+```
+
+### Safe indexed access
+
+```zc
+import "std/slice.zc"
+
+let arr: int[3] = [1, 2, 3];
+let slice = Slice<int>::from_array((int*)(&arr), 3);
+
+let opt = slice.get(1);
+if (!opt.is_none()) {
+    println "Value: {opt.unwrap()}";  // Prints: Value: 2
+}
+```
+
+## Notes
+
+- `Slice<T>` does not own its data — it's just a view
+- No memory management needed (no `free()` method)
+- **Auto-import**: `std/slice.zc` is automatically imported when using `for val in arr` on a fixed-size array
+- The array pointer cast `(T*)(&arr)` is required for fixed-size arrays
diff --git a/docs/std/stack.md b/docs/std/stack.md
new file mode 100644
index 0000000..6e5da84
--- /dev/null
+++ b/docs/std/stack.md
@@ -0,0 +1,38 @@
+# Stack (`std/stack.zc`)
+
+The `std/stack` module provides a LIFO (Last-In, First-Out) stack data structure.
+
+## Usage
+
+```zc
+import "std/stack.zc"
+```
+
+## Types
+
+### Struct `Stack<T>`
+
+A generic stack.
+
+#### Methods
+
+- **`fn new() -> Stack<T>`**
+  Creates a new empty stack.
+
+- **`fn push(self, value: T)`**
+  Pushes a value onto the top of the stack.
+
+- **`fn pop(self) -> Option<T>`**
+  Removes and returns the top element of the stack. Returns `None` if empty.
+
+- **`fn length(self) -> usize`**
+  Returns the number of elements in the stack.
+
+- **`fn is_empty(self) -> bool`**
+  Returns `true` if the stack contains no elements.
+
+- **`fn clear(self)`**
+  Removes all elements from the stack.
+
+- **`fn clone(self) -> Stack<T>`**
+  Creates a deep copy of the stack.
diff --git a/docs/std/string.md b/docs/std/string.md
index 1f89e0f..a2f63f5 100644
--- a/docs/std/string.md
+++ b/docs/std/string.md
@@ -49,8 +49,12 @@ struct String {
 | Method | Signature | Description |
 | :--- | :--- | :--- |
 | **append** | `append(self, other: String*)` | Appends another string to this one. |
+| **append_c** | `append_c(self, s: char*)` | Appends a C string literal. Uses value receiver. |
+| **append_c_ptr** | `append_c_ptr(ptr: String*, s: char*)` | Appends a C string literal using pointer receiver for guaranteed mutation. |
 | **add** | `add(self, other: String*) -> String` | Concatenates this string and another into a new String. |
 
+**Note:** When passing `String*` to functions that need to mutate, use `append_c_ptr` instead of `append_c` for reliable mutation.
+
 ### Access & Query
 
 | Method | Signature | Description |
diff --git a/docs/std/thread.md b/docs/std/thread.md
new file mode 100644
index 0000000..6ac7e29
--- /dev/null
+++ b/docs/std/thread.md
@@ -0,0 +1,47 @@
+# Concurrency (`std/thread.zc`)
+
+The `std/thread` module provides primitives for multithreading and synchronization.
+
+## Usage
+
+```zc
+import "std/thread.zc"
+```
+
+## Functions
+
+- **`fn sleep_ms(ms: int)`**
+  Sleeps the current thread for the specified number of milliseconds.
+
+## Types
+
+### Type `Thread`
+
+Represents a handle to a spawned thread.
+
+#### Methods
+
+- **`fn spawn(func: fn()) -> Result<Thread>`**
+  Spawns a new thread executing the provided function.
+  > Note: Currently supports void functions with no arguments.
+
+- **`fn join(self) -> Result<bool>`**
+  Blocks the current thread until the spawned thread finishes.
+
+### Type `Mutex`
+
+A mutual exclusion primitive for protecting shared data.
+
+#### Methods
+
+- **`fn new() -> Mutex`**
+  Creates a new mutex.
+
+- **`fn lock(self)`**
+  Acquires the lock. Blocks if the lock is already held.
+
+- **`fn unlock(self)`**
+  Releases the lock.
+
+- **`fn free(self)`**
+  Destroys the mutex and frees associated resources.
diff --git a/docs/std/time.md b/docs/std/time.md
new file mode 100644
index 0000000..97dd208
--- /dev/null
+++ b/docs/std/time.md
@@ -0,0 +1,38 @@
+# Time (`std/time.zc`)
+
+The `std/time` module provides functionality for measuring time and sleeping.
+
+## Usage
+
+```zc
+import "std/time.zc"
+```
+
+## Structs
+
+### Struct `Duration`
+
+Represents a span of time in milliseconds.
+
+#### Methods
+
+- **`fn from_ms(ms: U64) -> Duration`**
+  Creates a duration from milliseconds.
+
+- **`fn from_secs(s: U64) -> Duration`**
+  Creates a duration from seconds.
+
+### Struct `Time`
+
+Utilities for time manipulation.
+
+#### Methods
+
+- **`fn now() -> U64`**
+  Returns the current system time in milliseconds since the epoch.
+
+- **`fn sleep(d: Duration)`**
+  Sleeps for the specified duration.
+
+- **`fn sleep_ms(ms: U64)`**
+  Sleeps for the specified number of milliseconds.