jinja¶
Types
- jinja.Call :: struct¶
-
Call is what a native procedure receives: the positional and keyword arguments (for a filter or test, args[0] is the value being filtered or tested), the user pointer given at registration, and the receiver of a bound method.
- user: rawptr¶
- name: string¶
- jinja.Callable :: struct¶
-
Callable is a function value: a native procedure (optionally bound to self) or a macro.
- name: string¶
- user: rawptr¶
- macro: ^Macro¶
- jinja.Dict :: struct¶
-
Dict is an insertion-ordered dictionary. String keys are indexed; other keys are compared with Python equality (1 == 1.0 == True). allocator owns the dict as it owns a List.
- index: map[string]int¶
- name: string¶
-
the template name of a module
- allocator: mem.Allocator¶
- jinja.Dict_Kind :: enum u8¶
-
- Dict¶
-
a plain dict
- Namespace¶
-
namespace(): the only object whose attributes templates may assign
- Module¶
-
the result of {% import %}: exported macros and variables
- jinja.Environment :: struct¶
-
Environment holds options, filters, tests, globals and the template cache. Its own memory (parsed templates, tables) comes from an arena freed by destroy_environment.
- filters: map[string]Registered¶
- tests: map[string]Registered¶
- cache: map[string]^Compiled¶
- arena: ^Arena¶
- allocator: mem.Allocator¶
- backing: mem.Allocator¶
- stack: Stack_Guard¶
-
started by the outermost call on the environment
- out_of_memory: bool¶
-
Set when the environment’s memory could not hold its tables: every template it parses then fails with a Memory error.
- jinja.Error :: struct¶
-
Error describes a failure. kind == .None means success. excerpt is the template line the error points at; hint, when set, suggests a fix.
- kind: Error_Kind¶
- template: string¶
- line: int¶
- message: string¶
- excerpt: string¶
- hint: string¶
- jinja.Error_Kind :: enum u8¶
-
- None¶
- Syntax¶
-
the template does not parse (TemplateSyntaxError)
- Undefined¶
-
an undefined value was used (UndefinedError)
- Type¶
-
an operation got the wrong kind of value (TypeError)
- Not_Found¶
-
a template could not be loaded (TemplateNotFound)
- Limit¶
-
a recursion, iteration or output limit was reached
- Memory¶
-
the memory the parse or render may use could not hold it (MemoryError)
- Runtime¶
-
any other failure while rendering
- jinja.List :: struct¶
-
List is a list, or a tuple when tuple is set. fields names the items of a named tuple (the groups made by groupby), which can then also be read as attributes. allocator owns the list: its items grow there, and what a template stores in the list is copied there when the render ends (see Memory in the README).
- tuple: bool¶
- fields: []string¶
- allocator: mem.Allocator¶
- jinja.Loader :: struct¶
-
Loader is a procedure plus its data. destroy, when set, is called by destroy_environment.
- procedure: Loader_Proc¶
- user: rawptr¶
- destroy: proc(user: rawptr)¶
- jinja.Loader_Proc :: #type proc(user: rawptr, name: string, allocator: mem.Allocator) -> (source: string, found: bool)¶
-
Loader_Proc returns the source of a template, allocated with allocator.
- jinja.Loop :: struct¶
-
Loop is the special
loopvariable of a for loop.- index0: int¶
- depth0: int¶
- changed: bool¶
-
whether changed() was called before
- recurse: ^Recursion¶
-
set in a recursive loop
- jinja.Markup :: distinct string¶
-
Markup is a string that is already safe HTML: autoescaping leaves it alone.
- jinja.Native :: #type proc(call: ^Call) -> Value¶
-
Native is the one signature of every filter, test, global function and method written in Odin. Report errors with fail(call, …) and return anything.
- jinja.None :: struct¶
-
None is Jinja’s none / None.
- jinja.Options :: struct¶
-
- autoescape: bool¶
- autoescape_extensions: []string¶
-
When set, templates whose names end with one of these (「.html」) autoescape and others do not, like select_autoescape();
autoescapeis then ignored.
- trim_blocks: bool¶
- lstrip_blocks: bool¶
- keep_trailing_newline: bool¶
- undefined: Undefined_Mode¶
- max_recursion: int¶
-
nested macros, includes and recursive loops; 0 means 200
- max_iterations: int¶
-
loop iterations per render; 0 means 10,000,000
- max_output: int¶
-
Bytes per render, and per value a render builds (a repetition, padding, a join), checked before the value is allocated; 0 means unlimited.
- max_nesting: int¶
-
how deep template syntax nests; 0 means 100
- stack_bytes: int¶
-
machine stack parsing and rendering may use; 0 means 512 KiB
- random_seed: u64¶
-
seeds |random and lipsum(); renders are deterministic
- jinja.State :: struct¶
-
State is one render in progress. Natives reach it through Call.state.
- env: ^Environment¶
- out: ^strings.Builder¶
- failed: bool¶
- autoescape: bool¶
- depth: int¶
- iterations: int¶
- ctx: ^Context¶
- current: ^Compiled¶
- line: int¶
- rng: u64¶
- guard: ^Guard¶
-
the render’s allocator; see memory.odin.
- scratch: ^Arena¶
-
the render’s own memory, or nil; see ownership.odin.
- caller: mem.Allocator¶
-
context.allocator of the call that renders.
- jinja.Template :: struct¶
-
Template is a handle to a parsed template.
- env: ^Environment¶
- compiled: ^Compiled¶
- name: string¶
- jinja.Undefined :: struct¶
-
Undefined is what a missing variable, attribute or item evaluates to. The fields only feed the error message produced when the value is used in a way Jinja forbids.
- name: string¶
-
the missing variable or attribute
- owner: string¶
-
「dict object」 when an attribute or item was missing
- hint: string¶
-
a complete message that replaces the generated one
- jinja.Undefined_Mode :: enum u8¶
-
- Default¶
-
renders as 「」, fails on attribute access, calls and arithmetic
- Strict¶
-
fails on every use except
is definedand |default
- Chainable¶
-
like Default, but attributes of undefined are undefined too
- Debug¶
-
like Default, but renders as {{ name }}
- jinja.Value :: union #no_nil {Undefined, None, bool, i64, f64, string, Markup, ^List, ^Dict, ^Callable, ^Loop, ^Cycler}¶
-
Value is every value a template can see. The zero value is Undefined.
Procedures
- jinja.add_filter :: proc(env: ^Environment, name: string, procedure: Native, user: rawptr = nil)¶
-
add_filter registers a filter: call.args[0] is the filtered value. The environment copies name into its arena; user is borrowed until destroy_environment.
- jinja.add_function :: proc(env: ^Environment, name: string, procedure: Native, user: rawptr = nil)¶
-
add_function registers a native procedure as a global function, allocated in the environment’s arena; user is borrowed until destroy_environment.
- jinja.add_global :: proc(env: ^Environment, name: string, value: Value)¶
-
add_global makes a value visible to every template. The environment copies name into its arena; the value is borrowed and must outlive renders.
- jinja.add_template :: proc(env: ^Environment, name, source: string) -> Error¶
-
add_template parses source and caches it under name, so that extends, include and import find it without a loader. An error is allocated with context.allocator (destroy_error).
- jinja.add_test :: proc(env: ^Environment, name: string, procedure: Native, user: rawptr = nil)¶
-
add_test registers a test: call.args[0] is the tested value; return a bool. The environment copies name into its arena; user is borrowed until destroy_environment.
- jinja.append_value :: proc(l: Value, items: ..Value)¶
-
append_value adds values to the end of a list value, growing it with the list’s own allocator; nothing happens when l is not a list or that allocator refuses.
- jinja.arg :: proc(c: ^Call, index: int, name: string, default: Value = Undefined{}) -> Value¶
-
arg returns positional argument index, else the keyword argument name, else default.
- jinja.arg_int :: proc(c: ^Call, index: int, name: string, default: i64) -> (i64, bool)¶
-
arg_int reads an integer argument (bools and integral floats accepted).
- jinja.autoescaping :: proc(c: ^Call) -> bool¶
-
autoescaping reports whether the call happens while autoescape is on.
- jinja.call_filter :: proc(s: ^State, name: string, args: []Value, kwargs: []Keyword) -> Value¶
-
call_filter runs a registered filter by name (used by map, and by hosts).
- jinja.call_test :: proc(s: ^State, name: string, args: []Value, kwargs: []Keyword) -> bool¶
-
call_test runs a registered test by name (used by select and reject).
- jinja.check_args :: proc(c: ^Call, who: string, names: []string, required := 0) -> bool¶
-
check_args enforces a Python signature: at most len(names) positional arguments and only the named keywords, each at most once. who names the callable in errors.
- jinja.clear_cache :: proc(env: ^Environment)¶
-
clear_cache forgets parsed templates so the next load reads them again.
- jinja.create_environment :: proc(options: Options = {}) -> Environment¶
-
create_environment makes an environment with options, zero fields taking their defaults. It keeps its own arena, backed by context.allocator, for parsed templates and registrations; destroy_environment frees it. When that memory cannot hold the environment’s tables, out_of_memory is set and every parse fails with a Memory error.
- jinja.destroy_environment :: proc(env: ^Environment)¶
-
destroy_environment frees the environment’s arena, with every template parsed in it, and its loader’s state (Loader.destroy).
- jinja.destroy_error :: proc(err: Error, allocator := context.allocator)¶
-
destroy_error frees an error returned by this package.
- jinja.dict :: proc() -> Value¶
-
dict makes an empty dict, allocated with context.allocator (Undefined when it refuses the memory); fill it with set().
- jinja.escape :: proc(v: Value, allocator := context.allocator) -> Markup¶
-
escape converts a value to Markup: Markup stays as it is, everything else is converted to a string and escaped (MarkupSafe’s escape()), allocating with allocator when it must; the result may borrow v, so it belongs in an arena, as values do.
- jinja.escape_string :: proc(s: string, allocator := context.allocator) -> string¶
-
escape_string replaces the five HTML special characters as MarkupSafe does. When s has none it is returned as it is, borrowed; otherwise the result is allocated with allocator, which the caller owns (or, as usual, an arena holds).
- jinja.evaluate :: proc(env: ^Environment, expression: string, ctx: Value = {}) -> (Value, Error)¶
-
evaluate evaluates one expression against ctx (Jinja’s compile_expression). The value and an error’s message are allocated with context.allocator, the caller’s; the lists and dicts of the value grow through a small allocator record kept there too. When that allocator refuses memory the error is a Memory error.
- jinja.fail :: proc(c: ^Call, format: string, args: ..any) -> Value¶
-
fail records a runtime error from a native procedure; return its result. The message is formatted with context.allocator, the render’s arena.
- jinja.filesystem_loader :: proc(directories: []string) -> Loader¶
-
filesystem_loader serves templates from directories, searched in order; the first match wins. Names use 「/」 and may not climb out of a directory with 「..」. The loader copies directories with context.allocator and frees them when its environment is destroyed (Loader.destroy). When that allocator refuses the copy, the loader finds nothing.
- jinja.format_error :: proc(err: Error, allocator := context.allocator) -> string¶
-
format_error renders an error as a friendly report in the style of Elm’s compiler, in a string allocated with allocator that the caller owns (「」 for no error):
-- UNDEFINED VALUE ------------------------------------------ page.html:3 'user' is undefined 3| <h1>{{ user.name }}</h1> Hint: Pass it in the render context, or test it with `is defined`.
- jinja.function :: proc(name: string, procedure: Native, user: rawptr = nil) -> Value¶
-
function wraps a native procedure as a callable value for globals or context data, allocated with context.allocator (Undefined when it refuses the memory); name and user are borrowed.
- jinja.get :: proc(d: Value, key: string) -> Value¶
-
get reads a string key from a dict value; missing keys give Undefined.
- jinja.has_arg :: proc(c: ^Call, index: int, name: string) -> bool¶
-
has_arg reports whether the argument was passed at all.
- jinja.integer :: proc(i: i64) -> Value¶
-
integer makes an integer value (int would shadow Odin’s type).
- jinja.keys :: proc(d: Value, allocator := context.allocator) -> []string¶
-
keys returns the string keys of a dict value, in insertion order, in a slice allocated with allocator that the caller owns; the keys borrow the dict.
- jinja.length :: proc(v: Value) -> int¶
-
length is the number of items of a list or dict, or of runes of a string.
- jinja.list :: proc(items: ..Value) -> Value¶
-
list makes a list holding the given values, allocated with context.allocator; when it refuses the memory, the result is Undefined.
- jinja.load_template :: proc(env: ^Environment, name: string) -> (Template, Error)¶
-
load_template loads a template through the environment’s loader, cached in the environment’s arena until destroy_environment (or clear_cache). An error is allocated with context.allocator; the caller frees it with destroy_error.
- jinja.markup :: proc(s: string) -> Value¶
-
markup makes a string value that is safe HTML, which autoescaping leaves alone; the value borrows s.
- jinja.memory_loader :: proc(sources: ^map[string]string) -> Loader¶
-
memory_loader serves templates from a map the host owns (name -> source).
- jinja.parse_template :: proc(env: ^Environment, name, source: string) -> (Template, Error)¶
-
parse_template parses source directly (not cached; not visible to includes). The template lives in the environment’s arena, which copies source; an error is allocated with context.allocator (destroy_error).
- jinja.render :: proc(t: ^Template, ctx: Value = {}) -> (string, Error)¶
-
render renders a template with ctx (a dict value, or Undefined for none). The result and any error message are allocated with context.allocator; everything else lives in a scratch arena freed before returning. When that allocator refuses memory the render stops with a Memory error at the line it was rendering.
- jinja.render_position :: proc() -> (template: string, line: int, excerpt: string, ok: bool)¶
-
render_position is where the render running on this thread is: its template’s name, the line being rendered, and that line’s text; false when none runs. A host asked about a render while it runs, as when the render’s allocator asks what to do about memory, names the place with it. The strings borrow the template.
- jinja.render_source :: proc(env: ^Environment, source: string, ctx: Value = {}, name := "<template>") -> (string, Error)¶
-
render_source parses and renders source in one call (nothing is cached), in a scratch arena it frees before returning. The output, and an error, are allocated with context.allocator; the caller owns them.
- jinja.repr :: proc(v: Value, allocator := context.allocator) -> string¶
-
repr converts a value as Python’s repr() does, in a string allocated with allocator, which the caller owns.
- jinja.set :: proc(d: Value, key: string, value: Value)¶
-
set stores value under the string key in a dict value, growing it with the dict’s own allocator; nothing happens when d is not a dict or that allocator refuses.
- jinja.set_key :: proc(d: Value, key: Value, value: Value)¶
-
set_key stores value under any key in a dict value.
- jinja.to_string :: proc(v: Value, allocator := context.allocator) -> string¶
-
to_string converts a value as Python’s str() does (Undefined gives 「」). A string or Markup value is returned as it is, borrowed; anything else is written into a string allocated with allocator, so the result belongs in an arena, as values do.
- jinja.tuple :: proc(items: ..Value) -> Value¶
-
tuple makes a tuple holding the given values, allocated as list allocates.
- jinja.type_name :: proc(v: Value) -> string¶
-
type_name is the Python type name used in Jinja’s error messages.