High-level declarative configuration facade. More...

#include <phosphor-config/include/PhosphorConfig/Store.h>

Inheritance diagram for PhosphorConfig::Store:

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`.

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

Schema schema;
schema.version = 1;
schema.groups["Window"] = {
    {QStringLiteral("Width"),  600,       QMetaType::Int},
    {QStringLiteral("Height"), 400,       QMetaType::Int},
    {QStringLiteral("Title"),  QStringLiteral("Hello")},
};
 
auto store = std::make_unique<Store>(std::move(backend), schema);
int w = store->read<int>("Window", "Width"); // returns 600 if unset
store->write("Window", "Width", 800);
store->reset("Window", "Width"); // back to 600

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.

◆ 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 QString PhosphorConfig::Store::read	(	const QString &	,
		const QString &
	)		const

◆ read() [2/8]

template<>

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

◆ read() [3/8]

template<>

PHOSPHORCONFIG_EXPORT bool 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 QColor PhosphorConfig::Store::read	(	const QString &	,
		const QString &
	)		const

◆ read() [6/8]

template<>

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

◆ read() [7/8]

template<>

PHOSPHORCONFIG_EXPORT QVariantList 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.

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

phosphor-config/include/PhosphorConfig/Store.h

Phosphor Qt6 / Wayland library suite for window-management tools

Signals

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Store()

◆ ~Store()

Member Function Documentation

◆ backend()

◆ changed

◆ commit()

◆ defaultsToJson()

◆ exportToJson()

◆ importFromJson()

◆ read() [1/8]

◆ read() [2/8]

◆ read() [3/8]

◆ read() [4/8]

◆ read() [5/8]

◆ read() [6/8]

◆ read() [7/8]

◆ read() [8/8]

◆ readVariant()

◆ reset()

◆ resetAll()

◆ resetGroup()

◆ schema()

◆ sync()

◆ write()