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(std::initializer_list<detail::init::node> vs)
document_tree(array vs)
document_tree(object obj)
~document_tree()
document_tree &operator=(std::initializer_list<detail::init::node> vs)
document_tree &operator=(array vs)
document_tree &operator=(object obj)
void load(const std::string &strm, const json_config &config)

Load raw string stream containing a JSON structure to populate the document tree.

Parameters
  • strm: stream containing a JSON structure.

  • config: configuration object.

void load(const char *p, size_t n, const json_config &config)

Load raw string stream containing a JSON structure to populate the document tree.

Parameters
  • p: pointer to the stream containing a JSON structure.

  • n: size of the stream.

  • config: configuration object.

json::const_node get_document_root() const

Get the root node of the document.

Return

root node of the document.

json::node get_document_root()

Get the root node of the document.

Return

root node of the document.

std::string dump() const

Dump the JSON document tree to string.

Return

a string representation of the JSON document tree.

std::string dump_xml() const

Dump the JSON document tree to an XML structure.

Return

a string containing an XML structure representing the JSON content.

void swap(document_tree &other)

Swap the content of the document with another document instance.

Parameters
  • other: document instance to swap the content with.

struct orcus::json_config

Public Functions

json_config()
~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.

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()
node_t type() const

Get the type of a node.

Return

node type.

size_t child_count() const

Get the number of child nodes if any.

Return

number of child nodes.

std::vector<pstring> keys() const

Get a list of keys stored in a JSON object node.

Return

a list of keys.

Exceptions

pstring 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.

Return

key value.

Parameters
  • index: 0-based key index.

Exceptions
  • 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.

bool has_key(const pstring &key) const

Query whether or not a particular key exists in a JSON object node.

Return

true if this object node contains the specified key, otherwise false. If this node is not of a JSON object type, false is returned.

Parameters
  • key: key value.

const_node child(size_t index) const

Get a child node by index.

Return

child node instance.

Parameters
  • index: 0-based index of a child node.

Exceptions
  • 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.

const_node child(const pstring &key) const

Get a child node by textural key value.

Return

child node instance.

Parameters
  • key: textural key value to get a child node by.

Exceptions

const_node parent() const

Get the parent node.

Return

parent node instance.

Exceptions

const_node back() const

Get the last child node.

Return

last child node instance.

Exceptions

pstring string_value() const

Get the string value of a JSON string node.

Return

string value.

Exceptions

double numeric_value() const

Get the numeric value of a JSON number node.

Return

numeric value.

Exceptions

const_node &operator=(const 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.

Return

identifier of the JSON value object.

const_node_iterator begin() const
const_node_iterator end() const
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(const node &other)
node(node &&rhs)
~node()
node &operator=(const node &other)
node &operator=(const detail::init::node &v)
node operator[](const pstring &key)
node child(size_t index)

Get a child node by index.

Return

child node instance.

Parameters
  • index: 0-based index of a child node.

Exceptions
  • 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.

node child(const pstring &key)

Get a child node by textural key value.

Return

child node instance.

Parameters
  • key: textural key value to get a child node by.

Exceptions

node parent()

Get the parent node.

Return

parent node instance.

Exceptions

node back()

Get the last child node.

Return

last child node instance.

Exceptions

void push_back(const detail::init::node &v)

Append a new node value to the end of the array.

Exceptions
Parameters
  • v: new node value to append to the end of the array.

class orcus::json::array

This class represents a JSON array, to be used to explicitly create an array instance during initialization.

Public Functions

array()
array(const array&) = delete
array(array &&other)
array(std::initializer_list<detail::init::node> vs)
~array()

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.

Public Functions

object()
object(const object&) = delete
object(object &&other)
~object()
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(std::initializer_list<detail::init::node> vs)
node(json::array array)
node(json::object obj)
node(const node &other) = delete
node(node &&other)
~node()
node &operator=(node other) = delete

Friends

friend class ::orcus::json::document_tree
friend class ::orcus::json::node
enum orcus::json::node_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.

Exceptions

class orcus::json::document_error : public orcus::general_error

Exception related to JSON document tree construction.

Subclassed by orcus::json::key_value_error

Public Functions

document_error(const std::string &msg)
~document_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.

Public Functions

key_value_error(const std::string &msg)
~key_value_error()