Module pl.template
A template preprocessor.
Originally by [Ricki Lake](http://lua-users.org/wiki/SlightlyLessSimpleLuaPreprocessor)
There are two rules:
* lines starting with # are Lua * otherwise, `$(expr)` is the result of evaluating `expr`
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 ???.
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`, or `nil + 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`, or `nil + 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 `opts` table 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 is `nil` (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_code`
Usage:
local ct, err = template.compile(my_template) local rendered , err = ct:render(my_env, parent)