alethea 0.1.0

A Rust-native templating approach using normal Rust syntax.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

# alethea

[📚 Documentation](https://docs.rs/alethea) • [🧪 Examples](./examples)

## 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.
    
- Reduce the learning curve and use Rust directly inside templates:
    - 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.

---
## Quick Start

Add `alethea` to your `Cargo.toml`:

```toml
[dependencies]
alethea = "0.1.0"
```

## HTML Template Definition Example

```rust
use alethea::{append_to_template, new_template};

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="Animal">
                <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();

*/
```
## Examples

For more complete and advanced use cases (including template inheritance),
check the repository.

The [`examples/`](./examples) directory contains small projects demonstrating
how to use `alethea` in real scenarios, including:

- Web frameworks like **Axum**, **Actix**, and **Rocket**
- Standalone HTML rendering
- File generation

### Running an example

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