PhosphorFsLoader Namespace Reference

Namespaces
namespace	detail

Classes
class	DirectoryLoader
	Generic JSON-directory loader with debounced live reload. More...
class	IDirectoryLoaderSink
	Consumer-supplied strategy for a DirectoryLoader. More...
class	IScanStrategy
	Pluggable enumeration / parse / commit policy for WatchedDirectorySet. More...
struct	JsonEnvelope
	Result of a successful envelope validation. More...
class	MetadataPackRegistryBase
	QObject base for registries hosting a MetadataPackScanStrategy<Payload>. More...
class	MetadataPackScanStrategy
	Reusable scan strategy for metadata.json-driven subdirectory pack registries. More...
struct	ParsedEntry
	One parsed file's payload + metadata. More...
class	WatchedDirectorySet
	Watcher + debounce + rescan scaffolding for filesystem-backed loaders. More...

Enumerations
enum class	LiveReload : quint8 { Off , On }
	Opt-in policy for directory watching. More...
enum class	RegistrationOrder : quint8 { LowestPriorityFirst , HighestPriorityFirst }
	Caller's declared priority direction for registerDirectories / setDirectories input. More...

Functions
std::optional< JsonEnvelope >	validateJsonEnvelope (const QString &filePath, const QLoggingCategory &category)
	Validate the default envelope used by DirectoryLoader sinks.

Enumeration Type Documentation

LiveReload

enum class PhosphorFsLoader::LiveReload : quint8

strong

Opt-in policy for directory watching.

On installs a QFileSystemWatcher on every scanned directory (or its parent, if the target doesn't exist yet — so fresh installs that create the user-data dir later still pick up edits without a restart). Edits trigger a 50 ms debounced rescan.

Off is fire-and-forget — useful for tests, batch imports, and consumers that want explicit refresh semantics via requestRescan.

Enumerator
Off
On

RegistrationOrder

enum class PhosphorFsLoader::RegistrationOrder : quint8

strong

Caller's declared priority direction for registerDirectories / setDirectories input.

Strategies in this library always see the canonical scan order: [lowest-priority, ..., highest-priority], suitable for reverse- iterate-first-wins. The base normalises the caller's input into this shape before storing it in m_directories and handing it to the strategy, so the canonical convention is enforced once at the registration boundary instead of being repeated as a comment-driven contract every strategy author has to remember.

Pick the value that matches how your input is already ordered — do NOT pre-reverse and then claim the opposite. Both spellings are equivalent; the enum's only job is to keep the next strategy author from silently inverting every override by feeding locateAll's natural (highest-first) output as if it were the canonical (lowest-first) shape.

Enumerator
LowestPriorityFirst	[sys-lowest, ..., sys-highest, user] — the canonical strategy view. The daemon's curve/profile/script setup explicitly builds this shape via std::reverse(locateAll(...)) + userDir.append. Pass-through; the base stores the list verbatim.
HighestPriorityFirst	[user, sys-highest, ..., sys-lowest] — the natural output of QStandardPaths::locateAll(GenericDataLocation, ...) followed by a prepend(userDir). The base reverses internally before storing, so the strategy still sees LowestPriorityFirst.

Function Documentation

validateJsonEnvelope()

std::optional< JsonEnvelope > PhosphorFsLoader::validateJsonEnvelope ( const QString &  filePath, const QLoggingCategory &  category  )

inline

Validate the default envelope used by DirectoryLoader sinks.

Every IDirectoryLoaderSink whose schema follows the default name == filename basename envelope (CurveLoader and ProfileLoader today) starts its parseFile with the same boilerplate:

1. Open the file (skip on read error).
2. Parse JSON (skip on malformed).
3. Reject non-object roots.
4. Require a non-empty "name" field.
5. Reject mismatch between "name" and the file's completeBaseName (silent shadowing guard — a user copies widget.fade.json → custom.json and forgets to rename the inner field, the result registers under the original key while the file on disk suggests a different identity).

Loaders with a different envelope shape (e.g. ShaderRegistry, which keys by directory name and parses metadata.json with its own schema) do not use this helper — they roll their own parse pass.

On success this returns the parsed root with "name" stripped — sinks can pass root straight into a schema-specific fromJson without re-handling the bookkeeping field. On failure it logs a clear diagnostic at the supplied logging category and returns std::nullopt.

Parameters

filePath	Absolute path to the JSON file. Used for the read, for the completeBaseName diagnostic, and for log output.
category	Caller's Q_LOGGING_CATEGORY so warnings are tagged with the consumer-specific category (e.g. "phosphoranimation.curveloader") rather than a generic shared category — operators filtering log output by category keep their existing rules.

Header-only inline so consumers don't pay a translation-unit boundary crossing per parse — every loader sink is in a single source file already, and this helper is on the per-file hot path.