A Template Engine for Modern C++.zip

[<div align="center"><img width="500" src="https://raw.githubusercontent.com/pantor/inja/master/doc/logo.svg?sanitize=true"></div>](https://github.com/pantor/inja/releases) <p align="center"> <a href="https://github.com/pantor/inja/actions"> <img src="https://github.com/pantor/inja/workflows/CI/badge.svg" alt="CI Status"> </a> <a href="https://github.com/pantor/inja/actions"> <img src="https://github.com/pantor/inja/workflows/Documentation/badge.svg" alt="Documentation Status"> </a> <a href="https://app.codacy.com/gh/pantor/inja/dashboard"> <img src="https://app.codacy.com/project/badge/Grade/211718f7a36541819d1244c0e2ee6f08"/> </a> <a href="https://github.com/pantor/inja/releases"> <img src="https://img.shields.io/github/release/pantor/inja.svg" alt="Github Releases"> </a> <a href="http://github.com/pantor/inja/issues"> <img src="https://img.shields.io/github/issues/pantor/inja.svg" alt="Github Issues"> </a> <a href="https://raw.githubusercontent.com/pantor/inja/master/LICENSE"> <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="GitHub License"> </a> </p> Inja is a template engine for modern C++, loosely inspired by [jinja](http://jinja.pocoo.org) 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. Of course, everything is tested in CI on all relevant compilers. Here is what it looks like: ```.cpp json data; data["name"] = "world"; inja::render("Hello {{ name }}!", data); // Returns "Hello world!" ``` ## Integration Inja is a headers only library, which can be downloaded from the [releases](https://github.com/pantor/inja/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](https://github.com/nlohmann/json/releases). Then integration is as easy as: ```.cpp #include <inja.hpp> // Just for convenience using namespace inja; ``` If you are using the [Meson Build System](http://mesonbuild.com), then you can wrap this repository as a subproject. If you are using [Conan](https://conan.io) to manage your dependencies, have a look at [this repository](https://github.com/DEGoodmanWilson/conan-inja). Please file issues [here](https://github.com/DEGoodmanWilson/conan-inja/issues) if you experience problems with the packages. You can also integrate inja in your project using [Hunter](https://github.com/cpp-pm/hunter), a package manager for C++. If you are using [vcpkg](https://github.com/Microsoft/vcpkg) on your project for external dependencies, then you can use the [inja package](https://github.com/Microsoft/vcpkg/tree/master/ports/inja). Please see the vcpkg project for any issues regarding the packaging. If you are using [cget](https://cget.readthedocs.io/en/latest/), 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](https://formulae.brew.sh/formula/inja#default) and `brew install inja`. If you are using [conda](https://docs.conda.io/en/latest/), you can install the latest version from [conda-forge](https://anaconda.org/conda-forge/inja) 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](https://pantor.github.io/inja). ### 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`. ```.cpp json data; data["name"] = "world"; render("Hello {{ name }}!", data); // Returns std::string "Hello world!" render_to(std::cout, "Hello {{ name }}!", data); // Writes "Hello world!" to stream ``` For more advanced usage, an environment is recommended. ```.cpp Environment env; // Render a string with json data std::string result = env.render("Hello {{ name }}!", data); // "Hello world!" // Or directly read a template file Template temp = env.parse_template("./templates/greeting.txt"); std::string result = env.render(temp, data); // "Hello world!" data["name"] = "Inja"; std::string result = env.render(temp, data); // "Hello Inja!" // Or read the template file (and/or the json file) directly from the environment result = env.render_file("./templates/greeting.txt", data); result = env.render_file_with_json_file("./templates/greeting.txt", "./data.json"); // Or write a rendered template file env.write(temp, data, "./result.txt"); env.write_with_json_file("./templates/greeting.txt", "./data.json", "./result.txt"); ``` The environment class can be configured to your needs. ```.cpp // With default settings Environment env_default; // With global path to template files and where files will be saved Environment env_1 {"../path/templates/"}; // With separate input and output path Environment env_2 {"../path/templates/", "../path/results/"}; // With other opening and closing strings (here the defaults) env.set_expression("{{", "}}"); // Expressions env.set_comment("{#", "#}"); // Comments env.set_statement("{%", "%}"); // Statements {% %} for many things, see below env.set_line_statement("##"); // Line statements ## (just an opener) ``` ### Variables Variables are rendered within the `{{ ... }}` expressions. ```.cpp json data; data["neighbour"] = "Peter"; data["guests"] = {"Jeff", "Tom", "Patrick"}; data["time"]["start"] = 16; data["time"]["end"] = 22; // Indexing in array render("{{ guests.1 }}", data); // "Tom" // Objects render("{{ time.start }} to {{ time.end + 1 }}pm", data); // "16 to 23pm" ``` 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 ```.cpp // Combining loops and line statements render(R"(Guest List: ## for guest in guests {{ loop.index1 }}: {{ guest }} ## endfor )", data) /* Guest List: 1: Jeff 2: Tom 3: Patrick */ ``` 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: ```.cpp // Standard comparisons with a variable render("{% if time.hour >= 20 %}Serve{% else if time.hour >= 18 %}Make{% endif %} dinner.", data); // Serve dinner. // Variable in list render("{% if neighbour in guests %}Turn up the music!{% endif %}", data); // Turn up the music! // Logical operations render("{% if guest_count < (3+2) and all_tired %}Sleepy...{% else %}Keep going...{% endif %}", data); // Sleepy... // Negations render("{% if not guest_count %}The End{% endif %}", data); // The End ``` #### Includes You can either include other in-memory templates or from the file system. ```.cpp // To include in-memory templates, add them to the environment first inja::Template content_template = env.parse("Hello {{ neighbour }}!"); env.include_template("content", content_template); env.render("Content: {% include \"content\" %}", data); // "Content: Hello Peter!" // Other template files are included relative from the current file location render("{% include \"footer.html\" %}", data); ``` If a corresponding template could n