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.

Parameters:

  • str string the template string
  • env the environment. This table has the following special fields:
    • _parent table continue looking up in this table (e.g. _parent=_G). (default nil)
    • _brackets string bracket pair that wraps inline Lua expressions. (default "()")
    • _escape string character marking Lua lines. (default "#")
    • _inline_escape string character marking inline Lua expression. (default "$")
    • _chunk_name string chunk name for loaded templates, used if there is an error in Lua code. (default "TMP")
    • _debug boolean if truthy, the generated code will be printed upon a render error. (default false)

Returns:

  1. string render result
  2. nil
  3. string source_code (only if 'env._debug' was truthy).

Or

  1. nil
  2. string error message
  3. string source_code (only if 'env._debug' was truthy).
ct:render ([env[, parent[, db]]])
executes the previously compiled template and renders it.

Parameters:

  • env table the environment. (optional)
  • parent table continue looking up in this table (e.g. parent=_G). (optional)
  • db boolean if thruthy, it will print the code upon a render error (provided the template was compiled with the debug option). (optional)

Returns:

  1. string render result
  2. nil
  3. string source_code (only if 'env._debug' was truthy).

Or

  1. nil
  2. string error message
  3. string source_code (only if 'env._debug' was truthy).

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. Preserves the line layout of the template so that line numbers in error messages should point to the correct lines in the source string.

Parameters:

  • str string the template string
  • opts the compilation options to use. This table supports the following options:
    • chunk_name string chunk name for loaded templates, used if there is an error in Lua code. (default "TMP")
    • escape string character marking Lua lines. (default "#")
    • inline_escape string character marking inline Lua expression. (default "$")
    • inline_brackets string bracket pair that wraps inline Lua expressions. (default "()")
    • newline boolean if truthy, newlines will be stripped from text in the template. (default false)
    • debug boolean if truthy, the generated code will be printed upon a render error. (default false)

Returns:

    ct compiled template object

Or

  1. nil
  2. string error message
  3. string source_code

Usage:

    local ct, err = template.compile(my_template)
local rendered , err = ct:render(my_env, parent)
generated by LDoc 1.5.0