Skip to main content

Crate alethea

Crate alethea 

Source
Expand description

§alethea

§Overview

alethea is a Rust templating approach designed to keep templates simple, expressive, and fully aligned with the Rust language itself.

Instead of introducing a new syntax, it allows you to write templates using native Rust constructs, reducing cognitive overhead and increasing flexibility.

§Goals

  • Eliminate std::string-style complexity:

    • Avoid manual string building (push_str, etc.) in most cases.
    • Keep templates focused on structure rather than concatenation.

  • Use Rust directly inside templates:

    • Write if, for, match, and other Rust constructs naturally.
    • Generate dynamic output without learning a separate templating language.

  • Reduce the learning curve:

    • No new syntax to learn—just Rust.
    • Avoid limitations commonly found in traditional template engines.
    • Reuse existing powerful Rust features like format! and standard library utilities, including padding and alignment
    • Behavior should be predictable if you already know Rust.

  • Ensure compile-time template safety:

    • Catch errors early during compilation.
    • Enable more reliable and maintainable templates.

  • Treat input data as read-only:

    • Templates should not modify their inputs
    • Any attempt to mutate inputs will fail at compile time.

  • Keep composition simple:

    • Provide clear and straightforward template inheritance.
    • Support nested templates for better structure and reuse.

§Architecture and Philosophy

  • Define a template using the following syntax:
ⓘ
new_template! {
    template_name(var1, var2, ...) {
        /*
            Write regular Rust code inside the template.

            Parameters (`var1`, `var2`, ...) must be valid Rust identifiers (`Ident`).

            To access variables passed in `template_name(...)`,
            use `$var_name`.

            Variables are read-only: any attempt to mutate them
            will result in a compile-time error.

            Use `append_to_template!` to build the output.
            The appended value must be coercible to `&str`
            (e.g. `&str`, `String`).
        */
    }
}
  • Use the template by passing parameters to produce a String:
ⓘ
let result = template_name!(var1: value1, var2: value2, ...);

where:

  • var1, var2, … are valid identifiers (Ident)
  • value1, value2, … are Rust expressions (Expr)

§Quick Start

§Example 01

new_template! {
    template(name, is_doctor) {
        append_to_template!("Hello ");

        if $is_doctor {
            append_to_template!("Dr. ");
        }

        append_to_template!($name);
    }
}

assert_eq!(template!(name:"Alethea", is_doctor:true), "Hello Dr. Alethea");
assert_eq!(template!(name:"Alethea", is_doctor:false), "Hello Alethea");

let s = String::from("Alethea");
assert_eq!(template!(name:&s, is_doctor:true), "Hello Dr. Alethea");

§Example 02

new_template! {
    animals_html(animals) {
        append_to_template!{
r#"
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Pet Cards</title>
        <script src="https://cdn.tailwindcss.com"></script>
    </head>
    <body class="bg-gray-100 p-10">
        <h1 class="text-3xl font-bold text-center mb-10">Our Pets</h1>
        <div class="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-6">
"#
        }

        for animal in $animals.iter() {
            append_to_template!{
                format!(
r#"
            <!-- Card -->
            <div class="bg-white rounded-xl shadow-md overflow-hidden hover:shadow-xl transition">
                <img class="w-full h-40 object-cover" src="{}" alt="Dog">
                <div class="p-4">
                    <h2 class="text-lg font-semibold">{}</h2>
                    <p class="text-gray-500 text-sm mb-2">{}</p>
                    <p class="text-gray-600 text-sm mb-4">{}</p>
                    <button class="bg-green-500 text-white px-4 py-2 rounded-lg hover:bg-green-600">
                    Adopt
                    </button>
                </div>
            </div>
"#
                , animal.image_url, animal.species, animal.description, animal.name)
            }
        }

        append_to_template!{
r#"
        </div>
    </body>
</html>
"#        
        }

    }
}

/*
   Usage example :
   ...

   let animal_html = animals_html!(animals: animals);

   // Write the string directly to the file, panic on error
   fs::write(
       "examples/htmlgen_basic/output_html/animals.html",
       &animal_html,
   )
   .unwrap();
  ...
   
*/

§Advanced Examples

For more complete examples with usecases like inheritence , check the repository.

The examples/ directory contains small projects using frameworks like Axum, Actix, and Rocket, along with standalone HTML and file generation examples.

To run an example:

cargo run --manifest-path examples/<example>/Cargo.toml

§Template inheritance

Check examples/htmlgen_template_inheritance_indent for usage examples.

TODO: document inheritance behavior

§Nested templates

See examples/htmlgen_inner_templates for usage examples.

TODO: document nested templates

§Template readability guidelines

  • Keep appended or formatted strings aligned to the left (no indentation). This helps the reader see the output structure directly, almost as if they were reading the final rendered document, with control flow (if, for, etc.) appearing around it.

  • Prefer using “\ and type content in next line for paragraphs when possible, as it provides a more natural and readable flow for multi-line content.

Note: these are guidelines only. There are no strict limitations imposed by the library—you are free to structure templates as you see fit.

§HTML templates readability guidelines

When working with HTML, there is more flexibility since the generated output is interpreted as XML-like content and does not require strict indentation or line breaks for correct rendering.

To keep templates readable:

  • Prefer using “\ when possible.
  • Otherwise, use raw strings (r#"..."#) for multiline content. In that case, content typically begins on the line after r#", which introduces a newline in the template, but this does not affect HTML rendering and can improve readability.

Another important point is indentation in inheritance scenarios. When composing templates (parent/child), indentation can be applied in the parent when appending the child template (see examples/htmlgen_template_inheritance_indent).

However, this indentation may introduce a small runtime cost. For HTML use cases, it is recommended to:

  • Enable indentation in debug mode for readable output.
  • Disable it in release mode for better performance, especially in web contexts where performance matters.

Note: these are guidelines only. There are no strict limitations imposed by the library—you are free to structure templates as you see fit.

Macros§

append_to_template
Appends content to the current template output.
new_template
Defines a template-generating macro_rules! macro.

Functions§

indent
Indents each line of the given string with the provided prefix.