@shd101wyy/yo 0.1.13 → 0.1.14

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shd101wyy/yo",
   "displayName": "Yo",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "main": "./out/cjs/index.cjs",
   "module": "./out/esm/index.mjs",
   "types": "./out/types/src/index.d.ts",

package/scripts/build-site.ts

@@ -75,6 +75,42 @@ function escapeHtml(s: string): string {
  * - `https://shd101wyy.github.io/Yo/` → `std/index.html` (relative, same site)
  * - `#anchor` links → kept as-is
  */
+/**
+ * Generate a GitHub-compatible slug from heading text.
+ * - Strip HTML tags
+ * - Lowercase
+ * - Replace spaces with hyphens
+ * - Remove non-alphanumeric characters (except hyphens)
+ */
+function slugify(text: string): string {
+  return text
+    .replace(/<[^>]+>/g, "") // strip HTML tags
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, "-")
+    .replace(/[^a-z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+/**
+ * Add `id` attributes to heading elements so that #anchor links work.
+ * Handles duplicate slugs by appending `-1`, `-2`, etc.
+ */
+function injectHeadingIds(html: string): string {
+  const slugCounts = new Map<string, number>();
+  return html.replace(
+    /<(h[1-6])>([\s\S]*?)<\/\1>/gi,
+    (_match: string, tag: string, content: string) => {
+      let slug = slugify(content);
+      const count = slugCounts.get(slug) ?? 0;
+      slugCounts.set(slug, count + 1);
+      if (count > 0) slug = `${slug}-${count}`;
+      return `<${tag} id="${slug}">${content}</${tag}>`;
+    }
+  );
+}
+
 function rewriteReadmeLinks(html: string): string {
   // Rewrite the generated docs link to relative std/ path (same site)
   html = html.replace(
@@ -383,6 +419,7 @@ async function main(): Promise<void> {
   });
 
   let readmeHtml = md.render(readmeSrc);
+  readmeHtml = injectHeadingIds(readmeHtml);
   readmeHtml = rewriteReadmeLinks(readmeHtml);
 
   const css = generateHomepageCSS();

package/std/build.yo

@@ -18,13 +18,17 @@
 
 /// Optimization level for compiled artifacts.
 Optimize :: enum(
-  /// No optimizations, full debug info.
+  /// No optimizations, full debug info.  
+  /// Compiler Flags: `-O0 -g`
   Debug,
-  /// Optimized with safety checks.
+  /// Optimized with safety checks.  
+  /// Compiler Flags: `-O2 -g`
   ReleaseSafe,
-  /// Maximum speed optimizations.
+  /// Maximum speed optimizations.  
+  /// Compiler Flags: `-O3`
   ReleaseFast,
-  /// Optimize for binary size.
+  /// Optimize for binary size.  
+  /// Compiler Flags `-O2`
   ReleaseSmall
 );
 export Optimize;

package/std/encoding/base64.yo

@@ -1,10 +1,13 @@
 //! Base64 encoding and decoding (RFC 4648) with standard and URL-safe variants.
 //!
-//! Example:
-//!   { base64_encode, base64_decode } :: import "std/encoding/base64";
+//! # Example
 //!
-//!   s := base64_encode(data);
-//!   b := base64_decode(s.to_str()).unwrap();
+//! ```rust
+//! { base64_encode, base64_decode } :: import "std/encoding/base64";
+//!
+//! s := base64_encode(data);
+//! b := base64_decode(s.to_str()).unwrap();
+//! ```
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";

package/std/encoding/hex.yo

@@ -2,11 +2,14 @@
 //!
 //! Converts between raw bytes (`ArrayList(u8)`) and hex strings.
 //!
-//! Example:
-//!   { hex_encode, hex_decode } :: import "std/encoding/hex";
+//! # Example
 //!
-//!   s := hex_encode(data);         // "deadbeef"
-//!   b := hex_decode("deadbeef");
+//! ```rust
+//! { hex_encode, hex_decode } :: import "std/encoding/hex";
+//!
+//! s := hex_encode(data);         // "deadbeef"
+//! b := hex_decode("deadbeef");
+//! ```
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";

package/std/encoding/html.yo

@@ -3,11 +3,14 @@
 //! Decodes named (&), decimal (&), and hex (&) HTML character references.
 //! Uses Legacy mode — entities without trailing semicolon are also decoded.
 //!
-//! Example:
-//!   { decode_html } :: import "std/encoding/html";
+//! # Example
 //!
-//!   result := decode_html(`& < & &`);
-//!   assert((result == `& < & &`), "decoded entities");
+//! ```rust
+//! { decode_html } :: import "std/encoding/html";
+//!
+//! result := decode_html(`&amp; &lt; &#38; &#x26;`);
+//! assert((result == `& < & &`), "decoded entities");
+//! ```
 
 open import "../string";
 { HashMap } :: import "../collections/hash_map";

package/std/encoding/json.yo

@@ -2,13 +2,16 @@
 //!
 //! Provides a dynamically-typed JSON value tree.
 //!
-//! Example:
-//!   { json_parse, json_stringify, JsonValue } :: import "std/encoding/json";
-//!   { Exception } :: import "std/error";
+//! # Example
 //!
-//!   given(exn) := Exception(throw : ((err) -> { escape (); }));
-//!   v := json_parse(`{"x": 1}`);
-//!   println(json_stringify(v));
+//! ```rust
+//! { json_parse, json_stringify, JsonValue } :: import "std/encoding/json";
+//! { Exception } :: import "std/error";
+//!
+//! given(exn) := Exception(throw : ((err) -> { escape (); }));
+//! v := json_parse(`{"x": 1}`);
+//! println(json_stringify(v));
+//! ```
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";

package/std/encoding/punycode.yo

@@ -2,13 +2,16 @@
 //!
 //! Provides punycode encoding/decoding and IDN hostname conversion.
 //!
-//! Example:
-//!   { punycode_decode, punycode_encode, to_unicode, to_ascii } :: import "std/encoding/punycode";
+//! # Example
 //!
-//!   encoded := punycode_encode(`München`);
-//!   decoded := punycode_decode(encoded);
-//!   ascii_domain := to_ascii(`münchen.de`);  // "xn--mnchen-3ya.de"
-//!   unicode_domain := to_unicode(ascii_domain);  // "münchen.de"
+//! ```rust
+//! { punycode_decode, punycode_encode, to_unicode, to_ascii } :: import "std/encoding/punycode";
+//!
+//! encoded := punycode_encode(`München`);
+//! decoded := punycode_decode(encoded);
+//! ascii_domain := to_ascii(`münchen.de`);  // "xn--mnchen-3ya.de"
+//! unicode_domain := to_unicode(ascii_domain);  // "münchen.de"
+//! ```
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";

package/std/encoding/toml.yo

@@ -3,10 +3,13 @@
 //! Parses a subset of TOML into a `TomlValue` tree.
 //! Supports: strings, integers, booleans, table sections, comments.
 //!
-//! Example:
-//!   { toml_parse, TomlValue } :: import "std/encoding/toml";
-//!   // Or via the encoding index:
-//!   { toml_parse, TomlValue } :: import "std/encoding";
+//! # Example
+//!
+//! ```rust
+//! { toml_parse, TomlValue } :: import "std/encoding/toml";
+//! // Or via the encoding index:
+//! { toml_parse, TomlValue } :: import "std/encoding";
+//! ```
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";

package/std/encoding/utf16.yo

@@ -2,11 +2,14 @@
 //!
 //! Converts between Yo's UTF-8 `str` and UTF-16 code units (`ArrayList(u16)`).
 //!
-//! Example:
-//!   { utf8_to_utf16, utf16_to_utf8 } :: import "std/encoding/utf16";
+//! # Example
 //!
-//!   words := utf8_to_utf16("hello");
-//!   s := utf16_to_utf8(words);
+//! ```rust
+//! { utf8_to_utf16, utf16_to_utf8 } :: import "std/encoding/utf16";
+//!
+//! words := utf8_to_utf16("hello");
+//! s := utf16_to_utf8(words);
+//! ```
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";

package/std/fs/dir.yo

@@ -2,21 +2,24 @@
 //!
 //! Wraps low-level `std/sys/dir` with typed APIs using the `Exception` effect.
 //!
-//! Example:
-//!   { create_dir, remove_dir, read_dir } :: import "std/fs/dir";
-//!   { Path } :: import "std/path";
+//! # Example
 //!
-//!   main :: (fn(using(io : IO)) -> unit)({
-//!     given(exn) : Exception = {
-//!       throw : (fn(forall(T : Type), error: AnyError) -> T)(
-//!         { println(error.to_string()); exit(i32(1)); }
-//!       )
-//!     };
+//! ```rust
+//! { create_dir, remove_dir, read_dir } :: import "std/fs/dir";
+//! { Path } :: import "std/path";
 //!
-//!     io.await(create_dir(Path.new(`/tmp/yo_test`)));
-//!     entries := io.await(read_dir(Path.new(`/tmp/yo_test`)));
-//!     io.await(remove_dir(Path.new(`/tmp/yo_test`)));
-//!   });
+//! main :: (fn(using(io : IO)) -> unit)({
+//!   given(exn) : Exception = {
+//!     throw : (fn(forall(T : Type), error: AnyError) -> T)(
+//!       { println(error.to_string()); exit(i32(1)); }
+//!     )
+//!   };
+//!
+//!   io.await(create_dir(Path.new(`/tmp/yo_test`)));
+//!   entries := io.await(read_dir(Path.new(`/tmp/yo_test`)));
+//!   io.await(remove_dir(Path.new(`/tmp/yo_test`)));
+//! });
+//! ```
 
 { GlobalAllocator } :: import "../allocator";
 { malloc, free } :: GlobalAllocator;

package/std/fs/file.yo

@@ -3,26 +3,29 @@
 //! Wraps a file descriptor with typed async I/O operations.
 //! Uses the `Exception` effect for error handling.
 //!
-//! Example:
-//!   { File, read_string, write_file, OpenMode } :: import "std/fs/file";
+//! # Example
 //!
-//!   main :: (fn(using(io : IO)) -> unit)({
-//!     given(exn) := Exception(
-//!       throw : (fn(forall(T : Type), error: AnyError) -> T)(
-//!         { println(error); panic("Exception found."); }
-//!       )
-//!     );
+//! ```rust
+//! { File, read_string, write_file, OpenMode } :: import "std/fs/file";
 //!
-//!     // Write a file
-//!     io.await(write_file(Path.new(`test.txt`), `hello world`));
+//! main :: (fn(using(io : IO)) -> unit)({
+//!   given(exn) := Exception(
+//!     throw : (fn(forall(T : Type), error: AnyError) -> T)(
+//!       { println(error); panic("Exception found."); }
+//!     )
+//!   );
 //!
-//!     // Read it back
-//!     content := io.await(read_string(Path.new(`test.txt`)));
-//!     println(content);
+//!   // Write a file
+//!   io.await(write_file(Path.new(`test.txt`), `hello world`));
 //!
-//!     // Open with OpenMode
-//!     f := io.await(File.open(Path.new(`test.txt`), .Read));
-//!   });
+//!   // Read it back
+//!   content := io.await(read_string(Path.new(`test.txt`)));
+//!   println(content);
+//!
+//!   // Open with OpenMode
+//!   f := io.await(File.open(Path.new(`test.txt`), .Read));
+//! });
+//! ```
 
 { GlobalAllocator } :: import "../allocator";
 { malloc, free } :: GlobalAllocator;

package/std/http/client.yo

@@ -245,9 +245,12 @@ _read_http_response :: (fn(stream: TcpStream, using(io : IO, exn : Exception)) -
 
 /// Perform an HTTP request with custom options.
 ///
-/// Example:
-///   opts := FetchOptions.new().with_method(.POST).with_body(`{"key": "value"}`);
-///   resp := io.await(fetch_with(`http://example.com/api`, opts, using(io)));
+/// # Example
+///
+/// ```rust
+/// opts := FetchOptions.new().with_method(.POST).with_body(`{"key": "value"}`);
+/// resp := io.await(fetch_with(`http://example.com/api`, opts, using(io)));
+/// ```
 fetch_with :: (fn(url_str: String, opts: FetchOptions, using(io : IO)) ->
   Impl(Future(HttpResponse, IO, Exception))
 )(
@@ -359,9 +362,12 @@ export fetch_with;
 /// Perform an HTTP GET request to the given URL string.
 /// Returns the `HttpResponse` on success.
 ///
-/// Example:
-///   resp := io.await(fetch(`http://example.com`, using(io)));
-///   cond(resp.is_ok() => println(resp.body), true => println(`Error`));
+/// # Example
+///
+/// ```rust
+/// resp := io.await(fetch(`http://example.com`, using(io)));
+/// cond(resp.is_ok() => println(resp.body), true => println(`Error`));
+/// ```
 fetch :: (fn(url_str: String, using(io : IO)) ->
   Impl(Future(HttpResponse, IO, Exception))
 )(