{ "classes": [ { "constants": [], "types": [ { "lua_type": "type TemplateError = Parser.TemplateError", "name": "TemplateError", "tags": [], "source": { "path": "", "line": 253 }, "fields": [], "desc": "A structured error value thrown by `compileRaw` and `evaluateRaw`.\n\nRe-exported from the parser so consumers only need to import this\nmodule when working with structured errors.\n" }, { "lua_type": "type Template = Parser.AstSuite", "name": "Template", "tags": [], "source": { "path": "", "line": 255 }, "fields": [], "desc": "" } ], "name": "@eryx/template", "tags": [], "functions": [ { "source": { "path": "", "line": 715 }, "is_method": false, "signature": "template.compile(\n source: string, -- The template source string to compile.\n filepath: string? -- Optional file path of the template, required for `{% include %}` resolution.\n) → (\n AstSuite -- The compiled AST. \n)", "owner": "template", "desc": "Parses a template source string into a list of AST nodes.\n\nThe returned nodes can be passed to [[evaluate]] one or more times\nwith different context tables, avoiding repeated parsing.\n\nOn failure, calls `error()` with a formatted string such as\n`\"myfile.html:3:7: Unterminated string literal\"`.\nUse [[compileRaw]] if you need the structured [[TemplateError]] table.\n", "tags": [], "name": "compile", "return_str": "Template", "function_type": "Function", "returns": [ { "lua_type": "Template", "desc": "The compiled AST. " } ], "params": [ { "lua_type": "string", "name": "source", "desc": "The template source string to compile." }, { "lua_type": "string?", "name": "filepath", "desc": "Optional file path of the template, required for `{% include %}` resolution." } ] }, { "source": { "path": "", "line": 733 }, "is_method": false, "signature": "template.compileRaw(\n source: string, -- The template source string to compile.\n filepath: string? -- Optional file path of the template.\n) → (\n AstSuite -- The compiled AST. \n)", "owner": "template", "desc": "Like [[compile]], but propagates a [[TemplateError]] table via `error()`\ninstead of a formatted string. Use this when you want to inspect the\nstructured error (`.message`, `.line`, `.col`, `.filepath`) rather than\nwrapping the call in `pcall` yourself just to re-format the message.\n", "tags": [], "name": "compileRaw", "return_str": "Template", "function_type": "Function", "returns": [ { "lua_type": "Template", "desc": "The compiled AST. " } ], "params": [ { "lua_type": "string", "name": "source", "desc": "The template source string to compile." }, { "lua_type": "string?", "name": "filepath", "desc": "Optional file path of the template." } ] }, { "source": { "path": "", "line": 757 }, "is_method": false, "signature": "template.evaluate(\n nodes: Template, -- The AST produced by [[compile]].\n ctx: { [string]: any }?, -- Optional context table whose keys become template variables.\n filters: { [string]: ((any, { [string]: any }) → any) }? -- Optional table of custom filter functions.\n) → (\n string -- The fully rendered template output. \n)", "owner": "template", "desc": "Renders a compiled template (array of AST nodes) into a string.\n\nCustom filters can be supplied and will be merged with (and can\noverride) the built-in filter set.\n\nOn failure, calls `error()` with a formatted string such as\n`\"myfile.html:5:12: Unknown filter 'foo'\"`.\nUse [[evaluateRaw]] if you need the structured [[TemplateError]] table.\n\n```luau\nlocal nodes = template.compile(\"Hello, {{ name }}!\")\nprint(template.evaluate(nodes, { name = \"World\" })) --> \"Hello, World!\"\n```\n", "tags": [], "name": "evaluate", "return_str": "string", "function_type": "Function", "returns": [ { "lua_type": "string", "desc": "The fully rendered template output. " } ], "params": [ { "lua_type": "Template", "name": "nodes", "desc": "The AST produced by [[compile]]." }, { "lua_type": "{ [string]: any }?", "name": "ctx", "desc": "Optional context table whose keys become template variables." }, { "lua_type": "{ [string]: ((any, { [string]: any }) → any) }?", "name": "filters", "desc": "Optional table of custom filter functions." } ] }, { "source": { "path": "", "line": 778 }, "is_method": false, "signature": "template.evaluateRaw(\n nodes: Template, -- The AST produced by [[compile]] or [[compileRaw]].\n ctx: { [string]: any }?, -- Optional context table whose keys become template variables.\n filters: { [string]: ((any, { [string]: any }) → any) }? -- Optional table of custom filter functions.\n) → (\n string -- The fully rendered template output. \n)", "owner": "template", "desc": "Like [[evaluate]], but propagates a [[TemplateError]] table via `error()`\ninstead of a formatted string.\n", "tags": [], "name": "evaluateRaw", "return_str": "string", "function_type": "Function", "returns": [ { "lua_type": "string", "desc": "The fully rendered template output. " } ], "params": [ { "lua_type": "Template", "name": "nodes", "desc": "The AST produced by [[compile]] or [[compileRaw]]." }, { "lua_type": "{ [string]: any }?", "name": "ctx", "desc": "Optional context table whose keys become template variables." }, { "lua_type": "{ [string]: ((any, { [string]: any }) → any) }?", "name": "filters", "desc": "Optional table of custom filter functions." } ] } ], "properties": [], "source": { "path": "", "line": 0 }, "desc": "Jinja-inspired template engine for Luau.\n\nCompiles template source strings into an AST, then evaluates them\nagainst a context table to produce rendered output.\n\n## Template Syntax\n\n### Expressions - `{{ expr }}`\n\nOutputs the value of an expression, coerced to a string.\n\n```\n{{ name }} -- variable lookup from context\n{{ user.email }} -- nested/dotted property access\n{{ 42 }} -- numeric literal (integer or decimal)\n{{ \"hello\" }} -- string literal (supports \\n \\t \\r \\\\ \\\")\n{{ true }} -- boolean constant (renders as \"true\")\n{{ false }} -- boolean constant (renders as \"false\")\n{{ not logged_in }} -- unary not (negates truthiness)\n{{ items[i] }} -- subscript lookup with a variable key\n{{ data[\"key\"] }} -- subscript lookup with a string key\n{{ name | length }} -- pipe a value through a filter\n{{ x | filter1 | f2 }} -- chain multiple filters left-to-right\n```\n\n### Comments - `{# ... #}`\n\nIgnored by the engine; produces no output.\n\n```\n{# This is a comment #}\n```\n\n### Conditionals - `{% if … then %}`\n\nConditional blocks. The condition is truthy/falsy (`nil` and `false`\nare falsy; everything else is truthy).\n\n```\n{% if logged_in then %}Welcome!{% end %}\n\n{% if count == 0 then %}\n Empty\n{% elseif count < 5 then %}\n A few\n{% else %}\n Many\n{% end %}\n```\n\nSupported comparison operators: `==`, `~=`, `<`, `>`, `<=`, `>=`.\n\nConditions can be chained with `and` / `or`:\n\n```\n{% if role == \"admin\" and active then %}...{% end %}\n{% if x or y then %}...{% end %}\n```\n\nA bare expression (no operator) is treated as a truthiness check:\n\n```\n{% if user then %}...{% end %}\n{% if true then %}...{% end %}\n{% if not logged_in then %}...{% end %}\n```\n\n### Table For-Loop - `{% for k, v in tbl do %}`\n\nIterates over key/value pairs of a table expression. Both loop\nvariables are injected into the context and restored after the loop.\n\n```\n{% for i, item in items do %}\n {{ i }}: {{ item.name }}\n{% end %}\n```\n\n### Numeric For-Loop - `{% for i = start, end do %}`\n\nCounts from `start` to `end` (inclusive). The loop variable is\ninjected into the context and restored after the loop.\n\n```\n{% for i = 1, 5 do %}\n Row {{ i }}\n{% end %}\n```\n\n### Macros - `{% macro name(args) %}`\n\nDefines a reusable template block. Arguments become context variables\nwithin the macro body.\n\n```\n{% macro greeting(name, title) %}\n Hello, {{ title }} {{ name }}!\n{% end %}\n```\n\nCall a macro with `{% use %}` to provide a body, or `{{ }}` for a\nsimple inline call:\n\n```\n{% use greeting(\"Alice\", \"Dr.\") %}\n

Extra content here

\n{% end %}\n```\n\nInside a macro, `{% slot default %}` renders the caller's body.\nNamed slots can also be used - see **Slots** below.\n\n### Slots - `{% slot name %}` / `{% fill name %}`\n\nSlots define placeholder regions inside a macro body that callers\ncan fill with custom content. Each slot has a default body that is\nused when the caller does not provide a `{% fill %}` for it.\n\n```\n{% macro card(title) %}\n
\n

{{ title }}

\n {% slot body %}

Default body

{% end %}\n {% slot footer %}Default footer{% end %}\n
\n{% end %}\n\n{% use card(\"My Card\") %}\n {% fill body %}

Custom body!

{% end %}\n {% fill footer %}Custom footer{% end %}\n{% end %}\n```\n\nThe special slot name `\"default\"` is reserved and automatically\nreceives the caller's top-level body content (anything not inside a\n`{% fill %}`). You cannot explicitly name a slot `\"default\"`.\n\n### Includes - `{% include \"path\" %}`\n\nInlines another template file at parse time. The path is resolved\nrelative to the directory of the current template file.\n\n```\n{% include \"header.html\" %}{% end %}\n
Content
\n{% include \"footer.html\" %}{% end %}\n```\n\nIncludes accept a body block between `{% include %}` and `{% end %}`.\nThe body content is available to the included file as the `\"default\"`\nslot, and named slots can be filled with `{% fill %}` - just like\nmacro calls.\n\n```\n{% include \"layout.html\" %}\n {% fill sidebar %}{% end %}\n {% fill content %}

Page body here

{% end %}\n{% end %}\n```\n\nInside the included file, use `{% slot %}` to define the placeholder\nregions that callers can fill:\n\n```\n{# layout.html #}\n
{% slot sidebar %}{% end %}
\n
{% slot content %}

Default content

{% end %}
\n```\n\n:::caution\nA file path must be provided to [[compile]] for includes to work.\n:::\n\n### Literal Text\n\nAnything outside `{{ }}`, `{% %}`, and `{# #}` delimiters is emitted\nas-is.\n\n## Built-in Filters\n\n### String Filters\n\n| Filter | Description |\n|--------------|-------------|\n| `length` | Returns `#tbl` for tables, or `string.len` for everything else. |\n| `upper` | Converts to uppercase. |\n| `lower` | Converts to lowercase. |\n| `trim` | Strips leading and trailing whitespace. |\n| `capitalize` | Capitalizes the first letter, lowercases the rest. |\n| `title` | Capitalizes the first letter of each word. |\n| `replace` | Replaces occurrences using `replace_from` and `replace_to` context variables. |\n\n### Collection Filters\n\n| Filter | Description |\n|-----------|-------------|\n| `first` | Returns the first element of an array. |\n| `last` | Returns the last element of an array. |\n| `join` | Joins array elements with `join_separator` (default `\", \"`). |\n| `reverse` | Reverses an array or string. |\n| `keys` | Returns the keys of a table as an array. |\n| `values` | Returns the values of a table as an array. |\n| `sort` | Returns a sorted copy of an array (lexicographic). |\n\n### Numeric Filters\n\n| Filter | Description |\n|---------|-------------|\n| `abs` | Returns the absolute value. |\n| `round` | Rounds to the nearest integer. |\n| `floor` | Rounds down. |\n| `ceil` | Rounds up. |\n\n### Utility Filters\n\n| Filter | Description |\n|-----------|-------------|\n| `default` | Returns `default_value` from context if value is nil/false (defaults to `\"\"`). |\n| `json` | Encodes the value as a JSON string. |\n| `type` | Returns the Luau type name of the value. |\n\n## Error Handling\n\n`compile` and `evaluate` are the standard entry points. On failure they\ncall `error()` with a human-readable string (e.g. `\"3:7: Unknown filter 'foo'\"`).\n\nIf you want the structured [[TemplateError]] table instead, call the\n`Raw` variants (`compileRaw` / `evaluateRaw`), which propagate the\ntable directly so you can inspect `.message`, `.line`, `.col`, and\n`.filepath` yourself.\n\n## Example\n\n```luau\nlocal template = require(\"@eryx/template\")\n\nlocal tmpl = template.compile(\"Hello, {{ name | length }}!\")\nprint(template.evaluate(tmpl, { name = \"World\" })) --> \"Hello, 5!\"\n```\n" } ] }