Docs for stdlib

client/space_lua/stdlib/table.ts

@@ -108,6 +108,18 @@ export const tableApi = new LuaTable({
       }
       return out.join(sep);
     },
+    {
+      kind: "builtin",
+      description:
+        "Concatenates table elements from `i` through `j` using an optional separator.",
+      parameters: [
+        { name: "table", type: "table" },
+        { name: "sep", type: "string", optional: true },
+        { name: "i", type: "integer", optional: true },
+        { name: "j", type: "integer", optional: true },
+      ],
+      returns: [{ type: "string" }],
+    },
   ),
 
   /**
@@ -159,6 +171,32 @@ export const tableApi = new LuaTable({
 
       await luaSet(tbl, pos, v, sf);
     },
+    {
+      kind: "builtin",
+      description:
+        "Inserts a value at a position, shifting later elements, or appends it when no position is supplied.",
+      signatures: [
+        "table.insert(table, value)",
+        "table.insert(table, pos, value)",
+      ],
+      parameters: [
+        { name: "table", type: "table" },
+        {
+          name: "posOrValue",
+          description: "Insertion position or appended value.",
+        },
+        {
+          name: "value",
+          description: "Value for positional insertion.",
+          optional: true,
+        },
+      ],
+      examples: [
+        {
+          code: 'local fruits = {"apple", "orange"}\ntable.insert(fruits, 2, "banana")\nprint(table.concat(fruits, ", "))',
+        },
+      ],
+    },
   ),
 
   /**
@@ -202,6 +240,21 @@ export const tableApi = new LuaTable({
 
       return v;
     },
+    {
+      kind: "builtin",
+      description:
+        "Removes and returns an element, shifting later elements down.",
+      parameters: [
+        { name: "table", type: "table" },
+        {
+          name: "pos",
+          type: "integer",
+          description: "Position; defaults to the last element.",
+          optional: true,
+        },
+      ],
+      returns: [{ description: "Removed value." }],
+    },
   ),
 
   /**
@@ -252,6 +305,24 @@ export const tableApi = new LuaTable({
 
       return a2;
     },
+    {
+      kind: "builtin",
+      description:
+        "Moves an inclusive element range to a destination table while handling overlaps.",
+      parameters: [
+        { name: "a1", type: "table", description: "Source table." },
+        { name: "f", type: "integer", description: "First source index." },
+        { name: "e", type: "integer", description: "Last source index." },
+        { name: "t", type: "integer", description: "Destination start index." },
+        {
+          name: "a2",
+          type: "table",
+          description: "Destination table; defaults to `a1`.",
+          optional: true,
+        },
+      ],
+      returns: [{ type: "table", description: "Destination table." }],
+    },
   ),
 
   /**
@@ -311,6 +382,23 @@ export const tableApi = new LuaTable({
 
       return tbl;
     },
+    {
+      kind: "builtin",
+      description:
+        "Sorts a table in place using ascending order or an optional comparison function.",
+      parameters: [
+        { name: "table", type: "table" },
+        { name: "comp", type: "function", optional: true },
+      ],
+      returns: [
+        { type: "table", description: "The sorted table in Space Lua." },
+      ],
+      examples: [
+        {
+          code: "local numbers = {3, 1, 2}\ntable.sort(numbers, function(a, b) return a > b end)",
+        },
+      ],
+    },
   ),
 
   /**
@@ -319,12 +407,21 @@ export const tableApi = new LuaTable({
    * @param tbl - The table to get the keys from.
    * @returns The keys of the table.
    */
-  keys: new LuaBuiltinFunction((_sf, tbl: LuaTable | LuaEnv | any) => {
-    if (tbl.keys) {
-      return tbl.keys();
-    }
-    return Object.keys(tbl);
-  }),
+  keys: new LuaBuiltinFunction(
+    (_sf, tbl: LuaTable | LuaEnv | any) => {
+      if (tbl.keys) {
+        return tbl.keys();
+      }
+      return Object.keys(tbl);
+    },
+    {
+      kind: "builtin",
+      description:
+        "Returns an array containing all keys of a table or JavaScript object.",
+      parameters: [{ name: "table", type: "table" }],
+      returns: [{ type: "table", description: "Array of keys." }],
+    },
+  ),
 
   /**
    * Checks if a table (used as an array) contains a value.
@@ -355,6 +452,16 @@ export const tableApi = new LuaTable({
         sf,
       );
     },
+    {
+      kind: "builtin",
+      description:
+        "Returns whether any table value is Lua-equal to a requested value.",
+      parameters: [
+        { name: "table", type: "table" },
+        { name: "value", description: "Value to find." },
+      ],
+      returns: [{ type: "boolean" }],
+    },
   ),
 
   /**
@@ -383,21 +490,57 @@ export const tableApi = new LuaTable({
       }
       return resultTable;
     },
+    {
+      kind: "builtin",
+      description: "Copies selected keys from a table into a new table.",
+      signatures: [
+        "table.select(table, ...keys): table",
+        "table.select(table, keys): table",
+      ],
+      parameters: [
+        { name: "table", type: "table" },
+        {
+          name: "keys",
+          description: "Individual keys or one array-like table of keys.",
+        },
+      ],
+      returns: [{ type: "table" }],
+      examples: [
+        {
+          code: '${query[[\n  from p = index.pages()\n  limit 3\n  select table.select(p, "name", "lastModified")\n]]}',
+          language: "markdown",
+        },
+      ],
+    },
   ),
 
   /**
    * Returns a new table with all arguments stored in keys 1, 2, ..., n
    * and t.n = n (the total number of arguments).
    */
-  pack: new LuaBuiltinFunction(async (sf, ...args: any[]) => {
-    const tbl = new LuaTable();
-    const n = args.length;
-    for (let i = 0; i < n; i++) {
-      await luaSet(tbl, i + 1, args[i], sf);
-    }
-    void tbl.rawSet("n", n);
-    return tbl;
-  }),
+  pack: new LuaBuiltinFunction(
+    async (sf, ...args: any[]) => {
+      const tbl = new LuaTable();
+      const n = args.length;
+      for (let i = 0; i < n; i++) {
+        await luaSet(tbl, i + 1, args[i], sf);
+      }
+      void tbl.rawSet("n", n);
+      return tbl;
+    },
+    {
+      kind: "builtin",
+      description:
+        "Packs all arguments into a table with a count stored in field `n`.",
+      signatures: ["table.pack(...): table"],
+      returns: [
+        {
+          type: "table",
+          description: "Arguments at integer keys plus field `n`.",
+        },
+      ],
+    },
+  ),
 
   /**
    * Returns all values t[i], t[i+1], ..., t[j].
@@ -425,6 +568,20 @@ export const tableApi = new LuaTable({
       }
       return new LuaMultiRes(result);
     },
+    {
+      kind: "builtin",
+      description:
+        "Returns the table values from index `i` through `j` as separate results.",
+      parameters: [
+        { name: "table", type: "table" },
+        { name: "i", type: "integer", optional: true },
+        { name: "j", type: "integer", optional: true },
+      ],
+      returns: [{ description: "One result per selected element." }],
+      examples: [
+        { code: 'local second, third = table.unpack({"a", "b", "c"}, 2, 3)' },
+      ],
+    },
   ),
 
   // Non-standard Lua functions
@@ -457,5 +614,28 @@ export const tableApi = new LuaTable({
       }
       return null;
     },
+    {
+      kind: "builtin",
+      description:
+        "Finds the first array element accepted by a predicate and returns its index and value.",
+      parameters: [
+        { name: "table", type: "table" },
+        {
+          name: "criteriaFn",
+          type: "function",
+          description: "Predicate called with each value.",
+        },
+        { name: "fromIndex", type: "integer", optional: true },
+      ],
+      returns: [
+        { type: "integer|nil", description: "Matching index or `nil`." },
+        { description: "Matching value." },
+      ],
+      examples: [
+        {
+          code: "local index, value = table.find({1, 2, 3, 4}, function(n) return n % 2 == 0 end)",
+        },
+      ],
+    },
   ),
 });