Skip to content

json.md

Latest commit

 

History

History
738 lines (485 loc) · 25.9 KB

json.md

File metadata and controls

738 lines (485 loc) · 25.9 KB
Raw

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

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

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

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

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

Reimplemented by