ltp — preprocesses template files containing embedded Lua code
ltp is a general purpose text preprocessor intended for generative programming and template-based document generation. It processes a template file combined with zero or more environment files containing the data to be inserted into the template. Expressions embedded in templates are evaluated as Lua code within an environment formed from the successive composition of all the environment files.
The resulting document is written to standard output. To write output to a specific file, you should use shell output redirection.
- Compiles template to Lua code.
- Compiles template to Lua code, omitting the function wrapper.
- Executes Lua code within the template execution environment immediately before executing the template.
- Merges global environment into rendering environment.
- Prints a help message describing command line arguments and options.
- Adds a directory to the search path for require directives.
- Performs successive expansions of
template output, treating the output as a new template, for
a total of
#passes. This allows the use of embedded expressions. By default, only a single pass (
#= 1) is made (i.e., only the original template is evaluated). A value of 0 may be specified to cause as many passes to be performed as necessary so that no embedded expressions remain in the output.
- Specifies the start and end tokens that
demarcate embedded Lua code. The defaults are
- Prints version information.
- Prints the directory name containing the ltp library modules.
- Prints the directory name used as the ltp installation prefix.
This section is incomplete and will contain explanations
and examples for writing template and environment files. For
now, the most important items to understand are that you can
ltp.merge_table functions from within a
template or environment file.
Templates may be compiled for inclusion by other
templates via the
For example, you may have a header template that is imported
by a document template.
This template would be compiled with:
This command compiles the template to a lua function
that accepts a single argument
output. Import the template
output variable is an implicit
global table available inside of templates that stores
rendered content. The use of
page.title is availble
You can also create a library of functions by
compiling with the
-C option and returning a
table of functions from the template library. For example,
instead of a header template, you could write a header
Even though ltp merges multiple
environment files specified on the command line, there are
times when a self-contained template or environment file needs
to import and merge data from another source. You can use the
ltp.mergetable function to do this. For
example, let's say you have an environment file that uses
color data from another file:
Environment files must return a table whose fields are
merged into the global environment when executing a template.
ltp.merge_table merges the second
argument into the first argument and returns the first
argument after merging. Of course, the above example didn't
require the use of
environment file could have returned a single table:
However, when two tables share element names and one
should override the other, you must
- Indicates the program terminated without producing any errors.
- Indicates the program terminated after encountering an error.
Report bugs to software at savarese.com.
Currently, it is not possible to nest
... ?> within Lua code in a template file. A
workaround is to precompile the template, using different tokens
for the template code and the nested data. For example, you can
write the following:
Then you can precompile the template with:
Finally, you can use the compiled template via
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.