Ramhorns Templating Engine

Ramhorns implements the Mustache template syntax with several key features:

• Variables: Use {{variable}} to render common types like &str, String, bool, and numbers.
• Unescaped Printing: Use {{{triple-brace}}} or {{&ampersand}} to print content without HTML escaping.
• Sections: Use {{#foo}} ... {{/foo}} to render sections (useful for iterating over lists or conditional rendering).
• Inverse Sections: Use {{^foo}} ... {{/foo}} to render content when a section is empty or false.
• Partials: Use {{>file.html}} to include partial templates.
• Markdown Rendering: Fields marked with the #[md] attribute support zero-copy CommonMark rendering.

Add ramhorns to your Cargo.toml dependencies to use the template engine in your Rust project.

[dependencies]
ramhorns = "0.5"

When the indexes feature is enabled, you can perform specific list traversals within sections using index-based tags. This allows you to target specific elements in a list (like the first or last) or include/exclude specific indices.

Syntax

• Include an index: {{#-index}} (e.g., {{#-first}} or {{#-2}})
• Exclude an index: {{^-index}} (e.g., {{^-last}} or {{^-0}})

Supported Index Keywords

• first: Targets the first element of the list.
• last: Targets the last element of the list.
• n: Any integer targets the nth element (0-indexed).

<!-- Example of index-based tags in a template -->
{{#items}}
  {{#-first}} This is the first item! {{/items}}
  {{^-last}} This is not the last item! {{/items}}
  {{#-2}} This is the third item (index 2). {{/items}}
{{/items}}

The Ramhorns struct acts as an aggregator for Templates. It manages a collection of templates and handles the loading and resolution of partials (e.g., {{>partial}}). It is designed to load templates from the file system and can be configured with a custom hasher for performance or DOS resistance (e.g., using aHash).

// Example of creating an aggregator from a folder
let tpls: Ramhorns = Ramhorns::from_folder("./templates").unwrap();
let rendered = tpls.get("hello.html").unwrap().render(&content);

When using conditionals in templates, is_truthy() determines the outcome:

The Content trait is used to define how data structures can be used as context within Ramhorns templates. It provides methods for rendering variables (escaped or unescaped), handling conditional sections, and accessing fields by name or hash.

While you can implement this trait manually for custom types, most users should use the #[derive(Content)] attribute from the ramhorns-derive crate to automatically implement it for their structs and enums.

#[derive(ramhorns_derive::Content)]
struct MyContext {
    name: String,
    is_active: bool,
    items: Vec<String>,
}

The simplest way to render a template is using render(&self, content: &C), which returns a String. This method automatically handles HTML escaping and estimates the required buffer capacity to minimize reallocations.

// Assuming 'content' implements the Content trait
let rendered = tpl.render(&content);

The Content trait provides several methods for the template engine to interact with your data:

• is_truthy(): Determines if a value is considered 'true' for conditional rendering. For example, () is always false, while non-empty strings or non-zero numbers are true.
• render_escaped(): Renders the value with HTML escaping (e.g., < becomes <).
• render_unescaped(): Renders the value without any escaping.
• render_section(): Renders a template section if the current content is truthy.
• render_inverse(): Renders a template section if the current content is NOT truthy.
• render_field_escaped() / render_field_unescaped(): Accesses a specific field within a map-like structure by its name or hash and renders it.
• render_field_section() / render_field_inverse(): Accesses a field and renders it as a conditional section.

You can call capacity_hint() on a Template to get an estimate of the byte length required to render the template. This is useful for pre-allocating buffers in custom rendering workflows.

let hint = tpl.capacity_hint();
// Use hint to pre-allocate a buffer, etc.

Use Template::new(source) to create a preprocessed template from a string.

• If you pass a &str, the Template will borrow the source text (using the 'tpl lifetime).
• If you pass a String, the Template will take ownership of the string, resulting in a 'static lifetime.

// Borrowing a string slice
let source = "Hello {{name}}!";
let tpl = Template::new(source).unwrap();

// Taking ownership of a String
let source_string = String::from("Hello {{name}}!");
let tpl: Template<'static> = Template::new(source_string).unwrap();