Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/orbitalquark/lupa

Lupa is a Jinja2 template engine implementation written in Lua and supports Lua syntax within tags and variables.
https://github.com/orbitalquark/lupa

jinja2 lpeg lua template-engine

Last synced: 2 months ago
JSON representation

Lupa is a Jinja2 template engine implementation written in Lua and supports Lua syntax within tags and variables.

Awesome Lists containing this project

README 

        
# Lupa



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]: https://www.lua.org

[LPeg]: http://www.inf.puc-rio.br/~roberto/lpeg/



## Download



Lupa releases can be found [here][].



[here]: https://github.com/orbitalquark/lupa/releases



## 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]: https://orbitalquark.github.io/lupa/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).