Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
IBackend.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3
4#pragma once
5
6#include "phosphorconfig_export.h"
7
8#include <QColor>
9#include <QJsonArray>
10#include <QJsonDocument>
11#include <QJsonObject>
12#include <QJsonParseError>
13#include <QJsonValue>
14#include <QString>
15#include <QStringList>
16
17#include <memory>
18
19namespace PhosphorConfig {
20
22struct Schema;
23
37class PHOSPHORCONFIG_EXPORT IGroup
38{
39public:
40 virtual ~IGroup() = default;
41
42 // Typed reads — return defaultValue when the key is absent, present-but-wrong-type,
43 // or otherwise unparseable. Concrete backends document the exact coercion rules.
44 virtual QString readString(const QString& key, const QString& defaultValue = {}) const = 0;
45 virtual int readInt(const QString& key, int defaultValue = 0) const = 0;
46 virtual bool readBool(const QString& key, bool defaultValue = false) const = 0;
47 virtual double readDouble(const QString& key, double defaultValue = 0.0) const = 0;
48 virtual QColor readColor(const QString& key, const QColor& defaultValue = {}) const = 0;
49
56 virtual void writeString(const QString& key, const QString& value) = 0;
57 virtual void writeInt(const QString& key, int value) = 0;
58 virtual void writeBool(const QString& key, bool value) = 0;
59 virtual void writeDouble(const QString& key, double value) = 0;
60 virtual void writeColor(const QString& key, const QColor& value) = 0;
61
72 virtual void writeJson(const QString& key, const QJsonValue& value)
73 {
74 // QJsonDocument only accepts arrays/objects at the root. For scalar
75 // values (including strings, so writeJson/readJson round-trip
76 // correctly via a single uniform encoding) wrap in a one-element
77 // array and strip the brackets; for arrays/objects emit the compact
78 // form directly.
79 if (value.isArray()) {
80 writeString(key, QString::fromUtf8(QJsonDocument(value.toArray()).toJson(QJsonDocument::Compact)));
81 return;
82 }
83 if (value.isObject()) {
84 writeString(key, QString::fromUtf8(QJsonDocument(value.toObject()).toJson(QJsonDocument::Compact)));
85 return;
86 }
87 QJsonArray wrapped;
88 wrapped.append(value);
89 const QByteArray raw = QJsonDocument(wrapped).toJson(QJsonDocument::Compact);
90 writeString(key, QString::fromUtf8(raw.mid(1, raw.size() - 2)));
91 }
92
101 virtual QJsonValue readJson(const QString& key, const QJsonValue& defaultValue = {}) const
102 {
103 if (!hasKey(key)) {
104 return defaultValue;
105 }
106 const QString raw = readString(key);
107 // Wrap so QJsonDocument::fromJson accepts bare scalars.
108 const QByteArray wrapped = QByteArray("[") + raw.toUtf8() + QByteArray("]");
109 QJsonParseError err;
110 const QJsonDocument doc = QJsonDocument::fromJson(wrapped, &err);
111 if (err.error != QJsonParseError::NoError) {
112 return defaultValue;
113 }
114 const QJsonArray arr = doc.array();
115 if (arr.size() != 1) {
116 return defaultValue;
117 }
118 return arr.at(0);
119 }
120
121 // Key management.
122 virtual bool hasKey(const QString& key) const = 0;
123 virtual void deleteKey(const QString& key) = 0;
124
129 virtual QStringList keyList() const = 0;
130
131 IGroup(const IGroup&) = delete;
132 IGroup& operator=(const IGroup&) = delete;
133
134protected:
135 IGroup() = default;
136};
137
150class PHOSPHORCONFIG_EXPORT IBackend
151{
152public:
153 virtual ~IBackend() = default;
154
157 virtual std::unique_ptr<IGroup> group(const QString& name) = 0;
158
169 virtual std::unique_ptr<IGroup> persistedGroup(const QString& name)
170 {
171 return group(name);
172 }
173
179 virtual bool isDirty() const
180 {
181 return true;
182 }
183
194 virtual void reparseConfiguration() = 0;
195
206 virtual bool loadFailed() const
207 {
208 return false;
209 }
210
221 virtual bool sync() = 0;
222
233 virtual bool commit()
234 {
235 return sync();
236 }
237
240 virtual void deleteGroup(const QString& name) = 0;
241
243 virtual QString readRootString(const QString& key, const QString& defaultValue = {}) const = 0;
244 virtual void writeRootString(const QString& key, const QString& value) = 0;
245 virtual void removeRootKey(const QString& key) = 0;
246
268 virtual QStringList groupList() const = 0;
269
270 // ── Schema-aware hooks (default no-op) ────────────────────────────────
271 // Store consults these to wire a schema's resolver, version stamp, and
272 // migration chain into the backend. Backends without a JSON-root concept
273 // (in-memory test mocks) inherit the default no-ops; JsonBackend overrides.
274 // Keeping the hooks on IBackend lets Store work against the polymorphic
275 // interface instead of a dynamic_cast, and lets a future backend opt in
276 // to schema participation by providing its own overrides.
277
282 virtual void setPathResolver(std::shared_ptr<IGroupPathResolver>)
283 {
284 }
285
287 virtual std::shared_ptr<IGroupPathResolver> pathResolver() const
288 {
289 return nullptr;
290 }
291
296 virtual void setVersionStamp(const QString&, int)
297 {
298 }
299
302 virtual std::pair<QString, int> versionStamp() const
303 {
304 return {};
305 }
306
315 virtual bool applyMigration(const Schema&)
316 {
317 return false;
318 }
319
320 IBackend(const IBackend&) = delete;
321 IBackend& operator=(const IBackend&) = delete;
322
323protected:
324 IBackend() = default;
325};
326
327} // namespace PhosphorConfig
virtual void setVersionStamp(const QString &, int)
Install a "stamp on first sync" version annotation: if key is absent from the backend's root on the n...
Definition IBackend.h:296
virtual ~IBackend()=default
virtual bool isDirty() const
Whether the in-memory document carries changes not yet committed to disk.
Definition IBackend.h:179
virtual bool sync()=0
Request that pending writes reach disk.
virtual void removeRootKey(const QString &key)=0
virtual bool loadFailed() const
Whether the most recent load (construction or reparseConfiguration), or a flush that found the store ...
Definition IBackend.h:206
virtual bool commit()
Flush pending writes to disk NOW and report whether they landed.
Definition IBackend.h:233
virtual std::unique_ptr< IGroup > persistedGroup(const QString &name)
A view of the named group holding only what this backend PERSISTS, without any read-only layer that g...
Definition IBackend.h:169
virtual bool applyMigration(const Schema &)
Apply schema's migration chain against the backend's in-memory state and commit any resulting version...
Definition IBackend.h:315
virtual std::pair< QString, int > versionStamp() const
Currently-installed version stamp as {key, version}.
Definition IBackend.h:302
virtual void deleteGroup(const QString &name)=0
Delete an entire group and everything inside it.
virtual std::unique_ptr< IGroup > group(const QString &name)=0
Return a scoped view into the named group.
IBackend(const IBackend &)=delete
virtual void writeRootString(const QString &key, const QString &value)=0
IBackend & operator=(const IBackend &)=delete
virtual QString readRootString(const QString &key, const QString &defaultValue={}) const =0
Read/write ungrouped (root-level) keys.
virtual void reparseConfiguration()=0
Re-read configuration from disk, discarding any pending in-memory changes.
virtual void setPathResolver(std::shared_ptr< IGroupPathResolver >)
Install a group-path resolver.
Definition IBackend.h:282
virtual QStringList groupList() const =0
Enumerate every top-level group name.
virtual std::shared_ptr< IGroupPathResolver > pathResolver() const
Currently-installed resolver, or nullptr when none is set (also the default for backends that ignore ...
Definition IBackend.h:287
Optional plug-in for custom group name semantics.
Definition IGroupPathResolver.h:30
virtual ~IGroup()=default
virtual QStringList keyList() const =0
Enumerate scalar leaf keys directly under this group.
virtual bool readBool(const QString &key, bool defaultValue=false) const =0
IGroup(const IGroup &)=delete
virtual QJsonValue readJson(const QString &key, const QJsonValue &defaultValue={}) const
Read a structured JSON value.
Definition IBackend.h:101
virtual void writeColor(const QString &key, const QColor &value)=0
virtual QString readString(const QString &key, const QString &defaultValue={}) const =0
virtual int readInt(const QString &key, int defaultValue=0) const =0
virtual void writeJson(const QString &key, const QJsonValue &value)
Write a structured JSON value (array/object/scalar) natively where supported, or as a compact-JSON st...
Definition IBackend.h:72
virtual QColor readColor(const QString &key, const QColor &defaultValue={}) const =0
virtual void deleteKey(const QString &key)=0
virtual void writeBool(const QString &key, bool value)=0
virtual void writeString(const QString &key, const QString &value)=0
Write a string.
virtual double readDouble(const QString &key, double defaultValue=0.0) const =0
virtual void writeDouble(const QString &key, double value)=0
IGroup & operator=(const IGroup &)=delete
virtual bool hasKey(const QString &key) const =0
virtual void writeInt(const QString &key, int value)=0
Definition HostDirectory.h:19
Declarative description of a configuration store.
Definition Schema.h:127