Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorConfig::Store Class Reference

High-level declarative configuration facade. More...

#include <PhosphorConfig/Store.h>

Inheritance diagram for PhosphorConfig::Store:
[legend]

Signals

void changed (const QString &group, const QString &key)
 Emitted after any successful write() or reset() operation.

Public Member Functions

 Store (IBackend *backend, Schema schema, QObject *parent=nullptr)
 Construct a store that borrows backend and applies schema.
 ~Store () override
template<typename T>
T read (const QString &group, const QString &key) const
 Read a declared key.
QVariant readVariant (const QString &group, const QString &key) const
 Read as QVariant.
bool hasExplicitValue (const QString &group, const QString &key) const
 Whether key is physically stored, as opposed to being served from the schema default.
void write (const QString &group, const QString &key, const QVariant &value)
 Write a value.
void reset (const QString &group, const QString &key)
 Reset one key to its schema default.
void resetGroup (const QString &group)
 Reset every key declared in group.
void resetAll ()
 Reset every declared key in every declared group. Extras are untouched.
QJsonObject exportToJson () const
 Produce a JSON snapshot of every declared key's current value.
QJsonObject defaultsToJson () const
 Produce a JSON snapshot of every declared key's SCHEMA DEFAULT, independent of current values.
bool importFromJson (const QJsonObject &snapshot)
 Overwrite declared keys from snapshot.
bool sync ()
 Flush the underlying backend.
bool commit ()
 Durable flush: the backend's commit(), which never defers.
IBackend * backend () const
 Direct access for callers that still need the backend (e.g.
const Schema & schema () const
 The schema the store was constructed with.
template<>
PHOSPHORCONFIG_EXPORT QString read (const QString &, const QString &) const
template<>
PHOSPHORCONFIG_EXPORT int read (const QString &, const QString &) const
template<>
PHOSPHORCONFIG_EXPORT bool read (const QString &, const QString &) const
template<>
PHOSPHORCONFIG_EXPORT double read (const QString &, const QString &) const
template<>
PHOSPHORCONFIG_EXPORT QColor read (const QString &, const QString &) const
template<>
PHOSPHORCONFIG_EXPORT QVariantMap read (const QString &, const QString &) const
template<>
PHOSPHORCONFIG_EXPORT QVariantList read (const QString &, const QString &) const

Detailed Description

High-level declarative configuration facade.

Wraps an IBackend with a Schema so consumers get:

  • Automatic default fallback on reads (from the schema, no re-declared defaults at call sites)
  • reset() / resetGroup() / resetAll() operations, no hand-written switch statements
  • exportToJson() / importFromJson() for backup, dotfile sync, and settings-panel "export"
  • Automatic schema-version stamping and migration-runner execution on construction
  • A uniform changed() signal that consumers can wire directly to UI updates
const QString window = QStringLiteral("Window");
const QString width = QStringLiteral("Width");
schema.version = 1;
schema.groups[window] = {
{width, 600, QMetaType::Int},
{QStringLiteral("Height"), 400, QMetaType::Int},
{QStringLiteral("Title"), QStringLiteral("Hello"), QMetaType::QString},
};
// The store borrows the backend, so declare the backend first: it is
// then destroyed after the store.
auto backend = std::make_unique<JsonBackend>(configPath);
Store store(backend.get(), schema);
int w = store.read<int>(window, width); // 600 while unset
store.write(window, width, 800);
store.reset(window, width); // back to 600
IBackend * backend() const
Direct access for callers that still need the backend (e.g.
Store(IBackend *backend, Schema schema, QObject *parent=nullptr)
Construct a store that borrows backend and applies schema.
const Schema & schema() const
The schema the store was constructed with.
Declarative description of a configuration store.
Definition Schema.h:127

Constructor & Destructor Documentation

◆ Store()

PhosphorConfig::Store::Store ( IBackend * backend,
Schema schema,
QObject * parent = nullptr )

Construct a store that borrows backend and applies schema.

The backend must outlive the store — typically owned by the caller via std::unique_ptr in a containing class. On entry the version stamp is DECLARED to the backend first and the schema's migration chain runs second; the declared stamp only reaches the on-disk root when the migration did not write one (JsonBackend only).

◆ ~Store()

PhosphorConfig::Store::~Store ( )
override

Member Function Documentation

◆ backend()

IBackend * PhosphorConfig::Store::backend ( ) const

Direct access for callers that still need the backend (e.g.

to read an undeclared key or to call groupList()).

◆ changed

void PhosphorConfig::Store::changed ( const QString & group,
const QString & key )
signal

Emitted after any successful write() or reset() operation.

Connect to refresh dependent UI.

◆ commit()

bool PhosphorConfig::Store::commit ( )

Durable flush: the backend's commit(), which never defers.

true means the bytes landed (or nothing needed writing).

◆ defaultsToJson()

QJsonObject PhosphorConfig::Store::defaultsToJson ( ) const

Produce a JSON snapshot of every declared key's SCHEMA DEFAULT, independent of current values.

Stamped with the same version key as exportToJson, so the two snapshots are field-for-field comparable — which is what a "diff my settings against the defaults" feature needs.

◆ exportToJson()

QJsonObject PhosphorConfig::Store::exportToJson ( ) const

Produce a JSON snapshot of every declared key's current value.

Useful for "export settings" UIs and dotfile sync. Keys absent from the backing store are emitted with their schema default. The values are the ones reads observe, so a JsonBackend overlay is included.

◆ hasExplicitValue()

bool PhosphorConfig::Store::hasExplicitValue ( const QString & group,
const QString & key ) const

Whether key is physically stored, as opposed to being served from the schema default.

read and readVariant deliberately substitute the schema default for an absent key, which makes "the user chose this value" and "the user has never touched this" indistinguishable at those accessors. Some callers need that distinction — a layer that should only outrank another once the user has actually expressed an intent, for instance. This is the only way to ask.

Note what sparse persistence costs here: a default-equal write deletes the key, so a user who sets a value to exactly the shipped default reads back as unset. The predicate is therefore "differs from the shipped default", not "was never edited". Returns false for an undeclared key.

◆ importFromJson()

bool PhosphorConfig::Store::importFromJson ( const QJsonObject & snapshot)

Overwrite declared keys from snapshot.

Unknown groups/keys in snapshot are ignored (silently — no adaptive migration). Use MigrationRunner first if snapshot came from an older schema.

Keys declared in the schema but ABSENT from snapshot are also skipped — importFromJson is strictly additive / overwriting, never subtractive. For a full "restore defaults from snapshot" workflow, call resetAll() before importFromJson so absent keys land at their schema defaults.

Returns
true on a successful import; false when the snapshot is rejected (version mismatch, malformed version key). On a false return no keys are written. Callers should propagate the result so settings-panel UIs can distinguish "import succeeded" from "import refused" instead of relying on log scraping.

◆ read() [1/8]

template<>
PHOSPHORCONFIG_EXPORT QVariantList PhosphorConfig::Store::read ( const QString & ,
const QString &  ) const

◆ read() [2/8]

template<>
PHOSPHORCONFIG_EXPORT QVariantMap PhosphorConfig::Store::read ( const QString & ,
const QString &  ) const

◆ read() [3/8]

template<>
PHOSPHORCONFIG_EXPORT QColor PhosphorConfig::Store::read ( const QString & ,
const QString &  ) const

◆ read() [4/8]

template<>
PHOSPHORCONFIG_EXPORT double PhosphorConfig::Store::read ( const QString & ,
const QString &  ) const

◆ read() [5/8]

template<>
PHOSPHORCONFIG_EXPORT bool PhosphorConfig::Store::read ( const QString & ,
const QString &  ) const

◆ read() [6/8]

template<>
PHOSPHORCONFIG_EXPORT int PhosphorConfig::Store::read ( const QString & ,
const QString &  ) const

◆ read() [7/8]

template<>
PHOSPHORCONFIG_EXPORT QString PhosphorConfig::Store::read ( const QString & ,
const QString &  ) const

◆ read() [8/8]

template<typename T>
T PhosphorConfig::Store::read ( const QString & group,
const QString & key ) const
inline

Read a declared key.

  • If the key is ABSENT, returns the schema default.
  • If the key is PRESENT but unparseable as T:
    • For scalar types (QString, int, bool, double, QColor) returns the schema default.
    • For QVariantMap and QVariantList, returns an EMPTY collection (not the schema default). This intentional asymmetry lets the Settings layer distinguish "user has never written this blob" (returns the schema default — populated value) from "blob is corrupt" (returns empty — caller substitutes library/project defaults instead of stamping the schema default back over corrupt user data).
  • Undeclared keys always return QVariant() — effectively T{}.

The primary template is intentionally a static_assert trap: Store::read<T> is only fully specialized for the types listed below, and instantiating it with anything else should fail at compile time with a clear message rather than at link time with an opaque "undefined reference" error.

◆ readVariant()

QVariant PhosphorConfig::Store::readVariant ( const QString & group,
const QString & key ) const

Read as QVariant.

Dispatches on the declared expectedType for the known kinds (bool, the integer widths, double, QString, QColor, QStringList, QVariantMap/List). Any OTHER type round-trips as a QString: the write side stringifies it and this read returns the string, so an exotic-typed key (QDateTime, QPoint, …) changes type across the round trip. Undeclared keys return QVariant().

◆ reset()

void PhosphorConfig::Store::reset ( const QString & group,
const QString & key )

Reset one key to its schema default.

No-op when the key is undeclared.

Only emits changed when the key was actually present in the backing store — a reset on a never-written key is a no-op that skips the changed() emission, since the read path already returned the schema default and no observer would see a change. Callers relying on reset() to force a QML rebinding on a pristine key should re-read via read and emit their own signal instead.

◆ resetAll()

void PhosphorConfig::Store::resetAll ( )

Reset every declared key in every declared group. Extras are untouched.

◆ resetGroup()

void PhosphorConfig::Store::resetGroup ( const QString & group)

Reset every key declared in group.

Undeclared extras are left alone. Same semantics as reset() per key: a stored key is DELETED (sparse persistence), an absent key is skipped without dirtying the backend, and one changed per actually-deleted key is emitted after the group handle is released.

◆ schema()

const Schema & PhosphorConfig::Store::schema ( ) const

The schema the store was constructed with.

◆ sync()

bool PhosphorConfig::Store::sync ( )

Flush the underlying backend.

Mirrors IBackend::sync(): true means ACCEPTED, not committed — a backend may satisfy it by scheduling the write. Never advance a baseline or report success to a user off this result; use commit() for a durable answer.

◆ write()

void PhosphorConfig::Store::write ( const QString & group,
const QString & key,
const QVariant & value )

Write a value.

If the schema declares an expectedType for this key and value has a different typeId, a warning is logged but the write proceeds (Qt will coerce on read back). Emits changed when the observable value moves.

Persistence is SPARSE: a value equal to the schema default is stored as key ABSENCE (an existing key is deleted), so a stored file never freezes a default. The read path answers absence with the schema default, making the two indistinguishable to consumers — and letting a later default retune reach every store that has no explicit value.

Over a backend with a read-only layer (JsonBackend::setOverlay), reads see the layer but write, reset, resetGroup and importFromJson decide against what is persisted (IBackend::persistedGroup). A value equal to the layer's is still written, and changed reports the persisted change even while the layer keeps the value reads observe where it was.


The documentation for this class was generated from the following file:
  • phosphor-config/include/PhosphorConfig/Store.h