|
|
|
@@ -0,0 +1,179 @@ |
|
|
|
# Lupa |
|
|
|
|
|
|
|
## Introduction |
|
|
|
|
|
|
|
Lupa is a [Jinja2][] template engine implementation written in Lua and supports |
|
|
|
Lua syntax within tags and variables. |
|
|
|
|
|
|
|
Lupa was sponsored by the [Library of the University of Antwerp][]. |
|
|
|
|
|
|
|
[Jinja2]: http://jinja.pocoo.org |
|
|
|
[Library of the University of Antwerp]: http://www.uantwerpen.be/ |
|
|
|
|
|
|
|
## Requirements |
|
|
|
|
|
|
|
Lupa has the following requirements: |
|
|
|
|
|
|
|
* [Lua][] 5.1, 5.2, or 5.3. |
|
|
|
* The [LPeg][] library. |
|
|
|
|
|
|
|
[Lua]: http://www.lua.org |
|
|
|
[LPeg]: http://www.inf.puc-rio.br/~roberto/lpeg/ |
|
|
|
|
|
|
|
## Download |
|
|
|
|
|
|
|
Download Lupa from the project’s [download page][]. |
|
|
|
|
|
|
|
[download page]: download |
|
|
|
|
|
|
|
## Installation |
|
|
|
|
|
|
|
Unzip Lupa and place the "lupa.lua" file in your Lua installation's |
|
|
|
`package.path`. This location depends on your version of Lua. Typical locations |
|
|
|
are listed below. |
|
|
|
|
|
|
|
* Lua 5.1: */usr/local/share/lua/5.1/* or */usr/local/share/lua/5.1/* |
|
|
|
* Lua 5.2: */usr/local/share/lua/5.2/* or */usr/local/share/lua/5.2/* |
|
|
|
* Lua 5.3: */usr/local/share/lua/5.3/* or */usr/local/share/lua/5.3/* |
|
|
|
|
|
|
|
You can also place the "lupa.lua" file wherever you'd like and add it to Lua's |
|
|
|
`package.path` manually in your program. For example, if Lupa was placed in a |
|
|
|
*/home/user/lua/* directory, it can be used as follows: |
|
|
|
|
|
|
|
package.path = package.path..';/home/user/lua/?.lua' |
|
|
|
|
|
|
|
## Usage |
|
|
|
|
|
|
|
Lupa is simply a Lua library. Its `lupa.expand()` and `lupa.expand_file()` |
|
|
|
functions may called to process templates. For example: |
|
|
|
|
|
|
|
lupa = require('lupa') |
|
|
|
lupa.expand("hello {{ s }}!", {s = "world"}) --> "hello world!" |
|
|
|
lupa.expand("{% for i in {1, 2, 3} %}{{ i }}{% endfor %}") --> 123 |
|
|
|
|
|
|
|
By default, Lupa loads templates relative to the current working directory. This |
|
|
|
can be changed by reconfiguring Lupa: |
|
|
|
|
|
|
|
lupa.expand_file('name') --> expands template "./name" |
|
|
|
lupa.configure{loader = lupa.loaders.filesystem('path/to/templates')} |
|
|
|
lupa.expand_file('name') --> expands template "path/to/templates/name" |
|
|
|
|
|
|
|
See Lupa's [API documentation][] for more information. |
|
|
|
|
|
|
|
[API documentation]: api.html |
|
|
|
|
|
|
|
## Syntax |
|
|
|
|
|
|
|
Please refer to Jinja2's extensive [template documentation][]. Any |
|
|
|
incompatibilities are listed in the sections below. |
|
|
|
|
|
|
|
[template documentation]: http://jinja.pocoo.org/docs/dev/templates/ |
|
|
|
|
|
|
|
## Comparison with Jinja2 |
|
|
|
|
|
|
|
While Lua and Python (Jinja2's implementation language) share some similarities, |
|
|
|
the languages themselves are fundamentally different. Nevertheless, a |
|
|
|
significant effort was made to support a vast majority of Jinja2's Python-style |
|
|
|
syntax. As a result, Lupa passes Jinja2's test suite with only a handful of |
|
|
|
modifications. The comprehensive list of differences between Lupa and Jinja2 is |
|
|
|
described in the following sections. |
|
|
|
|
|
|
|
### Fundamental Differences |
|
|
|
|
|
|
|
* Expressions use Lua's syntax instead of Python's, so many of Python's |
|
|
|
syntactic constructs are not valid. However, the following constructs |
|
|
|
*are valid*, despite being invalid in pure Lua: |
|
|
|
|
|
|
|
+ Iterating over table literals or table variables directly in a "for" loop: |
|
|
|
|
|
|
|
{% for i in {1, 2, 3} %}...{% endfor %} |
|
|
|
|
|
|
|
+ Conditional loops via an "if" expression suffix: |
|
|
|
|
|
|
|
{% for x in range(10) if is_odd(x) %}...{% endfor %} |
|
|
|
|
|
|
|
+ Table unpacking for list elements when iterating through a list of lists: |
|
|
|
|
|
|
|
{% for a, b, c in {{1, 2, 3}, {4, 5, 6}} %}...{% endfor %} |
|
|
|
|
|
|
|
+ Default values for macro arguments: |
|
|
|
|
|
|
|
{% macro m(a, b, c='c', d='d') %}...{% endmacro %} |
|
|
|
|
|
|
|
* Strings do not have unicode escapes nor is unicode interpreted in any way. |
|
|
|
|
|
|
|
### Syntactic Differences |
|
|
|
|
|
|
|
* Line statements are not supported due to parsing complexity. |
|
|
|
* In `{% for ... %}` loops, the `loop.length`, `loop.revindex`, |
|
|
|
`loop.revindex0`, and `loop.last` variables only apply to sequences, where |
|
|
|
Lua's `'#'` operator applies. |
|
|
|
* The `{% continue %}` and `{% break %}` loop controls are not supported due to |
|
|
|
complexity. |
|
|
|
* Loops may be used recursively by default, so the `recursive` loop modifier is |
|
|
|
not supported. |
|
|
|
* The `is` operator is not supported by Lua, so tests of the form `{{ x is y }}` |
|
|
|
should be written `{{ is_y(x) }}` (e.g. `{{ is_number(42) }}`). |
|
|
|
* Filters cannot occur after tokens within an expression (e.g. |
|
|
|
`{{ "foo"|upper .. "bar"|upper }}`), but can only occur at the end of an |
|
|
|
expression (e.g. `{{ "foo".."bar"|upper }}`). |
|
|
|
* Blocks always have access to scoped variables, so the `scoped` block modifier |
|
|
|
is not supported. |
|
|
|
* Named block end tags are not supported since the parser cannot easily keep |
|
|
|
track of that state information. |
|
|
|
* Any `{% block ... %}` tags within a "false" block (e.g. `{% if a %}` where `a` |
|
|
|
evaluates to `false`) are never read and stored due to the parser |
|
|
|
implementation. |
|
|
|
* Inline "if" expressions (e.g. `{% extends b if a else c %}`) are not |
|
|
|
supported. Instead, use a Lua conditional expression |
|
|
|
(e.g. `{% extends a and b or c %}`). |
|
|
|
* Any `{% extends ... %}` tags within a sub-scope are not effective outside that |
|
|
|
scope (e.g. `{% if a %}{% extends a %}{% else %}{% extends b %}{% endif %}`). |
|
|
|
Instead, use a Lua conditional expression (e.g. `{% extends a or b %}`). |
|
|
|
* Macros are simply Lua functions and have no metadata attributes. |
|
|
|
* Macros do not have access to a `kwargs` variable since Lua does not support |
|
|
|
keyword arguments. |
|
|
|
* `{% from x import y %}` tags are not supported. Instead, you must use either |
|
|
|
`{% import x %}`, which imports all globals in `x` into the current |
|
|
|
environment, or use `{% import x as z %}`, which imports all globals in `x` |
|
|
|
into the variable `z`. |
|
|
|
* `{% set ... %}` does not support multiple assignment. Use `{% do ...%}` |
|
|
|
instead. The catch is that `{% do ... %}` does not support filters. |
|
|
|
* The `{% trans %}` and `{% endtrans %}` tags, `{% with %}` and `{% endwith %}` |
|
|
|
tags, and `{% autoescape %}` and `{% endautoescape %}` tags are not supported |
|
|
|
since they are outside the scope of this implementation. |
|
|
|
|
|
|
|
### Filter Differences |
|
|
|
|
|
|
|
* Only the `batch`, `groupby`, and `slice` filters return generators which |
|
|
|
produce one item at a time when looping. All other filters that produce |
|
|
|
iterable results generate all items at once. |
|
|
|
* The `float` filter only works in Lua 5.3 since that version of Lua has a |
|
|
|
distinction between floats and integers. |
|
|
|
* The `safe` filter must appear at the end of a filter chain since its output |
|
|
|
cannot be passed to any other filter. |
|
|
|
|
|
|
|
### Function Differences |
|
|
|
|
|
|
|
* The global `range(n)` function returns a sequence from 1 to `n`, inclusive, |
|
|
|
since lists start at 1 in Lua. |
|
|
|
* No `lipsum()`, `dict()`, or `joiner()` functions for the sake of simplicity. |
|
|
|
|
|
|
|
### API Differences |
|
|
|
|
|
|
|
* Lupa has a much simpler API consisting of just four functions and three |
|
|
|
fields: |
|
|
|
|
|
|
|
+ `lupa.expand()`: Expands a string template subject to an environment. |
|
|
|
+ `lupa.expand_file()`: Expands a file template subject to an environment. |
|
|
|
+ `lupa.configure()` Configures delimiters and template options. |
|
|
|
+ `lupa.reset()`: Resets delimiters and options to their defaults. |
|
|
|
+ `lupa.env`: The default environment for templates. |
|
|
|
+ `lupa.filters`: The set of available filters (`escape`, `join`, etc.). |
|
|
|
+ `lupa.tests`: The set of available tests (`is_odd`, `is_defined`, etc.). |
|
|
|
|
|
|
|
* There is no bytecode caching. |
|
|
|
* Lupa has no extension mechanism. Instead, modify `lupa.env`, `lupa.filters`, |
|
|
|
and `lupa.tests` directly. However, the parser cannot be extended. |
|
|
|
* Sandboxing is not supported, although `lupa.env` is safe by default (`io`, |
|
|
|
`os.execute`, `os.remove`, etc. are not available). |
Vsevolod Stakhov
5 years ago