Path syntax
Keys separated by ., array elements as [N] suffixes:
"database.host" "retries[2]" "servers[0].port" "matrix[1][2]"
Only ., [, ] are special — a key with spaces works ("my key.sub"); a key containing . or [ cannot be addressed. Disabled members are invisible. A malformed path resolves to nothing — never an exception.
Path methods
| Member | Behaviour |
|---|---|
findPath(path) → Value* | nullptr when absent or malformed |
containsPath(path) → bool | |
atPath(path) → Value& | throws std::out_of_range |
setPath(path, value) → Value* | replaces or appends; creates missing intermediate objects (bare keys where valid); never creates or grows arrays; never resurrects a disabled member; on failure returns nullptr and leaves the document untouched (intermediates rolled back) |
removePath(path) → bool | removes an active member or erases an array element |
Typed getters
Fallback used on a missing path or a type mismatch:
| Member | Type | Note |
|---|---|---|
getString(path, fallback = "") | std::string | non-String → fallback |
getInteger(path, fallback = 0) | long long | any Number; truncates |
getDouble(path, fallback = 0.0) | double | any Number |
getBoolean(path, fallback = false) | bool | Booleans only |
Provenance API — where did a resolved value come from?
After Fson::load resolves %include, a path may address a host member or one merged / aliased in from an included file. Write policy is host-only, so these queries let you locate the origin file to edit it there yourself.
| Member | Behaviour |
|---|---|
isLocal(path) → bool | true when the path resolves to a member physically in the host file |
provenanceOf(path) → std::optional<Provenance> | nullopt when the path resolves to nothing; else { queryPath, sourceFile, localPath, isHost } — sourceFile empty ⇒ host; localPath differs from queryPath for aliases |
provenanceMap() → std::vector<Provenance> | provenance of every active top-level member |
