Module pl.template
A template preprocessor.
Originally by Ricki Lake
There are two rules:
- lines starting with # are Lua
- otherwise,
$(expr)is the result of evaluatingexpr
Example:
# for i = 1,3 do $(i) Hello, Word! # end ===> 1 Hello, Word! 2 Hello, Word! 3 Hello, Word!
Other escape characters can be used, when the defaults conflict with the output language.
> for _,n in pairs{'one','two','three'} do static int l_${n} (luaState *state); > end
See the Guide.
Dependencies: pl.utils
Functions
| substitute (str[, env]) | expand the template using the specified environment. |
| ct:render ([env[, parent[, db]]]) | executes the previously compiled template and renders it. |
| compile (str[, opts]) | compiles the template. |
Functions
- substitute (str[, env])
-
expand the template using the specified environment. This function will compile and render the template. For more performant recurring usage use the two step approach by using compile and ct:render. There are six special fields in the environment table
env_parent: continue looking up in this table (e.g._parent=_G)._brackets: bracket pair that wraps inline Lua expressions, default is '()'._escape: character marking Lua lines, default is '#'_inline_escape: character marking inline Lua expression, default is '$'._chunk_name: chunk name for loaded templates, used if there is an error in Lua code. Default is 'TMP'._debug: if truthy, the generated code will be printed upon a render error
Parameters:
- str string the template string
- env tab the environment (optional)
Returns:
rendered template + nil + source_code, ornil + error + source_code. The last return value (source_code) is only returned if the debug option is used. - ct:render ([env[, parent[, db]]])
-
executes the previously compiled template and renders it.
Parameters:
- env tab the environment. (optional)
- parent
tab
continue looking up in this table (e.g.
parent=_G). (optional) - db bool if thruthy, it will print the code upon a render error (provided the template was compiled with the debug option). (optional)
Returns:
rendered template + nil + source_code, ornil + error + source_code. The last return value (source_code) is only returned if the template was compiled with the debug option.Usage:
local ct, err = template.compile(my_template) local rendered , err = ct:render(my_env, parent)
- compile (str[, opts])
-
compiles the template. Returns an object that can repeatedly be rendered without parsing/compiling the template again. The options passed in the
optstable support the following options:chunk_name: chunk name for loaded templates, used if there is an error in Lua code. Default is 'TMP'.escape: character marking Lua lines, default is '#'inline_escape: character marking inline Lua expression, default is '$'.inline_brackets: bracket pair that wraps inline Lua expressions, default is '()'.newline: string to replace newline characters, default isnil(not replacing newlines).- debug: if truthy, the generated source code will be retained within the compiled template object, default is
nil.
Parameters:
- str string the template string
- opts tab the compilation options to use (optional)
Returns:
-
template object, or
nil + error + source_codeUsage:
local ct, err = template.compile(my_template) local rendered , err = ct:render(my_env, parent)