Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
TemplateEngine.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3#pragma once
4
5#include <PhosphorTheme/phosphortheme_export.h>
6
7#include <QString>
8#include <QVariantMap>
9#include <QtQmlIntegration/qqmlintegration.h>
10
11namespace PhosphorTheme {
12
13// Minimal mustache-style template engine for the matugen fan-out pipeline.
14//
15// Templates contain `{{token}}` placeholders that resolve to color values
16// from a `token name -> QColor` map. A dot-suffix selects a representation:
17//
18// {{primary}} -> "#RRGGBB" (default = hex form)
19// {{primary.hex}} -> "#RRGGBB"
20// {{primary.hexa}} -> "#RRGGBBAA"
21// {{primary.r}} -> integer 0-255 (also: .red)
22// {{primary.g}} -> integer 0-255 (also: .green)
23// {{primary.b}} -> integer 0-255 (also: .blue)
24// {{primary.alpha}} -> "1.0" / "0.50" / etc (3 decimal places)
25// {{primary.rgb}} -> "R, G, B"
26// {{primary.rgba}} -> "R, G, B, A.AAA"
27//
28// Unknown tokens are left untouched as `{{token}}` in the output and emit
29// a warning on stderr, silent omission would hide rename mistakes.
30//
31// Unknown FIELDS behave differently. A typo'd suffix on a known token,
32// say `{{primary.hax}}`, degrades to the default hex form and logs a
33// warning. The asymmetry is intentional. A missing color is a structural
34// failure that needs to surface visibly in the rendered file. A typo'd
35// field on a valid color is recoverable with a sensible fallback. The
36// fallback also avoids leaking a literal `{{primary.hax}}` into config
37// files that downstream parsers like CSS or GTK treat as a hard error.
38//
39// This is NOT full mustache: no sections, partials, or escape handling.
40// Phosphor fan-out templates do simple substitution; sections / loops
41// would complicate the renderer and the templates without buying clarity.
42// If a downstream template needs real mustache, render it with the
43// external `mustache` CLI from a different stage of the pipeline.
44class PHOSPHORTHEME_EXPORT TemplateEngine
45{
46 Q_GADGET
47 QML_VALUE_TYPE(templateEngine)
48
49public:
50 // Render `templateSource` against `tokens`. Returns the substituted
51 // string. Missing tokens log a warning and leave the placeholder
52 // intact.
53 [[nodiscard]] static QString render(const QString& templateSource, const QVariantMap& tokens);
54
55 // Convenience: read template from disk, render, write to outPath.
56 // Returns true on success, false on any IO failure (rendering never
57 // fails). Logs a warning on either failure path.
58 static bool renderFile(const QString& templatePath, const QString& outPath, const QVariantMap& tokens);
59};
60
61} // namespace PhosphorTheme
Definition TemplateEngine.h:45
static QString render(const QString &templateSource, const QVariantMap &tokens)
static bool renderFile(const QString &templatePath, const QString &outPath, const QVariantMap &tokens)
Definition AppearanceLibrary.h:10