olav 0.1.0

Compile-time XML template engine with maud-like syntax for Rust.
Documentation

olav

A compile-time XML template engine for Rust, inspired by maud.

Example: an Atom feed

use olav::{xml, PreEscaped};

let feed_title = "Example Feed";
let feed_id = "urn:uuid:60a76e80-d399-11e9-b23e-2a8991f4d4ad";
let updated = "2026-08-22T18:30:02Z";
let author_name = "Jane Developer";
let author_email = "jane@example.com";
let is_published = true;

let entries: Vec<(&str, &str, &str, &str)> = vec![
    (
        "1225c695-cfb8-4ebb-aaaa-80da344efa6a",
        "Atom-Powered Robots Run Amok",
        "2026-08-22T18:30:02Z",
        "<p>Some atom news with <em>embedded HTML</em>.</p>",
    ),
    (
        "b3f5df58-2f55-4b56-9c52-9d6e0d3d7a8b",
        "Macros in Rust",
        "2026-08-15T10:00:00Z",
        "<p>Why compile-time templates are <strong>great</strong>.</p>",
    ),
];

let feed = xml! {
    ?xml version="1.0" encoding="utf-8"
    @comment " Atom 1.0 feed, generated by olav "
    feed(xmlns="http://www.w3.org/2005/Atom", [xml:lang]="en") {
        title(type="text") { @feed_title }
        subtitle { "An olav example feed." }
        id { @feed_id }
        updated { @updated }
        author {
            name { @author_name }
            email { @author_email }
        }
        [atom:link](rel="self", type="application/atom+xml", href="http://example.com/feed.atom") { }
        @if is_published {
            rights(type="text") { "© 2026 Example Inc." }
        }
        @for (eid, etitle, eupdated, econtent) in &entries {
            entry {
                title(type="text") { @etitle }
                id { "urn:uuid:" @eid }
                updated { @eupdated }
                summary(type="text") { "An atom-sized summary." }
                @if econtent.contains('<') {
                    content(type="html") {
                        @cdata {
                            @PreEscaped(econtent)
                        }
                    }
                }
            }
        }
    }
};

println!("{}", feed);

Produces:

<?xml version="1.0" encoding="utf-8"?><!-- Atom 1.0 feed, generated by olav -->
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en">
    <title type="text">Example Feed</title>
    <subtitle>An olav example feed.</subtitle>
    <id>urn:uuid:60a76e80-d399-11e9-b23e-2a8991f4d4ad</id>
    <updated>2026-08-22T18:30:02Z</updated>
    <author>
        <name>Jane Developer</name>
        <email>jane@example.com</email>
    </author>
    <atom:link rel="self" type="application/atom+xml" href="http://example.com/feed.atom"/>
    <rights type="text">© 2026 Example Inc.</rights>
    <entry>
        <title type="text">Atom-Powered Robots Run Amok</title>
        <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
        <updated>2026-08-22T18:30:02Z</updated>
        <summary type="text">An atom-sized summary.</summary>
        <content type="html"><![CDATA[<p>Some atom news with <em>embedded HTML</em>.</p>]]></content>
    </entry>
    <entry>
        <title type="text">Macros in Rust</title>
        <id>urn:uuid:b3f5df58-2f55-4b56-9c52-9d6e0d3d7a8b</id>
        <updated>2026-08-15T10:00:00Z</updated>
        <summary type="text">An atom-sized summary.</summary>
        <content type="html"><![CDATA[<p>Why compile-time templates are <strong>great</strong>.</p>]]></content>
    </entry>
</feed>

Features

  • Compile-time checking — malformed templates fail at build time, including well-formedness checks: invalid XML names, -- in comments, ]]> in CDATA, ?> in processing instructions, duplicate attributes.
  • Auto-escaping — text and attribute values are XML-escaped by default.
  • Unicode names — Cyrillic and any Rust-identifier names work: <книга>.
  • Namespaces — bracketed names for any element/attribute: [svg:rect], [xml:lang].
  • Full XML — processing instructions, DOCTYPE with internal subset, CDATA, comments.
  • Control flow — @if/@else, @for, @while, @match.
  • Splices — @expr (escaped) and @expr.raw (verbatim); PreEscaped for raw insertion.
  • Rich Render impls — &str, String, integers, floats, bool, Option<T>, Vec<T>, [T; N], plus a DisplayValue wrapper for any std::fmt::Display type.
  • Zero-cost sizing — the output buffer is pre-sized from template literals at compile time.

Unicode and Cyrillic names

use olav::xml;

let author = "Лев Толстой";
let year: i32 = 2026;

let library = xml! {
    ?xml version="1.0" encoding="UTF-8"
    каталог {
        книга(id="1", автор=author, год=year) {
            название { "Война и мир" }
            жанр { "роман" }
        }
        книга(id="2", автор=author, год=year) {
            название { "Анна Каренина" }
            жанр { "роман" }
        }
        @for genre in &["роман", "повесть", "рассказ"] {
            метка { @genre }
        }
    }
};

println!("{}", library);

Produces (UTF-8 output):

<?xml version="1.0" encoding="UTF-8"?>
<каталог>
    <книга id="1" автор="Лев Толстой" год="2026">
        <название>Война и мир</название>
        <жанр>роман</жанр>
    </книга>
    <книга id="2" автор="Лев Толстой" год="2026">
        <название>Анна Каренина</название>
        <жанр>роман</жанр>
    </книга>
    <метка>роман</метка>
    <метка>повесть</метка>
    <метка>рассказ</метка>
</каталог>

Works for any Unicode script that Rust accepts as an identifier: Cyrillic, Greek, CJK, Arabic, Hebrew, etc. Mixed Cyrillic + Latin + numbers in the same document is fine.

For non-standard names (hyphens, colons), use the bracketed form: [my-element] { }, [svg:rect] { }. Bracketed names must still be valid XML names — they have to start with a letter, _, or :; names like [1st] are rejected at compile time.

Syntax overview

Elements

book { "text" }              // <book>text</book>
book { }                     // <book/>
[ns:book] { "x" }            // <ns:book>x</ns:book>
[my-element] { }             // <my-element/>
книга { "текст" }            // <книга>текст</книга>

Attributes (in parentheses)

book(id="42", lang="en") { ... }     // attributes are wrapped in (...)
Form Result
id="literal" id="literal"
id=value id="<Display(value)>" (escaped)
id? if cond: id="true" else omit
id?=value if cond: id="<value>" else omit
[ns:attr]="value" namespaced attribute, e.g. [xlink:href], [xml:lang], [data-x]

Body and splices

"text"                       // escaped text
@expr                        // splice (Render, escaped)
@expr.raw                    // splice, no escaping
@cdata { "raw < > &" }       // <![CDATA[raw < > &]]>

Control flow

@if cond { "yes" } @else { "no" }
@for pat in iter { ... }
@while cond { ... }
@match expr { Pattern => { ... }, _ => { ... } }

XML constructs

?xml version="1.0" encoding="UTF-8"                  // <?xml ...?>
?xml version="1.0" encoding="UTF-8" standalone="yes" // with standalone
?xml-stylesheet type="text/xsl" href="style.xsl"
!DOCTYPE html                                         // <!DOCTYPE html>
!DOCTYPE name SYSTEM "x.dtd"
!DOCTYPE name PUBLIC "id" "url"
!DOCTYPE root [                                        // with internal subset
    <!ENTITY author "John">
    <!ELEMENT root (#PCDATA)>
]
@comment "this is a comment"                          // <!--this is a comment-->

Escape hatch

For pre-escaped or pre-built markup, use PreEscaped:

use olav::{xml, PreEscaped};

let raw = "<b>already escaped</b>";
let m = xml! { div { @PreEscaped(raw) } };

To render third-party types that implement std::fmt::Display, use DisplayValue (output is escaped as usual):

use olav::{xml, DisplayValue};
use std::net::Ipv4Addr;

let ip = Ipv4Addr::new(192, 168, 0, 1);
let m = xml! { addr { @DisplayValue(ip) } };

Why no /* */ for comments?

Rust's lexer strips block comments before they reach proc-macros, so /* ... */ is not usable inside xml! { ... }. Use @comment "..." instead.

License

MIT — see LICENSE-MIT.