Jinja2Cpp

by jinja2cpp

jinja2cpp / Jinja2Cpp

Jinja2 C++ (and for C++) almost full-conformance template engine implementation

236 Stars 39 Forks Last release: 9 months ago (1.1.0) Mozilla Public License 2.0 313 Commits 8 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Jinja2С++

Language Standard Coverage Status Codacy Badge Github Releases Github Issues GitHub License conan.io Gitter Chat

C++ implementation of the Jinja2 Python template engine. This library brings support of powerful Jinja2 template features into the C++ world, reports dynamic HTML pages and source code generation.

Introduction

Main features of Jinja2C++: - Easy-to-use public interface. Just load templates and render them. - Conformance to Jinja2 specification - Full support of narrow- and wide-character strings both for templates and parameters. - Built-in reflection for the common C++ types, nlohmann and rapid JSON libraries. - Powerful full-featured Jinja2 expressions with filtering (via '|' operator) and 'if'-expressions. - Control statements (

set
,
for
,
if
,
filter
,
do
,
with
). - Templates extension, including and importing - Macros - Rich error reporting. - Shared template environment with templates cache support

For instance, this simple code:

#include 

std::string source = R"( {{ ("Hello", 'world') | join }}!!! {{ ("Hello", 'world') | join(', ') }}!!! {{ ("Hello", 'world') | join(d = '; ') }}!!! {{ ("Hello", 'world') | join(d = '; ') | lower }}!!! )";

Template tpl; tpl.Load(source);

std::string result = tpl.RenderAsString({}).value();

produces the result string:

Helloworld!!!
Hello, world!!!
Hello; world!!!
hello; world!!!

Getting started

To use Jinja2C++ in your project you have to: * Clone the Jinja2C++ repository * Build it according to the instructions * Link to your project.

Usage of Jinja2C++ in the code is pretty simple: 1. Declare the jinja2::Template object:

jinja2::Template tpl;
  1. Populate it with template:
tpl.Load("{{ 'Hello World' }}!!!");
  1. Render the template:
std::cout << tpl.RenderAsString({}).value() << std::endl;

and get:

Hello World!!!

That's all!

More detailed examples and features description can be found in the documentation: https://jinja2cpp.dev/docs/usage

Current Jinja2 support

Currently, Jinja2C++ supports the limited number of Jinja2 features. By the way, Jinja2C++ is planned to be a full jinja2 specification-conformant. The current support is limited to: - expressions. You can use almost every expression style: simple, filtered, conditional, and so on. - the big number of filters (sort, default, first, last, length, max, min, reverse, unique, sum, attr, map, reject, rejectattr, select, selectattr, pprint, dictsort, abs, float, int, list, round, random, trim, title, upper, wordcount, replace, truncate, groupby, urlencode, capitalize, escape, tojson, striptags, center, xmlattr) - the big number of testers (eq, defined, ge, gt, iterable, le, lt, mapping, ne, number, sequence, string, undefined, in, even, odd, lower, upper) - the number of functions (range, loop.cycle) - 'if' statement (with 'elif' and 'else' branches) - 'for' statement (with 'else' branch and 'if' part support) - 'include' statement - 'import'/'from' statements - 'set' statement (both line and block) - 'filter' statement - 'extends'/'block' statements - 'macro'/'call' statements - 'with' statement - 'do' extension statement - recursive loops - space control and 'raw'/'endraw' blocks

Full information about Jinja2 specification support and compatibility table can be found here: https://jinja2cpp.dev/docs/j2_compatibility.html.

Supported compilers

Compilation of Jinja2C++ tested on the following compilers (with C++14 and C++17 enabled features): - Linux gcc 5.5 - 9.0 - Linux clang 5.0 - 9 - MacOS X-Code 9 - MacOS X-Code 10 - MacOS X-Code 11 (C++14 in default build, C++17 with externally-provided boost) - Microsoft Visual Studio 2015 - 2019 x86, x64 - MinGW gcc compiler 7.3 - MinGW gcc compiler 8.1

Note: Support of gcc version >= 9.x or clang version >= 8.0 depends on the version of the Boost library provided.

Build status

| Compiler | Status | |---------|---------:| | MSVC 2015 (x86, x64), MinGW 7 (x64), MinGW 8 (x64) | Build status | | X-Code 9, 10, 11 | Build Status | | MSVC 2017 (x86, x64), MSVC 2019 (x86, x64), C++14/C++17 | | | g++ 5, 6, 7, 8, 9, clang 5, 6, 7, 8 C++14/C++17 | |

Build and install

Jinja2C++ has several external dependencies: -

boost
library (at least version 1.65) -
nonstd::expected-lite
https://github.com/martinmoene/expected-lite -
nonstd::variant-lite
https://github.com/martinmoene/variant-lite -
nonstd::optional-lite
https://github.com/martinmoene/optional-lite -
nonstd::string-view-lite
https://github.com/martinmoene/string-view-lite -
fmtlib::fmt
https://github.com/fmtlib/fmt

Examples of build scripts and different build configurations can be found here: https://github.com/jinja2cpp/examples-build

In simplest case to compile Jinja2C++ you need:

  1. Install CMake build system (at least version 3.0)
  2. Clone jinja2cpp repository:
> git clone https://github.com/flexferrum/Jinja2Cpp.git
  1. Create build directory:
> cd Jinja2Cpp
> mkdir build
  1. Run CMake and build the library:
> cd build
> cmake .. -DCMAKE_INSTALL_PREFIX=
> cmake --build . --target all

"Path to install folder" here is a path to the folder where you want to install Jinja2C++ lib.

  1. Install library:
> cmake --build . --target install

In this case, Jinja2C++ will be built with internally-shipped dependencies and install them respectively. But Jinja2C++ supports build with externally-provided deps.

Usage with conan.io dependency manager

Jinja2C++ can be used as conan.io package. In this case, you should do the following steps:

  1. Install conan.io according to the documentation ( https://docs.conan.io/en/latest/installation.html )
  2. Add a reference to Jinja2C++ package (
    jinja2cpp/1.1.0
    ) to your conanfile.txt, conanfile.py or CMakeLists.txt. For instance, with the usage of
    conan-cmake
    integration it could be written this way:
include (../../cmake/conan.cmake)
if (NOT MSVC)
    set (CONAN_SETTINGS SETTINGS compiler.libcxx=libstdc++11)
endif ()

conan_cmake_run(REQUIRES jinja2cpp/1.1.0 gtest/[email protected]/stable BASIC_SETUP ${CONAN_SETTINGS} OPTIONS jinja2cpp:shared=False gtest:shared=False BUILD missing)

set (TARGET_NAME jinja2cpp_build_test)

add_executable (${TARGET_NAME} main.cpp)

target_link_libraries (${TARGET_NAME} ${CONAN_LIBS}) set_target_properties (${TARGET_NAME} PROPERTIES CXX_STANDARD 14 CXX_STANDARD_REQUIRED ON)

Additional CMake build flags

You can define (via -D command-line CMake option) the following build flags:

  • JINJA2CPPBUILDTESTS (default TRUE) - to build or not to Jinja2C++ tests.
  • JINJA2CPPSTRICTWARNINGS (default TRUE) - Enable strict mode compile-warnings(-Wall -Werror, etc).
  • JINJA2CPPMSVCRUNTIME_TYPE (default /MD) - MSVC runtime type to link with (if you use Microsoft Visual Studio compiler).
  • JINJA2CPPDEPSMODE (default "internal") - modes for dependency handling. Following values possible:
    • internal
      In this mode Jinja2C++ build script uses dependencies (include
      boost
      ) shipped as subprojects. Nothing needs to be provided externally.
    • external-boost
      In this mode Jinja2C++ build script uses only
      boost
      as an externally-provided dependency. All other dependencies are taken from subprojects.
    • external
      In this mode all dependencies should be provided externally. Paths to
      boost
      ,
      nonstd-*
      libs, etc. should be specified via standard CMake variables (like
      CMAKE_PREFIX_PATH
      or libname_DIR)
    • conan-build
      Special mode for building Jinja2C++ via conan recipe.

Build with C++17 standard enabled

Jinja2C++ try to use standard versions of

std::variant
,
std::string_view
and
std::optional
if possible.

Acknowledgments

Thanks to @manu343726 for CMake scripts improvement, bug hunting, and fixing and conan.io packaging.

Thanks to @martinmoene for the perfectly implemented xxx-lite libraries.

Thanks to @vitaut for the amazing text formatting library.

Thanks to @martinus for the fast hash maps implementation.

Changelog

Version 1.1.0

Changes and improvements

  • batch
    filter added
  • slice
    filter added
  • format
    filter added
  • tojson
    filter added
  • striptags
    filter added
  • center
    filter added
  • xmlattr
    filter added
  • raw
    /
    endraw
    tags added
  • repeat string operator added (e. g.
    'a' * 5
    will produce
    'aaaaa'
    )
  • support for templates metadata (
    meta
    /
    endmeta
    tags) added
  • -fPIC
    flag added to Linux build configuration

Fixed bugs

  • Fix behavior of lstripblock/trimblocks global settings. Now it fully corresponds to the origina jinja2
  • Fix bug with rendering parent
    block
    content if child doesn't override this block
  • Fix compilation issues with user-defined callables with number of arguments more than 2
  • Fix access to global Jinja2 functions from included/extended templates
  • Fix point of evaluation of macro params
  • Fix looping over the strings
  • Cleanup warnings

Breaking changes

  • From now with C++17 standard enabled Jinja2C++ uses standard versions of types
    variant
    ,
    string_view
    and
    optional

Version 1.0.0

Changes and improvements

  • default
    attribute added to the
    map
    filter (#48)
  • escape sequences support added to the string literals (#49)
  • arbitrary ranges, generated sequences, input iterators, etc. now can be used with
    GenericList
    type (#66)
  • nonstd::string_view is now one of the possible types for the
    Value
  • filter
    tag support added to the template parser (#44)
  • escape
    filter support added to the template parser (#140)
  • capitalize
    filter support added to the template parser (#137)
  • the multiline version of
    set
    tag added to the parser (#45)
  • added built-in reflection for nlohmann JSON and RapidJSON libraries (#78)
  • loop.depth
    and
    loop.depth0
    variables support added
  • {fmt} is now used as a formatting library instead of iostreams
  • robin hood hash map is now used for internal value storage
  • rendering performance improvements
  • template cache implemented in
    TemplateEnv
  • user-defined callables now can accept global context via
    *context
    special param
  • MinGW, clang >= 7.0, XCode >= 9, gcc >= 7.0 are now officially supported as a target compilers (#79)

Fixed bugs

  • Fixed pipe (
    |
    ) operator precedence (#47)
  • Fixed bug in internal char <-> wchar_t converter on Windows
  • Fixed crash in parsing
    endblock
    tag
  • Fixed scope control for
    include
    and
    for
    tags
  • Fixed bug with macros call within expression context

Breaking changes

  • MSVC runtime type is now defined by
    JINJA2CPP_MSVC_RUNTIME_TYPE
    CMake variable

Version 0.9.2

Major changes

  • User-defined callables implemented. Now you can define your own callable objects, pass them as input parameters and use them inside templates as regular (global) functions, filters or testers. See details here: https://jinja2cpp.dev/docs/usage/ud_callables.html
  • Now you can define global (template environment-wide) parameters that are accessible for all templates bound to this environment.
  • include
    ,
    import
    and
    from
    statements implemented. Now it's possible to include other templates and use macros from other templates.
  • with
    statement implemented
  • do
    statement implemented
  • Sample build projects for various Jinja2C++ usage variants created: https://github.com/jinja2cpp/examples-build](https://github.com/jinja2cpp/examples-build)
  • Documentation site created for Jinja2C++: https://jinja2cpp.dev/

Minor changes

  • Render-time error handling added
  • Dependency management mode added to the build script
  • Fix bugs with error reporting during the parse time
  • Upgraded versions of external dependencies

Breaking changes

  • RenderAsString
    method now returns
    nonstd::expected
    instead of regular
    std::string
  • Templates with
    import
    ,
    extends
    and
    include
    generate errors if parsed without
    TemplateEnv
    set
  • Release bundles (archives) are configured with
    external
    dependency management mode by default

Version 0.9.1

  • applymacro
    filter added which allows applying arbitrary macro as a filter
  • dependencies to boost removed from the public interface
  • CMake scripts improved
  • Various bugs fixed
  • Improve reflection
  • Warnings cleanup

Version 0.9

  • Support of 'extents'/'block' statements
  • Support of 'macro'/'call' statements
  • Rich error reporting
  • Support for recursive loops
  • Support for space control before and after control blocks
  • Improve reflection

Version 0.6

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.