<div align="center"><img width="500" src="https://raw.githubusercontent.com/pantor/inja/master/doc/logo.svg?sanitize=true">
Inja is a template engine for modern C++, loosely inspired by jinja for python. It has an easy and yet powerful template syntax with all variables, loops, conditions, includes, callbacks, and comments you need, nested and combined as you like. Inja uses the wonderful json library by nlohmann for data input. Most importantly, inja needs only two header files, which is (nearly) as trivial as integration in C++ can get. Of course, everything is tested on all relevant compilers. Here is what it looks like:
json data;
data["name"] = "world";
inja::render("Hello {{ name }}!", data);
Integration
Inja is a headers only library, which can be downloaded from the releases or directly from the include/
or single_include/
folder. Inja uses nlohmann/json.hpp
(>= v3.8.0) as its single dependency, so make sure it can be included from inja.hpp
. json can be downloaded here. Then integration is as easy as:
#include <inja.hpp>
using namespace inja;
using json = nlohmann::json;
If you are using the Meson Build System, then you can wrap this repository as a subproject.
If you are using Conan to manage your dependencies, have a look at this repository. Please file issues here if you experience problems with the packages.
You can also integrate inja in your project using Hunter, a package manager for C++.
If you are using vcpkg on your project for external dependencies, then you can use the inja package. Please see the vcpkg project for any issues regarding the packaging.
If you are using cget, you can install the latest development version with cget install pantor/inja
. A specific version can be installed with cget install pantor/inja@v2.1.0
.
On macOS, you can install inja via Homebrew and brew install inja
.
If you are using conda, you can install the latest version from conda-forge with conda install -c conda-forge inja
.
Tutorial
This tutorial will give you an idea how to use inja. It will explain the most important concepts and give practical advices using examples and executable code. Beside this tutorial, you may check out the documentation.
Template Rendering
The basic template rendering takes a template as a std::string
and a json
object for all data. It returns the rendered template as an std::string
.
json data;
data["name"] = "world";
render("Hello {{ name }}!", data);
render_to(std::cout, "Hello {{ name }}!", data);
For more advanced usage, an environment is recommended.
std::string result = env.render("Hello {{ name }}!", data);
Template temp = env.parse_template(
"./templates/greeting.txt");
std::string result = env.render(temp, data);
data["name"] = "Inja";
std::string result = env.render(temp, data);
result = env.render_file("./templates/greeting.txt", data);
result = env.render_file_with_json_file("./templates/greeting.txt", "./data.json");
env.write(temp, data, "./result.txt");
env.write_with_json_file("./templates/greeting.txt", "./data.json", "./result.txt");
Class for changing the configuration.
Definition: environment.hpp:27
The main inja Template.
Definition: template.hpp:18
The environment class can be configured to your needs.
Environment env_2 {
"../path/templates/",
"../path/results/"};
void set_statement(const std::string &open, const std::string &close)
Sets the opener and closer for template statements.
Definition: environment.hpp:47
void set_comment(const std::string &open, const std::string &close)
Sets the opener and closer for template comments.
Definition: environment.hpp:72
void set_line_statement(const std::string &open)
Sets the opener for template line statements.
Definition: environment.hpp:57
void set_expression(const std::string &open, const std::string &close)
Sets the opener and closer for template expressions.
Definition: environment.hpp:63
Variables
Variables are rendered within the {{ ... }}
expressions.
json data;
data["neighbour"] = "Peter";
data["guests"] = {"Jeff", "Tom", "Patrick"};
data["time"]["start"] = 16;
data["time"]["end"] = 22;
render("{{ guests.1 }}", data);
render("{{ time.start }} to {{ time.end + 1 }}pm", data);
If no variable is found, valid JSON is printed directly, otherwise an inja::RenderError
is thrown.
Statements
Statements can be written either with the {% ... %}
syntax or the ##
syntax for entire lines. Note that ##
needs to start the line without indentation. The most important statements are loops, conditions and file includes. All statements can be nested.
Loops
render(R"(Guest List:
## for guest in guests
{{ loop.index1 }}: {{ guest }}
## endfor )", data)
In a loop, the special variables loop/index (number)
, loop/index1 (number)
, loop/is_first (boolean)
and loop/is_last (boolean)
are defined. In nested loops, the parent loop variables are available e.g. via loop/parent/index
. You can also iterate over objects like {% for key, value in time %}
.
Conditions
Conditions support the typical if, else if and else statements. Following conditions are for example possible:
render("{% if time.hour >= 20 %}Serve{% else if time.hour >= 18 %}Make{% endif %} dinner.", data);
render("{% if neighbour in guests %}Turn up the music!{% endif %}", data);
render("{% if guest_count < (3+2) and all_tired %}Sleepy...{% else %}Keep going...{% endif %}", data);
render("{% if not guest_count %}The End{% endif %}", data);
Includes
You can either include other in-memory templates or from the file system.
inja::Template content_template = env.parse(
"Hello {{ neighbour }}!");
env.render("Content: {% include \"content\" %}", data);
render("{% include \"footer.html\" %}", data);
void set_search_included_templates_in_files(bool search_in_files)
Sets the element notation syntax.
Definition: environment.hpp:91
void include_template(const std::string &name, const Template &tmpl)
Definition: environment.hpp:206
Inja will throw an inja::RenderError
if an included file is not found. To disable this error, you can call env.set_throw_at_missing_includes(false)
.
Assignments
Variables can also be defined within the template using the set statment.
render("{% set new_hour=23 %}{{ new_hour }}pm", data);
render("{% set time.start=18 %}{{ time.start }}pm", data);
Assignments only set the value within the rendering context; they do not modify the json object passed into the render
call.
Functions
A few functions are implemented within the inja template syntax. They can be called with
render("Hello {{ upper(neighbour) }}!", data);
render("Hello {{ lower(neighbour) }}!", data);
render("{% for i in range(4) %}{{ loop.index1 }}{% endfor %}", data);
render("{% for i in range(3) %}{{ at(guests, i) }} {% endfor %}", data);
render("I count {{ length(guests) }} guests.", data);
render("{{ first(guests) }} was first.", data);
render("{{ last(guests) }} was last.", data);
render("{{ sort([3,2,1]) }}", data);
render("{{ sort(guests) }}", data);
render("{{ join([1,2,3], \" + \") }}", data);
render("{{ join(guests, \", \") }}", data);
render("{{ round(3.1415, 0) }}", data);
render("{{ round(3.1415, 3) }}", data);
render("{{ odd(42) }}", data);
render("{{ even(42) }}", data);
render("{{ divisibleBy(42, 7) }}", data);
render("{{ max([1, 2, 3]) }}", data);
render("{{ min([-2.4, -1.2, 4.5]) }}", data);
render("{{ int(\"2\") == 2 }}", data);
render("{{ float(\"1.8\") > 2 }}", data);
render("Hello {{ default(neighbour, \"my friend\") }}!", data);
render("Hello {{ default(colleague, \"my friend\") }}!", data);
render("{{ at(time, \"start\") }} to {{ time.end }}", data);
render("{{ exists(\"guests\") }}", data);
render("{{ exists(\"city\") }}", data);
render("{{ existsIn(time, \"start\") }}", data);
render("{{ existsIn(time, neighbour) }}", data);
render("{{ isString(neighbour) }}", data);
render("{{ isArray(guests) }}", data);
Callbacks
You can create your own and more complex functions with callbacks. These are implemented with std::function
, so you can for example use C++ lambdas. Inja Arguments
are a vector of json pointers.
int number = args.at(0)->get<int>();
return 2 * number;
});
env.render("{{ double(16) }}", data);
auto result = std::max_element(args.begin(), args.end(), [](const json* a, const json* b) { return *a < *b;});
return std::distance(args.begin(), result);
});
env.render("{{ argmax(4, 2, 6) }}", data);
env.render("{{ argmax(0, 2, 6, 8, 3) }}", data);
std::string greet = "Hello";
env.
add_callback(
"double-greetings", 0, [greet](Arguments args) {
return greet + " " + greet + "!";
});
env.render("{{ double-greetings }}", data);
void add_callback(const std::string &name, const CallbackFunction &callback)
Adds a variadic callback.
Definition: environment.hpp:177
You can also add a void callback without return variable, e.g. for debugging:
std::cout << "logging: " << args[0] << std::endl;
});
env.render("{{ log(neighbour) }}", data);
void add_void_callback(const std::string &name, const VoidCallbackFunction &callback)
Adds a variadic void callback.
Definition: environment.hpp:184
Template Inheritance
Template inheritance allows you to build a base skeleton template that contains all the common elements and defines blocks that child templates can override. Lets show an example: The base template
<!DOCTYPE html>
<html>
<head>
{% block head %}
<link rel="stylesheet" href="style.css" />
<title>{% block title %}{% endblock %} - My Webpage</title>
{% endblock %}
</head>
<body>
<div id="content">{% block content %}{% endblock %}</div>
</body>
</html>
contains three blocks
that child templates can fill in. The child template
{% extends "base.html" %}
{% block title %}Index{% endblock %}
{% block head %}
{{ super() }}
<style type="text/css">
.important { color: #336699; }
</style>
{% endblock %}
{% block content %}
<h1>Index</h1>
<p class="important">
Welcome to my blog!
</p>
{% endblock %}
calls a parent template with the extends
keyword; it should be the first element in the template. It is possible to render the contents of the parent block by calling super()
. In the case of multiple levels of {% extends %}
, super references may be called with an argument (e.g. super(2)
) to skip levels in the inheritance tree.
Whitespace Control
In the default configuration, no whitespace is removed while rendering the file. To support a more readable template style, you can configure the environment to control whitespaces before and after a statement automatically. While enabling set_trim_blocks
removes the first newline after a statement, set_lstrip_blocks
strips tabs and spaces from the beginning of a line to the start of a block.
void set_trim_blocks(bool trim_blocks)
Sets whether to remove the first newline after a block.
Definition: environment.hpp:81
void set_lstrip_blocks(bool lstrip_blocks)
Sets whether to strip the spaces and tabs from the start of a line to a block.
Definition: environment.hpp:86
With both trim_blocks
and lstrip_blocks
enabled, you can put statements on their own lines. Furthermore, you can also strip whitespaces for both statements and expressions by hand. If you add a minus sign (-
) to the start or end, the whitespaces before or after that block will be removed:
render("Hello {{- name -}} !", data);
render("{% if neighbour in guests -%} I was there{% endif -%} !", data);
Stripping behind a statement or expression also removes any newlines.
Comments
Comments can be written with the {# ... #}
syntax.
render("Hello{# Todo #}!", data);
Exceptions
Inja uses exceptions to handle ill-formed template input. However, exceptions can be switched off with either using the compiler flag -fno-exceptions
or by defining the symbol INJA_NOEXCEPTION
. In this case, exceptions are replaced by abort()
calls.
Supported compilers
Inja uses string_view
from C++17, but includes the polyfill from martinmoene. This way, the minimum version is C++11. Currently, the following compilers are tested:
- GCC 5 - 11 (and possibly later)
- Clang 3.8 - 11 (and possibly later)
- Microsoft Visual C++ 2016 - 2019 (and possibly later)
The unit tests fail to compile with GCC 4.8 but should just work fine. A complete list of supported compiler / os versions can be found in the CI definition.