API

struct Env

Where templates come from and what they all see: the settings, the filters, tests and global values, the loader and the seams for translation and caching. Compiled templates are kept per environment.

pub struct Env {
  // private fields
}

pub fn Env::add_filter(Self, String, (@spec.Call, @spec.Value, Array[@spec.Value], Map[String, @spec.Value]) -> @spec.Value raise @spec.Refused) -> Unit

pub fn Env::add_global(Self, String, @spec.Value) -> Unit

pub fn Env::add_host(Self, host? : @spec.Host) -> Unit

pub fn Env::add_lang(Self, @syntax.Lang) -> Unit

pub fn Env::add_test(Self, String, (@spec.Call, @spec.Value, Array[@spec.Value]) -> Bool raise @spec.Refused) -> Unit

pub fn Env::compile(Self, StringView, name? : String, format? : Format) -> Template raise @spec.Refused

pub fn Env::new(settings? : Settings, load? : (String) -> String?, translate? : (String, String?, Int32?) -> String?, cache? : (String, () -> String raise @spec.Refused) -> String raise @spec.Refused) -> Self

pub fn Env::template(Self, String) -> Template raise @spec.Refused

struct Format

What a template writes, and so how it reads: the name of its language, whether output is escaped, whether HTML the author wrote is written as it stands, and how whitespace around tags is handled.

pub(all) struct Format {
  lang : String
  autoescape : Bool
  safe : Bool
  trim_blocks : Bool
  lstrip_blocks : Bool
  keep_trailing_newline : Bool
}

safe

Whether HTML the template's author wrote reaches the page as it stands. Off, a converter escapes it, the way a Markdown page leaves html: false; {% block lang=md safe=false %} turns it off for one stretch.

struct Limits

Bounds on what one render may do.

pub(all) struct Limits {
  depth : Int32
  range : Int32
  write : Int32
}

depth

Nested macro calls, includes, extends and recursive loops.

range

The longest sequence range builds.

write

Characters one buffer may take: the page being written, or a block captured for a macro, a filter or set. Each buffer counts on its own and the text carried between them is counted where it lands, so the number is the length of the longest stretch written at once.

struct Settings

Everything an environment is configured with.

pub(all) struct Settings {
  format : Format
  formats : (String) -> Format
  force : Bool
  undefined : @spec.Undefined
  line_statement : String?
  line_comment : String?
  delimiters : @syntax.Delimiters
  shortcuts : Map[String, String]
  limits : Limits
}

format

The format of a source compiled without a name.

formats

The format of a template from its name.

force

Whether a template reads only its own language, leaving blocks in another as text.

undefined

What using an undefined name does.

line_statement

A prefix that makes a whole line a statement, as # for x in y.

line_comment

A prefix that makes the rest of a line a comment.

delimiters

The strings that open and close a tag.

shortcuts

The indentation syntax's shorthand prefixes and the attribute each one names: . writes a class, # an id, and a prefix of your own writes whatever attribute you give it.

struct Template

A compiled template, ready to render any number of times.

pub struct Template {
  // private fields
}

pub fn Template::name(Self) -> String

pub fn[C : @json.ToJson] Template::render(Self, C) -> String raise @spec.Refused

pub fn Template::render_values(Self, Map[String, @spec.Value]) -> String raise @spec.Refused

type Filter

pub type Filter = (@spec.Call, @spec.Value, Array[@spec.Value], Map[String, @spec.Value]) -> @spec.Value raise @spec.Refused

type Func

pub type Func = (@spec.Call, Array[@spec.Value], Map[String, @spec.Value]) -> @spec.Value raise @spec.Refused

type Test

pub type Test = (@spec.Call, @spec.Value, Array[@spec.Value]) -> Bool raise @spec.Refused

suberror Refused

Why a template could not be read or rendered. Every variant names the template and the one-based line it stopped at; a fault raised by an extension carries an empty name and line 0 until the engine fills in where it was called from.

pub(all) suberror Refused {
  Syntax(template~ : String, line~ : Int32, column~ : Int32, reason~ : String)
  Unknown(template~ : String, line~ : Int32, kind~ : String, name~ : String)
  Invalid(template~ : String, line~ : Int32, reason~ : String)
  Exceeded(template~ : String, line~ : Int32, limit~ : Int32, got~ : Int32)
}

Syntax

The source is not well formed.

Unknown

A name that resolves to nothing: a variable under the strict policy, a filter, a test, a template, an attribute. kind says which.

Invalid

The source is well formed and the values do not fit: wrong arguments, a type an operation does not take.

Exceeded

A bound in Limits was crossed.

pub fn Refused::at(Self, String, Int32) -> Self

pub fn Refused::place(Self) -> (String, Int32)

struct Call

What an extension can reach of the render in flight: whether output is being escaped, the undefined policy, the other filters and tests, the translation seam, and the bound on range.

pub struct Call {
  autoescape : Bool
  undefined : Undefined
  range : Int32
  // private fields
}

autoescape

Whether {{ }} escapes here; a filter that builds markup reads it.

undefined

How an undefined value behaves when used.

range

The largest sequence range may build.

pub fn Call::check(Self, String, Value, Array[Value]) -> Bool raise Refused

pub fn Call::draw(Self) -> Int32

pub fn Call::escaping(Self, Bool) -> Self

pub fn Call::filter(Self, String, Value, Array[Value], Map[String, Value]) -> Value raise Refused

pub fn Call::has_filter(Self, String) -> Bool

pub fn Call::has_test(Self, String) -> Bool

pub fn Call::items(Self, Value) -> Array[Value] raise Refused

pub fn Call::new(autoescape? : Bool, undefined? : Undefined, range? : Int32, filters? : Map[String, (Self, Value, Array[Value], Map[String, Value]) -> Value raise Refused], tests? : Map[String, (Self, Value, Array[Value]) -> Bool raise Refused], translate? : (String, String?, Int32?) -> String?) -> Self

pub fn Call::refuses(Self, String) -> Bool

pub fn Call::text(Self, Value) -> String raise Refused

pub fn Call::translate(Self, String, context? : String, count? : Int32) -> String?

pub fn Call::truthy(Self, Value) -> Bool raise Refused

struct Host

What a template asks of the program around it: an address by name, the prefix its static and media files sit under, a token to sign a form with, and the clock. Each is a global function a template calls, and each is optional: what is not given is not defined in templates.

pub(all) struct Host {
  url : ((String, Array[Value], Map[String, Value]) -> String raise Refused)?
  asset : ((String) -> String)?
  asset_prefix : (() -> String)?
  media_prefix : (() -> String)?
  csrf_token : (() -> String)?
  now : (() -> String)?
}

url

url(name, …): the address the program gives a route, the rest of the arguments filling it.

asset

static(path): where a static file is served from.

asset_prefix

static_prefix(): the prefix on its own.

media_prefix

media_prefix(): the prefix uploaded files sit under.

csrf_token

csrf_token(): the token a form carries, as markup.

now

now(): the moment to render, as ISO 8601 text. The format letters are applied to it here, so the program only says what time it is.

enum Undefined

What happens when an undefined value is used, Jinja's three answers: Lenient prints nothing and iterates as empty but refuses attribute access; Chainable also lets attributes of it be undefined in turn; Strict refuses every use except asking whether it is defined.

pub(all) enum Undefined {
  Lenient
  Chainable
  Strict
}

enum Value

A value in a template. The context arrives as data; functions and host objects enter as Object. Markup is text already safe to write as it stands. Undefined is a name that resolved to nothing, carrying the name for the message a later use may need.

pub(all) enum Value {
  Null
  Bool(Bool)
  Int(Int64)
  Double(Double)
  Text(String)
  Markup(String)
  Seq(Array[Value])
  Tuple(Array[Value])
  Dict(Map[String, Value])
  Undefined(String)
  Object(&Object)
}

pub fn Value::contains(Self, Self) -> Bool raise Refused

pub fn Value::field(Self, String) -> Self?

pub fn Value::func(String, (Call, Array[Self], Map[String, Self]) -> Self raise Refused) -> Self

pub fn Value::index(Self) -> Int32?

pub fn Value::item(Self, Self) -> Self?

pub fn Value::iter(Self) -> Array[Self] raise Refused

pub fn Value::kind(Self) -> String

pub fn Value::markup(Self) -> String

pub fn Value::number(Self) -> Double?

pub fn Value::of_json(@json.Json) -> Self

pub fn Value::path(Self, String) -> Self?

pub fn Value::repr(Self) -> String

pub fn Value::to_json(Self) -> @json.Json

pub fn Value::truthy(Self) -> Bool

type Filter

A filter: the value left of |, the arguments in parentheses.

pub type Filter = (Call, Value, Array[Value], Map[String, Value]) -> Value raise Refused

type Func

What a function receives: what the engine knows about the render in flight, positional arguments, named arguments.

pub type Func = (Call, Array[Value], Map[String, Value]) -> Value raise Refused

type Test

A test: the value left of is, the arguments after the name.

pub type Test = (Call, Value, Array[Value]) -> Bool raise Refused

trait Object

A host value a template can use. Each method is optional: an object that only has attributes implements attr, a function only call. Cyclers, macros, namespaces and the loop variable are objects too.

pub(open) trait Object {
  fn kind(Self) -> String
  fn attr(Self, String) -> Value? = _
  fn call(Self, Call, Array[Value], Map[String, Value]) -> Value raise Refused = _
  fn callable(Self) -> Bool = _
  fn assign(Self, String, Value) -> Unit raise Refused = _
  fn show(Self) -> String = _
  fn items(Self) -> Array[Value]? = _
}

kind

What messages call it: "a cycler", "the macro row".

attr

obj.name; None when there is no such attribute.

call

obj(args).

callable

Whether call does anything; the callable test asks this.

assign

{% set obj.name = value %}.

show

What {{ obj }} prints.

items

What a loop over it walks; None when it cannot be iterated.

enum Arg

An argument: positional, named, or spread with * and **.

pub(all) enum Arg {
  Pos(Expr)
  Named(String, Expr)
  Spread(Expr)
  SpreadNamed(Expr)
}

struct Attr

An attribute of an element in the indentation syntax. None is a bare attribute such as checked.

pub(all) struct Attr {
  name : String
  value : Expr?
  escape : Bool
}

struct Block

pub(all) struct Block {
  name : String
  body : Array[Node]
  scoped : Bool
  required : Bool
  placement : Placement
}

struct Delimiters

The strings that open and close a tag of the brace syntax: an output, a statement and a comment each have their own pair.

pub(all) struct Delimiters {
  variable_start : String
  variable_end : String
  block_start : String
  block_end : String
  comment_start : String
  comment_end : String
}

struct Element

pub(all) struct Element {
  tag : Expr
  attrs : Array[Attr]
  splats : Array[Expr]
  self_close : Bool
  body : Array[Node]
}

enum Expr

The tree both syntaxes read into. Nothing after reading knows which syntax a template was written in.

pub(all) enum Expr {
  Lit(@spec.Value)
  Name(String)
  List(Array[Expr])
  Tuple(Array[Expr])
  Dict(Array[(Expr, Expr)])
  Attr(Expr, String)
  Item(Expr, Expr)
  Slice(Expr?, Expr?, Expr?)
  Call(Expr, Array[Arg])
  Not(Expr)
  Neg(Expr)
  Pos(Expr)
  Binary(Op, Expr, Expr)
  Compare(Expr, Array[(Op, Expr)])
  Concat(Array[Expr])
  Cond(Expr, Expr, Expr?)
  Filter(Expr?, String, Array[Arg])
  Test(Expr, String, Array[Arg])
  Attributes(Array[Attr], Array[Expr])
}

Slice

A slice as a subscript: a[1:2] is Item(a, Slice(1, 2, None)).

Attributes

The attributes of a mixin call, merged the way an element merges its own: classes gather, &attributes splats override.

struct Lang

A language a template or a {% block lang=… %} is read in: its name, the other names it answers to, how its brace tags treat whitespace, the reader that turns its source into the tree, and the conversion its output goes through. The three built in are registered the same way a user's own is.

pub(all) struct Lang {
  name : String
  aliases : Array[String]
  options : Options
  read : (String, Reading) -> Array[Node] raise @spec.Refused
  finish : ((String, Reading) -> String raise @spec.Refused)?
}

finish

What the text a stretch in this language rendered becomes. None writes it as it stands; Markdown gives the converter that turns the Markdown into HTML.

struct Lexer

A cursor over source text that knows its line and column.

pub(all) struct Lexer {
  src : String
  template : String
  mut pos : Int32
  mut line : Int32
  mut line_start : Int32
}

pub fn Lexer::column(Self) -> Int32

pub fn Lexer::fail(Self, String) -> @spec.Refused

pub fn Lexer::new(String, String, pos? : Int32, line? : Int32, line_start? : Int32) -> Self

pub fn Lexer::token(Self) -> Token raise @spec.Refused

struct Macro

A macro, or a mixin of the indentation syntax: a mixin also receives the call's attributes as attributes and its block as block.

pub(all) struct Macro {
  name : String
  params : Array[Param]
  body : Array[Node]
  pug : Bool
}

enum Node

pub(all) enum Node {
  Line(Int32)
  Text(String)
  Stretch(Reading, Array[Node])
  Out(Expr)
  Raw(Expr)
  For(target~ : Target, iter~ : Expr, cond~ : Expr?, recursive~ : Bool, each~ : Bool, body~ : Array[Node], otherwise~ : Array[Node])
  If(Array[(Expr, Array[Node])], Array[Node])
  Set(Target, Expr)
  SetBlock(Target, Expr?, Array[Node])
  MacroDef(Macro)
  CallBlock(Array[Param], Expr, Array[Node])
  FilterBlock(Expr, Array[Node])
  Extends(Expr)
  BlockDef(Block)
  Include(Expr, missing~ : Bool, context~ : Bool, raw~ : Bool, inline~ : Bool, block~ : Array[Node])
  Yield
  Import(Expr, String, context~ : Bool)
  FromImport(Expr, Array[(String, String?)], context~ : Bool)
  With(Array[(Target, Expr)], Array[Node])
  Autoescape(Expr, Array[Node])
  Do(Expr)
  Debug
  Show(Expr, Array[Node])
  Once(Expr?, Array[Node])
  TransOut(Trans)
  Break
  Continue
  Element(Element)
  Doctype(String)
  Comment(Array[Node])
  Case(Expr, Array[(Array[Expr], Array[Node])], Array[Node])
}

Line

The line in the template where the following node starts.

Stretch

A stretch read in one language and kept whole: what it renders goes through that language's conversion, and inside a stretch that converts its own output it is put back after the conversion rather than before.

Raw

Output never escaped: the indentation syntax's != and !{…}.

For

A loop. each is the indentation syntax's: with two names the value binds first, then the index or key.

Include

raw includes the text as it stands, as the indentation syntax does for a file that is not a template. inline renders the file in place, as the indentation syntax does: what it defines stays defined and its blocks take part in inheritance. block is the indentation syntax's body under an include, rendered where the included file says yield.

Yield

Where an include's block goes.

enum Op

pub(all) enum Op {
  Add
  Sub
  Mul
  Div
  FloorDiv
  Mod
  Pow
  And
  Or
  Eq
  Ne
  Lt
  Gt
  Le
  Ge
  In
  NotIn
}

struct Options

How the brace syntax reads whitespace, line-oriented tags and the strings that make a tag.

pub(all) struct Options {
  trim_blocks : Bool
  lstrip_blocks : Bool
  keep_trailing_newline : Bool
  line_statement : String?
  line_comment : String?
  delimiters : Delimiters
}

struct Param

A macro or call-block parameter.

pub(all) struct Param {
  name : String
  default : Expr?
  rest : Bool
}

struct Parser

A token stream and the way its syntax reads a statement's body. The brace syntax reads on through the same stream; the indentation syntax reads the indented lines and swaps in the tokens of the closing line.

pub(all) struct Parser {
  template : String
  mut tokens : Array[Token]
  mut at : Int32
  body : (Parser, Array[String]) -> Array[Node] raise @spec.Refused
}

body

Read nodes until one of the end tags; on return the current token is the end tag's name.

pub fn Parser::current(Self) -> Token

pub fn Parser::expect(Self, Tok) -> Unit raise @spec.Refused

pub fn Parser::fail(Self, String) -> @spec.Refused

pub fn Parser::next(Self) -> Token

pub fn Parser::parse_expression(Self) -> Expr raise @spec.Refused

pub fn Parser::parse_filter(Self, Expr?) -> Expr raise @spec.Refused

pub fn Parser::parse_signature(Self) -> Array[Param] raise @spec.Refused

pub fn Parser::parse_statement(Self) -> Array[Node] raise @spec.Refused

pub fn Parser::parse_tuple(Self, simplified? : Bool, condexpr? : Bool, extra? : Array[String], parenthesised? : Bool) -> Expr raise @spec.Refused

pub fn Parser::statements(Self, Array[String], drop? : Bool) -> Array[Node] raise @spec.Refused

enum Placement

pub(all) enum Placement {
  Replace
  Append
  Prepend
}

struct Reading

Where a reader stands: the language and whether it is forced, the template and the line the source starts on, the brace options in effect, whether raw HTML is allowed through, the indentation syntax's shorthand prefixes, and the languages a block may name.

pub(all) struct Reading {
  lang : Lang
  force : Bool
  template : String
  line : Int32
  options : Options
  safe : Bool
  shortcuts : Map[String, String]
  langs : (String) -> Lang?
}

safe

Whether HTML written by the template's author is written as it is. Off, a converter escapes it, as a Markdown page leaves html: false.

pub fn Reading::allows(Self, Lang) -> Bool

pub fn Reading::block(Self, String, String, Bool?, Int32) -> Array[Node] raise @spec.Refused

pub fn Reading::inside(Self, Lang, Bool?, Bool?, Int32) -> Self

pub fn Reading::stretch(Self, String, String, Bool?, Bool?, Int32) -> Node raise @spec.Refused

enum Target

Where an assignment or a loop binds.

pub(all) enum Target {
  Name(String)
  Tuple(Array[Target])
  Field(String, String)
}

enum Tok

One token. Template text and the delimiters of the brace syntax sit in the same stream as the tokens inside tags, as in Jinja's lexer.

pub(all) enum Tok {
  Data(String)
  VarBegin
  VarEnd
  BlockBegin
  BlockEnd
  Name(String)
  Str(String)
  Int(Int64)
  Float(Double)
  Op(String)
  Lang(String, Bool?, Bool?, String)
  Eof
}

Lang

A language block's language, its force and its safety if given, and its body.

struct Token

pub(all) struct Token {
  tok : Tok
  line : Int32
  column : Int32
}

struct Trans

A {% trans %}: message ids with %(name)s placeholders, the values those names take, the plural count, and the message context.

pub(all) struct Trans {
  context : String?
  singular : String
  plural : String?
  vars : Array[(String, Expr)]
  count : Expr?
}