Struct upon::Engine

pub struct Engine<'engine> { /* private fields */ }

The compilation and rendering engine.

Implementations

impl<'engine> Engine<'engine>

pub fn new() -> Self

Construct a new engine.

pub fn with_syntax(syntax: Syntax<'engine>) -> Self

Construct a new engine with custom syntax.

Examples

use upon::{Engine, Syntax};

let syntax = Syntax::builder().expr("<{", "}>").block("<[", "]>").build();
let engine = Engine::with_syntax(syntax);

pub fn set_max_include_depth(&mut self, depth: usize)

Set the maximum length of the template render stack.

This is the maximum number of nested {% include ... %} statements that are allowed during rendering, as counted from the root template.

Defaults to 64.

pub fn set_default_formatter<F>(&mut self, f: &'engine F)

where F: Fn(&mut Formatter<'_>, &Value) -> Result + Sync + Send + 'static,

Set the default formatter.

The default formatter defines how values are formatted in the rendered template. If not configured this defaults to fmt::default which does not perform any escaping. See the fmt module documentation for more information on value formatters.

pub fn add_formatter<N, F>(&mut self, name: N, f: F) -> Option<EngineFn>

where N: Into<Cow<'engine, str>>, F: Fn(&mut Formatter<'_>, &Value) -> Result + Sync + Send + 'static,

Add a new value formatter to the engine.

See the fmt module documentation for more information on formatters.

Note

Formatters and filters share the same namespace. If a filter or formatter with the same name already exists in the engine, it is replaced and Some(_) with the type of function that was replaced is returned, else None is returned.

pub fn add_filter<N, F, R, A>(&mut self, name: N, f: F) -> Option<EngineFn>

where N: Into<Cow<'engine, str>>, F: Filter<R, A> + Send + Sync + 'static, R: FilterReturn, A: FilterArgs,

Available on crate feature filters only.

Add a new filter to the engine.

See the filters module documentation for more information on filters.

Note

Formatters and filters share the same namespace. If a filter or formatter with the same name already exists in the engine, it is replaced and Some(_) with the type of function that was replaced is returned, else None is returned.

pub fn remove_function(&mut self, name: &str) -> Option<EngineFn>

Remove a formatter or filter by name.

Note

Formatters and filters share the same namespace. If a filter or formatter with name existed in the engine, it is replaced and Some(_) with the type of function that was replaced is returned, else None is returned.

pub fn add_template<N, S>(&mut self, name: N, source: S) -> Result<()>

where N: Into<Cow<'engine, str>>, S: Into<Cow<'engine, str>>,

Add a template to the engine.

The template will be compiled and stored under the given name.

You can either pass a borrowed template (&str) or owned template (String) to this function. When passing a borrowed template, the lifetime needs to be at least as long as the engine lifetime. For shorter template lifetimes use .compile(..).

pub fn template(&self, name: &str) -> TemplateRef<'_>

Lookup a template by name.

Panics

If the template with the given name does not exist.

pub fn get_template(&self, name: &str) -> Option<TemplateRef<'_>>

Lookup a template by name, returning None if it does not exist.

pub fn remove_template(&mut self, name: &str) -> bool

Remove a template by name.

Returns true if a template was removed, false if there was no template of that name.

pub fn compile<'source, S>(&self, source: S) -> Result<Template<'source>>

where S: Into<Cow<'source, str>>,

Compile a template.

The template will not be stored in the engine. The advantage over using .add_template(..) here is that if the template source is borrowed, it does not need to outlive the engine.

Trait Implementations

impl Debug for Engine<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'engine> Default for Engine<'engine>

fn default() -> Self

Returns the “default value” for a type.