markup.rs

一个blazingly fast、类型安全的Rust模板引擎。

</div>

markup.rs是一个由过程宏驱动的Rust模板引擎,它在编译时解析模板并生成最优的Rust代码以在运行时渲染模板。模板可以嵌入Rust代码,这些代码由Rust编译器进行类型检查,实现完全的类型安全。

特性

完全类型安全,使用诸如rust-analyzer等编辑器扩展时可显示内联高亮错误。
受Haml、Slim和Pug启发的简洁易用、不容易出错的语法。
零不安全代码。
零运行时依赖。
⚡ 速度极快。在这个基准测试中,在不使用不安全代码的模板引擎中速度最快,总体第二快。

安装

[dependencies]
markup = "0.15.0"

框架集成

我们有以下web框架的集成示例:

Axum
Rocket

快速示例

markup::define! {
    Home<'a>(title: &'a str) {
        @markup::doctype()
        html {
            head {
                title { @title }
                style {
                    "body { background: #fafbfc; }"
                    "#main { padding: 2rem; }"
                }
            }
            body {
                @Header { title }
                #main {
                    p {
                        "本域名用于文档中的说明性示例。您可以在文献中使用此域名,无需事先协调或请求许可。"
                    }
                    p {
                        a[href = "https://www.iana.org/domains/example"] {
                            "更多信息..."
                        }
                    }
                }
                @Footer { year: 2020 }
            }
        }
    }

    Header<'a>(title: &'a str) {
        header {
            h1 { @title }
        }
    }

    Footer(year: u32) {
        footer {
            "(c) " @year
        }
    }
}

fn main() {
    println!(
        "{}",
        Home {
            title: "示例域名"
        }
    )
}

输出

<!DOCTYPE html><html><head><title>示例域名</title><style>body { background: #fafbfc; }#main { padding: 2rem; }</style></head><body><header><h1>示例域名</h1></header><div id="main"><p>本域名用于文档中的说明性示例。您可以在文献中使用此域名,无需事先协调或请求许可。</p><p><a href="https://www.iana.org/domains/example">更多信息...</a></p></div><footer>(c) 2020</footer></body></html>

输出(手动美化)

<!doctype html>
<html>
  <head>
    <title>示例域名</title>
    <style>
      body {
        background: #fafbfc;
      }
      #main {
        padding: 2rem;
      }
    </style>
  </head>
  <body>
    <header><h1>示例域名</h1></header>
    <div id="main">
      <p>
        本域名用于文档中的说明性示例。您可以在文献中使用此域名,无需事先协调或请求许可。
      </p>
      <p>
        <a href="https://www.iana.org/domains/example">更多信息...</a>
      </p>
    </div>
    <footer>(c) 2020</footer>
  </body>
</html>

语法参考 (待完善)

markup::define! 和 markup::new!

定义模板有两种方式: markup::define! 和 markup::new!。

markup::define! 定义具有命名参数的模板。这些模板不能访问外部作用域的变量。这些模板可以有泛型参数。在底层,markup::define! 编译为实现了 markup::Render 和 std::fmt::Display trait 的 Rust 结构体。

markup::define! {
    Hello<'a>(name: &'a str) {
        "你好, " @name "!"
    }
    HelloGeneric<T: std::fmt::Display>(name: T) {
        "你好, " @name.to_string() "!"
    }
}

// 现在可以直接打印模板或写入流:
println!("{}", Hello { name: "世界" });
writeln!(&mut std::io::stdout(), "{}", HelloGeneric { name: "世界 2" }).unwrap();

// 模板也可以渲染为String:
let string = Hello { name: "世界 3" }.to_string();
println!("{}", string);

</td></tr> <tr><th>输出</th></tr> <tr><td width="1000px">

你好, 世界!
你好, 世界 2!
你好, 世界 3!

</td></tr> </table>

markup::new! 定义没有任何参数的模板。这些模板可以访问外部作用域的变量。

let name = "世界";
let template = markup::new! {
    "你好, " @name "!"
};

// 现在可以直接打印模板或写入流:
println!("{}", template);
writeln!(&mut std::io::stdout(), "{}", template).unwrap();

// 模板也可以渲染为String:
let string = template.to_string();
println!("{}", string);

</td></tr> <tr><th>输出</th></tr> <tr><td width="1000px">

你好, 世界!
你好, 世界!
你好, 世界!

</td></tr> </table>

表达式

模板可以包含裸字面值,这些值会按原样渲染。它们也可以包含以 @ 符号开头的表达式(包括函数和宏调用)。所有字符串都会进行HTML转义,除非它们被包裹在 markup::raw() 中。

markup::define! {
    Expressions(a: i32, b: i32) {
        1 " + " 2 " = " @{1 + 2} '\n'
        @a " - " @b " = " @{a - b} '\n'
        @format!("{} * {} = {}", a, b, a * b) '\n'
        @a " ^ 4 = " @a.pow(4) '\n'

        // 默认情况下所有输出都会被转义。
        "<>\n"
        // 可以使用 `markup::raw()` 禁用转义。
        @markup::raw("<div></div>")
    }
}

println!("{}", Expressions { a: 5, b: 3 });

</td></tr> <tr><th>输出</th></tr> <tr><td width="1000px">

1 + 2 = 3
5 - 3 = 2
5 * 3 = 15
5 ^ 4 = 625
&lt;&gt;
<div></div>

</td></tr> </table>

元素

元素使用类似CSS选择器的语法定义。元素可以在花括号中包含其他嵌套元素,或者在自闭合元素后跟分号。

markup::define! {
    Elements(name: &'static str) {
        // 仅一个div。
        div {}
        '\n'
        // 三个嵌套元素。
        main {
            aside {
                h3 { "侧边栏" }
            }
        }
        '\n'
        // 自闭合的input元素。
        input;
        '\n'
        // 名称包含破折号的元素。
        $"my-custom-element" {}
        '\n'
        // 动态名称的元素。
        ${name} {}
    }
}

println!("{}", Elements { name: "span" });

</td></tr> <tr><th>输出</th></tr> <tr><td width="1000px">

<div></div>
<main><aside><h3>侧边栏</h3></aside></main>
<input>
<my-custom-element></my-custom-element>
<span></span>

</td></tr> </table>

属性

属性在元素名称后定义。id 和 class 属性可以使用类似CSS选择器的语法,使用 # 和 . 定义。可以使用此简写语法多次指定类。其他属性在方括号中指定。

markup::define! {
    Attributes(id: u32, category: String, data: std::collections::BTreeMap<String, String>) {
        // 一个带有id和两个类的div。
        // 注意:从Rust 2021开始,元素名称和 `#` 之间必须有一个空格,
        // 因为保留语法 (https://doc.rust-lang.org/edition-guide/rust-2021/reserving-syntax.html)
        div #foo.bar.baz {}
        '\n'
        // 一个带有动态计算的id以及一个静态和一个动态类的div。
        div #{format!("post-{}", id)}.post.{format!("category-{}", category)} {}
        '\n'

        // 布尔属性只有在为true时才会渲染。不指定值等同于 `true`。
        input[checked = true];
        '\n'
        input[checked = false];
        '\n'
        input[checked];
        '\n'

        // `Option` 属性只有在它们是 `Some` 时才会渲染。
        input[type = Some("text"), minlength = None::<String>];
        '\n'

        // 属性名也可以是用花括号包裹的表达式。
        div[{format!("{}{}", "data-", "post-id")} = id] {}
        '\n'

        // 可以使用 `..` 语法动态添加多个属性。
        div[..data.iter().map(|(k, v)| (("data-", k), v))] {}
    }
}

</td></tr> </table> println!("{}", Attributes { id: 123, category: String::from("tutorial"), data: [ (String::from("foo"), String::from("bar")), (String::from("baz"), String::from("quux")) ].iter().cloned().collect(), }); ``` </td></tr> <tr><th>输出</th></tr> <tr><td width="1000px">

<div id="foo" class="bar baz"></div>
<div id="post-123" class="post category-tutorial"></div>
<input checked>
<input>
<input checked>
<input type="text">
<div data-post-id="123"></div>
<div data-baz="quux" data-foo="bar"></div>

</td></tr> </table>

@if 和 @if let

@if 和 @if let 的工作方式类似于 Rust。

markup::define! {
    If(x: u32, y: Option<u32>) {
        @if *x == 1 {
            "x = 1\n"
        } else if *x == 2 {
            "x = 2\n"
        } else {
            "x 既不是 1 也不是 2\n"
        }

        @if let Some(y) = y {
            "y = " @y "\n"
        } else {
            "y 是 None\n"
        }
    }
}

println!("{}", If { x: 2, y: Some(2) });
println!("{}", If { x: 3, y: None });

</td></tr> <tr><th>输出</th></tr> <tr><td width="1000px">

x = 2
y = 2

x 既不是 1 也不是 2
y 是 None

</td></tr> </table>

@match

@match 的工作方式类似于 Rust，但分支必须用大括号括起来。

markup::define! {
    Match(x: Option<u32>) {
        @match x {
            Some(1) | Some(2) => {
                "x 是 1 或 2"
            }
            Some(x) if *x == 3 => {
                "x 是 3"
            }
            None => {
                "x 是 None"
            }
            _ => {
                "x 是其他值"
            }
        }
    }
}

println!("{}", Match { x: None });
println!("{}", Match { x: Some(2) });
println!("{}", Match { x: Some(4) });

</td></tr> <tr><th>输出</th></tr> <tr><td width="1000px">

x 是 None
x 是 1 或 2
x 是其他值

</td></tr> </table>

@for

@for 的工作方式类似于 Rust。

markup::define! {
    For<'a>(xs: &'a [u32]) {
        @for (i, x) in xs.iter().enumerate() {
            @i ": " @x "\n"
        }
    }
}

println!("{}", For { xs: &[1, 2, 4, 8] });

</td></tr> <tr><th>输出</th></tr> <tr><td width="1000px">

0: 1
1: 2
2: 4
3: 8

</td></tr> </table>

语句

模板可以包含以 @ 符号开头的语句。最常用的是 @let 语句，用于计算一个值以供后续重复使用。@fn 可用于定义函数。此外还支持 @struct、@mod、@impl、@const、@static 等。

markup::define! {
    Statement(x: i32) {
        @let double_x = x * 2;
        @double_x '\n'

        @fn triple(x: i32) -> i32 { x * 3 }
        @triple(*x)
    }
}

println!("{}", Statement { x: 2 });