@shd101wyy/yo 0.1.12 → 0.1.13

package/std/process.yo

@@ -1,5 +1,4 @@
-// Process Module
-// Provides access to process information and command-line arguments
+//! Process information, command-line arguments, environment variables, and platform detection.
 
 open import "./collections/array_list";
 open import "./string";
@@ -7,19 +6,12 @@ open import "./path";
 { GlobalAllocator } :: import "./allocator";
 { malloc, free } :: GlobalAllocator;
 
-/**
- * Target platform for the current compilation.
- * Uses standard naming:
- * - "linux"
- * - "macos"
- * - "windows"
- * - "freebsd"
- * - "emscripten"
- * - "wasi"
- */
+/// Current target platform as a compile-time string.
+/// One of: "linux", "macos", "windows", "freebsd", "emscripten", "wasi".
 platform :: __yo_process_platform();
 export platform;
 
+/// Platform constants for compile-time platform comparisons.
 Platform :: {
   Linux : "linux",
   Macos : "macos",
@@ -30,18 +22,12 @@ Platform :: {
 };
 export Platform;
 
-/**
- * Target architecture for the current compilation.
- * Uses standard naming:
- * - "x86_64"
- * - "aarch64"
- * - "x86"
- * - "arm"
- * - "wasm32"
- */
+/// Current target architecture as a compile-time string.
+/// One of: "x86_64", "aarch64", "x86", "arm", "wasm32".
 arch :: __yo_process_arch();
 export arch;
 
+/// Architecture constants for compile-time architecture comparisons.
 Arch :: {
   X86_64 : "x86_64",
   Aarch64 : "aarch64",
@@ -62,21 +48,20 @@ extern "Yo",
 
 // === Raw command-line arguments ===
 
-// Returns the raw command-line arguments as a slice of C strings
-// The first element is the program name
-// Example: ["./program", "arg1", "arg2"]
+/// Get raw command-line arguments as a slice of C strings.
+/// The first element is the program name.
 raw_args :: (fn() -> [*(u8)]) {
   return __yo_args;
 };
 export raw_args;
 
-// Returns the number of command-line arguments (including program name)
+/// Get the number of command-line arguments (including program name).
 argc :: (fn() -> i32) {
   return __yo_argc;
 };
 export argc;
 
-// Return the argv u8** pointer
+/// Get the raw `argv` pointer (`*(*(u8))`).
 argv :: (fn() -> *(*(u8))) {
   return __yo_argv;
 };
@@ -84,9 +69,8 @@ export argv;
 
 // === Convenient command-line arguments ===
 
-// Returns command-line arguments as an ArrayList of Strings
-// The first element is the program name
-// Example: [String("./program"), String("arg1"), String("arg2")]
+/// Get command-line arguments as an `ArrayList(String)`.
+/// The first element is the program name.
 args :: (fn() -> ArrayList(String)) {  
   raw := raw_args();
   i := usize(0);
@@ -104,9 +88,12 @@ args :: (fn() -> ArrayList(String)) {
 };
 export args;
 
+/// Environment variable access and manipulation.
 env :: impl {
   { getenv, setenv } :: import "./libc/stdlib";
 
+  /// Get the value of an environment variable by name.
+  /// Returns `.None` if the variable is not set.
   get :: (fn(name : String) -> Option(String)) {  
     name_cstr := name.to_cstr().ptr().unwrap();
     val_ptr := getenv(*(char)(name_cstr));
@@ -117,6 +104,8 @@ env :: impl {
   };
   export get;
 
+  /// Set an environment variable. If `overwrite` is false and the variable
+  /// already exists, it is not modified. Returns true on success.
   set :: (fn(name : String, value : String, (overwrite : bool) ?= true) -> bool) {
     name_cstr := name.to_cstr().ptr().unwrap();
     value_cstr := value.to_cstr().ptr().unwrap();
@@ -156,10 +145,8 @@ env :: impl {
 };
 export env;
 
-/**
- * Get the current working directory at runtime.
- * Returns a Result with the current directory as a Path, or an error message.
- */
+/// Get the current working directory as a `Path`.
+/// Returns `Err` with a message on failure.
 cwd :: (fn() -> Result(Path, String))(
   cond(
     (platform == Platform.Windows) => {
@@ -265,10 +252,8 @@ cwd :: (fn() -> Result(Path, String))(
 );
 export cwd;
 
-/**
- * Change the current working directory.
- * Returns Ok(()) on success, or an error message on failure.
- */
+/// Change the current working directory to `path`.
+/// Returns `Ok(())` on success, or `Err` with a message on failure.
 chdir :: (fn(path: Path) -> Result(unit, String))(
   cond(
     (platform == Platform.Windows) => {
@@ -301,6 +286,7 @@ chdir :: (fn(path: Path) -> Result(unit, String))(
 );
 export chdir;
 
+/// Exit the process with the given status code.
 exit :: (fn(code : usize) -> unit) {
   { exit : _exit } :: import "./libc/stdlib";
   _exit(int(code));

package/std/regex/compiler.yo

@@ -1,13 +1,11 @@
-// std/regex/compiler.yo - NFA compiler
-//
-// Compiles a RegexNode AST into a flat list of NFA instructions
-// using Thompson's construction algorithm.
+//! NFA compiler — compiles a `RegexNode` AST into a flat list of NFA instructions
+//! using Thompson's construction algorithm.
 
 open import "std/collections/array_list";
 open import "std/string";
 { RegexNode, NodeKind, CharRange, AnchorKind, GroupNameEntry } :: import "./node.yo";
 
-// NFA instruction types
+/// NFA instruction types.
 InstrKind :: enum(
   Char,
   CharClass,

package/std/regex/flags.yo

@@ -1,14 +1,14 @@
-// std/regex/flags.yo - RegexFlags parsing and representation
-//
-// Regex flags follow JavaScript syntax: "gi", "ms", "iu", etc.
-//
-// Supported flags:
-//   g - global: match all occurrences
-//   i - ignoreCase: case-insensitive matching
-//   m - multiline: ^ and $ match line boundaries
-//   s - dotAll: . matches newline characters
-//   u - unicode: full Unicode matching
-//   y - sticky: match from lastIndex only
+//! Regex flags parsing and representation.
+//!
+//! Regex flags follow JavaScript syntax: `"gi"`, `"ms"`, `"iu"`, etc.
+//!
+//! Supported flags:
+//! - `g` — global: match all occurrences
+//! - `i` — ignoreCase: case-insensitive matching
+//! - `m` — multiline: `^` and `$` match line boundaries
+//! - `s` — dotAll: `.` matches newline characters
+//! - `u` — unicode: full Unicode matching
+//! - `y` — sticky: match from lastIndex only
 
 open import "std/string";
 open import "std/collections/array_list";

package/std/regex/index.yo

@@ -1,15 +1,4 @@
-// std/regex - Regular expression engine
-//
-// High-level regex API similar to JavaScript's RegExp.
-//
-// Example:
-//   { Regex } :: import "std/regex";
-//   re := Regex.new(`\\d+`).unwrap();
-//   m := re.exec(`abc123def`);
-//   match(m,
-//     .Some(result) => println(result.value()),
-//     .None => println(`no match`)
-//   );
+//! Regular expression engine with an NFA-based virtual machine.
 
 open import "std/collections/array_list";
 open import "std/string";
@@ -19,7 +8,7 @@ open import "std/string";
 { RegexFlags } :: import "./flags.yo";
 { RegexMatch } :: import "./match.yo";
 
-// The Regex type: a compiled regular expression
+/// Compiled regular expression backed by an NFA program.
 Regex :: object(
   _program     : NfaProgram,
   _flags       : RegexFlags,

package/std/regex/match.yo

@@ -1,13 +1,11 @@
-// std/regex/match.yo - Match result type
-//
-// Represents the result of a regex match, including the matched text,
-// position, and captured groups.
+//! Match result type — represents the result of a regex match,
+//! including the matched text, position, and captured groups.
 
 open import "std/collections/array_list";
 open import "std/string";
 { GroupNameEntry } :: import "./node.yo";
 
-// A single regex match result
+/// A single regex match result.
 RegexMatch :: object(
   _value       : String,
   _index       : usize,

package/std/regex/node.yo

@@ -1,13 +1,13 @@
-// std/regex/node.yo - Regex AST node types
-//
-// The parser produces a tree of RegexNode objects representing the
-// structure of a regex pattern. Nodes are reference-counted objects
-// since they form a recursive tree.
+//! Regex AST node types.
+//!
+//! The parser produces a tree of `RegexNode` objects representing the
+//! structure of a regex pattern. Nodes are reference-counted objects
+//! since they form a recursive tree.
 
 open import "std/collections/array_list";
 open import "std/string";
 
-// A range of characters for character classes, e.g. 'a'-'z'
+/// A range of characters for character classes, e.g. `a`–`z`.
 CharRange :: struct(
   low  : u32,
   high : u32

package/std/regex/parser.yo

@@ -1,7 +1,5 @@
-// std/regex/parser.yo - Regex pattern parser
-//
-// Parses a regex pattern string into an AST of RegexNode objects.
-// Uses an iterative stack-based approach to avoid mutual recursion.
+//! Regex pattern parser — parses a regex pattern string into an AST
+//! of `RegexNode` objects. Uses an iterative stack-based approach.
 
 open import "std/collections/array_list";
 open import "std/string";

package/std/regex/unicode.yo

@@ -1,8 +1,8 @@
-// std/regex/unicode.yo - Unicode property ranges for \p{...} support
-//
-// Provides character ranges for common Unicode general categories.
-// Uses compact range representation covering the most commonly used
-// Unicode blocks. Not exhaustive but covers practical use cases.
+//! Unicode property ranges for `\p{...}` support.
+//!
+//! Provides character ranges for common Unicode general categories.
+//! Uses compact range representation covering the most commonly used
+//! Unicode blocks. Not exhaustive but covers practical use cases.
 
 open import "std/collections/array_list";
 open import "std/string";

package/std/regex/vm.yo

@@ -1,8 +1,8 @@
-// std/regex/vm.yo - NFA virtual machine (Thompson simulation)
-//
-// Executes a compiled NFA program against an input string.
-// Uses Thompson's NFA simulation with parallel state tracking
-// for O(n*m) worst-case time complexity.
+//! NFA virtual machine (Thompson simulation).
+//!
+//! Executes a compiled NFA program against an input string.
+//! Uses Thompson's NFA simulation with parallel state tracking
+//! for O(n×m) worst-case time complexity.
 
 open import "std/collections/array_list";
 open import "std/string";

package/std/string/index.yo

@@ -1,4 +1,5 @@
-// other data types
+//! String and Unicode types.
+
 _rune :: import "./rune.yo";
 _string :: import "./string.yo";
 

package/std/string/rune.yo

@@ -1,7 +1,13 @@
+//! Unicode code point type (`rune`) for representing individual characters.
+
+/// Unicode code point (U+0000 to U+10FFFF, excluding surrogates).
+/// Similar to Go's `rune` or Rust's `char`.
 rune :: newtype(
+  /// The raw Unicode code point value.
   char : u32
 );
 impl(rune,
+  /// Create a rune from a `u32` value, returning `None` if the value is not a valid Unicode code point.
   from_u32 : (fn(value: u32) -> Option(Self))(
     cond(
       ((value <= u32(0x10FFFF)) && (((value < 0xD800) || (value > 0xDFFF)))) => .Some(Self(value)),
@@ -9,34 +15,42 @@ impl(rune,
     )
   ),
 
+  /// Return the raw `u32` code point value.
   to_u32 : (fn(self: Self) -> u32)(
     self.char
   ),
 
+  /// Check if this is an ASCII character (U+0000 to U+007F).
   is_ascii : (fn(self: Self) -> bool)(
     (self.char <= 0x7F)
   ),
 
+  /// Check if this is a whitespace character (space, tab, newline, or carriage return).
   is_whitespace : (fn(self: Self) -> bool)(
     (((self.char == 0x20) || (self.char == 0x09)) || ((self.char == 0x0A) || (self.char == 0x0D)))
   ),
 
+  /// Check if this is an ASCII digit ('0' to '9').
   is_digit : (fn(self: Self) -> bool)(
     ((self.char >= 0x30) && (self.char <= 0x39))
   ),
 
+  /// Check if this is an ASCII letter ('A'-'Z' or 'a'-'z').
   is_alphabetic : (fn(self: Self) -> bool)(
     (((self.char >= 0x41) && (self.char <= 0x5A)) || ((self.char >= 0x61) && (self.char <= 0x7A)))
   ),
 
+  /// Check if this is an ASCII uppercase letter ('A'-'Z').
   is_uppercase : (fn(self: Self) -> bool)(
     ((self.char >= 0x41) && (self.char <= 0x5A))
   ),
 
+  /// Check if this is an ASCII lowercase letter ('a'-'z').
   is_lowercase : (fn(self: Self) -> bool)(
     ((self.char >= 0x61) && (self.char <= 0x7A))
   ),
 
+  /// Convert to lowercase. Only affects ASCII uppercase letters.
   to_lowercase : (fn(self: Self) -> Self)(
     cond(
       is_uppercase(self) => Self((self.char + 32)),
@@ -44,6 +58,7 @@ impl(rune,
     )
   ),
 
+  /// Convert to uppercase. Only affects ASCII lowercase letters.
   to_uppercase : (fn(self: Self) -> Self)(
     cond(
       is_lowercase(self) => Self((self.char - 32)),
@@ -51,16 +66,25 @@ impl(rune,
     )
   ),
 
-  // Some constants
+  /// Null character (U+0000).
   NUL        : Self(0x00),
+  /// Horizontal tab (U+0009).
   TAB        : Self(0x09),
+  /// Line feed / newline (U+000A).
   NEWLINE    : Self(0x0A),
+  /// Space (U+0020).
   SPACE      : Self(0x20),
+  /// Digit zero '0' (U+0030).
   ZERO       : Self(0x30),
+  /// Digit nine '9' (U+0039).
   NINE       : Self(0x39),
+  /// Uppercase 'A' (U+0041).
   UPPERCASE_A : Self(0x41),
+  /// Uppercase 'Z' (U+005A).
   UPPERCASE_Z : Self(0x5A),
+  /// Lowercase 'a' (U+0061).
   LOWERCASE_A : Self(0x61),
+  /// Lowercase 'z' (U+007A).
   LOWERCASE_Z : Self(0x7A)
 );
 

package/std/string/string.yo

@@ -1,21 +1,20 @@
+//! Immutable UTF-8 string type with comprehensive operations.
+
 { ArrayList } :: import "../collections/array_list.yo";
 { rune } :: import "./rune.yo";
 { memcpy, memcmp, strlen } :: import "../libc/string.yo";
 
+/// String operation error variants.
 StringError :: enum(
+  /// The input bytes are not valid UTF-8.
   InvalidUtf8,
+  /// The index is out of bounds for the string's byte length.
   IndexOutOfBounds(index: usize, length: usize)
 );
 
-/**
- * String - Immutable UTF-8 encoded string
- * 
- * Similar to JavaScript String, Python str, and Rust String.
- * Strings are immutable - all operations return new strings.
- * 
- * Internal storage uses Option(ArrayList(u8)) for UTF-8 bytes.
- * An empty string is represented as .None (zero allocation).
- */
+/// Immutable UTF-8 encoded string.
+/// All operations return new strings; mutable operations require a pointer to self.
+/// Empty strings use zero allocation (represented as `Option.None` internally).
 String :: newtype(
   _bytes: Option(ArrayList(u8))
 );
@@ -82,6 +81,8 @@ impl(String,
     return .Ok(Self(_bytes: .Some(bytes)));
   }),
 
+  /// Convert the string to a null-terminated C string.
+  /// Returns an `ArrayList(u8)` with the string bytes followed by a `\0`.
   to_cstr : (fn(self: Self) -> ArrayList(u8))({
     (bytes_len : usize) = match(self._bytes,
       .Some(b) => b.len(),
@@ -318,7 +319,7 @@ impl(String,
     return Self(_bytes: .Some(new_bytes));
   }),
 
-  // Append another String to this String in-place (mutates self)
+  /// Append another `String` to this string in-place (mutates `self`).
   push_string : (fn(self: *(Self), other: Self) -> unit)({
     (olen : usize) = match(other._bytes, .Some(b) => b.len(), .None => usize(0));
     if((olen > usize(0)), {
@@ -343,6 +344,7 @@ impl(String,
     });
   }),
 
+  /// Append a `str` slice to this string in-place (mutates `self`).
   push_str : (fn(self: *(Self), s: str) -> unit)({
     (slen : usize) = s.len();
     if((slen > usize(0)), {
@@ -359,6 +361,8 @@ impl(String,
     });
   }),
 
+  /// Append a single byte to this string in-place (mutates `self`).
+  /// The caller must ensure the byte maintains valid UTF-8.
   push_byte : (fn(self: *(Self), b: u8) -> unit)({
     match(self.*._bytes,
       .None => {
@@ -372,6 +376,8 @@ impl(String,
     );
   }),
 
+  /// Reserve capacity for at least `additional` more bytes.
+  /// If the string is empty, creates a new buffer with the given capacity.
   reserve : (fn(self: *(Self), additional: usize) -> unit)({
     match(self.*._bytes,
       .None => {
@@ -384,7 +390,7 @@ impl(String,
     );
   }),
 
-  // Clear the string content but keep the allocated buffer for reuse
+  /// Clear the string content but keep the allocated buffer for reuse.
   clear : (fn(self: *(Self)) -> unit)(
     match(self.*._bytes,
       .Some(al) => al.clear(),
@@ -392,7 +398,7 @@ impl(String,
     )
   ),
 
-  // Create a deep copy of this string with its own buffer
+  /// Create a deep copy of this string with its own buffer.
   clone : (fn(self: Self) -> Self)(
     match(self._bytes,
       .None => Self(_bytes: .None),
@@ -407,7 +413,8 @@ impl(String,
     )
   ),
 
-  // Get the number of bytes in the string (not Unicode characters)
+  /// Get the number of bytes in the string (not Unicode characters).
+  /// Use `len()` for Unicode character count.
   bytes_len : (fn(self: Self) -> usize)(
     match(self._bytes, .Some(b) => b.len(), .None => usize(0))
   ),
@@ -1393,6 +1400,7 @@ impl(String,
   )
 );
 
+/// Add trait implementation — concatenate two strings with `+`.
 impl(String, Add(String)(
   Output : String,
   (+) : (fn(self: Self, other: Self) -> Self.Output)({
@@ -1400,6 +1408,7 @@ impl(String, Add(String)(
   })
 ));
 
+/// Eq trait implementation — byte-level comparison of two strings.
 impl(String, Eq(String)(
   (==) : (fn(self: Self, other: Self) -> bool)({
     (self_len : usize) = match(self._bytes, .Some(b) => b.len(), .None => usize(0));
@@ -1433,6 +1442,7 @@ impl(String, Eq(String)(
   })
 ));
 
+/// Hash trait implementation — FNV-1a hash over the string's bytes.
 impl(String, Hash(
   (hash): (fn(self: *(Self)) -> u64)({
     h := u64(14695981039346656037);
@@ -1458,11 +1468,11 @@ impl(String, Hash(
   })
 ));
 
-// === Iterator support ===
+/// === Iterator support ===
 
 /**
- * Rune iterator for String - yields decoded Unicode runes
- * Used by chars() and into_iter()
+ * Rune iterator for `String` — yields decoded Unicode runes.
+ * Used by `chars()` and `into_iter()`.
  */
 StringChars :: struct(
   _string     : String,
@@ -1500,8 +1510,8 @@ impl(StringChars, Iterator(
 ));
 
 /**
- * Byte iterator for String - yields raw UTF-8 bytes
- * Used by bytes()
+ * Byte iterator for `String` — yields raw UTF-8 bytes.
+ * Used by `bytes()`.
  */
 StringBytes :: struct(
   _string : String,
@@ -1548,7 +1558,7 @@ impl(String,
   )
 );
 
-// === Numeric parsing methods ===
+/// === Numeric parsing methods ===
 
 impl(String,
   /**
@@ -1910,6 +1920,8 @@ impl(String,
   )
 );
 
+/// Index trait implementation — access a single byte by index.
+/// Panics if the string is empty.
 impl(String, Index(usize)(
   Output : u8,
   index : (fn(self: *(Self), idx: usize) -> *(Self.Output))(

package/std/string/unicode.yo

@@ -1,14 +1,13 @@
-// Unicode-aware case conversion
-//
-// Provides Unicode-aware lowercase/uppercase conversion using C's towlower/towupper,
-// plus hand-coded tables for special case folding entries where one codepoint
-// maps to multiple codepoints.
-//
-// Example:
-//   { unicode_to_lowercase, unicode_to_uppercase } :: import "std/string/unicode";
-//
-//   lower := unicode_to_lowercase(`HELLO WÖRLD`);  // "hello wörld"
-//   upper := unicode_to_uppercase(`hello wörld`);  // "HELLO WÖRLD"
+//! Unicode-aware case conversion using full case folding rules.
+//!
+//! # Example
+//!
+//! ```rust
+//! { unicode_to_lowercase, unicode_to_uppercase } :: import "std/string/unicode";
+//!
+//! lower := unicode_to_lowercase(`HELLO WÖRLD`);  // "hello wörld"
+//! upper := unicode_to_uppercase(`hello wörld`);  // "HELLO WÖRLD"
+//! ```
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";
@@ -164,8 +163,8 @@ _special_to_upper :: (fn(cp: i32, out: *(ArrayList(u8))) -> bool)({
 });
 
 // Convert a String to lowercase using Unicode-aware case mapping.
-// Handles both ASCII and non-ASCII codepoints via C's towlower,
-// plus special multi-char expansions (e.g., ẞ → ss).
+/// Convert a `String` to lowercase using Unicode case mapping rules.
+/// Handles both ASCII and non-ASCII codepoints, plus special multi-char expansions (e.g., ẞ → ss).
 unicode_to_lowercase :: (fn(input: String) -> String)({
   (bytes : ArrayList(u8)) = input.as_bytes();
   (out : ArrayList(u8)) = ArrayList(u8).with_capacity(bytes.len());
@@ -202,8 +201,8 @@ unicode_to_lowercase :: (fn(input: String) -> String)({
 });
 
 // Convert a String to uppercase using Unicode-aware case mapping.
-// Handles both ASCII and non-ASCII codepoints via C's towupper,
-// plus special multi-char expansions (e.g., ß → SS, ligatures).
+/// Convert a `String` to uppercase using Unicode case mapping rules.
+/// Handles both ASCII and non-ASCII codepoints, plus special multi-char expansions (e.g., ß → SS).
 unicode_to_uppercase :: (fn(input: String) -> String)({
   (bytes : ArrayList(u8)) = input.as_bytes();
   (out : ArrayList(u8)) = ArrayList(u8).with_capacity(bytes.len());

package/std/sync/channel.yo

@@ -1,36 +1,26 @@
-// std/sync/channel.yo - Bounded multi-producer multi-consumer channel
-//
-// A thread-safe channel for sending values between threads and workers.
-// Uses Mutex + Cond internally — does NOT require async/await or IO effect.
-//
-// Design rationale:
-//   Channel uses blocking send/recv via condition variables rather than
-//   async/await. This is intentional:
-//   - Works with both Thread and Worker without requiring an IO effect context
-//   - Simpler mental model: send blocks when full, recv blocks when empty
-//   - Channel is a synchronization primitive, not an I/O operation
-//   - For async usage, wrap Channel.recv in io.async() if needed
-//
-// Example:
-//   { Channel } :: import "std/sync/channel";
-//   { Thread } :: import "std/thread";
-//
-//   ch := Channel(i32).new(usize(10));
-//   t := Thread.spawn(() => {
-//     ch.send(i32(42));
-//   });
-//   val := ch.recv();   // blocks until data available
-//   assert((val.unwrap() == i32(42)), "received value");
-//   t.join();
+//! Bounded multi-producer multi-consumer (MPMC) channel.
+//! Uses blocking send/recv via condition variables — does not require IO.
+//!
+//! # Example
+//!
+//! ```rust
+//! { Channel } :: import "std/sync/channel";
+//! { Thread } :: import "std/thread";
+//!
+//! ch := Channel(i32).new(usize(10));
+//! t := Thread.spawn(() => {
+//!   ch.send(i32(42));
+//! });
+//! val := ch.recv();   // blocks until data available
+//! assert((val.unwrap() == i32(42)), "received value");
+//! t.join();
+//! ```
 
 { Deque } :: import "../collections/deque";
 { Mutex } :: import "./mutex";
 { Cond } :: import "./cond";
 
-// ============================================================================
-// Channel - Bounded MPMC channel
-// ============================================================================
-
+/// Thread-safe bounded channel for passing values between threads.
 Channel :: (fn(comptime(T) : Type) -> comptime(Type))
   object(
     _buf      : Deque(T),