@silverbulletmd/silverbullet 2.9.0 → 2.11.0

package/client/space_lua/stdlib/string.ts

@@ -28,22 +28,35 @@ function capturesToLua(caps: CaptureResult[]): any {
 }
 
 export const stringApi = new LuaTable({
-  byte: new LuaBuiltinFunction((_sf, s: string, i?: number, j?: number) => {
-    i = i ?? 1;
-    j = j ?? i;
-    if (j > s.length) j = s.length;
-    if (i < 1) i = 1;
-    const result = [];
-    for (let k = i; k <= j; k++) {
-      result.push(s.charCodeAt(k - 1));
-    }
-    return new LuaMultiRes(result);
-  }),
-  char: new LuaBuiltinFunction((_sf, ...args: number[]) => {
-    return String.fromCharCode(...args);
-  }),
-  find: new LuaBuiltinFunction(
-    (_sf, s: string, pattern: string, init = 1, plain = false) => {
+  byte: new LuaBuiltinFunction({
+    callback: (_sf, s: string, i?: number, j?: number) => {
+      i = i ?? 1;
+      j = j ?? i;
+      if (j > s.length) j = s.length;
+      if (i < 1) i = 1;
+      const result = [];
+      for (let k = i; k <= j; k++) {
+        result.push(s.charCodeAt(k - 1));
+      }
+      return new LuaMultiRes(result);
+    },
+    description:
+      "Returns the numeric character codes in the inclusive range from `i` to `j`.",
+    parameters: [
+      { name: "s", type: "string" },
+      { name: "i", type: "integer", optional: true },
+      { name: "j", type: "integer", optional: true },
+    ],
+    returns: [{ type: "integer", description: "One result per character." }],
+  }),
+  char: new LuaBuiltinFunction({
+    callback: (_sf, ...args: number[]) => String.fromCharCode(...args),
+    description: "Creates a string from numeric character codes.",
+    signatures: ["string.char(...): string"],
+    returns: [{ type: "string" }],
+  }),
+  find: new LuaBuiltinFunction({
+    callback: (_sf, s: string, pattern: string, init = 1, plain = false) => {
       const r = patternFind(s, pattern, init, plain);
       if (!r) return null;
       const result: any[] = [r.start, r.end];
@@ -52,15 +65,42 @@ export const stringApi = new LuaTable({
       }
       return new LuaMultiRes(result);
     },
-  ),
-  format: new LuaBuiltinFunction((_sf, format: string, ...args: any[]) => {
-    for (let i = 0; i < args.length; i++) {
-      args[i] = untagNumber(args[i]);
-    }
-    return luaFormat(format, ...args);
-  }),
-  gmatch: new LuaBuiltinFunction(
-    (_sf, s: string, pattern: string, init = 1) => {
+    description:
+      "Finds the first Lua-pattern match and returns its bounds followed by captures.",
+    parameters: [
+      { name: "s", type: "string" },
+      { name: "pattern", type: "string" },
+      { name: "init", type: "integer", optional: true },
+      { name: "plain", type: "boolean", optional: true },
+    ],
+    returns: [
+      { type: "integer|nil", description: "Start index or `nil`." },
+      { type: "integer", description: "End index." },
+    ],
+  }),
+  format: new LuaBuiltinFunction({
+    callback: (_sf, format: string, ...args: any[]) => {
+      for (let i = 0; i < args.length; i++) {
+        args[i] = untagNumber(args[i]);
+      }
+      return luaFormat(format, ...args);
+    },
+    description: "Formats values according to a C-style format string.",
+    signatures: ["string.format(format, ...): string"],
+    parameters: [
+      { name: "format", type: "string" },
+      {
+        name: "...",
+        description: "Values consumed by conversion specifiers.",
+      },
+    ],
+    returns: [{ type: "string" }],
+    examples: [
+      { code: 'print(string.format("Name: %s, score: %.1f", "Ada", 9.5))' },
+    ],
+  }),
+  gmatch: new LuaBuiltinFunction({
+    callback: (_sf, s: string, pattern: string, init = 1) => {
       const iter = patternGmatch(s, pattern, init);
       return () => {
         const caps = iter();
@@ -68,9 +108,22 @@ export const stringApi = new LuaTable({
         return capturesToLua(caps);
       };
     },
-  ),
-  gsub: new LuaBuiltinFunction(
-    async (sf, s: string, pattern: string, repl: any, n?: number) => {
+    description:
+      "Returns an iterator over successive Lua-pattern matches and captures.",
+    parameters: [
+      { name: "s", type: "string" },
+      { name: "pattern", type: "string" },
+      { name: "init", type: "integer", optional: true },
+    ],
+    returns: [{ type: "function", description: "Match iterator." }],
+    examples: [
+      {
+        code: 'for word in string.gmatch("hello world", "%w+") do\n  print(word)\nend',
+      },
+    ],
+  }),
+  gsub: new LuaBuiltinFunction({
+    callback: async (sf, s: string, pattern: string, repl: any, n?: number) => {
       const callbacks: GsubCallbacks = {};
       if (typeof repl === "string") {
         callbacks.replString = repl;
@@ -103,61 +156,135 @@ export const stringApi = new LuaTable({
       const [result, count] = await patternGsub(s, pattern, callbacks, n);
       return new LuaMultiRes([result, count]);
     },
-  ),
-  len: new LuaBuiltinFunction((_sf, s: string) => {
-    return s.length;
-  }),
-  lower: new LuaBuiltinFunction((_sf, s: string) => {
-    return luaToString(s.toLowerCase());
-  }),
-  upper: new LuaBuiltinFunction((_sf, s: string) => {
-    return luaToString(s.toUpperCase());
-  }),
-  match: new LuaBuiltinFunction((_sf, s: string, pattern: string, init = 1) => {
-    const caps = patternMatch(s, pattern, init);
-    if (!caps) return null;
-    return capturesToLua(caps);
-  }),
-  rep: new LuaBuiltinFunction((_sf, s: string, n: number, sep?: string) => {
-    if (n <= 0) return "";
-    sep = sep ?? "";
-    const parts: string[] = [];
-    for (let i = 0; i < n; i++) {
-      parts.push(s);
-    }
-    return parts.join(sep);
-  }),
-  reverse: new LuaBuiltinFunction((_sf, s: string) => {
-    return s.split("").reverse().join("");
-  }),
-  sub: new LuaBuiltinFunction((_sf, s: string, i: number, j?: number) => {
-    const len = s.length;
-    let start: number;
-    if (i > 0) {
-      start = i;
-    } else if (i < -len) {
-      start = 1;
-    } else {
-      start = i === 0 ? 1 : len + i + 1;
-    }
-    let end: number;
-    if (j === undefined || j === null || j > len) {
-      end = len;
-    } else if (j >= 0) {
-      end = j;
-    } else if (j < -len) {
-      end = 0;
-    } else {
-      end = len + j + 1;
-    }
-    if (start <= end) {
-      return s.substring(start - 1, end);
-    }
-    return "";
+    description:
+      "Replaces Lua-pattern matches using a string, table, or function replacement.",
+    parameters: [
+      { name: "s", type: "string" },
+      { name: "pattern", type: "string" },
+      { name: "replacement", type: "string|table|function" },
+      { name: "n", type: "integer", optional: true },
+    ],
+    returns: [
+      { type: "string", description: "Result string." },
+      { type: "integer", description: "Number of replacements." },
+    ],
+    examples: [
+      {
+        code: 'local result, count = string.gsub("hello hello", "hello", "hi", 1)\nprint(result, count) -- hi hello  1',
+      },
+    ],
+  }),
+  len: new LuaBuiltinFunction({
+    callback: (_sf, s: string) => s.length,
+    description: "Returns the length of a string.",
+    parameters: [{ name: "s", type: "string" }],
+    returns: [{ type: "integer" }],
+  }),
+  lower: new LuaBuiltinFunction({
+    callback: (_sf, s: string) => luaToString(s.toLowerCase()),
+    description: "Returns a copy of a string converted to lowercase.",
+    parameters: [{ name: "s", type: "string" }],
+    returns: [{ type: "string" }],
+  }),
+  upper: new LuaBuiltinFunction({
+    callback: (_sf, s: string) => luaToString(s.toUpperCase()),
+    description: "Returns a copy of a string converted to uppercase.",
+    parameters: [{ name: "s", type: "string" }],
+    returns: [{ type: "string" }],
+  }),
+  match: new LuaBuiltinFunction({
+    callback: (_sf, s: string, pattern: string, init = 1) => {
+      const caps = patternMatch(s, pattern, init);
+      if (!caps) return null;
+      return capturesToLua(caps);
+    },
+    description:
+      "Returns captures from the first Lua-pattern match, or `nil` when none is found.",
+    parameters: [
+      { name: "s", type: "string" },
+      { name: "pattern", type: "string" },
+      { name: "init", type: "integer", optional: true },
+    ],
+    returns: [{ description: "Pattern captures, whole match, or `nil`." }],
+    examples: [
+      { code: 'local year, month = string.match("2024-03", "(%d+)%-(%d+)")' },
+    ],
+  }),
+  rep: new LuaBuiltinFunction({
+    callback: (_sf, s: string, n: number, sep?: string) => {
+      if (n <= 0) return "";
+      sep = sep ?? "";
+      const parts: string[] = [];
+      for (let i = 0; i < n; i++) {
+        parts.push(s);
+      }
+      return parts.join(sep);
+    },
+    description:
+      "Returns `n` copies of a string joined by an optional separator.",
+    parameters: [
+      { name: "s", type: "string" },
+      { name: "n", type: "integer" },
+      { name: "sep", type: "string", optional: true },
+    ],
+    returns: [{ type: "string" }],
+  }),
+  reverse: new LuaBuiltinFunction({
+    callback: (_sf, s: string) => s.split("").reverse().join(""),
+    description: "Returns a string with its characters in reverse order.",
+    parameters: [{ name: "s", type: "string" }],
+    returns: [{ type: "string" }],
+  }),
+  sub: new LuaBuiltinFunction({
+    callback: (_sf, s: string, i: number, j?: number) => {
+      const len = s.length;
+      let start: number;
+      if (i > 0) {
+        start = i;
+      } else if (i < -len) {
+        start = 1;
+      } else {
+        start = i === 0 ? 1 : len + i + 1;
+      }
+      let end: number;
+      if (j === undefined || j === null || j > len) {
+        end = len;
+      } else if (j >= 0) {
+        end = j;
+      } else if (j < -len) {
+        end = 0;
+      } else {
+        end = len + j + 1;
+      }
+      if (start <= end) {
+        return s.substring(start - 1, end);
+      }
+      return "";
+    },
+    description:
+      "Returns the substring from inclusive index `i` through `j`, supporting negative indices.",
+    parameters: [
+      { name: "s", type: "string" },
+      { name: "i", type: "integer" },
+      { name: "j", type: "integer", optional: true },
+    ],
+    returns: [{ type: "string" }],
   }),
 
-  split: new LuaBuiltinFunction((_sf, s: string, sep: string) => {
-    return s.split(sep);
+  split: new LuaBuiltinFunction({
+    callback: (_sf, s: string, sep: string) => s.split(sep),
+    description:
+      "Splits a string on a literal separator and returns the substrings.",
+    parameters: [
+      { name: "s", type: "string" },
+      { name: "sep", type: "string" },
+    ],
+    returns: [{ type: "table" }],
+    examples: [
+      {
+        code: 'for part in each(string.split("a,b,c", ",")) do\n  print(part)\nend',
+      },
+    ],
   }),
 
   pack: strPackFn,
@@ -165,34 +292,85 @@ export const stringApi = new LuaTable({
   packsize: strPackSizeFn,
 
   // Non-standard extensions
-  startsWith: new LuaBuiltinFunction((_sf, s: string, prefix: string) => {
-    return s.startsWith(prefix);
+  startsWith: new LuaBuiltinFunction({
+    callback: (_sf, s: string, prefix: string) => s.startsWith(prefix),
+    description: "Returns whether a string starts with a literal prefix.",
+    parameters: [
+      { name: "s", type: "string" },
+      { name: "prefix", type: "string" },
+    ],
+    returns: [{ type: "boolean" }],
   }),
-  endsWith: new LuaBuiltinFunction((_sf, s: string, suffix: string) => {
-    return s.endsWith(suffix);
+  endsWith: new LuaBuiltinFunction({
+    callback: (_sf, s: string, suffix: string) => s.endsWith(suffix),
+    description: "Returns whether a string ends with a literal suffix.",
+    parameters: [
+      { name: "s", type: "string" },
+      { name: "suffix", type: "string" },
+    ],
+    returns: [{ type: "boolean" }],
   }),
-  trim: new LuaBuiltinFunction((_sf, s: string) => {
-    return s.trim();
+  trim: new LuaBuiltinFunction({
+    callback: (_sf, s: string) => s.trim(),
+    description: "Removes whitespace from both ends of a string.",
+    parameters: [{ name: "s", type: "string" }],
+    returns: [{ type: "string" }],
   }),
-  trimStart: new LuaBuiltinFunction((_sf, s: string) => {
-    return s.trimStart();
+  trimStart: new LuaBuiltinFunction({
+    callback: (_sf, s: string) => s.trimStart(),
+    description: "Removes whitespace from the beginning of a string.",
+    parameters: [{ name: "s", type: "string" }],
+    returns: [{ type: "string" }],
   }),
-  trimEnd: new LuaBuiltinFunction((_sf, s: string) => {
-    return s.trimEnd();
+  trimEnd: new LuaBuiltinFunction({
+    callback: (_sf, s: string) => s.trimEnd(),
+    description: "Removes whitespace from the end of a string.",
+    parameters: [{ name: "s", type: "string" }],
+    returns: [{ type: "string" }],
   }),
-  matchRegex: new LuaBuiltinFunction((_sf, s: string, pattern: string) => {
-    const regex = new RegExp(pattern);
-    const result = s.match(regex);
-    return jsToLuaValue(result);
+  matchRegex: new LuaBuiltinFunction({
+    callback: (_sf, s: string, pattern: string) => {
+      const regex = new RegExp(pattern);
+      const result = s.match(regex);
+      return jsToLuaValue(result);
+    },
+    description:
+      "Matches a string with a JavaScript regular expression and returns the match array.",
+    parameters: [
+      { name: "s", type: "string" },
+      { name: "pattern", type: "string" },
+    ],
+    returns: [{ type: "table|nil" }],
+    examples: [
+      {
+        code: 'local match = string.matchRegex("hello123", "([a-z]+)([0-9]+)")\nprint(match[1], match[2], match[3])',
+      },
+    ],
   }),
-  matchRegexAll: new LuaBuiltinFunction((_sf, s: string, pattern: string) => {
-    const regex = new RegExp(pattern, "g");
-    return () => {
-      const match = regex.exec(s);
-      if (!match) {
-        return;
-      }
-      return jsToLuaValue(match);
-    };
+  matchRegexAll: new LuaBuiltinFunction({
+    callback: (_sf, s: string, pattern: string) => {
+      const regex = new RegExp(pattern, "g");
+      return () => {
+        const match = regex.exec(s);
+        if (!match) {
+          return;
+        }
+        return jsToLuaValue(match);
+      };
+    },
+    description:
+      "Returns an iterator over all JavaScript regular-expression matches.",
+    parameters: [
+      { name: "s", type: "string" },
+      { name: "pattern", type: "string" },
+    ],
+    returns: [
+      { type: "function", description: "Iterator yielding match arrays." },
+    ],
+    examples: [
+      {
+        code: 'for match in string.matchRegexAll("a1b2", "([a-z])([0-9])") do\n  print(match[1], match[2], match[3])\nend',
+      },
+    ],
   }),
 });

package/client/space_lua/stdlib/string_pack.ts

@@ -145,7 +145,6 @@ function getOption(
   }
 }
 
-// Compute alignment padding
 function getDetails(
   fmt: string,
   pos: number,
@@ -252,8 +251,8 @@ function unpackFloat64(
   );
 }
 
-export const strPackFn = new LuaBuiltinFunction(
-  (sf, fmt: string, ...args: any[]) => {
+export const strPackFn = new LuaBuiltinFunction({
+  callback: (sf, fmt: string, ...args: any[]) => {
     const h = makeHeader();
     const parts: Uint8Array[] = [];
     let totalsize = 0;
@@ -264,7 +263,6 @@ export const strPackFn = new LuaBuiltinFunction(
       let opt: ParsedOption;
       [opt, pos] = getDetails(fmt, pos, h, totalsize);
 
-      // alignment padding
       if (opt.ntoalign > 0) {
         parts.push(new Uint8Array(opt.ntoalign));
         totalsize += opt.ntoalign;
@@ -349,7 +347,6 @@ export const strPackFn = new LuaBuiltinFunction(
       }
     }
 
-    // Concatenate all parts into one binary string (latin-1 encoding)
     let total = 0;
     for (const p of parts) total += p.length;
     const out = new Uint8Array(total);
@@ -364,10 +361,18 @@ export const strPackFn = new LuaBuiltinFunction(
     for (let i = 0; i < out.length; i++) result += String.fromCharCode(out[i]);
     return result;
   },
-);
+  description:
+    "Packs values into a binary string according to a Lua 5.4 format string.",
+  signatures: ["string.pack(format, ...): string"],
+  parameters: [
+    { name: "format", type: "string", description: "Binary packing format." },
+    { name: "...", description: "Values consumed by the format options." },
+  ],
+  returns: [{ type: "string", description: "Packed binary string." }],
+});
 
-export const strUnpackFn = new LuaBuiltinFunction(
-  (sf, fmt: string, data: string, init?: number) => {
+export const strUnpackFn = new LuaBuiltinFunction({
+  callback: (sf, fmt: string, data: string, init?: number) => {
     const h = makeHeader();
 
     const buf = new Uint8Array(data.length);
@@ -468,23 +473,54 @@ export const strUnpackFn = new LuaBuiltinFunction(
     results.push(pos + 1);
     return new LuaMultiRes(results);
   },
-);
+  description:
+    "Unpacks values from a binary string according to a Lua 5.4 format string.",
+  parameters: [
+    {
+      name: "format",
+      type: "string",
+      description: "Binary unpacking format.",
+    },
+    { name: "data", type: "string", description: "Packed binary string." },
+    {
+      name: "init",
+      type: "integer",
+      description: "One-based starting position.",
+      optional: true,
+    },
+  ],
+  returns: [
+    { description: "Unpacked values followed by the next unread position." },
+  ],
+});
 
-export const strPackSizeFn = new LuaBuiltinFunction((_sf, fmt: string) => {
-  const h = makeHeader();
-  let totalsize = 0;
-  let pos = 0;
+export const strPackSizeFn = new LuaBuiltinFunction({
+  callback: (_sf, fmt: string) => {
+    const h = makeHeader();
+    let totalsize = 0;
+    let pos = 0;
 
-  while (pos < fmt.length) {
-    let opt: ParsedOption;
-    [opt, pos] = getDetails(fmt, pos, h, totalsize);
+    while (pos < fmt.length) {
+      let opt: ParsedOption;
+      [opt, pos] = getDetails(fmt, pos, h, totalsize);
 
-    if (opt.opt === "string" || opt.opt === "zstr") {
-      throw new LuaRuntimeError("variable-length format", _sf);
-    }
+      if (opt.opt === "string" || opt.opt === "zstr") {
+        throw new LuaRuntimeError("variable-length format", _sf);
+      }
 
-    totalsize += opt.ntoalign + opt.size;
-  }
+      totalsize += opt.ntoalign + opt.size;
+    }
 
-  return totalsize;
+    return totalsize;
+  },
+  description:
+    "Returns the byte size of a fixed-length Lua 5.4 packing format.",
+  parameters: [
+    {
+      name: "format",
+      type: "string",
+      description: "Fixed-length binary packing format.",
+    },
+  ],
+  returns: [{ type: "integer", description: "Packed byte count." }],
 });