IBackend.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
#include <phosphorconfig_export.h>
 
#include <QColor>
#include <QJsonArray>
#include <QJsonDocument>
#include <QJsonObject>
#include <QJsonParseError>
#include <QJsonValue>
#include <QString>
#include <QStringList>
 
#include <memory>
 
namespace PhosphorConfig {
 
class IGroupPathResolver;
struct Schema;
 
class PHOSPHORCONFIG_EXPORT IGroup
{
public:
    virtual ~IGroup() = default;
 
    // Typed reads — return defaultValue when the key is absent, present-but-wrong-type,
    // or otherwise unparseable. Concrete backends document the exact coercion rules.
    virtual QString readString(const QString& key, const QString& defaultValue = {}) const = 0;
    virtual int readInt(const QString& key, int defaultValue = 0) const = 0;
    virtual bool readBool(const QString& key, bool defaultValue = false) const = 0;
    virtual double readDouble(const QString& key, double defaultValue = 0.0) const = 0;
    virtual QColor readColor(const QString& key, const QColor& defaultValue = {}) const = 0;
 
    virtual void writeString(const QString& key, const QString& value) = 0;
    virtual void writeInt(const QString& key, int value) = 0;
    virtual void writeBool(const QString& key, bool value) = 0;
    virtual void writeDouble(const QString& key, double value) = 0;
    virtual void writeColor(const QString& key, const QColor& value) = 0;
 
    virtual void writeJson(const QString& key, const QJsonValue& value)
    {
        // QJsonDocument only accepts arrays/objects at the root. For scalar
        // values (including strings, so writeJson/readJson round-trip
        // correctly via a single uniform encoding) wrap in a one-element
        // array and strip the brackets; for arrays/objects emit the compact
        // form directly.
        if (value.isArray()) {
            writeString(key, QString::fromUtf8(QJsonDocument(value.toArray()).toJson(QJsonDocument::Compact)));
            return;
        }
        if (value.isObject()) {
            writeString(key, QString::fromUtf8(QJsonDocument(value.toObject()).toJson(QJsonDocument::Compact)));
            return;
        }
        QJsonArray wrapped;
        wrapped.append(value);
        const QByteArray raw = QJsonDocument(wrapped).toJson(QJsonDocument::Compact);
        writeString(key, QString::fromUtf8(raw.mid(1, raw.size() - 2)));
    }
 
    virtual QJsonValue readJson(const QString& key, const QJsonValue& defaultValue = {}) const
    {
        if (!hasKey(key)) {
            return defaultValue;
        }
        const QString raw = readString(key);
        // Wrap so QJsonDocument::fromJson accepts bare scalars.
        const QByteArray wrapped = QByteArray("[") + raw.toUtf8() + QByteArray("]");
        QJsonParseError err;
        const QJsonDocument doc = QJsonDocument::fromJson(wrapped, &err);
        if (err.error != QJsonParseError::NoError) {
            return defaultValue;
        }
        const QJsonArray arr = doc.array();
        if (arr.size() != 1) {
            return defaultValue;
        }
        return arr.at(0);
    }
 
    // Key management.
    virtual bool hasKey(const QString& key) const = 0;
    virtual void deleteKey(const QString& key) = 0;
 
    virtual QStringList keyList() const = 0;
 
    IGroup(const IGroup&) = delete;
    IGroup& operator=(const IGroup&) = delete;
 
protected:
    IGroup() = default;
};
 
class PHOSPHORCONFIG_EXPORT IBackend
{
public:
    virtual ~IBackend() = default;
 
    virtual std::unique_ptr<IGroup> group(const QString& name) = 0;
 
    virtual void reparseConfiguration() = 0;
 
    virtual bool sync() = 0;
 
    virtual void deleteGroup(const QString& name) = 0;
 
    virtual QString readRootString(const QString& key, const QString& defaultValue = {}) const = 0;
    virtual void writeRootString(const QString& key, const QString& value) = 0;
    virtual void removeRootKey(const QString& key) = 0;
 
    virtual QStringList groupList() const = 0;
 
    // ── Schema-aware hooks (default no-op) ────────────────────────────────
    // Store consults these to wire a schema's resolver, version stamp, and
    // migration chain into the backend. Backends without a JSON-root concept
    // (QSettingsBackend) inherit the default no-ops; JsonBackend overrides.
    // Keeping the hooks on IBackend lets Store work against the polymorphic
    // interface instead of a dynamic_cast, and lets a future backend opt in
    // to schema participation by providing its own overrides.
 
    virtual void setPathResolver(std::shared_ptr<IGroupPathResolver>)
    {
    }
    virtual std::shared_ptr<IGroupPathResolver> pathResolver() const
    {
        return nullptr;
    }
 
    virtual void setVersionStamp(const QString&, int)
    {
    }
    virtual std::pair<QString, int> versionStamp() const
    {
        return {};
    }
 
    virtual bool applyMigration(const Schema&)
    {
        return false;
    }
 
    IBackend(const IBackend&) = delete;
    IBackend& operator=(const IBackend&) = delete;
 
protected:
    IBackend() = default;
};
 
} // namespace PhosphorConfig