builtins.json

{
  "categories": [
    {
      "id": "xllify.builtins",
      "name": "Built-in Utilities",
      "description": "Fast native helper functions available on the xllify global. These are not Excel functions — call them inside your own functions for parsing, matching, and text processing without the overhead of a pure-Lua implementation.",
      "functionCount": 8
    }
  ],
  "functions": [
    {
      "name": "xllify.json_parse",
      "file": "lib/builtins/json_parse",
      "description": "Parse a JSON string into a native Lua table",
      "tags": [
        "json",
        "parse",
        "decode",
        "deserialize",
        "table",
        "object",
        "array",
        "data"
      ],
      "queries": [
        "parse json",
        "json to table",
        "decode json string",
        "read json"
      ],
      "params": [
        {
          "name": "json_string",
          "type": "string",
          "description": "A valid JSON string to parse"
        }
      ],
      "returns": "table | nil, error - Parsed Lua table, or nil and an error message on failure",
      "examples": [
        "xllify.json_parse('{\"name\": \"Alice\", \"age\": 30}') → {name = \"Alice\", age = 30}",
        "xllify.json_parse('[1, 2, 3]') → {1, 2, 3}",
        "xllify.json_parse('invalid') → nil, \"error message\""
      ]
    },
    {
      "name": "xllify.levenshtein_distance",
      "file": "lib/builtins/levenshtein_distance",
      "description": "Calculate the Levenshtein edit distance between two strings",
      "tags": [
        "levenshtein",
        "edit distance",
        "fuzzy",
        "similarity",
        "compare",
        "string distance",
        "typo",
        "match"
      ],
      "queries": [
        "edit distance between strings",
        "levenshtein distance",
        "string similarity",
        "fuzzy string match",
        "how similar are two strings"
      ],
      "params": [
        {
          "name": "a",
          "type": "string",
          "description": "First string"
        },
        {
          "name": "b",
          "type": "string",
          "description": "Second string"
        }
      ],
      "returns": "number - The minimum number of single-character edits (insertions, deletions, substitutions) to transform a into b",
      "examples": [
        "xllify.levenshtein_distance(\"kitten\", \"sitting\") → 3",
        "xllify.levenshtein_distance(\"hello\", \"hello\") → 0",
        "xllify.levenshtein_distance(\"abc\", \"\") → 3"
      ]
    },
    {
      "name": "xllify.strip_html",
      "file": "lib/builtins/strip_html",
      "description": "Remove HTML tags and decode common HTML entities from a string",
      "tags": [
        "html",
        "strip",
        "clean",
        "tags",
        "sanitize",
        "entities",
        "markup",
        "text"
      ],
      "queries": [
        "remove html tags",
        "strip html from text",
        "clean html",
        "html to plain text",
        "sanitize html"
      ],
      "params": [
        {
          "name": "text",
          "type": "string",
          "description": "HTML string to strip"
        }
      ],
      "returns": "string - Plain text with HTML tags removed and common entities decoded",
      "examples": [
        "xllify.strip_html(\"<b>Hello</b> <i>world</i>\") → \"Hello world\"",
        "xllify.strip_html(\"Price: &amp;pound;5 &amp;gt; &amp;pound;3\") → \"Price: £5 > £3\"",
        "xllify.strip_html(\"No tags here\") → \"No tags here\""
      ]
    },
    {
      "name": "xllify.spell_number",
      "file": "lib/builtins/spell_number",
      "description": "Convert a number to English words (handles up to trillions, negatives, and decimals)",
      "tags": [
        "spell",
        "number",
        "words",
        "english",
        "text",
        "convert",
        "cardinal",
        "amount",
        "cheque"
      ],
      "queries": [
        "number to words",
        "spell out number",
        "convert number to english",
        "number as text",
        "write number in words"
      ],
      "params": [
        {
          "name": "n",
          "type": "number",
          "description": "Number to spell out"
        }
      ],
      "returns": "string - The number spelled out in English words",
      "examples": [
        "xllify.spell_number(42) → \"forty-two\"",
        "xllify.spell_number(-7) → \"negative seven\"",
        "xllify.spell_number(1000000) → \"one million\""
      ]
    },
    {
      "name": "xllify.json_stringify",
      "file": "lib/builtins/json_stringify",
      "description": "Convert a Lua value (table, string, number, boolean, nil) to a JSON string",
      "tags": [
        "json",
        "stringify",
        "encode",
        "serialize",
        "table",
        "object",
        "array",
        "data"
      ],
      "queries": [
        "convert to json",
        "table to json string",
        "serialize to json",
        "encode json",
        "json stringify"
      ],
      "params": [
        {
          "name": "value",
          "type": "any",
          "description": "A Lua value to convert to JSON"
        }
      ],
      "returns": "string - JSON string representation of the value",
      "examples": [
        "xllify.json_stringify({name = \"Alice\", age = 30}) → \"{\\\"age\\\":30,\\\"name\\\":\\\"Alice\\\"}\"",
        "xllify.json_stringify({1, 2, 3}) → \"[1,2,3]\"",
        "xllify.json_stringify(\"hello\") → \"\\\"hello\\\"\""
      ]
    }
  ,
    {
      "name": "xllify.ensure_matrix",
      "file": "lib/builtins/ensure_matrix",
      "description": "Normalise a scalar or range parameter to always be a 2D table of rows. Use at the top of any function with dimensionality = \"matrix\" that might receive a single cell instead of a range.",
      "tags": ["matrix", "range", "normalise", "scalar", "guard", "excel", "2d"],
      "queries": [
        "normalise matrix parameter",
        "handle single cell or range",
        "guard against scalar range",
        "ensure 2d table",
        "dimensionality matrix guard"
      ],
      "params": [
        { "name": "v", "type": "any", "description": "A scalar value, 1D table, or 2D table of rows" }
      ],
      "returns": "table - Always a 2D table of rows",
      "examples": [
        "xllify.ensure_matrix(42) → {{42}}",
        "xllify.ensure_matrix({1, 2, 3}) → {{1, 2, 3}}",
        "xllify.ensure_matrix({{1, 2}, {3, 4}}) → {{1, 2}, {3, 4}}"
      ]
    },
    {
      "name": "xllify.flatten_range",
      "file": "lib/builtins/flatten_range",
      "description": "Flatten a matrix range (2D table of rows) to a 1D array of numbers, skipping any non-numeric cells. Handles scalars, 1D arrays, and 2D matrices uniformly.",
      "tags": ["flatten", "range", "matrix", "1d", "numbers", "excel", "array"],
      "queries": [
        "flatten excel range to 1d",
        "flatten matrix numbers",
        "extract numbers from range",
        "collapse 2d range",
        "flatten range skip non numbers"
      ],
      "params": [
        { "name": "m", "type": "any", "description": "A scalar, 1D table, or 2D matrix of rows" }
      ],
      "returns": "table - 1D array containing only the numeric values from the input",
      "examples": [
        "xllify.flatten_range({{1, 2}, {3, 4}}) → {1, 2, 3, 4}",
        "xllify.flatten_range({{10}, {\"N/A\"}, {30}}) → {10, 30}",
        "xllify.flatten_range(42) → {42}"
      ]
    },
    {
      "name": "xllify.criteria_pred",
      "file": "lib/builtins/criteria_pred",
      "description": "Returns a predicate function for an Excel-style criteria string. Supports \"odd\", \"even\", comparison operators (>, >=, <, <=, =, <>, !=), and falls back to strict equality for plain values. Composes naturally with functional.filter.",
      "tags": ["criteria", "predicate", "filter", "countif", "sumif", "comparison", "excel", "functional"],
      "queries": [
        "excel criteria predicate",
        "countif style filter",
        "criteria string to function",
        "filter by comparison operator",
        "sumif criteria"
      ],
      "params": [
        { "name": "criteria", "type": "any", "description": "An Excel-style criteria string: \"odd\", \"even\", \">5\", \">=10\", \"<>3\", or a plain value for equality" }
      ],
      "returns": "function - A predicate function(v) → boolean",
      "examples": [
        "xllify.criteria_pred(\">5\")(7) → true",
        "xllify.criteria_pred(\"odd\")(3) → true",
        "xllify.criteria_pred(\"<>10\")(10) → false",
        "functional.filter({1,2,3,4,5,6}, xllify.criteria_pred(\"even\")) → {2, 4, 6}"
      ]
    }
  ]
}