Penlight

• Index

Contents

• Functions

Libraries

• pl
• pl.Set
• pl.app
• pl.array2d
• pl.class
• pl.compat
• pl.comprehension
• pl.config
• pl.data
• pl.dir
• pl.file
• pl.func
• pl.import_into
• pl.input
• pl.lapp
• pl.lexer
• pl.luabalanced
• pl.operator
• pl.path
• pl.permute
• pl.pretty
• pl.seq
• pl.sip
• pl.strict
• pl.stringio
• pl.stringx
• pl.tablex
• pl.template
• pl.test
• pl.text
• pl.types
• pl.url
• pl.utils
• pl.xml

Classes

• pl.Date
• pl.List
• pl.Map
• pl.MultiMap
• pl.OrderedMap

Manual

• Introduction
• Tables and Arrays
• Strings. Higher-level operations on strings.
• Paths and Directories
• Date and Time
• Data
• Functional Programming
• Additional Libraries
• Technical Choices

Examples

• seesubst.lua
• sipscan.lua
• symbols.lua
• test-cmp.lua
• test-data.lua
• test-listcallbacks.lua
• test-pretty.lua
• test-symbols.lua
• testapp.lua
• testclone.lua
• testconfig.lua
• testglobal.lua
• testinputfields.lua
• testinputfields2.lua
• testxml.lua
• which.lua

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)