Penlight Documentation

# 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