原文
Glaze provides string interpolation for C++ structs through the stencil and mustache formats. These provide templating mechanisms for formatting structured data into strings, inspired by the Mustache templating language. This enables the generation of dynamic output by combining predefined templates with C++ structs.
Basic Usage
struct person
{
std::string first_name{};
std::string last_name{};
uint32_t age{};
bool hungry{};
bool employed{};
};
// Basic interpolation
std::string_view layout = R"({{first_name}} {{last_name}} is {{age}} years old)";
person p{"Henry", "Foster", 34};
auto result = glz::stencil(layout, p);
// Result: "Henry Foster is 34 years old"
[!NOTE]
resultin these examples is astd::expected<std::string, glz::error_ctx>. Like most functions in Glaze (e.g.glz::write_json) you can also pass in your own string buffer as the last argument, in which case the return type isglz::error_ctx.
Template Syntax Specification
Variable Interpolation
{{key}}- Replaces with the value of the specified field from the struct{{{key}}}- Triple braces for unescaped output (mustache format only)
Boolean Sections
{{#boolean_key}} CONTENT {{/boolean_key}}- Shows CONTENT if the boolean field is true{{^boolean_key}} CONTENT {{/boolean_key}}- Shows CONTENT if the boolean field is false (inverted section)
Container Iteration
{{#container_key}} TEMPLATE {{/container_key}}- Iterates over container elements, applying TEMPLATE to each item{{^container_key}} CONTENT {{/container_key}}- Shows CONTENT if the container is empty
{{! This is a comment}}- Comments are ignored during template processing
Examples
Boolean Sections
std::string_view layout = R"({{first_name}} {{last_name}} {{#employed}}Status: Employed, Age: {{age}}{{/employed}})";
person p{"Carol", "Davis", 30, true, true};
auto result = glz::stencil(layout, p);
// Result: "Carol Davis Status: Employed, Age: 30"
Inverted Sections
std::string_view layout = R"({{first_name}} {{last_name}} {{^hungry}}I'm not hungry{{/hungry}})";
person p{"Henry", "Foster", 34, false}; // hungry is false
auto result = glz::stencil(layout, p);
// Result: "Henry Foster I'm not hungry"
Container Iteration
struct TodoItem {
std::string text;
bool completed;
std::string priority;
size_t id;
};
struct TodoList {
std::string title;
std::vector<TodoItem> items;
bool has_items;
};
std::string_view layout = R"({{title}}: {{#items}}{{text}} ({{priority}}) {{/items}})";
TodoList list{
"My Tasks",
{{"Buy milk", false, "normal", 1}, {"Call mom", true, "high", 2}},
true
};
auto result = glz::stencil(layout, list);
// Result: "My Tasks: Buy milk (normal) Call mom (high) "
Nested Sections
std::string_view layout = R"({{#items}}{{text}} {{#completed}}✓{{/completed}}{{^completed}}○{{/completed}} {{/items}})";
TodoList list{"Mixed Tasks", {{"Task 1", false, "high", 1}, {"Task 2", true, "low", 2}}, true};
auto result = glz::stencil(layout, list);
// Result: "Task 1 ○Task 2 ✓"
Empty Container Handling
std::string_view layout = R"({{title}}{{^items}} - No items found{{/items}})";
TodoList empty_list{"Empty List", {}, false};
auto result = glz::stencil(layout, empty_list);
// Result: "Empty List - No items found"
Mustache Format
Glaze provides glz::mustache with the same interface as glz::stencil, but with HTML escaping behavior:
- Double braces
{{key}}- HTML-escaped output (safe for HTML) - Triple braces
{{{key}}}- Unescaped output (raw HTML)
HTML Escaping Examples
struct html_content {
std::string title;
std::string raw_html;
};
// Double braces escape HTML
std::string_view layout = R"(<h1>{{title}}</h1>)";
html_content content{"My <Script> Title", ""};
auto result = glz::mustache(layout, content);
// Result: "<h1>My <Script> Title</h1>"
// Triple braces preserve HTML
std::string_view layout2 = R"(<div>{{{raw_html}}}</div>)";
html_content content2{"", "<strong>Bold text</strong>"};
auto result2 = glz::mustache(layout2, content2);
// Result: "<div><strong>Bold text</strong></div>"
HTML Entities Escaped
The following characters are escaped in mustache double-brace interpolation:
- < → <
- > → >
- & → &
- " → "
- ' → '
Advanced Features
Complex Template Example
std::string_view blog_template = R"(
<!DOCTYPE html>
<html>
<head>
<title>{{title}}</title>
</head>
<body>
<h1>{{title}}</h1>
<p>{{description}}</p>
<div class="content">
{{{raw_html}}}
</div>
{{#has_items}}
<ul>
{{#items}}
<li class="{{css_class}}">{{text}} {{#completed}}✓{{/completed}}</li>
{{/items}}
</ul>
{{/has_items}}
</body>
</html>)";
Error Handling
The stencil/mustache functions return std::expected<std::string, glz::error_ctx>. Common errors include:
glz::error_code::unknown_key- Referenced field doesn't exist in structglz::error_code::unexpected_end- Mismatched or missing closing tagsglz::error_code::syntax_error- Malformed template syntax
[!TIP]
Use
glz::format_errorlike the rest of Glaze to generate a nicely formatted error with context. Note that rather than passing the buffer into the formatter, pass in the layout/template string.
std::string_view layout = R"({{bad_key}} {{last_name}} {{age}})";
person p{"Henry", "Foster", 34};
auto result = glz::stencil(layout, p);
expect(result.error());
auto error_msg = glz::format_error(result, layout);
In this example error_msg will look like:
StencilCount
Glaze also provides glz::stencilcount for automatic numbering in documents:
std::string_view layout = R"(# About
## {{+}} {{first_name}} {{last_name}}
{{++}} {{first_name}} is {{age}} years old.
## {{+}} Hobbies
{{++}} Outdoor
{{+++}} Running
{{+++}} Hiking
)";
person p{"Henry", "Foster", 34};
auto result = glz::stencilcount(layout, p);
// Result:
// # About
// ## 1. Henry Foster
// 1.1 Henry is 34 years old.
//
// ## 2. Hobbies
// 2.1 Outdoor
// 2.1.1 Running
// 2.1.2 Hiking
StencilCount Syntax
{{+}}- Major section number (1, 2, 3, ...){{++}}- Sub-section number (1.1, 1.2, 2.1, ...){{+++}}- Sub-sub-section number (1.1.1, 1.1.2, ...)- And so on for deeper nesting levels
Requirements
- Structs must be reflectable (using Glaze reflection) or be glaze objects
- Boolean fields are used for section conditions
- All field names in templates must exist in the struct