mrdocs::lua::registerHelper

Register a Lua helper function

Synopsis

Declared in <mrdocs/Support/Lua.hpp>

[[nodiscard]]
Expected<void, Error>
registerHelper(
    mrdocs::Handlebars& hbs,
    std::string_view name,
    Context& ctx,
    std::string_view script);

Description

Register a Lua chunk as a Handlebars helper. The chunk source is resolved to a callable in the following order:

1. Chunk return value ‐ load and execute the chunk; if it returns a function, use that. This is the idiomatic shape for a per‐file helper: Example: return function(x) return 'lua:' .. tostring(x) end

2. Global lookup ‐ if the chunk does not return a function, look up the helper name on the global table. This handles chunks that define a function as a side effect: Example: function helper_name(x) return tostring(x) end

The resolved function is anchored in LUA_REGISTRYINDEX for the lifetime of the registration. When the helper is invoked from a template, positional arguments are converted from dom::Value to Lua values; the trailing Handlebars options object is dropped (matching the JavaScript helper semantics) to avoid recursive marshalling of symbol contexts.

Return Value

Success, or an error if the script could not be resolved to a function

The return value should not be discarded.

Parameters

Name

Description

hbs

The Handlebars instance to register the helper into

name

The name of the helper function

ctx

The Lua context that anchors the helper closure

script

The Lua source that defines the helper function

Created with MrDocs