Lupa API Documentation

The lupa Module


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

Functions defined by lupa

_G.cycler()

Returns an object that cycles through the given values by calls to its next() function. A current field contains the cycler’s current value and a reset() function resets the cycler to its beginning.

Parameters:

Usage:

_G.range(start, stop, step)

Returns a sequence of integers from start to stop, inclusive, in increments of step. The complete sequence is generated at once – no generator is returned.

Parameters:

lupa.configure(ts, te, vs, ve, cs, ce, options)

Configures the basic delimiters and options for templates. This function then regenerates the grammar for parsing templates. Note: this function cannot be used iteratively to configure Lupa options. Any options not provided are reset to their default values.

Parameters:

lupa.expand(template, env)

Expands the string template template, subject to template environment env, and returns the result.

Parameters:

lupa.expand_file(filename, env)

Expands the template within file filename, subject to template environment env, and returns the result.

Parameters:

filters.batch(t, size, fill)

Returns a generator that produces all of the items in table t in batches of size size, filling any empty spaces with value fill. Combine this with the “list” filter to produce a list.

Parameters:

Usage:

See also:

filters.capitalize(s)

Capitalizes string s. The first character will be uppercased, the others lowercased.

Parameters:

Usage:

filters.center(s, width)

Centers string s within a string of length width.

Parameters:

Usage:

filters.default(value, default, false_defaults)

Returns value value or value default, depending on whether or not value is “true” and whether or not boolean false_defaults is true.

Parameters:

Usage:

filters.dictsort(t, case_sensitive, by, value)

Returns a table constructed from table t such that each element is a list that contains a single key-value pair and all elements are sorted according to string by (which is either “key” or “value”) and boolean case_sensitive.

Parameters:

Usage:

filters.e(s)

Returns an HTML-safe copy of string s.

Parameters:

Usage:

filters.escape(s)

Returns an HTML-safe copy of string s.

Parameters:

Usage:

filters.filesizeformat(bytes, binary)

Returns a human-readable, decimal (or binary, depending on boolean binary) file size for bytes number of bytes.

Parameters:

Usage:

filters.first(t)

Returns the first element in table t.

Parameters:

Usage:

filters.float(value)

Returns value value as a float. This filter only works in Lua 5.3, which has a distinction between floats and integers.

Parameters:

Usage:

filters.forceescape(value)

Returns an HTML-safe copy of value value, even if value was returned by the “safe” filter.

Parameters:

Usage:

filters.format(s, …)

Returns the given arguments formatted according to string s. See Lua’s string.format() for more information.

Parameters:

Usage:

filters.groupby(t, attribute)

Returns a generator that produces lists of items in table t grouped by string attribute attribute.

Parameters:

Usage:

filters.indent(s, width, first_line)

Returns a copy of string s with all lines after the first indented by width number of spaces. If boolean first_line is true, indents the first line as well.

Parameters:

Usage:

filters.int(value)

Returns value value as an integer.

Parameters:

Usage:

filters.join(t, sep, attribute)

Returns a string that contains all the elements in table t (or all the attributes named attribute in t) separated by string sep.

Parameters:

Usage:

filters.last(t)

Returns the last element in table t.

Parameters:

Usage:

filters.length(value)

Returns the length of string or table value.

Parameters:

Usage:

filters.list(generator, s, i)

Returns the list of items produced by generator generator, subject to initial state s and initial iterator variable i. This filter should only be used after a filter that returns a generator.

Parameters:

Usage:

See also:

filters.lower(s)

Returns a copy of string s with all lowercase characters.

Parameters:

Usage:

filters.map(t, filter, …)

Maps each element of table t to a value produced by filter name filter and returns the resultant table.

Parameters:

Usage:

filters.mapattr(t, attribute, filter, …)

Maps the value of each element’s string attribute in table t to the value produced by filter name filter and returns the resultant table.

Parameters:

Usage:

filters.random(t)

Returns a random element from table t.

Parameters:

Usage:

filters.reject(t, test, …)

Returns a list of elements in table t that fail test name test.

Parameters:

Usage:

filters.rejectattr(t, attribute, test, …)

Returns a list of elements in table t whose string attribute attribute fails test name test.

Parameters:

Usage:

filters.replace(s, pattern, repl, n)

Returns a copy of string s with all (or up to n) occurrences of string old replaced by string new. Identical to Lua’s string.gsub() and handles Lua patterns.

Parameters:

Usage:

filters.reverse(value)

Returns a copy of the given string or table value in reverse order.

Parameters:

Usage:

filters.round(value, precision, method)

Returns number value rounded to precision decimal places based on string method (if given).

Parameters:

Usage:

filters.safe(s)

Marks string s as HTML-safe, preventing Lupa from modifying it when configured to autoescape HTML entities. This filter must be used at the end of a filter chain unless it is immediately proceeded by the “forceescape” filter.

Parameters:

Usage:

filters.select(t, test, …)

Returns a list of the elements in table t that pass test name test.

Parameters:

Usage:

filters.selectattr(t, attribute, test, …)

Returns a list of elements in table t whose string attribute attribute passes test name test.

Parameters:

Usage:

filters.slice(t, slices, fill)

Returns a generator that produces all of the items in table t in slices number of iterations, filling any empty spaces with value fill. Combine this with the “list” filter to produce a list.

Parameters:

Usage:

See also:

filters.sort(value, reverse, case_sensitive, attribute)

Returns a copy of table or string value in sorted order by value (or by an attribute named attribute), depending on booleans reverse and case_sensitive.

Parameters:

Usage:

filters.string(value)

Returns the string representation of value value, handling lists properly.

Parameters:

Usage:

filters.striptags(s)

Returns a copy of string s with any HTML tags stripped. Also cleans up whitespace.

Parameters:

Usage:

filters.sum(t, attribute)

Returns the numeric sum of the elements in table t or the sum of all attributes named attribute in t.

Parameters:

Usage:

filters.title(s)

Returns a copy of all words in string s in titlecase.

Parameters:

Usage:

filters.truncate(s, length, partial_words, delimiter)

Returns a copy of string s truncated to length number of characters. Truncated strings end with ‘…’ or string delimiter. If boolean partial_words is false, truncation will only happen at word boundaries.

Parameters:

Usage:

filters.upper(s)

Returns a copy of string s with all uppercase characters.

Parameters:

Usage:

filters.urlencode(value)

Returns a string suitably encoded to be used in a URL from value value. value may be a string, table of key-value query parameters, or table of lists of key-value query parameters (for order).

Parameters:

Usage:

filters.urlize(s, length, nofollow)

Replaces any URLs in string s with HTML links, limiting link text to length characters.

Parameters:

Usage:

filters.wordcount(s)

Returns the number of words in string s. A word is a sequence of non-space characters.

Parameters:

Usage:

filters.xmlattr(t)

Interprets table t as a list of XML attribute-value pairs, returning them as a properly formatted, space-separated string.

Parameters:

Usage:

loaders.filesystem(directory)

Returns a loader for templates that uses the filesystem starting at directory directory. When looking up the template for a given filename, the loader considers the following: if no template is being expanded, the loader assumes the given filename is relative to directory and returns the full path; otherwise the loader assumes the given filename is relative to the current template’s directory and returns the full path. The returned path may be passed to io.open().

Parameters:

See also:

lupa.reset()

Resets Lupa’s default delimiters, options, and environments to their original default values.

tests.is_callable(value)

Returns whether or not value value is a function.

Parameters:

Usage:

tests.is_defined(value)

Returns whether or not value value is non-nil, and thus defined.

Parameters:

Usage:

tests.is_divisibleby(n, num)

Returns whether or not number n is evenly divisible by number num.

Parameters:

Usage:

tests.is_escaped(value)

Returns whether or not value value is HTML-safe.

Parameters:

Usage:

tests.is_even(n)

Returns whether or not number n is even.

Parameters:

Usage:

tests.is_iterable(value)

Returns whether or not value value is a sequence (a table with non-zero length) or a generator. At the moment, all functions are considered generators.

Parameters:

Usage:

tests.is_lower(s)

Returns whether or not string s is in all lower-case characters.

Parameters:

Usage:

tests.is_mapping(value)

Returns whether or not value value is a table.

Parameters:

Usage:

tests.is_nil(value)

Returns whether or not value value is nil.

Parameters:

Usage:

tests.is_none(value)

Returns whether or not value value is nil.

Parameters:

Usage:

tests.is_number(value)

Returns whether or not value value is a number.

Parameters:

Usage:

tests.is_odd(n)

Returns whether or not number n is odd.

Parameters:

Usage:

tests.is_sameas(value, other)

Returns whether or not value value is the same as value other.

Parameters:

Usage:

tests.is_sequence(value)

Returns whether or not value value is a sequence, namely a table with non-zero length.

Parameters:

Usage:

tests.is_string(value)

Returns whether or not value value is a string.

Parameters:

Usage:

tests.is_table(value)

Returns whether or not value value is a table.

Parameters:

Usage:

tests.is_undefined(value)

Returns whether or not value value is nil, and thus effectively undefined.

Parameters:

Usage:

tests.is_upper(s)

Returns whether or not string s is in all upper-case characters.

Parameters:

Usage:

Tables defined by lupa

lupa.env

The default template environment.

lupa.filters

Lupa’s expression filters.

lupa.loaders

Lupa’s template loaders.

lupa.tests

Lupa’s value tests.