{"id":13470977,"url":"https://github.com/pantor/inja","last_synced_at":"2025-05-14T02:06:30.526Z","repository":{"id":37818762,"uuid":"100109300","full_name":"pantor/inja","owner":"pantor","description":"A Template Engine for Modern C++","archived":false,"fork":false,"pushed_at":"2025-03-31T21:22:39.000Z","size":2932,"stargazers_count":1761,"open_issues_count":47,"forks_count":218,"subscribers_count":53,"default_branch":"main","last_synced_at":"2025-04-10T18:32:07.470Z","etag":null,"topics":["header-only","inja","jinja","json","string-template","template","template-engine"],"latest_commit_sha":null,"homepage":"https://pantor.github.io/inja/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pantor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["pantor"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"custom":null}},"created_at":"2017-08-12T11:53:49.000Z","updated_at":"2025-04-08T23:06:34.000Z","dependencies_parsed_at":"2023-02-15T22:40:24.070Z","dependency_job_id":"69b56442-d0e1-47e0-bb35-05e9fea08f3a","html_url":"https://github.com/pantor/inja","commit_stats":{"total_commits":434,"total_committers":45,"mean_commits":9.644444444444444,"dds":"0.24884792626728114","last_synced_commit":"9e92a7c0fa50861f1206a24635b8dc14f10e3335"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pantor%2Finja","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pantor%2Finja/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pantor%2Finja/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pantor%2Finja/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pantor","download_url":"https://codeload.github.com/pantor/inja/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254052701,"owners_count":22006716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["header-only","inja","jinja","json","string-template","template","template-engine"],"created_at":"2024-07-31T16:00:37.985Z","updated_at":"2025-05-14T02:06:25.506Z","avatar_url":"https://github.com/pantor.png","language":"C++","readme":"[\u003cdiv align=\"center\"\u003e\u003cimg width=\"500\" src=\"https://raw.githubusercontent.com/pantor/inja/master/doc/logo.svg?sanitize=true\"\u003e\u003c/div\u003e](https://github.com/pantor/inja/releases)\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/pantor/inja/actions\"\u003e\n    \u003cimg src=\"https://github.com/pantor/inja/workflows/CI/badge.svg\" alt=\"CI Status\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/pantor/inja/actions\"\u003e\n    \u003cimg src=\"https://github.com/pantor/inja/workflows/Documentation/badge.svg\" alt=\"Documentation Status\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://app.codacy.com/gh/pantor/inja/dashboard\"\u003e\n    \u003cimg src=\"https://app.codacy.com/project/badge/Grade/211718f7a36541819d1244c0e2ee6f08\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/pantor/inja/releases\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/release/pantor/inja.svg\" alt=\"Github Releases\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"http://github.com/pantor/inja/issues\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/issues/pantor/inja.svg\" alt=\"Github Issues\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://raw.githubusercontent.com/pantor/inja/master/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"GitHub License\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nInja 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:\n\n```.cpp\njson data;\ndata[\"name\"] = \"world\";\n\ninja::render(\"Hello {{ name }}!\", data); // Returns \"Hello world!\"\n```\n\n## Integration\n\nInja 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` (\u003e= 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:\n\n```.cpp\n#include \u003cinja.hpp\u003e\n\n// Just for convenience\nusing namespace inja;\n```\n\nIf you are using the [Meson Build System](http://mesonbuild.com), then you can wrap this repository as a subproject.\n\nIf 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.\n\nYou can also integrate inja in your project using [Hunter](https://github.com/cpp-pm/hunter), a package manager for C++.\n\nIf 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.\n\nIf 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`.\n\nOn macOS, you can install inja via [Homebrew](https://formulae.brew.sh/formula/inja#default) and `brew install inja`.\n\nIf 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`.\n\n## Tutorial\n\nThis 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).\n\n### Template Rendering\n\nThe 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`.\n\n```.cpp\njson data;\ndata[\"name\"] = \"world\";\n\nrender(\"Hello {{ name }}!\", data); // Returns std::string \"Hello world!\"\nrender_to(std::cout, \"Hello {{ name }}!\", data); // Writes \"Hello world!\" to stream\n```\n\nFor more advanced usage, an environment is recommended.\n```.cpp\nEnvironment env;\n\n// Render a string with json data\nstd::string result = env.render(\"Hello {{ name }}!\", data); // \"Hello world!\"\n\n// Or directly read a template file\nTemplate temp = env.parse_template(\"./templates/greeting.txt\");\nstd::string result = env.render(temp, data); // \"Hello world!\"\n\ndata[\"name\"] = \"Inja\";\nstd::string result = env.render(temp, data); // \"Hello Inja!\"\n\n// Or read the template file (and/or the json file) directly from the environment\nresult = env.render_file(\"./templates/greeting.txt\", data);\nresult = env.render_file_with_json_file(\"./templates/greeting.txt\", \"./data.json\");\n\n// Or write a rendered template file\nenv.write(temp, data, \"./result.txt\");\nenv.write_with_json_file(\"./templates/greeting.txt\", \"./data.json\", \"./result.txt\");\n```\n\nThe environment class can be configured to your needs.\n```.cpp\n// With default settings\nEnvironment env_default;\n\n// With global path to template files and where files will be saved\nEnvironment env_1 {\"../path/templates/\"};\n\n// With separate input and output path\nEnvironment env_2 {\"../path/templates/\", \"../path/results/\"};\n\n// With other opening and closing strings (here the defaults)\nenv.set_expression(\"{{\", \"}}\"); // Expressions\nenv.set_comment(\"{#\", \"#}\"); // Comments\nenv.set_statement(\"{%\", \"%}\"); // Statements {% %} for many things, see below\nenv.set_line_statement(\"##\"); // Line statements ## (just an opener)\nenv.set_html_autoescape(true); // Perform HTML escaping on all strings\n```\n\n### Variables\n\nVariables are rendered within the `{{ ... }}` expressions.\n```.cpp\njson data;\ndata[\"neighbour\"] = \"Peter\";\ndata[\"guests\"] = {\"Jeff\", \"Tom\", \"Patrick\"};\ndata[\"time\"][\"start\"] = 16;\ndata[\"time\"][\"end\"] = 22;\n\n// Indexing in array\nrender(\"{{ guests.1 }}\", data); // \"Tom\"\n\n// Objects\nrender(\"{{ time.start }} to {{ time.end + 1 }}pm\", data); // \"16 to 23pm\"\n```\nIf no variable is found, valid JSON is printed directly, otherwise an `inja::RenderError` is thrown.\n\n### Statements\n\nStatements 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.\n\n#### Loops\n\n```.cpp\n// Combining loops and line statements\nrender(R\"(Guest List:\n## for guest in guests\n\t{{ loop.index1 }}: {{ guest }}\n## endfor )\", data)\n\n/* Guest List:\n\t1: Jeff\n\t2: Tom\n\t3: Patrick */\n```\nIn 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 %}`.\n\n#### Conditions\n\nConditions support the typical if, else if and else statements. Following conditions are for example possible:\n```.cpp\n// Standard comparisons with a variable\nrender(\"{% if time.hour \u003e= 20 %}Serve{% else if time.hour \u003e= 18 %}Make{% endif %} dinner.\", data); // Serve dinner.\n\n// Variable in list\nrender(\"{% if neighbour in guests %}Turn up the music!{% endif %}\", data); // Turn up the music!\n\n// Logical operations\nrender(\"{% if guest_count \u003c (3+2) and all_tired %}Sleepy...{% else %}Keep going...{% endif %}\", data); // Sleepy...\n\n// Negations\nrender(\"{% if not guest_count %}The End{% endif %}\", data); // The End\n```\n\n#### Includes\n\nYou can either include other in-memory templates or from the file system.\n```.cpp\n// To include in-memory templates, add them to the environment first\ninja::Template content_template = env.parse(\"Hello {{ neighbour }}!\");\nenv.include_template(\"content\", content_template);\nenv.render(\"Content: {% include \\\"content\\\" %}\", data); // \"Content: Hello Peter!\"\n\n// Other template files are included relative from the current file location\nrender(\"{% include \\\"footer.html\\\" %}\", data);\n```\nIf a corresponding template could not be found in the file system, the *include callback* is called:\n```.cpp\n// The callback takes the current path and the wanted include name and returns a template\nenv.set_include_callback([\u0026env](const std::filesystem::path\u0026 path, const std::string\u0026 template_name) {\n  return env.parse(\"Hello {{ neighbour }} from \" + template_name);\n});\n\n// You can disable to search for templates in the file system via\nenv.set_search_included_templates_in_files(false);\n```\n\nInja will throw an `inja::RenderError` if an included file is not found and no callback is specified. To disable this error, you can call `env.set_throw_at_missing_includes(false)`.\n\n#### Assignments\n\nVariables can also be defined within the template using the set statment.\n```.cpp\nrender(\"{% set new_hour=23 %}{{ new_hour }}pm\", data); // \"23pm\"\nrender(\"{% set time.start=18 %}{{ time.start }}pm\", data); // using json pointers\n```\n\nAssignments only set the value within the rendering context; they do not modify the json object passed into the `render` call.\n\n### Functions\n\nA few functions are implemented within the inja template syntax. They can be called with\n```.cpp\n// Upper, lower and capitalize function, for string cases\nrender(\"Hello {{ upper(neighbour) }}!\", data); // \"Hello PETER!\"\nrender(\"Hello {{ lower(neighbour) }}!\", data); // \"Hello peter!\"\nrender(\"Hello {{ capitalize(neighbour) }}!\", data); // \"Hello Peter!\"\n\n// Range function, useful for loops\nrender(\"{% for i in range(4) %}{{ loop.index1 }}{% endfor %}\", data); // \"1234\"\nrender(\"{% for i in range(3) %}{{ at(guests, i) }} {% endfor %}\", data); // \"Jeff Tom Patrick \"\n\n// Length function (please don't combine with range, use list directly...)\nrender(\"I count {{ length(guests) }} guests.\", data); // \"I count 3 guests.\"\n\n// Get first and last element in a list\nrender(\"{{ first(guests) }} was first.\", data); // \"Jeff was first.\"\nrender(\"{{ last(guests) }} was last.\", data); // \"Patir was last.\"\n\n// Sort a list\nrender(\"{{ sort([3,2,1]) }}\", data); // \"[1,2,3]\"\nrender(\"{{ sort(guests) }}\", data); // \"[\\\"Jeff\\\", \\\"Patrick\\\", \\\"Tom\\\"]\"\n\n// Join a list with a separator\nrender(\"{{ join([1,2,3], \\\" + \\\") }}\", data); // \"1 + 2 + 3\"\nrender(\"{{ join(guests, \\\", \\\") }}\", data); // \"Jeff, Patrick, Tom\"\n\n// Round numbers to a given precision\nrender(\"{{ round(3.1415, 0) }}\", data); // 3\nrender(\"{{ round(3.1415, 3) }}\", data); // 3.142\n\n// Check if a value is odd, even or divisible by a number\nrender(\"{{ odd(42) }}\", data); // false\nrender(\"{{ even(42) }}\", data); // true\nrender(\"{{ divisibleBy(42, 7) }}\", data); // true\n\n// Maximum and minimum values from a list\nrender(\"{{ max([1, 2, 3]) }}\", data); // 3\nrender(\"{{ min([-2.4, -1.2, 4.5]) }}\", data); // -2.4\n\n// Convert strings to numbers\nrender(\"{{ int(\\\"2\\\") == 2 }}\", data); // true\nrender(\"{{ float(\\\"1.8\\\") \u003e 2 }}\", data); // false\n\n// Set default values if variables are not defined\nrender(\"Hello {{ default(neighbour, \\\"my friend\\\") }}!\", data); // \"Hello Peter!\"\nrender(\"Hello {{ default(colleague, \\\"my friend\\\") }}!\", data); // \"Hello my friend!\"\n\n// Access an objects value dynamically\nrender(\"{{ at(time, \\\"start\\\") }} to {{ time.end }}\", data); // \"16 to 22\"\n\n// Check if a key exists in an object\nrender(\"{{ exists(\\\"guests\\\") }}\", data); // \"true\"\nrender(\"{{ exists(\\\"city\\\") }}\", data); // \"false\"\nrender(\"{{ existsIn(time, \\\"start\\\") }}\", data); // \"true\"\nrender(\"{{ existsIn(time, neighbour) }}\", data); // \"false\"\n\n// Check if a key is a specific type\nrender(\"{{ isString(neighbour) }}\", data); // \"true\"\nrender(\"{{ isArray(guests) }}\", data); // \"true\"\n// Implemented type checks: isArray, isBoolean, isFloat, isInteger, isNumber, isObject, isString,\n```\n\n### Callbacks\n\nYou 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.\n```.cpp\nEnvironment env;\n\n/*\n * Callbacks are defined by its:\n * - name,\n * - (optional) number of arguments,\n * - callback function.\n */\nenv.add_callback(\"double\", 1, [](Arguments\u0026 args) {\n\tint number = args.at(0)-\u003eget\u003cint\u003e(); // Adapt the index and type of the argument\n\treturn 2 * number;\n});\n\n// You can then use a callback like a regular function\nenv.render(\"{{ double(16) }}\", data); // \"32\"\n\n// Inja falls back to variadic callbacks if the number of expected arguments is omitted.\nenv.add_callback(\"argmax\", [](Arguments\u0026 args) {\n  auto result = std::max_element(args.begin(), args.end(), [](const json* a, const json* b) { return *a \u003c *b;});\n  return std::distance(args.begin(), result);\n});\nenv.render(\"{{ argmax(4, 2, 6) }}\", data); // \"2\"\nenv.render(\"{{ argmax(0, 2, 6, 8, 3) }}\", data); // \"3\"\n\n// A callback without argument can be used like a dynamic variable:\nstd::string greet = \"Hello\";\nenv.add_callback(\"double-greetings\", 0, [greet](Arguments args) {\n\treturn greet + \" \" + greet + \"!\";\n});\nenv.render(\"{{ double-greetings }}\", data); // \"Hello Hello!\"\n```\nYou can also add a void callback without return variable, e.g. for debugging:\n```.cpp\nenv.add_void_callback(\"log\", 1, [greet](Arguments args) {\n\tstd::cout \u003c\u003c \"logging: \" \u003c\u003c args[0] \u003c\u003c std::endl;\n});\nenv.render(\"{{ log(neighbour) }}\", data); // Prints nothing to result, only to cout...\n```\n\n### Template Inheritance\n\nTemplate 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\n```.html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n  {% block head %}\n  \u003clink rel=\"stylesheet\" href=\"style.css\" /\u003e\n  \u003ctitle\u003e{% block title %}{% endblock %} - My Webpage\u003c/title\u003e\n  {% endblock %}\n\u003c/head\u003e\n\u003cbody\u003e\n  \u003cdiv id=\"content\"\u003e{% block content %}{% endblock %}\u003c/div\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\ncontains three `blocks` that child templates can fill in. The child template\n```.html\n{% extends \"base.html\" %}\n{% block title %}Index{% endblock %}\n{% block head %}\n  {{ super() }}\n  \u003cstyle type=\"text/css\"\u003e\n    .important { color: #336699; }\n  \u003c/style\u003e\n{% endblock %}\n{% block content %}\n  \u003ch1\u003eIndex\u003c/h1\u003e\n  \u003cp class=\"important\"\u003e\n    Welcome to my blog!\n  \u003c/p\u003e\n{% endblock %}\n```\ncalls 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.\n\n### Whitespace Control\n\nIn 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.\n\n```.cpp\nEnvironment env;\nenv.set_trim_blocks(true);\nenv.set_lstrip_blocks(true);\n```\n\nWith 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:\n\n```.cpp\nrender(\"Hello       {{- name -}}     !\", data); // \"Hello Inja!\"\nrender(\"{% if neighbour in guests -%}   I was there{% endif -%}   !\", data); // Renders without any whitespaces\n```\n\nStripping behind a statement or expression also removes any newlines.\n\n### HTML escaping\n\nTemplates are frequently used to creat HTML pages. Source data that contains\ncharacters that have meaning within HTML (like \u003c. \u003e, \u0026) needs to be escaped.\nIt is often inconvenient to perform such escaping within the JSON data. With `Environment::set_html_autoescape(true)`, Inja can be configured to\nHTML escape each and every string created.\n\n### Comments\n\nComments can be written with the `{# ... #}` syntax.\n```.cpp\nrender(\"Hello{# Todo #}!\", data); // \"Hello!\"\n```\n\n### Exceptions\n\nInja 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.\n\n\n## Supported compilers\n\nInja uses the `string_view` feature of the C++17 STL. Currently, the following compilers are tested:\n\n- GCC 8 - 11 (and possibly later)\n- Clang 5 - 12 (and possibly later)\n- Microsoft Visual C++ 2017 15.0 - 2022 (and possibly later)\n\nA list of supported compiler / os versions can be found in the [CI definition](https://github.com/pantor/inja/blob/master/.github/workflows/ci.yml).\n","funding_links":["https://github.com/sponsors/pantor"],"categories":["Miscellaneous","C++","C++ (70)","Templating Engines","Libraries","**Code**"],"sub_categories":["String formatting \u0026 templating"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpantor%2Finja","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpantor%2Finja","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpantor%2Finja/lists"}