molde

Contents

• Tables
• Fields
• Internal functions
• Functions

Modules

• molde

Topics

• README

Module molde

Tables

Token	Tokens returned by tokenize
ParseState	Parse states returned by parse
ParseError	Parse errors that can occur in a template

Fields

VERSION

Module version: 2.0.0

Internal functions

tokenize (template)	Tokenize template, returning a coroutine that yields pairs of Token, string.
parse (template)	Parse template, returning a coroutine that yields pairs of ParseState, string.
compile (template[, string_bracket_level=1])	Compiles a string with contents to Lua code that generates the (hopefully) desired result.

Functions

load (template[, chunk_name='molde generator'[, string_bracket_level=1]])	Compiles the template, returning a closure that executes the substitution.
loadfile (filename[, chunk_name=filename[, string_bracket_level=1]])	Same as molde.load, but loads the template from a file.
TemplateFunctionPrototype ([values[, env=_G]])	This is the prototype of the function returned by molde.load and molde.loadfile.

Tables

Token

Tokens returned by tokenize

Fields:

• LITERAL Literal token, accompanied by the read literal value
• NEWLINE New line token, accompanied by it's value "\n"
• VALUE_BEGIN Begin value token, accompanied by it's value "{{"
• VALUE_END End value token, accompanied by it's value "}}"
• STATEMENT_BEGIN Begin statement token, accompanied by it's value "{%"
• STATEMENT_END End statement token, accompanied by it's value "}}"

ParseState

Parse states returned by parse

Fields:

• LITERAL Parser read a literal, accompanied by the read text
• VALUE Parser read a value, accompanied by the text between "{{" and "}}"
• STATEMENT Parser read a statement, accompanied by the text between "{%" and "%}"
• ERROR Parser error, accompanied by the corresponding ParseError

ParseError

Parse errors that can occur in a template

Fields:

• EXPECTED_CLOSING_VALUE "closing '}}' expected"
• EXPECTED_CLOSING_STATEMENT "closing '%}' expected"
• UNEXPECTED_OPENING_VALUE "unexpected opening '{{' found"
• UNEXPECTED_OPENING_STATEMENT "unexpected opening '{%' found"
• UNEXPECTED_CLOSING_VALUE "unexpected closing '}}' found"
• UNEXPECTED_CLOSING_STATEMENT "unexpected closing '%}' found"
• EMPTY_VALUE "empty value between '{{' and '}}'"
• EMPTY_STATEMENT "empty statement between '{%' and '%}'"

Fields

VERSION

Module version: 2.0.0

Internal functions

tokenize (template)

Tokenize template, returning a coroutine that yields pairs of Token, string.

Parameters:

• template Text string

Returns:

function Token, string pair iterator

Usage:

for token, value in molde.tokenize(template_text) do
    if token == molde.Token.LITERAL then
        print('Literal found: ', value)
    elseif token == molde.Token.NEWLINE then
        print('New line found', value == '\n')
    elseif token == molde.Token.VALUE_BEGIN then
        print('Value begin found', value == '{{')
    -- ...
    end
end

parse (template)

Parse template, returning a coroutine that yields pairs of ParseState, string.

Parameters:

• template Text string

Returns:

function ParseState, string pair iterator. The parser will stop at the first error it encounters.

Usage:

for parse_state, value in molde.parse(template_text) do
    if parse_state == molde.ParseState.LITERAL then
        print('Literal found: ', value)
    elseif parse_state == molde.ParseState.VALUE then
        print('{{ Value found }}', value)
    elseif parse_state == molde.ParseState.STATEMENT then
        print('{% Statement found %}', value)
    else  -- parse_state == molde.ParseState.ERROR
        error('Parse error: ' .. value)
    end
end

compile (template[, string_bracket_level=1])

Compiles a string with contents to Lua code that generates the (hopefully) desired result.

The code generated for literals use Lua's long strings, with a level of string_bracket_level (default: 1). You should set it to a higher level if your literal may contain the string "]=]".

Parameters:

• template Template string to be compiled
• string_bracket_level Long string bracket level, used to create the necessary string delimiters for literals: string.rep('=', string_bracket_level) (default 1)

Returns:

string Generated code

Or

1. nil
2. string Parse error message

Functions

load (template[, chunk_name='molde generator'[, string_bracket_level=1]])

Compiles the template, returning a closure that executes the substitution.

The returned function behaves as described in TemplateFunctionPrototype.

Parameters:

• template Template string
• chunk_name Name of the chunk for error messages (default 'molde generator')
• string_bracket_level Long string bracket level, forwarded to molde.compile (default 1)

Returns:

function Template processor

Or

1. nil
2. Parse error message

Or

1. nil
2. Template process function call error message

Usage:

hello_template = molde.load([[Hello {{ name or "world" }}]])
hello = hello_template()
print(hello) -- "Hello world"

loadfile (filename[, chunk_name=filename[, string_bracket_level=1]])

Same as molde.load, but loads the template from a file.

Uses filename as chunkname by default.

Every caveat for molde.load applies.

Parameters:

• filename Template file path
• chunk_name Name of the chunk for error messages (default filename)
• string_bracket_level Long string bracket level, forwarded to molde.load (default 1)

Returns:

function Template processor

Or

1. nil
2. File open error

Or

1. nil
2. Parse error

Or

1. nil
2. Template process function call error message

See also:

molde.load

Usage:

-- hello_template_file contents == "literal {{ value }} {% statement %}"
hello_template = molde.loadfile("hello_template_file")
hello = hello_template()
print(hello) -- "Hello world"

TemplateFunctionPrototype ([values[, env=_G]])

This is the prototype of the function returned by molde.load and molde.loadfile.

The environment is sandboxed, so assigning variables directly to it won't affect the original tables. Variable lookup order: local environment, values, env. The env table serves as a fallback environment, and is useful when you want to sandbox builtin Lua functions.

Parameters:

• values Table with the values to substitute (optional)
• env Fallback environment (default _G)

Returns:

1. string Processed template
2. table The sandboxed environment used

Raises:

When the generated code is invalid

Usage:

hello_template = molde.load([[
{% name = (name or "world") .. "!!!" %}
Hello {{ name }}
]])
message, template_env = hello_template()
print(message, template_env.name) -- "Hello world!!!"  "world!!!"
values = { name = "gilzoide" }
message, template_env = hello_template(values)
print(message, values.name, template_env.name) -- "Hello gilzoide!!!"  "gilzoide"  "gilzoide!!!"
env = { name = "y'all" }
message, template_env = hello_template(values, env)
print(message, template_env.name) -- "Hello gilzoide!!!"  "gilzoide!!!"
message, template_env = hello_template(nil, env)
print(message, env.name, template_env.name) -- "Hello y'all!!!"  "y'all"  "y'all!!!"