{#jsonmodule}

json

JSON serialization using nlohmann/json.

Namespaces

Name	Description
json	JSON value aliases, serialization helpers, and file utilities built on nlohmann/json.

{#json}

json

JSON value aliases, serialization helpers, and file utilities built on nlohmann/json.

Classes

Name	Description
Configuration	JSON configuration file
ISerializable	Abstract interface for JSON-serializable objects.

Typedefs

Return	Name	Description
nlohmann::json	Value	Primary JSON value type used throughout the library.

---

{#value}

Value

nlohmann::json Value()

Primary JSON value type used throughout the library.

Functions

Return	Name	Description
bool	serialize inline	Serializes pObj to a pretty-printed JSON string.
bool	deserialize inline	Deserializes pObj from a JSON string.
void	loadFile inline	Load a JSON file into a value. Throws on missing file or parse error.
void	saveFile inline	Save a JSON value to a file. Throws on write error.
void	assertMember inline	Assert that a required member exists. Throws if missing.
void	countNestedKeys inline	Count how many nested objects contain the given key.
bool	hasNestedKey inline	Return true if any nested object contains the given key.
bool	findNestedObjectWithProperty inline	Find a nested object whose property matches the given key/value.

---

{#serialize}

serialize

inline

inline bool serialize(ISerializable * pObj, std::string & output)

Serializes pObj to a pretty-printed JSON string.

Parameters

• pObj Object to serialize; must not be null.

• output Receives the 4-space indented JSON string.

Returns

true on success, false if pObj is null.

---

{#deserialize}

deserialize

inline

inline bool deserialize(ISerializable * pObj, std::string & input)

Deserializes pObj from a JSON string.

Parameters

• pObj Object to populate; must not be null.

• input JSON string to parse.

Returns

true on success, false if pObj is null or parsing fails.

---

{#loadfile}

loadFile

inline

inline void loadFile(const std::string & path, json::Value & root)

Load a JSON file into a value. Throws on missing file or parse error.

---

{#savefile-1}

saveFile

inline

inline void saveFile(const std::string & path, const json::Value & root, int indent)

Save a JSON value to a file. Throws on write error.

---

{#assertmember}

assertMember

inline

inline void assertMember(const json::Value & root, const std::string & name)

Assert that a required member exists. Throws if missing.

---

{#countnestedkeys}

countNestedKeys

inline

inline void countNestedKeys(const json::Value & root, const std::string & key, int & count)

Count how many nested objects contain the given key.

---

{#hasnestedkey}

hasNestedKey

inline

inline bool hasNestedKey(const json::Value & root, const std::string & key)

Return true if any nested object contains the given key.

---

{#findnestedobjectwithproperty}

findNestedObjectWithProperty

inline

inline bool findNestedObjectWithProperty(json::Value & root, json::Value *& result, std::string_view key, std::string_view value, bool partial, int index)

Find a nested object whose property matches the given key/value.

Key or value may be empty for wildcard matching. If partial is true, substring matches are accepted for string values. The index parameter selects the Nth match (0 = first).

Returns true if found, with result pointing to the matching object.

{#configuration-1}

Configuration

#include <icy/json/configuration.h>

Inherits: Configuration

JSON configuration file

See base Configuration for all accessors

Public Attributes

Return	Name	Description
json::Value	root

---

{#root}

root

json::Value root

Public Methods

Return	Name	Description
	Configuration
	~Configuration virtual	Destroys the Configuration.
void	load virtual	Sets the file path and loads the configuration.
void	load virtual	Reloads the configuration from the previously set path. Silently ignores parse errors (e.g. empty file).
void	save virtual	Writes the current JSON root to the file at the stored path.
bool	remove virtual	Removes the top-level key key from the JSON root.
void	removeAll virtual	Removes all top-level keys whose names contain baseKey as a substring.
void	replace virtual	Performs a global string substitution on the serialized JSON, replacing all occurrences of from with to, then re-parses.
void	keys virtual	Populates keys with all top-level key names containing baseKey as a substring.
void	print virtual	Writes the pretty-printed JSON to ost with 4-space indentation.
std::string	path virtual	Returns the file path that was passed to load().
bool	loaded virtual	Returns true if load() has been called at least once.

---

{#configuration-2}

Configuration

Configuration()

---

{#configuration-3}

~Configuration

virtual

virtual ~Configuration()

Destroys the Configuration.

---

{#load}

load

virtual

virtual void load(const std::string & path, bool create)

Sets the file path and loads the configuration.

Parameters

• path Absolute or relative path to the JSON file.

• create Reserved for future use (currently unused).

Exceptions

• std::runtime_error if the path is empty.

---

{#load-1}

load

virtual

virtual void load(bool create)

Reloads the configuration from the previously set path. Silently ignores parse errors (e.g. empty file).

Parameters

• create Reserved for future use (currently unused).

Exceptions

• std::runtime_error if the path has not been set.

---

{#save}

save

virtual

virtual void save()

Writes the current JSON root to the file at the stored path.

Exceptions

• std::runtime_error if the path is empty or the file cannot be written.

---

{#remove}

remove

virtual

virtual bool remove(const std::string & key)

Removes the top-level key key from the JSON root.

Parameters

• key Key to remove.

Returns

true if the key existed and was removed.

---

{#removeall}

removeAll

virtual

virtual void removeAll(const std::string & baseKey)

Removes all top-level keys whose names contain baseKey as a substring.

Parameters

• baseKey Substring to match against key names.

---

{#replace-2}

replace

virtual

virtual void replace(const std::string & from, const std::string & to)

Performs a global string substitution on the serialized JSON, replacing all occurrences of from with to, then re-parses.

Parameters

• from Substring to find.

• to Replacement string.

---

{#keys}

keys

virtual

virtual void keys(std::vector< std::string > & keys, const std::string & baseKey)

Populates keys with all top-level key names containing baseKey as a substring.

Parameters

• keys Output vector to append matching key names to.

• baseKey Filter substring; empty string matches all keys.

---

{#print-8}

print

virtual

virtual void print(std::ostream & ost)

Writes the pretty-printed JSON to ost with 4-space indentation.

Parameters

• ost Output stream.

---

{#path-1}

path

virtual

virtual std::string path()

Returns the file path that was passed to load().

---

{#loaded}

loaded

virtual

virtual bool loaded()

Returns true if load() has been called at least once.

Protected Attributes

Return	Name	Description
bool	_loaded
std::string	_path
std::mutex	_mutex

---

{#_loaded}

_loaded

bool _loaded

---

{#_path-3}

_path

std::string _path

---

{#_mutex-9}

_mutex

std::mutex _mutex

Protected Methods

Return	Name	Description
bool	getRaw virtual const	Retrieves the string value for key from the JSON root.
void	setRaw virtual	Stores value under key in the JSON root and emits PropertyChanged.

---

{#getraw}

getRaw

virtual const

virtual bool getRaw(const std::string & key, std::string & value) const

Retrieves the string value for key from the JSON root.

Parameters

• key Top-level JSON key.

• value Set to the string value if the key exists.

Returns

true if the key was found, false otherwise.

---

{#setraw}

setRaw

virtual

virtual void setRaw(const std::string & key, const std::string & value)

Stores value under key in the JSON root and emits PropertyChanged.

Parameters

• key Top-level JSON key.

• value String value to store.

{#iserializable}

ISerializable

#include <icy/json/iserializable.h>

Subclassed by: Scheduler, Task, Trigger

Abstract interface for JSON-serializable objects.

Public Methods

Return	Name	Description
void	serialize	Serializes this object's state into root.
void	deserialize	Populates this object's state from root.

---

{#serialize-1}

serialize

void serialize(json::Value & root)

Serializes this object's state into root.

Parameters

• root JSON object to populate.

---

{#deserialize-1}

deserialize

void deserialize(json::Value & root)

Populates this object's state from root.

Parameters

• root JSON object previously produced by serialize().