Struct Template

Source

#[non_exhaustive]
pub struct Template<T, A> { /* private fields */ }

Expand description

A compiled representation of a template string with expression syntax defined by an Ast.

Compile a template by providing a template string and an Ast using Template::compile. Once you have a template, render it using an appropriate Manifest:

Template::render returns a String.
Template::render_io writes to an io::Write implementation, such as a File or stdout).
Template::render_fmt writes to a fmt::Write implementation, such as a &mut String buffer.

Templates are immutable, but you can deconstruct and reconstruct a template using its IntoIterator and FromIterator implementations.

§Type parameters

A Template is generic over two type parameters:

T: the template text type. For example, T = &str or T = Box<str>. These cases are aliased in BorrowedTemplate and OwnedTemplate. T can be any type which is From<&'fmt str> (when compiling) and AsRef<str> (when rendering).
A: the compiled format of the expression. When compiling from a template string, this must implement Ast.

For example, if you want ownership:

use mufmt::Template;
let template_str = "A {0}".to_owned();

// A template which owns all of its own data:
// - text stored as `String`
// - expressions compiled as `usize`
let template = Template::<String, usize>::compile(&template_str).unwrap();

// we can safely drop the original data
drop(template_str);

// and still use the template
let mfst = vec!["cat"];
assert_eq!(template.render(&mfst).unwrap(), "A cat");

Or if you want to borrow:

let template_str = "A {key}".to_owned();

// A template which borrows all of its data from the template string
let template = Template::<&str, &str>::compile(&template_str).unwrap();

// drop(template_str); // uncomment for compile error

let mfst = HashMap::from([("key", "cat")]);
assert_eq!(template.render(&mfst).unwrap(), "A cat");

§Template spans

A template is internally a Vec of Spans with additional metadata.

Access the spans with Template::spans.

let template = Template::<&str, usize>::compile("Items {1} and {12}").unwrap();
// the implementation of `len` and `nth` efficient
assert_eq!(template.spans().len(), 4);
assert_eq!(template.spans().get(3), Some(&Span::Expr(12)));

Then, modify the template by decomposing it into spans and then reconstructing it.

let mapped_template: Template<&str, usize> = template
    // a template can be converted into an iterator of `Span`s.
    .into_iter()
    .map(|span| match span {
        Span::Text(t) => Span::Text(t),
        Span::Expr(b) => Span::Expr(b.max(4)),
    })
    // a template can be constructed from an iterator of `Span`s.
    .collect();
assert_eq!(mapped_template.spans().get(1), Some(&Span::Expr(4)));

Manually construct a template from an iterator of Spans.

let template: Template<&'static str, usize> =
    [Span::Text("Hello "), Span::Expr(2), Span::Text("!")]
        .into_iter()
        .collect();

let mfst = ["Eero", "Aino", "Maija"];

assert_eq!(template.render(&mfst).unwrap(), "Hello Maija!");

Implementations§

Source §

impl<T, A> Template<T, A>

Source

pub fn compile<'fmt>(s: &'fmt str) -> Result<Self, SyntaxError<A::Error>>
where A: Ast<'fmt>, T: From<&'fmt str>,

Compile the provided template string, interpreting the expressions using the Ast.

Source

pub fn render<M>(&self, mfst: &M) -> Result<String, M::Error>
where T: AsRef<str>, M: ManifestMut<A>,

A convenience function to render directly into a newly allocated String.

This is equivalent to allocating a new String yourself and writing into it with render_fmt.

Source

pub fn render_io<M, W>( &self, mfst: &M, writer: W, ) -> Result<(), IORenderError<M::Error>>
where T: AsRef<[u8]>, M: ManifestMut<A>, W: Write,

Write the compiled template into the provided io::Write implementation.

The writer is not flushed unless the Manifest implementation overrides the default Manifest::write_io implementation to manually flush the writer.

Source