#include <XML_fwd.hpp>

Detailed Description

Class for reading and storing values to XML files.

The whole XML file is stored in memory, along with the created document nodes. This class aims to provide simplified support for reading attributes from XML files, usually meant to be used as configurations, similar to Boost.PropertyTree. It uses the RapidXml XML library for parsing. For any specifics on parsing XML files, refer to RapidXml documentation.

The intended use is very simple: .get<int>("element1.element2.attribute") returns the value of the attribute, nested in element2 inside element1 inside XML root element. The complementary .set("element3.attribute", 34.4) sets the attribute to 34.4.

Warning: The attribute path does not contain the root XML element for brevity, as XML standard requires each document to have unique root element and that part of the path would have always been the same.

Usage example:

    XML xml("test/testdata/test_conf.xml");
    if (xml.exists("element1.attr")) {
        int a = xml.get<int>("element1.attr");
        std::cout << a << std::endl;  // do something with a
    }
    xml.set("test.abc.xyz", 12.4543);
    double r = xml.get<double>("test.abc.xyz");  // r is 12.4543
    xml.set("element1.attr", 12, true);  // specify `overwrite = true` to change existing values
    std::cout << xml << std::endl;  // outputs the loaded xml contents to screen
    xml.load("test/testdata/another_file.xml");

Definition at line 40 of file XML_fwd.hpp.

Public Member Functions
	XML ()=default
	Creates an XML reader linked to no document. More...

	XML (const XML &)
	Creates a copy of the XML document. More...

	XML (const std::string &filename)
	Constructs a XML reader by reading the file given by `filename`. More...

void	load (const std::string &filename)
	Loads XML document from a file given by `filename`. More...

bool	exists (const std::string &path) const
	Returns `true` if the an attribute specified by `path` exists and `false` otherwise. More...

template<typename T >
T	get (const std::string &path) const
	Reads a values from an attribute specified by `path`. More...

template<typename T >
void	set (const std::string &path, const T &value, bool overwrite=false)
	Saves a value to the attribute pointed to by `path`. More...

std::vector< std::pair< std::string, std::string > >	getAll () const
	Returns all pairs `(path, attribute_value)`. More...

rapidxml::xml_document< char > &	documentRoot ()
	Access to underlying XML root element from RapidXml library. More...

const rapidxml::xml_document< char > &	documentRoot () const
	Const version of XML::documentRoot. More...

Friends
std::ostream &	operator<< (std::ostream &os, const XML &xml)
	Prints the contents of currently loaded XML document. More...

Private Member Functions
void	loadFileHelper (const std::string &file)
	Function for opening files, called by XML::XML(const std::string&) and XML::load(). More...

void	loadFromStoredContents ()
	Loads the XML document from a stored null-terminated `file_contents`. More...

char *	getString (const std::vector< std::string > &path, const std::string &attribute_name) const
	Reads the contents of the attribute specified by `path` as a string. More...

void	setString (const std::vector< std::string > &path, const std::string &attribute_name, const std::string &content)
	Writes the contents of string `content` to the attribute specified by `path`. More...

void	getAllRecursive (const rapidxml::xml_node<> *node, std::string path, std::vector< std::pair< std::string, std::string >> &all_attr) const
	Fills the `all_attr` array with all pairs `(path, value)` pairs that are descendants of node `node` at path `path`. More...

Static Private Member Functions
static std::pair< std::vector< std::string >, std::string >	splitPath (std::string path)
	Splits dot separated path into elements path and attribute name. More...

static std::string	join (const std::vector< std::string > &path)
	Join a path into dot separated string. More...

Private Attributes
std::vector< char >	file_contents
	Whole XML file contents. More...

rapidxml::xml_document< char >	doc
	XML document root. More...

Constructor & Destructor Documentation

◆ XML() [1/3]

mm::XML::XML ( )

default

Creates an XML reader linked to no document.

◆ XML() [2/3]

mm::XML::XML ( const XML & xml )

Creates a copy of the XML document.

Note: This re-parses the whole document. It should be used sparingly, and XML configurations can usually be passed around as const & to avoid this.

Definition at line 39 of file XML.cpp.

◆ XML() [3/3]

mm::XML::XML ( const std::string & filename )

explicit

Constructs a XML reader by reading the file given by filename.

Definition at line 38 of file XML.cpp.

Member Function Documentation

◆ documentRoot() [1/2]

const rapidxml::xml_document< char > & mm::XML::documentRoot ( )

Access to underlying XML root element from RapidXml library.

Definition at line 45 of file XML.cpp.

◆ documentRoot() [2/2]

const rapidxml::xml_document<char>& mm::XML::documentRoot ( ) const

Const version of XML::documentRoot.

◆ exists()

bool mm::XML::exists ( const std::string & path ) const

Returns true if the an attribute specified by path exists and false otherwise.

Definition at line 164 of file XML.cpp.

◆ get()

template<typename T >

T mm::XML::get ( const std::string & path ) const

Reads a values from an attribute specified by path.

Template Parameters

T	Type to which the attribute value should be converted. This is done using the stream extraction operator `>>` for type `T`.

Parameters

path	Dot separated path to the attribute, excluding the root XML tag.

Returns: Value of the attribute converted to type T.

Exceptions

Assertion fails if the attribute does not exist.

Definition at line 17 of file XML.hpp.

◆ getAll()

std::vector< std::pair< std::string, std::string > > mm::XML::getAll ( ) const

Returns all pairs (path, attribute_value).

Definition at line 148 of file XML.cpp.

◆ getAllRecursive()

void mm::XML::getAllRecursive	(	const rapidxml::xml_node<> *	node,
		std::string	path,
		std::vector< std::pair< std::string, std::string >> &	all_attr
	)		const

private

Fills the all_attr array with all pairs (path, value) pairs that are descendants of node node at path path.

Parameters

[in]	node	Current node, whose descendants will be searched.
[in]	path	Path of the given `node`.
[out]	all_attr	Container to be filled with `(path, value)` pairs.

Definition at line 154 of file XML.cpp.

◆ getString()

char * mm::XML::getString	(	const std::vector< std::string > &	path,
		const std::string &	attribute_name
	)		const

private

Reads the contents of the attribute specified by path as a string.

Definition at line 87 of file XML.cpp.

◆ join()

std::string mm::XML::join ( const std::vector< std::string > & path )

staticprivate

Join a path into dot separated string.

Definition at line 77 of file XML.cpp.

◆ load()

void mm::XML::load ( const std::string & filename )

Loads XML document from a file given by filename.

Any previous data held in this object instance is lost.

Definition at line 44 of file XML.cpp.

◆ loadFileHelper()

void mm::XML::loadFileHelper ( const std::string & file )

private

Function for opening files, called by XML::XML(const std::string&) and XML::load().

The file is opened in this function and closed after this function finishes.

Exceptions

Assertion fails if anything is wrong when accessing or reading the file.

Definition at line 16 of file XML.cpp.

◆ loadFromStoredContents()

void mm::XML::loadFromStoredContents ( )

private

Loads the XML document from a stored null-terminated file_contents.

This modifies the file_contents buffer, so the function is not idempotent.

Exceptions

rapidxml::parse_error Exception is thrown if the string stored in file_contents cannot be parsed to a valid XML document.

Definition at line 28 of file XML.cpp.

◆ set()

template<typename T >

void mm::XML::set	(	const std::string &	path,
		const T &	value,
		bool	overwrite = `false`
	)

Saves a value to the attribute pointed to by path.

If the attribute or path does not exist it is created.

Parameters

path	Dot separated path to the attribute, excluding root XML tag. It the path does not exist, it is created on the fly.
value	Value to save. It is converted to string before saving using the stream insertion operator `<<` for type `T`.
overwrite	If `true`, possible existing value is overwritten, otherwise an assertion is triggered. Defaults to `false`.

Warning: If overwrite is false, assertion fails if the attribute exists. This is the default behaviour.

Definition at line 33 of file XML.hpp.

◆ setString()

void mm::XML::setString	(	const std::vector< std::string > &	path,
		const std::string &	attribute_name,
		const std::string &	content
	)

private

Writes the contents of string content to the attribute specified by path.

Definition at line 101 of file XML.cpp.

◆ splitPath()

std::pair< std::vector< std::string >, std::string > mm::XML::splitPath ( std::string path )

staticprivate

Splits dot separated path into elements path and attribute name.

Returns: Pair {{sequence_of_elements}, attribute_name} representing the path.

Definition at line 55 of file XML.cpp.

Friends And Related Function Documentation

◆ operator<<

std::ostream& operator<<	(	std::ostream &	os,
		const XML &	xml
	)

friend

Prints the contents of currently loaded XML document.

Definition at line 49 of file XML.cpp.

Member Data Documentation

◆ doc

rapidxml::xml_document<char> mm::XML::doc

private

XML document root.

Definition at line 42 of file XML_fwd.hpp.

◆ file_contents

std::vector<char> mm::XML::file_contents

private

Whole XML file contents.

Definition at line 41 of file XML_fwd.hpp.

The documentation for this class was generated from the following files:

include/medusa/bits/io/XML_fwd.hpp
include/medusa/bits/io/XML.hpp
src/io/XML.cpp

Detailed Description

Public Member Functions

Friends

Private Member Functions

Static Private Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ XML() [1/3]

◆ XML() [2/3]

◆ XML() [3/3]

Member Function Documentation

◆ documentRoot() [1/2]

◆ documentRoot() [2/2]

◆ exists()

◆ get()

◆ getAll()

◆ getAllRecursive()

◆ getString()

◆ join()

◆ load()

◆ loadFileHelper()

◆ loadFromStoredContents()

◆ set()

◆ setString()

◆ splitPath()

Friends And Related Function Documentation

◆ operator<<

Member Data Documentation

◆ doc

◆ file_contents