XML class. More...

#include <GXml.hpp>

Inheritance diagram for GXml:

Public Member Functions
	GXml (void)
	Void constructor. More...

	GXml (const GXml &xml)
	Copy constructor. More...

	GXml (const std::string &xml)
	XML document constructor. More...

	GXml (const GXmlDocument &root)
	Document constructor. More...

virtual	~GXml (void)
	Destructor. More...

GXml &	operator= (const GXml &xml)
	Assignment operator. More...

GXmlNode *	operator[] (const int &index)
	Return pointer to child of XML document root element. More...

const GXmlNode *	operator[] (const int &index) const
	Return pointer to child of XML document root element (const variant) More...

void	clear (void)
	Clear XML object. More...

GXml *	clone (void) const
	Clone XML object. More...

std::string	classname (void) const
	Return class name. More...

int	size (void) const
	Return number of child nodes. More...

bool	is_empty (void) const
	Signals if document has no child nodes. More...

GXmlNode *	set (const int &index, const GXmlNode &node)
	Set child node in XML document root. More...

GXmlNode *	append (const GXmlNode &node)
	Append child node to XML document root. More...

GXmlElement *	append (const std::string &segment)
	Append child node to XML document root. More...

GXmlNode *	insert (const int &index, const GXmlNode &node)
	Insert child node into XML document root. More...

void	remove (const int &index)
	Remove child node from XML document root. More...

void	reserve (const int &num)
	Reserve space for child nodes in XML document root. More...

void	extend (const GXmlNode &node)
	Append all XML child nodes from another XML node in the XML document root. More...

int	elements (void) const
	Return number of child elements in XML document root. More...

int	elements (const std::string &name) const
	Return number of child elements with a given name in XML document root. More...

GXmlElement *	element (const int &index)
	Return pointer to child element. More...

const GXmlElement *	element (const int &index) const
	Return pointer to child element (const variant) More...

GXmlElement *	element (const std::string &name)
	Return pointer to child element by hierarchy. More...

const GXmlElement *	element (const std::string &name) const
	Return pointer to child element by hierarchy (const version) More...

GXmlElement *	element (const std::string &name, const int &index)
	Return pointer to child element of a given name. More...

const GXmlElement *	element (const std::string &name, const int &index) const
	Return pointer to child element of a given name (const variant) More...

const GXmlDocument &	root (void) const
	Return document root. More...

void	root (const GXmlDocument &root)
	Set document root. More...

void	load (const GFilename &filename)
	Load XML document from file. More...

void	save (const GFilename &filename) const
	Save XML document into file. More...

void	read (const GUrl &url)
	Read XML document from URL. More...

void	write (GUrl &url, const int &indent=0) const
	Write XML document into URL. More...

std::string	print (const GChatter &chatter=NORMAL) const
	Print XML object. More...

std::string	print (const GChatter &chatter=NORMAL, const int &indent=0) const
	Print XML object. More...

Public Member Functions inherited from GContainer
virtual	~GContainer (void)
	Destructor. More...

Public Member Functions inherited from GBase
virtual	~GBase (void)
	Destructor. More...

Protected Types
enum	MarkupType { MT_ELEMENT_START, MT_ELEMENT_END, MT_ELEMENT_EMPTY, MT_COMMENT, MT_DECLARATION, MT_PROCESSING, MT_INVALID }

Protected Member Functions
void	init_members (void)
	Initialise class members. More...

void	copy_members (const GXml &xml)
	Copy class members. More...

void	free_members (void)
	Delete class members. More...

void	parse (const GUrl &url)
	Parse XML URL. More...

void	process_markup (GXmlNode **current, const std::string &segment)
	Process markup segment. More...

void	process_text (GXmlNode **current, const std::string &segment)
	Process text segment. More...

MarkupType	get_markuptype (const std::string &segment) const
	Get Markup type of segment. More...

Protected Attributes
GXmlDocument	m_root
	Root document node. More...

Friends
class	GXmlNode

class	GXmlDocument

class	GXmlText

Detailed Description

XML class.

This class holds the content of an Extensible Markup Language (XML) document. An XML document is composed of a list of nodes, each of which may contain lists of nodes, which again can contain list of nodes and so on. This produces a tree made of nodes with an arbitrary complexity. Nodes that do not contain any further nodes are the endpoints of the tree that are called leafs.

An example of an XML document is shown below

<?xml version="1.0" encoding="UTF-8" ?>
<element type="Measurement">
  <parameter name="Flux" value="1.0"/>
</element>
<element>
  <list>
    <string>This is a text</string>
    <integer>17</integer>
  </list>
</element>

An XML document is a plain ASCII file. Every XML document begins by a declaration of the XML version and an optional information about the encoding of the text.

The XML document is structured using tags. A tag is a markup construct that begins with < and ends with >. Tags come in three flavors:

start-tags; for example: <section>
end-tags; for example: </section>
empty-element tags; for example: <line-break />

The header line of an XML document is an empty-element tag. Each tag may contain an arbitrary number of attributes of the form

version="1.0"

Alternative quotes ' are also allowed.

A logical document component which either begins with a start-tag and ends with a matching end-tag or consists only of an empty-element tag is called an element. The characters between the start- and end-tags, if any, are the element's content, and may contain markup, including other elements, which are called child elements. An example of an element is

<string>This is a text</string>

Another is

<parameter name="Flux" value="1.0"/>

This last example has two attributes. The first word in an element is called the element name. Every element has a name. Elements can therefore be accessed by name, however, several elements with the same name may exist.

GammaLib implements the XML document in form of a master class GXml which contains the root node of the document. The root node is realized by the GXmlDocument class. GXmlDocument derives from GXmlNode, which defines the abstract interface for all XML nodes. The following XML nodes exist:

GXmlElement: implements an element
GXmlText: implements a text leaf
GXmlPI: implements a Processing Instruction
GXmlComment: implement a comment

XML element attributes are implemented using GXmlAttribute.

The GXml class provides methods to access the nodes of the XML document, and to load and save the document from a URL. GXml derives from GContainer as it behaves like a container class. It does, however, not contain an explicit list, as the only data member of the class is a single instance of GXmlDocument. GXmlDocument contains the hierarchical list of all XML nodes.

To manipulate the child nodes of GXmlDocument, the usual container class methods are available. size() returns the number of child nodes that exist in the XML document root (in the above example there would be two child elements with name element). The child nodes are accessed using the operator[]. The is_empty() method checks whether the document root has no children.

The set() method allows to set a specific child node, the append() method appends a child node to the XML document root. There is a second variant of the append() method that appends a element of type GXmlElement to the XML document root and that returns a pointer to this element. As argument, this second method takes a text string that defines the element name and attributes. For example, the first node in the above example could have been generated using

GXml xml;
xml.append("element type=\"Measurement\"");

Note that the < and > symbols are not part of the text string that is passed to the append() method.

The insert() method inserts a child node at the specified index in the XML root document. The remove() method removes the child node at the specified index from the document root. The reserve() method reserves space for a specified number of child nodes in the XML document root. And the extend() method appends all child nodes that are found in the specified argument to the XML document root.

Most of the nodes encountered in a XML document will be element nodes, hence special methods for handling element nodes have been implemented. The elements() method returns the number of child elements that are present in the XML document root. A variant that takes a string argument counts the number of child elements with a given name. The element() method allows to access the child elements. There are again two flavours, one that simply takes an index to loop over all child elements, and another that takes a name and a index to loop over all child elements of a given name. For element access, non-const and const variants exist.

Finally, the load() and save() methods enable loading and saving a XML document from and to disk. The read() and write() method, which do the actual job of reading and writing, operate on general Unified Resource Locators, so that XML documents can also through other media than flat files.

The print() method does not print the full XML document into a string but shows a concise summary that reflects the tree structure. For writing the document in a string, use the write() method to write in a string URL object (GUrlString).

Definition at line 172 of file GXml.hpp.

Member Enumeration Documentation

enum GXml::MarkupType

protected

Enumerator
MT_ELEMENT_START
MT_ELEMENT_END
MT_ELEMENT_EMPTY
MT_COMMENT
MT_DECLARATION
MT_PROCESSING
MT_INVALID

Definition at line 225 of file GXml.hpp.

Constructor & Destructor Documentation

GXml::GXml ( void )

Void constructor.

Definition at line 65 of file GXml.cpp.

References init_members().

Referenced by clone().

GXml::GXml ( const GXml & xml )

Copy constructor.

Parameters

[in] xml XML object.

Definition at line 80 of file GXml.cpp.

References copy_members(), and init_members().

GXml::GXml ( const std::string & xml )

explicit

XML document constructor.

Parameters

[in] xml XML text string or file name.

Constructs GXml object by either parsing a text string or a file. If the xml argument starts with <?xml it is interpreted as a XML file and parsed directly. Otherwise the constructor will interpret xml as a filename, and opens the file for parsing.

Definition at line 103 of file GXml.cpp.

References GUrlString::close(), init_members(), load(), and read().

GXml::GXml ( const GXmlDocument & root )

explicit

Document constructor.

Parameters

[in] root Root document.

Definition at line 130 of file GXml.cpp.

References init_members(), and root().

GXml::~GXml ( void )

virtual

Destructor.

Definition at line 146 of file GXml.cpp.

References free_members().

Member Function Documentation

GXmlNode * GXml::append ( const GXmlNode & node )

Append child node to XML document root.

Parameters

[in] node Child node.

Returns: Pointer to appended child node.

Appends node to XML document root by making a deep copy of the node.

Definition at line 279 of file GXml.cpp.

References GXmlNode::append(), and m_root.

Referenced by GDaemon::create_xml(), GVOTable::read(), GModels::save(), GTestSuites::write(), GObservations::write(), and GModels::write().

GXmlElement * GXml::append ( const std::string & segment )

Append child node to XML document root.

Parameters

[in] segment XML child node.

Returns: Pointer to appended child node.

Appends XML element that is constructed from a text segment. The text segment is parsed and the element name and attributes are extracted using the GXmlElement::parse_start() method. The method returns a pointer to the XML element child node that has been appended.

Definition at line 297 of file GXml.cpp.

References GXmlNode::append(), and m_root.

std::string GXml::classname ( void ) const

inlinevirtual

Return class name.

Returns: String containing the class name ("GXml").

Implements GBase.

Definition at line 255 of file GXml.hpp.

void GXml::clear ( void )

virtual

Clear XML object.

Resets XML object to a clean initial state.

Implements GBase.

Definition at line 232 of file GXml.cpp.

References free_members(), and init_members().

Referenced by GVOTable::init_members(), GVOTable::read(), and read().

GXml * GXml::clone ( void ) const

virtual

Clone XML object.

Returns: Pointer to deep copy of XML object.

Implements GBase.

Definition at line 248 of file GXml.cpp.

References GXml().

void GXml::copy_members ( const GXml & xml )

protected

Copy class members.

Parameters

[in] xml Object from which members which should be copied.

Definition at line 708 of file GXml.cpp.

References m_root.

Referenced by GXml(), and operator=().

GXmlElement * GXml::element ( const int & index )

Return pointer to child element.

Parameters

[in] index Node index [0,...,elements()-1].

Returns: Pointer to child element.

Returns a pointer to the child number index of the XML document root. An exception will be thrown if the index is not valid.

Definition at line 419 of file GXml.cpp.

References GXmlNode::element(), and m_root.

Referenced by GVOHub::get_callback_url(), GVOHub::get_client_key(), GVOHub::get_client_name(), GVOHub::get_mtype(), GVOClient::get_response_value(), GVOHub::get_subscriptions(), GVOHub::handle_request(), GVOHub::notify_image_load(), GVOHub::notify_table_load(), parse(), process_markup(), GObservations::read(), GModels::read(), GVOHub::request_declare_metadata(), GVOClient::response_error_code(), GVOClient::response_error_message(), GVOClient::response_is_valid(), GDaemon::update_countries_data(), GDaemon::update_countries_header(), GDaemon::update_daily(), GDaemon::update_dates(), GDaemon::update_versions_data(), GObservations::write(), and GModels::write().

const GXmlElement * GXml::element ( const int & index ) const

Return pointer to child element (const variant)

Parameters

[in] index Node index [0,...,elements()-1].

Returns: Pointer to child element.

Returns a pointer to the child number index of the XML document root. An exception will be thrown if the index is not valid.

Definition at line 435 of file GXml.cpp.

References GXmlNode::element(), and m_root.

GXmlElement * GXml::element ( const std::string & name )

Return pointer to child element by hierarchy.

Parameters

[in] name Child element hierarchy.

Returns: Pointer to child element.

Returns a pointer to the child element described by a hierarchy of the following syntax

params > param[1] > value > struct

The > symbols indicate subsequent hierarchy levels, the square brackets provides the index in case that multiple tags with the same name exist at a given hierarchy level. Omitting the index means that the first tag with the specified name is accessed.

Definition at line 458 of file GXml.cpp.

References GXmlNode::element(), and m_root.

const GXmlElement * GXml::element ( const std::string & name ) const

Return pointer to child element by hierarchy (const version)

Parameters

[in] name Child element hierarchy.

Returns: Pointer to child element.

Returns a pointer to the child element described by a hierarchy of the following syntax

params > param[1] > value > struct

The > symbols indicate subsequent hierarchy levels, the square brackets provides the index in case that multiple tags with the same name exist at a given hierarchy level. Omitting the index means that the first tag with the specified name is accessed.

Definition at line 481 of file GXml.cpp.

References GXmlNode::element(), and m_root.

GXmlElement * GXml::element	(	const std::string &	name,
		const int &	index
	)

Return pointer to child element of a given name.

Parameters

[in]	name	Name of child element.
[in]	index	Node index [0,...,elements()-1].

Returns: Pointer to child element.

Returns a pointer to the child number index with name of the XML document root. An exception will be thrown if the index is not valid.

Definition at line 498 of file GXml.cpp.

References GXmlNode::element(), and m_root.

const GXmlElement * GXml::element	(	const std::string &	name,
		const int &	index
	)		const

Return pointer to child element of a given name (const variant)

Parameters

[in]	name	Name of child element.
[in]	index	Node index [0,...,elements()-1].

Returns: Pointer to child element.

Returns a pointer to the child number index with name of the XML document root. An exception will be thrown if the index is not valid.

Definition at line 515 of file GXml.cpp.

References GXmlNode::element(), and m_root.

int GXml::elements ( void ) const

Return number of child elements in XML document root.

Returns: Number of child elements in XML document root.

Returns the number of GXmlElement child elements of the XML document root. GXMLElement child elements are nodes of type NT_ELEMENT.

Definition at line 384 of file GXml.cpp.

References GXmlNode::elements(), and m_root.

Referenced by GObservations::write(), and GModels::write().

int GXml::elements ( const std::string & name ) const

Return number of child elements with a given name in XML document root.

Parameters

[in] name Name of child elements.

Returns: Number of child elements with a given name in XML document root.

Returns the number of GXMLElement child elements of the XML document root that have a given name. GXmlElement child elements are nodes of type NT_ELEMENT.

Definition at line 403 of file GXml.cpp.

References GXmlNode::elements(), and m_root.

void GXml::extend ( const GXmlNode & node )

Append all XML child nodes from another XML node in the XML document root.

Parameters

[in] node XML child node.

Append all XML child nodes found in node to the XML document root. Nodes are copied deeply so that they live now on their on in the actual object.

Definition at line 366 of file GXml.cpp.

References GXmlNode::extend(), and m_root.

void GXml::free_members ( void )

protected

Delete class members.

Definition at line 721 of file GXml.cpp.

Referenced by clear(), operator=(), and ~GXml().

GXml::MarkupType GXml::get_markuptype ( const std::string & segment ) const

protected

Get Markup type of segment.

Parameters

[in] segment Segment for which Markup Type should be determined.

Returns Markup Type of segment.

Definition at line 1063 of file GXml.cpp.

References MT_COMMENT, MT_DECLARATION, MT_ELEMENT_EMPTY, MT_ELEMENT_END, MT_ELEMENT_START, MT_INVALID, and MT_PROCESSING.

Referenced by process_markup().

void GXml::init_members ( void )

protected

Initialise class members.

Definition at line 693 of file GXml.cpp.

References GXmlDocument::clear(), and m_root.

Referenced by clear(), GXml(), and operator=().

GXmlNode * GXml::insert	(	const int &	index,
		const GXmlNode &	node
	)

Insert child node into XML document root.

Parameters

[in]	index	Child node index [0,...,size()-1].
[in]	node	XML child node.

Returns: Pointer to inserted child node.

Inserts the XML child node before the node with the specified index. A deep copy of the node will be made and the pointer to this node will be stored.

Definition at line 315 of file GXml.cpp.

References GXmlNode::insert(), and m_root.

bool GXml::is_empty ( void ) const

inlinevirtual

Signals if document has no child nodes.

Returns: True if document has no child nodes.

Implements GContainer.

Definition at line 279 of file GXml.hpp.

References GXmlNode::is_empty(), and m_root.

Referenced by GDaemon::update_statistics().

void GXml::load ( const GFilename & filename )

Load XML document from file.

Parameters

[in] filename File name.

Exceptions

GException::file_error Unable to open file.

Loads a XML document from a file by reading from the file's Unified Resource Locator (URL). The read() method is invoked for this purpose.

The method uses the GUrlFile file opening constructor to open the URL. This constructor will automatically expand any environment variables that are present in the filename.

Todo:: Ideally, we would like to extract the URL type from the filename so that any kind of URL can be used for loading.

Definition at line 540 of file GXml.cpp.

References GFilename::exists(), GXmlDocument::filename(), G_LOAD, m_root, read(), and GFilename::url().

Referenced by GXml(), GDaemon::recover_valid_xml(), and GDaemon::update_statistics().

GXml & GXml::operator= ( const GXml & xml )

Assignment operator.

Parameters

[in] xml XML object.

Returns: XML object.

Definition at line 168 of file GXml.cpp.

References copy_members(), free_members(), and init_members().

GXmlNode * GXml::operator[] ( const int & index )

Return pointer to child of XML document root element.

Parameters

[in] index Node index [0,...,size()-1].

Returns: Pointer to child of XML document root element.

Returns a pointer to the child number index of the XML document root element. An exception will be thrown if the index is not valid.

Definition at line 198 of file GXml.cpp.

References m_root.

const GXmlNode * GXml::operator[] ( const int & index ) const

Return pointer to child of XML document root element (const variant)

Parameters

[in] index Node index [0,...,size()-1].

Returns: Pointer to child of XML document root element.

Returns a pointer to the child number index of the XML document root element. An exception will be thrown if the index is not valid.

Definition at line 214 of file GXml.cpp.

References m_root.

void GXml::parse ( const GUrl & url )

protected

Parse XML URL.

Parameters

[in] url Unified Resource Locator.

Exceptions

GException::invalid_value XML syntax error.

Parses either a XML file or a XML text string and creates all associated nodes. The XML file is split into segments, made either of text or of tags.

Definition at line 740 of file GXml.cpp.

References element(), G_PARSE, GUrl::get_char(), m_root, GXmlElement::name(), process_markup(), process_text(), and gammalib::str().

Referenced by read().

std::string GXml::print ( const GChatter & chatter = NORMAL ) const

virtual

Print XML object.

Parameters

[in] chatter Chattiness.

Returns: String containing XML object.

Implements GBase.

Definition at line 674 of file GXml.cpp.

Referenced by GVOTable::print().

std::string GXml::print	(	const GChatter &	chatter = `NORMAL`,
		const int &	indent = `0`
	)		const

Print XML object.

Parameters

[in]	chatter	Chattiness.
[in]	indent	Text indentation.

Returns: String containing XML object.

Definition at line 647 of file GXml.cpp.

References m_root, GXmlDocument::print(), and SILENT.

void GXml::process_markup	(	GXmlNode **	current,
		const std::string &	segment
	)

protected

Process markup segment.

Parameters

[in]	current	Handle to current node.
[in]	segment	Segment string.

Exceptions

GException::invalid_value XML syntax error encoutered.

Process markup segment.

Definition at line 898 of file GXml.cpp.

References GXmlNode::append(), GXmlElement::attribute(), element(), GXmlDocument::encoding(), G_PROCESS, get_markuptype(), GXmlNode::is_empty(), m_root, MT_COMMENT, MT_DECLARATION, MT_ELEMENT_EMPTY, MT_ELEMENT_END, MT_ELEMENT_START, MT_INVALID, MT_PROCESSING, GXmlNode::NT_ELEMENT, GXmlNode::parent(), GXmlElement::parse_attribute(), GXmlElement::parse_stop(), gammalib::pi, GXmlNode::size(), GXmlDocument::standalone(), and GXmlDocument::version().

Referenced by parse().

void GXml::process_text	(	GXmlNode **	current,
		const std::string &	segment
	)

protected

Process text segment.

Parameters

[in]	current	Handle to current node.
[in]	segment	Segment string.

Process text segment.

Definition at line 1035 of file GXml.cpp.

References GXmlText.

Referenced by parse().

void GXml::read ( const GUrl & url )

Read XML document from URL.

Parameters

[in] url Unified Resource Locator.

Reads in the XML document by parsing a Unified Resource Locator of any type.

Definition at line 608 of file GXml.cpp.

References clear(), and parse().

Referenced by GXml(), and load().

void GXml::remove ( const int & index )

virtual

Remove child node from XML document root.

Parameters

[in] index Child node index [0,...,size()-1].

Remove XML child node at index from the XML document root.

Implements GContainer.

Definition at line 329 of file GXml.cpp.

References m_root, and GXmlNode::remove().

void GXml::reserve ( const int & num )

virtual

Reserve space for child nodes in XML document root.

Parameters

[in] num Number of nodes.

Reserves space for num nodes in the XML document root.

Implements GContainer.

Definition at line 346 of file GXml.cpp.

References m_root, and GXmlNode::reserve().

const GXmlDocument & GXml::root ( void ) const

inline

Return document root.

Returns: Document root.

Definition at line 291 of file GXml.hpp.

References m_root.

Referenced by GXml(), and root().

void GXml::root ( const GXmlDocument & root )

inline

Set document root.

Parameters

[in] root Document root.

Definition at line 303 of file GXml.hpp.

References m_root, and root().

void GXml::save ( const GFilename & filename ) const

Save XML document into file.

Parameters

[in] filename File name.

Saves the XML document into a file by writing into the file's Unified Resource Locator (URL). The write() method is invoked for this purpose.

The method uses the GUrlFile file opening constructor to open the URL. This constructor will automatically expand any environment variables that are present in the filename.

Todo:: Ideally, we would like to extract the URL type from the filename so that any kind of URL can be used for loading.

Definition at line 581 of file GXml.cpp.

References GUrlFile::close(), m_root, GFilename::url(), and write().

Referenced by GDaemon::create_xml(), GVOClient::publish(), GDaemon::recover_valid_xml(), GTestSuites::save(), GObservations::save(), GModels::save(), and GDaemon::update_statistics().

GXmlNode * GXml::set	(	const int &	index,
		const GXmlNode &	node
	)

Set child node in XML document root.

Parameters

[in]	index	Child node index [0,...,size()-1].
[in]	node	XML child node.

Returns: Pointer to deep copy of child node.

Set node with index of XML document root.

Definition at line 264 of file GXml.cpp.

References m_root, and GXmlNode::set().

int GXml::size ( void ) const

inlinevirtual

Return number of child nodes.

Returns: Number of child nodes in node.

Implements GContainer.

Definition at line 267 of file GXml.hpp.

References m_root, and GXmlNode::size().

void GXml::write	(	GUrl &	url,
		const int &	indent = `0`
	)		const

Write XML document into URL.

Parameters

[in]	url	Unified Resource Locator.
[in]	indent	Indentation (default = 0).

Writes the XML document in a Unified Resource Locator. Formatting of the document can be adapted using the indent parameter.

Definition at line 630 of file GXml.cpp.

References m_root, and GXmlDocument::write().

Referenced by save().

Friends And Related Function Documentation

friend class GXmlDocument

friend

Definition at line 176 of file GXml.hpp.

friend class GXmlNode

friend

Definition at line 175 of file GXml.hpp.

friend class GXmlText

friend

Definition at line 177 of file GXml.hpp.

Referenced by process_text().

Member Data Documentation

GXmlDocument GXml::m_root

protected

Root document node.

Definition at line 245 of file GXml.hpp.

Referenced by append(), copy_members(), element(), elements(), extend(), init_members(), insert(), is_empty(), load(), operator[](), parse(), print(), process_markup(), remove(), reserve(), root(), save(), set(), size(), and write().

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

include/GXml.hpp
src/xml/GXml.cpp

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation