{#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

using Value = nlohmann::json

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 = 4)

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 = true, int index = 0)

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>

class Configuration

Defined in src/json/include/icy/json/configuration.h:28

Inherits: Configuration

JSON configuration file

See base Configuration for all accessors

List of all members

Name	Kind	Owner
root	variable	Declared here
Configuration	function	Declared here
~Configuration	function	Declared here
load	function	Declared here
load	function	Declared here
save	function	Declared here
remove	function	Declared here
removeAll	function	Declared here
replace	function	Declared here
keys	function	Declared here
print	function	Declared here
path	function	Declared here
loaded	function	Declared here
_loaded	variable	Declared here
_path	variable	Declared here
_mutex	variable	Declared here
getRaw	function	Declared here
setRaw	function	Declared here
PropertyChanged	variable	Inherited from Configuration
_mutex	variable	Inherited from Configuration
Configuration	function	Inherited from Configuration
~Configuration	function	Inherited from Configuration
exists	function	Inherited from Configuration
getString	function	Inherited from Configuration
getString	function	Inherited from Configuration
getRawString	function	Inherited from Configuration
getRawString	function	Inherited from Configuration
getInt	function	Inherited from Configuration
getInt	function	Inherited from Configuration
getLargeInt	function	Inherited from Configuration
getLargeInt	function	Inherited from Configuration
getDouble	function	Inherited from Configuration
getDouble	function	Inherited from Configuration
getBool	function	Inherited from Configuration
getBool	function	Inherited from Configuration
setString	function	Inherited from Configuration
setInt	function	Inherited from Configuration
setLargeInt	function	Inherited from Configuration
setDouble	function	Inherited from Configuration
setBool	function	Inherited from Configuration
getRaw	function	Inherited from Configuration
setRaw	function	Inherited from Configuration
Configuration	function	Inherited from Configuration
operator=	function	Inherited from Configuration
Configuration	function	Inherited from Configuration
operator=	function	Inherited from Configuration
parseInt	function	Inherited from Configuration
parseLargeInt	function	Inherited from Configuration
parseBool	function	Inherited from Configuration

Inherited from Configuration

Kind	Name	Description
variable	PropertyChanged	The Key and Value of the changed configuration property.
variable	_mutex
function	Configuration	Creates the Configuration.
function	~Configuration virtual	Destroys the Configuration.
function	exists const	Returns true if the property with the given key exists.
function	getString const	Returns the string value of the property with the given name. Throws a NotFoundException if the key does not exist.
function	getString const	If a property with the given key exists, returns the property's string value, otherwise returns the given default value.
function	getRawString const	Returns the raw string value of the property with the given name. Throws a NotFoundException if the key does not exist. References to other properties are not expanded.
function	getRawString const	If a property with the given key exists, returns the property's raw string value, otherwise returns the given default value. References to other properties are not expanded.
function	getInt const	Returns the int value of the property with the given name. Throws a NotFoundException if the key does not exist. Throws a SyntaxException if the property can not be converted to an int. Numbers starting with 0x are treated as hexadecimal.
function	getInt const	If a property with the given key exists, returns the property's int value, otherwise returns the given default value. Throws a SyntaxException if the property can not be converted to an int. Numbers starting with 0x are treated as hexadecimal.
function	getLargeInt const	Returns the int value of the property with the given name. Throws a NotFoundException if the key does not exist. Throws a SyntaxException if the property can not be converted to an int. Numbers starting with 0x are treated as hexadecimal.
function	getLargeInt const	If a property with the given key exists, returns the property's int value, otherwise returns the given default value. Throws a SyntaxException if the property can not be converted to an int. Numbers starting with 0x are treated as hexadecimal.
function	getDouble const	Returns the double value of the property with the given name. Throws a NotFoundException if the key does not exist. Throws a SyntaxException if the property can not be converted to a double.
function	getDouble const	If a property with the given key exists, returns the property's double value, otherwise returns the given default value. Throws a SyntaxException if the property can not be converted to an double.
function	getBool const	Returns the double value of the property with the given name. Throws a NotFoundException if the key does not exist. Throws a SyntaxException if the property can not be converted to a double.
function	getBool const	If a property with the given key exists, returns the property's bool value, otherwise returns the given default value. Throws a SyntaxException if the property can not be converted to a boolean. The following string values can be converted into a boolean:
function	setString	Sets the property with the given key to the given value. An already existing value for the key is overwritten.
function	setInt	Sets the property with the given key to the given value. An already existing value for the key is overwritten.
function	setLargeInt	Sets the property with the given key to the given value. An already existing value for the key is overwritten.
function	setDouble	Sets the property with the given key to the given value. An already existing value for the key is overwritten.
function	setBool	Sets the property with the given key to the given value. An already existing value for the key is overwritten.
function	getRaw virtual const	If the property with the given key exists, stores the property's value in value and returns true. Otherwise, returns false.
function	setRaw virtual	Sets the property with the given key to the given value. An already existing value for the key is overwritten.
function	Configuration	Deleted constructor.
function	operator=	Deleted assignment operator.
function	Configuration	Deleted constructor.
function	operator=	Deleted assignment operator.
function	parseInt static	Parses a decimal or 0x-prefixed hexadecimal string to int.
function	parseLargeInt static	Parses a decimal or 0x-prefixed hexadecimal string to int64.
function	parseBool static	Parses a boolean string (true/false/yes/no/on/off/0/1, case-insensitive).

Public Attributes

Return	Name	Description
json::Value	root

---

{#root}

root

json::Value root

Defined in src/json/include/icy/json/configuration.h:80

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()

Defined in src/json/include/icy/json/configuration.h:31

---

{#configuration-3}

~Configuration

virtual

virtual ~Configuration()

Defined in src/json/include/icy/json/configuration.h:32

Destroys the Configuration.

Reimplements

• ~Configuration

---

{#load}

load

virtual

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

Defined in src/json/include/icy/json/configuration.h:38

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 = false)

Defined in src/json/include/icy/json/configuration.h:44

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()

Defined in src/json/include/icy/json/configuration.h:48

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)

Defined in src/json/include/icy/json/configuration.h:53

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)

Defined in src/json/include/icy/json/configuration.h:57

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)

Defined in src/json/include/icy/json/configuration.h:63

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 = "")

Defined in src/json/include/icy/json/configuration.h:68

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)

Defined in src/json/include/icy/json/configuration.h:72

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

Parameters

• ost Output stream.

---

{#path-1}

path

virtual

virtual std::string path()

Defined in src/json/include/icy/json/configuration.h:75

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

---

{#loaded}

loaded

virtual

virtual bool loaded()

Defined in src/json/include/icy/json/configuration.h:78

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

Defined in src/json/include/icy/json/configuration.h:94

---

{#_path-3}

_path

std::string _path

Defined in src/json/include/icy/json/configuration.h:95

---

{#_mutex-9}

_mutex

std::mutex _mutex

Defined in src/json/include/icy/json/configuration.h:96

Protected Methods

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

---

{#getraw}

getRaw

virtual const override

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

Defined in src/json/include/icy/json/configuration.h:87

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.

Reimplements

• getRaw

---

{#setraw}

setRaw

virtual override

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

Defined in src/json/include/icy/json/configuration.h:92

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

Parameters

• key Top-level JSON key.

• value String value to store.

Reimplements

• setRaw

{#iserializable}

ISerializable

#include <icy/json/iserializable.h>

class ISerializable

Defined in src/json/include/icy/json/iserializable.h:24

Subclassed by: Scheduler, Task, Trigger

Abstract interface for JSON-serializable objects.

List of all members

Name	Kind	Owner
serialize	function	Declared here
deserialize	function	Declared here

Public Methods

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

---

{#serialize-1}

serialize

virtual

virtual void serialize(json::Value & root)

Defined in src/json/include/icy/json/iserializable.h:31

Serializes this object's state into root.

Parameters

• root JSON object to populate.

Reimplemented by

• serialize
• serialize
• serialize
• serialize

---

{#deserialize-1}

deserialize

virtual

virtual void deserialize(json::Value & root)

Defined in src/json/include/icy/json/iserializable.h:35

Populates this object's state from root.

Parameters

• root JSON object previously produced by serialize().

Reimplemented by

• deserialize
• deserialize
• deserialize
• deserialize