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. 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