JSON Document Tree
Document tree
-
class orcus::json::document_tree
This class stores a parsed JSON document tree structure.
Public Functions
-
document_tree()
-
document_tree(const document_tree&) = delete
-
document_tree(document_tree &&other)
-
document_tree(document_resource &res)
-
~document_tree()
-
document_tree &operator=(std::initializer_list<detail::init::node> vs)
-
document_tree &operator=(array vs)
-
document_tree &operator=(object obj)
-
void load(std::string_view stream, const json_config &config)
Load raw string stream containing a JSON structure to populate the document tree.
- Parameters
stream – stream containing a JSON structure.
config – configuration object.
-
json::const_node get_document_root() const
Get the root node of the document.
- Returns
root node of the document.
-
json::node get_document_root()
Get the root node of the document.
- Returns
root node of the document.
-
std::string dump() const
Dump the JSON document tree to string.
- Returns
a string representation of the JSON document tree.
-
std::string dump_xml() const
Dump the JSON document tree to an XML structure.
- Returns
a string containing an XML structure representing the JSON content.
-
std::string dump_yaml() const
Dump the JSON document tree as YAML output.
- Returns
string containing a YAML output representing the JSON document tree structure.
-
void swap(document_tree &other)
Swap the content of the document with another document instance.
- Parameters
other – document instance to swap the content with.
-
document_tree()
-
struct orcus::json_config
-
Public Members
-
std::string input_path
Path of the JSON file being parsed, in case the JSON string originates from a file. This parameter is required if external JSON files need to be resolved. Otherwise it’s optional.
-
std::string output_path
Path of the file to which output is written to. Used only from the orcus-json command line tool.
-
dump_format_t output_format
Output format type. Used only from the orcus-json command line tool.
-
bool preserve_object_order
Control whether or not to preserve the order of object’s child name/value pairs. By definition, JSON’s object is an unordered set of name/value pairs, but in some cases preserving the original order may be desirable.
-
bool resolve_references
Control whether or not to resolve JSON references to external files.
-
bool persistent_string_values
When true, the document tree should allocate memory and hold copies of string values in the tree. When false, no extra memory is allocated for string values in the tree and the string values simply point to the original json string stream.
In other words, when this option is set to false, the caller must ensure that the json string stream instance stays alive for the entire life cycle of the document tree.
-
std::string input_path
-
class orcus::json::const_node
Each node instance represents a JSON value stored in the document tree. It’s immutable.
Subclassed by orcus::json::node
Public Functions
-
const_node() = delete
-
const_node(const const_node &other)
-
const_node(const_node &&rhs)
-
~const_node()
-
size_t child_count() const
Get the number of child nodes if any.
- Returns
number of child nodes.
-
std::vector<std::string_view> keys() const
Get a list of keys stored in a JSON object node.
- Throws
orcus::json::document_error – if the node is not of the object type.
- Returns
a list of keys.
-
std::string_view key(size_t index) const
Get the key by index in a JSON object node. This method works only when the preserve object order option is set.
- Parameters
index – 0-based key index.
- Throws
orcus::json::document_error – if the node is not of the object type.
std::out_of_range – if the index is equal to or greater than the number of keys stored in the node.
- Returns
key value.
-
bool has_key(std::string_view key) const
Query whether or not a particular key exists in a JSON object node.
- Parameters
key – key value.
- Returns
true if this object node contains the specified key, otherwise false. If this node is not of a JSON object type, false is returned.
-
const_node child(size_t index) const
Get a child node by index.
- Parameters
index – 0-based index of a child node.
- Throws
orcus::json::document_error – if the node is not one of the object or array types.
std::out_of_range – if the index is equal to or greater than the number of child nodes that the node has.
- Returns
child node instance.
-
const_node child(std::string_view key) const
Get a child node by textural key value.
- Parameters
key – textural key value to get a child node by.
- Throws
orcus::json::document_error – if the node is not of the object type, or the node doesn’t have the specified key.
- Returns
child node instance.
-
const_node parent() const
Get the parent node.
- Throws
orcus::json::document_error – if the node doesn’t have a parent node which implies that the node is a root node.
- Returns
parent node instance.
-
const_node back() const
Get the last child node.
- Throws
orcus::json::document_error – if the node is not of array type or node has no children.
- Returns
last child node instance.
-
std::string_view string_value() const
Get the string value of a JSON string node.
- Throws
orcus::json::document_error – if the node is not of the string type.
- Returns
string value.
-
double numeric_value() const
Get the numeric value of a JSON number node.
- Throws
orcus::json::document_error – if the node is not of the number type.
- Returns
numeric value.
-
const_node &operator=(const const_node &other)
-
const_node &operator=(const_node &&other)
-
uintptr_t identity() const
Return an indentifier of the JSON value object that the node represents. The identifier is derived directly from the memory address of the value object.
- Returns
identifier of the JSON value object.
-
const_node_iterator begin() const
-
const_node_iterator end() const
-
const_node() = delete
-
class orcus::json::node : public orcus::json::const_node
Each node instance represents a JSON value stored in the document tree. This class allows mutable operations.
Public Functions
-
node() = delete
-
~node()
-
node child(size_t index)
Get a child node by index.
- Parameters
index – 0-based index of a child node.
- Throws
orcus::json::document_error – if the node is not one of the object or array types.
std::out_of_range – if the index is equal to or greater than the number of child nodes that the node has.
- Returns
child node instance.
-
node child(std::string_view key)
Get a child node by textural key value.
- Parameters
key – textural key value to get a child node by.
- Throws
orcus::json::document_error – if the node is not of the object type, or the node doesn’t have the specified key.
- Returns
child node instance.
-
node parent()
Get the parent node.
- Throws
orcus::json::document_error – if the node doesn’t have a parent node which implies that the node is a root node.
- Returns
parent node instance.
-
node back()
Get the last child node.
- Throws
orcus::json::document_error – if the node is not of array type or node has no children.
- Returns
last child node instance.
-
void push_back(const detail::init::node &v)
Append a new node value to the end of the array.
- Throws
orcus::json::document_error – if the node is not of array type.
- Parameters
v – new node value to append to the end of the array.
-
node() = delete
-
class orcus::json::array
This class represents a JSON array, to be used to explicitly create an array instance during initialization.
Friends
- friend class detail::init::node
-
class orcus::json::object
This class represents a JSON object, primarily to be used to create an empty object instance.
-
class orcus::json::detail::init::node
Node to store an initial value during document tree initialization. It’s not meant to be instantiated explicitly. A value passed from the braced initialization list is implicitly converted to an instance of this class.
Public Functions
-
node(double v)
-
node(int v)
-
node(bool b)
-
node(std::nullptr_t)
-
node(const char *p)
-
node(const std::string &s)
-
~node()
Friends
- friend class ::orcus::json::document_tree
- friend class ::orcus::json::node
-
node(double v)
-
enum class orcus::json::node_t : uint8_t
Values:
-
enumerator unset
node type is not set.
-
enumerator string
JSON string node. A node of this type contains a string value.
-
enumerator number
JSON number node. A node of this type contains a numeric value.
-
enumerator object
JSON object node. A node of this type contains one or more key-value pairs.
-
enumerator array
JSON array node. A node of this type contains one or more child nodes.
-
enumerator boolean_true
JSON boolean node containing a value of ‘true’.
-
enumerator boolean_false
JSON boolean node containing a value of ‘false’.
-
enumerator null
JSON node containing a ‘null’ value.
-
enumerator unset
Exceptions
-
class orcus::json::document_error : public orcus::general_error
Exception related to JSON document tree construction.
Subclassed by orcus::json::key_value_error
-
class orcus::json::key_value_error : public orcus::json::document_error
Exception that gets thrown due to ambiguity when you specify a braced list that can be interpreted either as a key-value pair inside an object or as values of an array.