functional.json

{
  "functions": [
    {
      "name": "functional.map",
      "file": "lib/functional/map",
      "description": "Transform every element of a table using a function. The function receives the value and index.",
      "tags": ["map", "transform", "array", "table", "functional", "higher-order"],
      "queries": ["map over table", "transform each element", "apply function to list", "map array"],
      "params": [
        { "name": "t", "type": "table", "description": "Input array-style table" },
        { "name": "f", "type": "function", "description": "Function called as f(value, index), must return the new value" }
      ],
      "returns": "table - New table of the same length with each element replaced by f(v, i)",
      "examples": [
        "functional.map({1, 2, 3}, function(x) return x * 2 end) → {2, 4, 6}",
        "functional.map({\"a\", \"b\", \"c\"}, function(v, i) return i .. \":\" .. v end) → {\"1:a\", \"2:b\", \"3:c\"}"
      ]
    },
    {
      "name": "functional.filter",
      "file": "lib/functional/filter",
      "description": "Keep only the elements of a table for which a predicate function returns true.",
      "tags": ["filter", "where", "select", "predicate", "array", "table", "functional"],
      "queries": ["filter table", "keep matching elements", "remove elements", "where clause on table"],
      "params": [
        { "name": "t", "type": "table", "description": "Input array-style table" },
        { "name": "f", "type": "function", "description": "Predicate function called as f(value), return true to keep the element" }
      ],
      "returns": "table - New table containing only the elements for which f returned true",
      "examples": [
        "functional.filter({1, 2, 3, 4, 5}, function(x) return x % 2 == 0 end) → {2, 4}",
        "functional.filter({10, -3, 7, -1, 4}, function(x) return x > 0 end) → {10, 7, 4}"
      ]
    },
    {
      "name": "functional.fold",
      "file": "lib/functional/fold",
      "description": "Left fold: reduce a table to a single value by repeatedly applying a function, starting from an explicit seed accumulator.",
      "tags": ["fold", "reduce", "accumulate", "aggregate", "functional", "sum", "product"],
      "queries": ["fold table", "reduce with seed", "accumulate values", "left fold", "aggregate table"],
      "params": [
        { "name": "t", "type": "table", "description": "Input array-style table" },
        { "name": "f", "type": "function", "description": "Combiner function called as f(accumulator, value)" },
        { "name": "acc", "type": "any", "description": "Initial accumulator value (seed)" }
      ],
      "returns": "any - Final accumulated value",
      "examples": [
        "functional.fold({1, 2, 3, 4, 5}, function(acc, x) return acc + x end, 0) → 15",
        "functional.fold({\"b\", \"c\", \"d\"}, function(acc, x) return acc .. x end, \"a\") → \"abcd\""
      ]
    },
    {
      "name": "functional.reduce",
      "file": "lib/functional/reduce",
      "description": "Reduce a table to a single value using the first element as the seed. Errors on an empty table. Use functional.fold when you need an explicit starting value.",
      "tags": ["reduce", "fold", "accumulate", "aggregate", "functional", "sum"],
      "queries": ["reduce table", "collapse to single value", "sum table", "reduce array"],
      "params": [
        { "name": "t", "type": "table", "description": "Input array-style table (must be non-empty)" },
        { "name": "f", "type": "function", "description": "Combiner function called as f(accumulator, value)" }
      ],
      "returns": "any - Final accumulated value",
      "examples": [
        "functional.reduce({1, 2, 3, 4, 5}, function(acc, x) return acc + x end) → 15",
        "functional.reduce({3, 1, 4, 1, 5}, function(acc, x) return math.max(acc, x) end) → 5"
      ]
    },
    {
      "name": "functional.zip",
      "file": "lib/functional/zip",
      "description": "Combine two tables element-wise. With a function, produces f(a[i], b[i]). Without a function, produces pairs as {a[i], b[i]}. Length is capped at the shorter table.",
      "tags": ["zip", "combine", "merge", "pair", "two tables", "functional"],
      "queries": ["zip two tables", "combine arrays element by element", "pair up two lists", "merge two arrays"],
      "params": [
        { "name": "a", "type": "table", "description": "First input table" },
        { "name": "b", "type": "table", "description": "Second input table" },
        { "name": "f", "type": "function", "description": "Optional combining function called as f(a[i], b[i])" }
      ],
      "returns": "table - Combined table, length equal to math.min(#a, #b)",
      "examples": [
        "functional.zip({1, 2, 3}, {4, 5, 6}, function(a, b) return a + b end) → {5, 7, 9}",
        "functional.zip({\"Alice\", \"Bob\"}, {95, 82}) → {{\"Alice\", 95}, {\"Bob\", 82}}"
      ]
    },
    {
      "name": "functional.flatten",
      "file": "lib/functional/flatten",
      "description": "Recursively flatten nested tables up to a given depth. Depth defaults to 1.",
      "tags": ["flatten", "flat", "nested", "array", "table", "depth", "functional"],
      "queries": ["flatten nested table", "collapse nested arrays", "flatten 2d table to 1d", "flatten matrix"],
      "params": [
        { "name": "t", "type": "table", "description": "Input table, possibly nested" },
        { "name": "depth", "type": "number", "description": "How many levels to flatten (default 1)" }
      ],
      "returns": "table - Flattened table",
      "examples": [
        "functional.flatten({{1, 2}, {3, 4}, {5}}) → {1, 2, 3, 4, 5}",
        "functional.flatten({{{1, 2}}, {{3}}}, 2) → {1, 2, 3}",
        "functional.flatten({{10}, {20}, {30}}) → {10, 20, 30}  -- useful for matrix ranges"
      ]
    },
    {
      "name": "functional.flat_map",
      "file": "lib/functional/flat_map",
      "description": "Map a function over a table then flatten the result by one level. Equivalent to functional.flatten(functional.map(t, f), 1).",
      "tags": ["flat_map", "flatmap", "map", "flatten", "one-to-many", "functional"],
      "queries": ["flat map table", "map and flatten", "one to many transform", "expand elements"],
      "params": [
        { "name": "t", "type": "table", "description": "Input array-style table" },
        { "name": "f", "type": "function", "description": "Function that returns a table for each element" }
      ],
      "returns": "table - Mapped and flattened result",
      "examples": [
        "functional.flat_map({{1, 2}, {3}}, function(row) return row end) → {1, 2, 3}",
        "functional.flat_map({1, 2, 3}, function(x) return {x, x * x} end) → {1, 1, 2, 4, 3, 9}"
      ]
    },
    {
      "name": "functional.compose",
      "file": "lib/functional/compose",
      "description": "Right-to-left function composition. Returns a new function that applies its arguments in reverse order: compose(f, g, h)(x) = f(g(h(x))).",
      "tags": ["compose", "function composition", "pipeline", "chain", "functional"],
      "queries": ["compose functions", "function composition", "chain functions right to left", "mathematical composition"],
      "params": [
        { "name": "...", "type": "function", "description": "Two or more functions to compose (all must be functions)" }
      ],
      "returns": "function - A new function that applies the arguments right-to-left",
      "examples": [
        "local f = functional.compose(functional.double, functional.inc, functional.square)\nf(3) → double(inc(square(3))) = double(inc(9)) = double(10) = 20"
      ]
    },
    {
      "name": "functional.pipe",
      "file": "lib/functional/pipe",
      "description": "Left-to-right function composition. Returns a new function that applies its arguments in order: pipe(f, g, h)(x) = h(g(f(x))). The order you read matches the order of execution.",
      "tags": ["pipe", "pipeline", "function composition", "chain", "functional"],
      "queries": ["pipe functions", "left to right composition", "chain functions in order", "function pipeline"],
      "params": [
        { "name": "...", "type": "function", "description": "Two or more functions to chain (all must be functions)" }
      ],
      "returns": "function - A new function that applies the arguments left-to-right",
      "examples": [
        "local f = functional.pipe(functional.double, functional.inc, functional.square)\nf(3) → square(inc(double(3))) = square(inc(6)) = square(7) = 49"
      ]
    },
    {
      "name": "functional.partial",
      "file": "lib/functional/partial",
      "description": "Bind the leading arguments of a function, returning a new function that takes the remaining arguments.",
      "tags": ["partial", "curry", "bind", "partial application", "functional"],
      "queries": ["partial application", "bind function arguments", "curry function", "fix first arguments"],
      "params": [
        { "name": "f", "type": "function", "description": "Function to partially apply" },
        { "name": "...", "type": "any", "description": "Arguments to bind to the leading parameters of f" }
      ],
      "returns": "function - A new function that prepends the bound arguments before any new arguments",
      "examples": [
        "local function multiply(x, y) return x * y end\nlocal double = functional.partial(multiply, 2)\ndouble(5) → 10",
        "local function add(a, b) return a + b end\nlocal addTen = functional.partial(add, 10)\nfunctional.map({1, 2, 3}, addTen) → {11, 12, 13}"
      ]
    },
    {
      "name": "functional.identity",
      "file": "lib/functional/identity",
      "description": "Returns its argument unchanged. Useful as a no-op placeholder in compose or pipe chains.",
      "tags": ["identity", "noop", "passthrough", "functional"],
      "queries": ["identity function", "return value unchanged", "noop function"],
      "params": [
        { "name": "x", "type": "any", "description": "Any value" }
      ],
      "returns": "any - The same value passed in",
      "examples": [
        "functional.identity(42) → 42",
        "functional.identity(\"hello\") → \"hello\""
      ]
    },
    {
      "name": "functional.const",
      "file": "lib/functional/const",
      "description": "Returns a function that always returns the given value, ignoring its argument. Useful for providing fixed values in map or compose chains.",
      "tags": ["const", "constant", "always", "fixed", "functional"],
      "queries": ["constant function", "always return value", "ignore argument return fixed value"],
      "params": [
        { "name": "v", "type": "any", "description": "The value to always return" }
      ],
      "returns": "function - A function that ignores its argument and always returns v",
      "examples": [
        "local always5 = functional.const(5)\nalways5(99) → 5",
        "functional.map({1, 2, 3}, functional.const(0)) → {0, 0, 0}"
      ]
    },
    {
      "name": "functional.double",
      "file": "lib/functional/double",
      "description": "Multiply a number by 2.",
      "tags": ["double", "multiply", "numeric", "functional"],
      "queries": ["double a number", "multiply by two"],
      "params": [{ "name": "x", "type": "number", "description": "Input number" }],
      "returns": "number - x * 2",
      "examples": [
        "functional.double(5) → 10",
        "functional.map({1, 2, 3}, functional.double) → {2, 4, 6}"
      ]
    },
    {
      "name": "functional.square",
      "file": "lib/functional/square",
      "description": "Square a number.",
      "tags": ["square", "power", "numeric", "functional"],
      "queries": ["square a number", "raise to power of two", "x squared"],
      "params": [{ "name": "x", "type": "number", "description": "Input number" }],
      "returns": "number - x * x",
      "examples": [
        "functional.square(4) → 16",
        "functional.map({1, 2, 3, 4}, functional.square) → {1, 4, 9, 16}"
      ]
    },
    {
      "name": "functional.negate",
      "file": "lib/functional/negate",
      "description": "Negate a number.",
      "tags": ["negate", "negative", "flip sign", "numeric", "functional"],
      "queries": ["negate number", "flip sign", "negative value"],
      "params": [{ "name": "x", "type": "number", "description": "Input number" }],
      "returns": "number - -x",
      "examples": [
        "functional.negate(7) → -7",
        "functional.map({1, -2, 3}, functional.negate) → {-1, 2, -3}"
      ]
    },
    {
      "name": "functional.abs",
      "file": "lib/functional/abs",
      "description": "Absolute value of a number. Alias for math.abs.",
      "tags": ["abs", "absolute value", "numeric", "functional"],
      "queries": ["absolute value", "abs number", "remove sign"],
      "params": [{ "name": "x", "type": "number", "description": "Input number" }],
      "returns": "number - math.abs(x)",
      "examples": [
        "functional.abs(-5) → 5",
        "functional.map({-3, 1, -4, 1, -5}, functional.abs) → {3, 1, 4, 1, 5}"
      ]
    },
    {
      "name": "functional.inc",
      "file": "lib/functional/inc",
      "description": "Increment a number by 1.",
      "tags": ["inc", "increment", "add one", "numeric", "functional"],
      "queries": ["increment number", "add one", "plus one"],
      "params": [{ "name": "x", "type": "number", "description": "Input number" }],
      "returns": "number - x + 1",
      "examples": [
        "functional.inc(4) → 5",
        "functional.map({0, 1, 2}, functional.inc) → {1, 2, 3}"
      ]
    },
    {
      "name": "functional.dec",
      "file": "lib/functional/dec",
      "description": "Decrement a number by 1.",
      "tags": ["dec", "decrement", "subtract one", "numeric", "functional"],
      "queries": ["decrement number", "subtract one", "minus one"],
      "params": [{ "name": "x", "type": "number", "description": "Input number" }],
      "returns": "number - x - 1",
      "examples": [
        "functional.dec(4) → 3",
        "functional.map({1, 2, 3}, functional.dec) → {0, 1, 2}"
      ]
    },
    {
      "name": "functional.half",
      "file": "lib/functional/half",
      "description": "Divide a number by 2.",
      "tags": ["half", "divide", "numeric", "functional"],
      "queries": ["halve a number", "divide by two"],
      "params": [{ "name": "x", "type": "number", "description": "Input number" }],
      "returns": "number - x / 2",
      "examples": [
        "functional.half(10) → 5",
        "functional.map({2, 4, 6}, functional.half) → {1, 2, 3}"
      ]
    },
    {
      "name": "functional.sqrt",
      "file": "lib/functional/sqrt",
      "description": "Square root of a number. Alias for math.sqrt.",
      "tags": ["sqrt", "square root", "numeric", "functional"],
      "queries": ["square root", "sqrt"],
      "params": [{ "name": "x", "type": "number", "description": "Input number" }],
      "returns": "number - math.sqrt(x)",
      "examples": [
        "functional.sqrt(9) → 3",
        "functional.map({4, 9, 16}, functional.sqrt) → {2, 3, 4}"
      ]
    },
    {
      "name": "functional.floor",
      "file": "lib/functional/floor",
      "description": "Floor a number. Alias for math.floor.",
      "tags": ["floor", "round down", "numeric", "functional"],
      "queries": ["floor number", "round down"],
      "params": [{ "name": "x", "type": "number", "description": "Input number" }],
      "returns": "number - math.floor(x)",
      "examples": [
        "functional.floor(3.7) → 3",
        "functional.map({1.1, 2.9, 3.5}, functional.floor) → {1, 2, 3}"
      ]
    },
    {
      "name": "functional.ceil",
      "file": "lib/functional/ceil",
      "description": "Ceiling of a number. Alias for math.ceil.",
      "tags": ["ceil", "ceiling", "round up", "numeric", "functional"],
      "queries": ["ceil number", "round up"],
      "params": [{ "name": "x", "type": "number", "description": "Input number" }],
      "returns": "number - math.ceil(x)",
      "examples": [
        "functional.ceil(3.2) → 4",
        "functional.map({1.1, 2.9, 3.5}, functional.ceil) → {2, 3, 4}"
      ]
    },
    {
      "name": "functional.round",
      "file": "lib/functional/round",
      "description": "Round a number to the nearest integer.",
      "tags": ["round", "nearest", "numeric", "functional"],
      "queries": ["round number", "nearest integer"],
      "params": [{ "name": "x", "type": "number", "description": "Input number" }],
      "returns": "number - math.floor(x + 0.5)",
      "examples": [
        "functional.round(3.4) → 3",
        "functional.round(3.5) → 4",
        "functional.map({1.1, 2.6, 3.5}, functional.round) → {1, 3, 4}"
      ]
    },
    {
      "name": "functional.add",
      "file": "lib/functional/add",
      "description": "Returns a function that adds n to its argument. Arithmetic combinator.",
      "tags": ["add", "plus", "combinator", "arithmetic", "functional"],
      "queries": ["add n to each", "increment by n", "add combinator"],
      "params": [{ "name": "n", "type": "number", "description": "Value to add" }],
      "returns": "function - function(x) return x + n end",
      "examples": [
        "functional.map({1, 2, 3}, functional.add(10)) → {11, 12, 13}",
        "functional.add(5)(3) → 8"
      ]
    },
    {
      "name": "functional.sub",
      "file": "lib/functional/sub",
      "description": "Returns a function that subtracts n from its argument. Arithmetic combinator.",
      "tags": ["sub", "subtract", "minus", "combinator", "arithmetic", "functional"],
      "queries": ["subtract n from each", "decrement by n", "sub combinator"],
      "params": [{ "name": "n", "type": "number", "description": "Value to subtract" }],
      "returns": "function - function(x) return x - n end",
      "examples": [
        "functional.map({10, 20, 30}, functional.sub(5)) → {5, 15, 25}"
      ]
    },
    {
      "name": "functional.mul",
      "file": "lib/functional/mul",
      "description": "Returns a function that multiplies its argument by n. Arithmetic combinator.",
      "tags": ["mul", "multiply", "times", "combinator", "arithmetic", "functional"],
      "queries": ["multiply each by n", "scale values", "mul combinator"],
      "params": [{ "name": "n", "type": "number", "description": "Multiplier" }],
      "returns": "function - function(x) return x * n end",
      "examples": [
        "functional.map({1, 2, 3}, functional.mul(3)) → {3, 6, 9}",
        "functional.mul(2)(5) → 10"
      ]
    },
    {
      "name": "functional.div",
      "file": "lib/functional/div",
      "description": "Returns a function that divides its argument by n. Arithmetic combinator.",
      "tags": ["div", "divide", "combinator", "arithmetic", "functional"],
      "queries": ["divide each by n", "scale down", "div combinator"],
      "params": [{ "name": "n", "type": "number", "description": "Divisor" }],
      "returns": "function - function(x) return x / n end",
      "examples": [
        "functional.map({10, 20, 30}, functional.div(10)) → {1, 2, 3}"
      ]
    },
    {
      "name": "functional.pow",
      "file": "lib/functional/pow",
      "description": "Returns a function that raises its argument to the power n. Arithmetic combinator.",
      "tags": ["pow", "power", "exponent", "combinator", "arithmetic", "functional"],
      "queries": ["raise to power", "exponent combinator", "pow each element"],
      "params": [{ "name": "n", "type": "number", "description": "Exponent" }],
      "returns": "function - function(x) return x ^ n end",
      "examples": [
        "functional.map({1, 2, 3, 4}, functional.pow(2)) → {1, 4, 9, 16}",
        "functional.map({1, 2, 3}, functional.pow(3)) → {1, 8, 27}"
      ]
    },
    {
      "name": "functional.mod",
      "file": "lib/functional/mod",
      "description": "Returns a function that computes its argument modulo n. Arithmetic combinator.",
      "tags": ["mod", "modulo", "remainder", "combinator", "arithmetic", "functional"],
      "queries": ["modulo each element", "remainder combinator", "mod n"],
      "params": [{ "name": "n", "type": "number", "description": "Modulus" }],
      "returns": "function - function(x) return x % n end",
      "examples": [
        "functional.map({1, 2, 3, 4, 5}, functional.mod(2)) → {1, 0, 1, 0, 1}",
        "functional.filter({1,2,3,4,5,6}, function(x) return functional.mod(2)(x) == 0 end) → {2, 4, 6}"
      ]
    }
  ]
}