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 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 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, 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)
generated by LDoc 1.4.6 Last updated 2017-07-18 16:28:41