Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
InjaBridge Class Reference

Adapter for converting Qt JSON types to Inja template engine format. More...

#include <injabridge.h>

Collaboration diagram for InjaBridge:

Public Types

using IncludeCallback = std::function<QString(const QString &name)>

Static Public Member Functions

static nlohmann::json toInjaJson (const QJsonValue &value)
 Converts a QJsonValue, value, to nlohmann::json.
static nlohmann::json toInjaJson (const QJsonObject &obj)
 Converts a QJsonObject, obj, to nlohmann::json.
static nlohmann::json toInjaJson (const QJsonArray &array)
 Converts a QJsonArray, array, to nlohmann::json.
static QString render (const QString &templateStr, const QJsonObject &data)
 Renders a template string, templateStr, with provided data.
static QString render (const QString &templateStr, const QJsonObject &data, const IncludeCallback &includeCallback)
 Renders a template string, templateStr, with provided data, using includeCallback to resolve {{% include %}} directives.
static QString renderFile (const QString &templatePath, const QJsonObject &data)
 Renders a template file with provided data.

Detailed Description

Adapter for converting Qt JSON types to Inja template engine format.

InjaBridge provides static methods to convert between Qt's native JSON types (QJsonObject, QJsonArray, QJsonValue) and nlohmann::json, which is the data format expected by the Inja template engine.

This adapter allows QDoc to maintain its Qt-native API while leveraging Inja for template-based documentation generation. All JSON data in QDoc's intermediate representation (IR) uses Qt types, and InjaBridge handles the conversion when rendering templates.

Note
All numbers in QJsonValue are stored as doubles. Whole-number doubles (e.g., 30.0, 2.0) are converted to int64_t so that template output renders them as integers (e.g., "30" not "30.0"). Fractional values pass through as doubles.
Inja and nlohmann::json may report template or data errors. QDoc is built with exceptions disabled ({-fno-exceptions}), so such errors are treated as fatal and will terminate the process. A custom INJA_THROW override in the header ensures that error details (including source location) are logged via qFatal() before termination, rather than calling std::abort() silently.

All render methods register an {escape_html()} callback that templates can invoke to escape HTML special characters ({&}, {<}, {>}, {"}, {'}). This keeps format-specific escaping under template author control rather than baking it into the rendering bridge.

See also
QJsonObject, QJsonArray, QJsonValue

Definition at line 28 of file injabridge.h.

Member Typedef Documentation

◆ IncludeCallback

using InjaBridge::IncludeCallback = std::function<QString(const QString &name)>

Definition at line 31 of file injabridge.h.

Member Function Documentation

◆ render() [1/2]

QString InjaBridge::render ( const QString & templateStr,
const QJsonObject & data )
static

Renders a template string, templateStr, with provided data.

Uses Inja to render the template with the given JSON data. The data is automatically converted from QJsonObject to nlohmann::json.

The Inja template string, templateStr, supports Jinja2 syntax. data is the JSON data to use for rendering.

Returns the rendered template as a QString.

Definition at line 143 of file injabridge.cpp.

◆ render() [2/2]

QString InjaBridge::render ( const QString & templateStr,
const QJsonObject & data,
const IncludeCallback & includeCallback )
static

Renders a template string, templateStr, with provided data, using includeCallback to resolve {{% include %}} directives.

This overload configures the Inja environment with a custom include callback so that templates can use {{% include "name" %}} directives. The includeCallback receives the include name and returns the partial's content as a QString. If the callback returns an empty string, the include is treated as missing and a fatal error is raised.

This enables Inja's include mechanism to work with Qt's resource system, where {std::ifstream} cannot open {:/} paths.

Returns the rendered template as a QString.

Definition at line 177 of file injabridge.cpp.

◆ renderFile()

QString InjaBridge::renderFile ( const QString & templatePath,
const QJsonObject & data )
static

Renders a template file with provided data.

Loads and renders a template from the filesystem, using templatePath which holds the absolute path to the template file. The file should use Inja/Jinja2 syntax. data is the JSON data to use for rendering.

Returns the rendered template as a QString.

Definition at line 213 of file injabridge.cpp.

◆ toInjaJson() [1/3]

nlohmann::json InjaBridge::toInjaJson ( const QJsonArray & array)
static

Converts a QJsonArray, array, to nlohmann::json.

Recursively converts all elements in the array, preserving order. Mixed-type arrays are supported.

Returns the equivalent nlohmann::json array.

Definition at line 122 of file injabridge.cpp.

◆ toInjaJson() [2/3]

nlohmann::json InjaBridge::toInjaJson ( const QJsonObject & obj)
static

Converts a QJsonObject, obj, to nlohmann::json.

Recursively converts all values in the object, preserving the key-value structure. Nested objects and arrays are handled correctly.

Returns the equivalent nlohmann::json object.

Definition at line 104 of file injabridge.cpp.

◆ toInjaJson() [3/3]

nlohmann::json InjaBridge::toInjaJson ( const QJsonValue & value)
static

Converts a QJsonValue, value, to nlohmann::json.

Handles all QJsonValue types: Null, Bool, Double, String, Array, Object, and Undefined. Undefined values are treated as null.

Returns the equivalent nlohmann::json representation.

Definition at line 71 of file injabridge.cpp.

The documentation for this class was generated from the following files: