docs: update code snippets in docstrings (100+ files, various pkgs)

packages/strings/src/ansi.ts

@@ -4,10 +4,12 @@ const RE = /\x1b\[[0-9;]+m/g;
  * Removes all ANSI control sequences from given string.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/strip-ansi.ts
  * import { stripAnsi } from "@thi.ng/strings";
  *
- * stripAnsi("\x1B[32mhello\x1B[0m \x1B[91mworld\x1B[0m!"");
+ * console.log(
+ *   stripAnsi("\x1B[32mhello\x1B[0m \x1B[91mworld\x1B[0m!")
+ * );
  * // 'hello world!'
  * ```
  *

packages/strings/src/case.ts

@@ -27,10 +27,12 @@ export const capitalize: FnS = (x) =>
  * delimiter (`-` by default).
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/kebab.ts
  * import { kebab } from "@thi.ng/strings";
  *
- * kebab("FooBar23Baz");
+ * console.log(
+ *   kebab("FooBar23Baz")
+ * );
  * // "foo-bar23-baz"
  * ```
  *

packages/strings/src/center.ts

@@ -15,22 +15,24 @@ import { truncate } from "./truncate.js";
  * Note: The padding string can contain multiple characters.
  *
  * @example
- * ```ts
- * import { center, wrap } from "@thi.ng/strings";
+ * ```ts tangle:../export/center.ts
+ * import { center } from "@thi.ng/strings";
  *
- * center(20, "<>")(wrap(" ")("thi.ng"))
+ * console.log(
+ *   center(20, "<>")(" thi.ng ")
+ * );
  * // "<><><> thi.ng <><><>"
  * ```
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/center-2.ts
  * import { comp } from "@thi.ng/compose";
  * import { center, wrap } from "@thi.ng/strings";
  *
  * // compose formatting function
  * const fmt = comp(center(20,"<>"), wrap(" "));
  *
- * fmt("thi.ng")
+ * console.log(fmt("thi.ng"));
  * // "<><><> thi.ng <><><>"
  * ```
  *

packages/strings/src/cursor.ts

@@ -8,14 +8,18 @@
  * optional `offset` arg (also in `[line,column]` order).
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/compute-cursor-pos.ts
  * import { computeCursorPos } from "@thi.ng/strings";
  *
- * computeCursorPos("thi.ng\numbrella", 10);
+ * console.log(
+ *   computeCursorPos("thi.ng\numbrella", 10)
+ * );
  * // [ 2, 4 ]
  *
  * // w/ custom offset
- * computeCursorPos("thi.ng\numbrella", 10, "\n", [11, 1]);
+ * console.log(
+ *   computeCursorPos("thi.ng\numbrella", 10, "\n", [11, 1])
+ * );
  * // [ 12, 4 ]
  * ```
  *

packages/strings/src/escape.ts

@@ -36,6 +36,8 @@ export const ESCAPES_REV: Record<number, string> = {
  * - Non-BMP chars will be escaped using `\Uxxxxxxxx`
  * - Chars outside 0x20 - 0x7e range will be escaped using `\uxxxxx`
  *
+ * Also see {@link unescape}.
+ *
  * @param src -
  */
 export const escape = (src: string) =>
@@ -60,11 +62,13 @@ export const escape = (src: string) =>
  * - https://www.branah.com/unicode-converter
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/unescape.ts
  * import { unescape } from "@thi.ng/strings";
  *
- * unescape("\\ud83d\\ude0e \\U0001f60e")
- * // '😎'
+ * console.log(
+ *   unescape("\\ud83d\\ude0e \\U0001f60e")
+ * );
+ * // '😎 😎'
  * ```
  *
  * @param src -

packages/strings/src/hollerith.ts

@@ -3,18 +3,21 @@ import type { Stringer } from "./api.js";
 /**
  * Formats given value `x` as Fortran style Hollerith string.
  *
+ * @remarks
+ * References:
+ * - https://en.wikipedia.org/wiki/Hollerith_constant
+ * - https://en.wikipedia.org/wiki/IGES#File_format
+ *
  * @example
- * ```ts
+ * ```ts tangle:../export/hstr.ts
  * import { hstr } from "@thi.ng/strings";
  *
- * hstr("abc")  // "3Habc"
- * hstr(123.45) // "6H123.45"
- * hstr("")     // "0H"
- * hstr(null)   // ""
+ * console.log(hstr("abc"));  // "3Habc"
+ * console.log(hstr(123.45)); // "6H123.45"
+ * console.log(hstr(""));     // "0H"
+ * console.log(hstr(null));   // ""
  * ```
  *
- * https://en.wikipedia.org/wiki/Hollerith_constant
- *
  * @param x -
  */
 export const hstr: Stringer<any> = (x) =>

packages/strings/src/initials.ts

@@ -4,14 +4,22 @@
  * (default: uppercase). If `mode` is null, the original casing will be kept.
  *
  * @example
- * ```ts
- * initials(["alicia", "bella", "carerra"]);
+ * ```ts tangle:../export/initials.ts
+ * import { initials } from "@thi.ng/strings";
+ *
+ * console.log(
+ *   initials(["alicia", "bella", "carerra"])
+ * );
  * // "ABC"
  *
- * initials("shader-ast-GLSL".split("-"))
+ * console.log(
+ *   initials("shader-ast-GLSL".split("-"))
+ * );
  * // "SAG"
  *
- * initials("Ludwig van Beethoven".split(" "), null)
+ * console.log(
+ *   initials("Ludwig van Beethoven".split(" "), null)
+ * );
  * // "LvB"
  * ```
  *

packages/strings/src/interpolate.ts

@@ -9,9 +9,16 @@ const TPL_K = /\{([a-z0-9_.-]+)\}/gi;
  * number of args. Replaces numbered terms with their respective args
  * given.
  *
+ * @remarks
+ * Also see {@link interpolateKeys}.
+ *
  * @example
- * ```ts
- * interpolate("let {0}: {2} = {1};", "a", 42, "number")
+ * ```ts tangle:../export/interpolate.ts
+ * import { interpolate } from "@thi.ng/strings";
+ *
+ * console.log(
+ *   interpolate("let {0}: {2} = {1};", "a", 42, "number")
+ * );
  * // "let a: number = 42;"
  * ```
  *
@@ -28,11 +35,15 @@ export const interpolate = (src: string, ...args: any[]) =>
  * template string and an object of values for the stated keys.
  *
  * @example
- * ```ts
- * interpolateKeys(
- *   "let {id}: {type} = {val};",
- *   { id: "a", type: "number", val: 42 }
- * )
+ * ```ts tangle:../export/interpolate-keys.ts
+ * import { interpolateKeys } from "@thi.ng/strings";
+ *
+ * console.log(
+ *   interpolateKeys(
+ *     "let {id}: {type} = {val};",
+ *     { id: "a", type: "number", val: 42 }
+ *   )
+ * );
  * // "let a: number = 42;"
  * ```
  *

packages/strings/src/join.ts

@@ -7,21 +7,25 @@ import type { Stringer } from "./api.js";
  * separator into a result string.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/join.ts
  * import { format, join } from "@thi.ng/strings";
  * import { partial } from "@thi.ng/compose";
  *
  * const slashes = join("/");
  *
- * slashes([1, 2, 3]);
+ * console.log(
+ *   slashes([1, 2, 3])
+ * );
  * // "1/2/3"
  *
  * // pre-compose formatter function w/ partial arguments
  * const formatOBJFace = partial(
  *   format, ["f ", slashes, " ", slashes, " ", slashes]
  * );
  *
- * formatOBJFace([1, 2], [3, 4], [5, 6]);
+ * console.log(
+ *   formatOBJFace([1, 2], [3, 4], [5, 6])
+ * );
  * // "f 1/2 3/4 5/6"
  * ```
  */

packages/strings/src/ruler.ts

@@ -5,7 +5,7 @@ import { repeat } from "./repeat.js";
  * ticks and `b` for minor ticks.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/ruler.ts
  * import { ruler } from "@thi.ng/strings";
  *
  * console.log(ruler(40))
@@ -31,7 +31,7 @@ export const ruler = (width: number, major = 5, a = "|", b = "'") =>
  * `h`. The optional `chars` can be used to customize the grid.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/grid.ts
  * import { grid } from "@thi.ng/strings";
  *
  * console.log(grid(3, 3, 4, 2));

packages/strings/src/slugify.ts

@@ -12,10 +12,12 @@ const RE = new RegExp(SRC.split("").join("|"), "g");
  * https://medium.com/@matthagemann/the-ultimate-way-to-slugify-a-url-string-in-javascript-b8e4a0d849e1
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/slugify.ts
  * import { slugify } from "@thi.ng/strings";
  *
- * slugify("Me, myself (& ëye) 😀!")
+ * console.log(
+ *   slugify("Me, myself (& ëye) 😀!")
+ * );
  * // "me-myself-and-eye"
  * ```
  *
@@ -41,10 +43,12 @@ export const slugify: Stringer<string> = (str: string) => {
  * for headings in markdown files (AFAICT).
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/slugify-gh.ts
  * import { slugifyGH } from "@thi.ng/strings";
  *
- * slugifyGH("Me, myself (& ëye) 😀!")
+ * console.log(
+ *   slugifyGH("Me, myself (& ëye) 😀!")
+ * );
  * // "me-myself--ëye-"
  * ```
  *

packages/strings/src/stringify.ts

@@ -8,16 +8,22 @@ import type { Stringer } from "./api.js";
  * null, indent)`
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/stringify.ts
  * import { stringify } from "@thi.ng/strings";
  *
- * stringify()("hello");
+ * console.log(
+ *   stringify()("hello")
+ * );
  * // hello
  *
- * stringify(true)("hello");
+ * console.log(
+ *   stringify(true)("hello")
+ * );
  * // "hello"
  *
- * stringify()({ a: "hello" })
+ * console.log(
+ *   stringify()({ a: "hello" })
+ * );
  * // { "a": "hello" }
  * ```
  *

packages/strings/src/tabs.ts

@@ -8,7 +8,7 @@ const __nextTab = (x: number, tabSize: number) =>
  * Multi-line version of {@link tabsToSpacesLine}.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/tabs-to-spaces.ts
  * import { tabsToSpaces } from "@thi.ng/strings";
  *
  * console.log(
@@ -34,7 +34,7 @@ export const tabsToSpaces = (src: string, tabSize = 4) =>
 
 /**
  * Takes a single line string and converts all tab characters to spaces, using
- * given `tabSize`.
+ * given `tabSize` (default: 4).
  *
  * @param line -
  * @param tabSize -

packages/strings/src/trim.ts

@@ -6,13 +6,17 @@ import type { Stringer } from "./api.js";
  * trimmable characters (default: whitespace only).
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/trim.ts
  * import { trim } from "@thi.ng/strings";
  *
- * trim()("  Hello   ")
+ * console.log(
+ *   trim()("  Hello   ")
+ * );
  * // "Hello"
  *
- * trim(" -+")("-+-+- Hello -+-+-")
+ * console.log(
+ *   trim(" -+")("-+-+- Hello -+-+-")
+ * );
  * // "Hello"
  * ```
  *

packages/text-canvas/src/image.ts

@@ -77,7 +77,7 @@ export const blit = (dest: Canvas, src: Canvas, x = 0, y = 0) => {
  * pixels/chars will be copied. Supports region clipping.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/blit-mask.ts
  * import {
  *   blitMask, canvas, canvasFromText, clear, formatCanvas
  * } from "@thi.ng/text-canvas";
@@ -91,17 +91,19 @@ export const blit = (dest: Canvas, src: Canvas, x = 0, y = 0) => {
  *   "###==###",
  * ]);
  *
+ * console.log(formatCanvas(a));
+ *
  * // destination canvas (filled w/ "-")
  * const b = canvas(12,7);
  * clear(b, true, "-");
  *
  * // paste `a` several times into `b` using "#" as mask
- * blitMask(b, -4, -2, a, "#"); // top-left (partially outside)
- * blitMask(b, 2, 1, a, "#");   // center
- * blitMask(b, 8, 4, a, "#");   // bottom-right (part outside)
+ * blitMask(b, a, -4, -2, "#"); // top-left (partially outside)
+ * blitMask(b, a, 2, 1, "#"); // center
+ * blitMask(b, a, 8, 4, "#"); // bottom-right (part outside)
  *
  * // show result
- * console.log(formatCanvas(b))
+ * console.log(formatCanvas(b));
  * // ===---------
  * // ==---==-----
  * // =---====----

packages/text-format/src/format.ts

@@ -11,13 +11,16 @@ import {
  * {@link StringFormat} impl.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/def-format.ts
  * import { defFormat, FMT_ANSI16, FG_RED } from "@thi.ng/text-format";
  *
  * const red = defFormat(FMT_ANSI16, FG_RED);
  *
- * red("hello");
- * // "\x1B[31mhello\x1B[0m"
+ * console.log(red("hello"));
+ * // hello (shown in red in ANSI-supporting terminals)
+ *
+ * console.log(escape(red("hello")));
+ * // "%1B%5B31mhello%1B%5B0m"
  * ```
  *
  * @param fmt -