Jinja2C++ Documentation

Jinja2C++ is available as a Conan package. You can integrate it into your project by adding jinja2cpp/1.1.0 (or the desired version) to your conanfile.txt or conanfile.py. Below is an example of using conan-cmake integration in a CMakeLists.txt file.

cmake_minimum_required(VERSION 3.24)
project(Jinja2CppSampleConan CXX)

list(APPEND CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR})
list(APPEND CMAKE_PREFIX_PATH ${CMAKE_BINARY_DIR})

add_definitions("-std=c++14")

if(NOT EXISTS "${CMAKE_BINARY_DIR}/conan.cmake")
  file(DOWNLOAD "https://raw.githubusercontent.com/conan-io/cmake-conan/0.18.1/conan.cmake"
                "${CMAKE_BINARY_DIR}/conan.cmake"
                TLS_VERIFY ON)
endif()
include(${CMAKE_BINARY_DIR}/conan.cmake)

conan_cmake_autodetect(settings)
conan_cmake_run(REQUIRES
                    jinja2cpp/1.1.0
                    gtest/1.14.0
                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)

To map custom C++ data types to Jinja2 template values, you can implement interfaces that follow the patterns established by the IndexedListItemAccessorImpl, IndexedListAccessorImpl, and MapAccessorImpl templates. These adapters allow the Jinja2 engine to interact with your native C++ collections (like lists or maps) as if they were native Jinja2 types.

Key Adapter Patterns

1. Indexed Item Access (Single Element Access)

For types that allow accessing an element by an index (e.g., a single object that behaves like a container), implement the logic required by IndexedListItemAccessorImpl. You must provide:

• GetItem(idx): Returns the item at the specified index.
• ItemsCountImpl(): Returns the total number of items.
• GetIndexer(): Returns a pointer to the indexer (usually this).

2. Indexed List Access (Collection Access)

For types representing a collection of items, implement IndexedListAccessorImpl. This provides both index-based access and iteration capabilities. You must provide:

• GetItem(idx): Returns the item at the specified index.
• ItemsCountImpl(): Returns the total number of items.
• CreateListAccessorEnumerator(): Returns an enumerator for iterating over the collection.

3. Map Access (Key-Value Access)

For types representing key-value pairs (like a dictionary or map), implement MapAccessorImpl. You must provide:

• GetItem(name): Returns the value associated with the string key name.

Enumerator Lifecycle

When implementing iterators for these collections, the engine uses an Enumerator pattern. The enumerator supports:

• MoveNext(): Advances the iterator to the next item.
• GetCurrent(): Returns the current value in the iteration.
• Reset(): Resets the iterator to the beginning.
• Clone() / Move(): Allows for duplicating or transferring the state of the iterator.

Jinja2C++ provides support for a wide range of Jinja2 specification features, including:

• Expressions: Simple, filtered, and conditional expressions.
• 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.
• Testers: eq, defined, ge, gt, iterable, le, lt, mapping, ne, number, sequence, string, undefined, in, even, odd, lower, upper.
• Functions: range, loop.cycle.
• Control Statements: if (with elif/else), for (with else/if parts), set (line and block), filter, do (extension), with.
• Template Logic: include, import/from, extends/block, macro/call, recursive loops, space control, and raw/endraw blocks.

The IRendererCallback is an interface used by RenderContext to interact with the rendering engine. Users must implement this interface to provide functionality for string conversion, stream management, template loading, and error handling.

Required Methods:

• GetAsTargetString(const InternalValue& val): Converts an InternalValue into the target string format.
• GetStreamOnString(TargetString& str): Provides an output stream for writing to a string.
• LoadTemplate(const std::string& fileName): Loads a template from a file path. Returns a variant containing either an error or a shared pointer to a TemplateImpl (supporting both char and wchar_t).
• LoadTemplate(const InternalValue& fileName): Overload for loading templates using an InternalValue as the filename.
• ThrowRuntimeError(ErrorCode code, ValuesList extraParams): Handles runtime errors during template execution.