GammaLib  1.7.0.dev
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
GXml Class Reference

XML class. More...

#include <GXml.hpp>

Inheritance diagram for GXml:
GContainer GBase

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...
 
GXmloperator= (const GXml &xml)
 Assignment operator. More...
 
GXmlNodeoperator[] (const int &index)
 Return pointer to child of XML document root element. More...
 
const GXmlNodeoperator[] (const int &index) const
 Return pointer to child of XML document root element (const variant) More...
 
void clear (void)
 Clear XML object. More...
 
GXmlclone (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...
 
GXmlNodeset (const int &index, const GXmlNode &node)
 Set child node in XML document root. More...
 
GXmlNodeappend (const GXmlNode &node)
 Append child node to XML document root. More...
 
GXmlElementappend (const std::string &segment)
 Append child node to XML document root. More...
 
GXmlNodeinsert (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...
 
GXmlElementelement (const int &index)
 Return pointer to child element. More...
 
const GXmlElementelement (const int &index) const
 Return pointer to child element (const variant) More...
 
GXmlElementelement (const std::string &name)
 Return pointer to child element by hierarchy. More...
 
const GXmlElementelement (const std::string &name) const
 Return pointer to child element by hierarchy (const version) More...
 
GXmlElementelement (const std::string &name, const int &index)
 Return pointer to child element of a given name. More...
 
const GXmlElementelement (const std::string &name, const int &index) const
 Return pointer to child element of a given name (const variant) More...
 
const GXmlDocumentroot (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:

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]xmlXML 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]xmlXML 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]rootRoot 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]nodeChild 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 GVOTable::read(), GTestSuites::write(), GObservations::write(), and GModels::write().

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

Append child node to XML document root.

Parameters
[in]segmentXML 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]xmlObject from which members which should be copied.

Definition at line 703 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]indexNode 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(), GObservations::write(), and GModels::write().

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

Return pointer to child element (const variant)

Parameters
[in]indexNode 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]nameChild 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]nameChild 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]nameName of child element.
[in]indexNode 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]nameName of child element.
[in]indexNode 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]nameName 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]nodeXML 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 716 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]segmentSegment for which Markup Type should be determined.

Returns Markup Type of segment.

Definition at line 1039 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 688 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]indexChild node index [0,...,size()-1].
[in]nodeXML 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.

void GXml::load ( const GFilename filename)

Load XML document from file.

Parameters
[in]filenameFile name.

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 537 of file GXml.cpp.

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

Referenced by GXml().

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

Assignment operator.

Parameters
[in]xmlXML 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]indexNode 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]indexNode 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]urlUnified Resource Locator.
Exceptions
GException::xml_syntax_errorXML 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 735 of file GXml.cpp.

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

Referenced by read().

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

Print XML object.

Parameters
[in]chatterChattiness.
Returns
String containing XML object.

Implements GBase.

Definition at line 669 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]chatterChattiness.
[in]indentText indentation.
Returns
String containing XML object.

Definition at line 642 of file GXml.cpp.

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

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

Process text segment.

Parameters
[in]currentHandle to current node.
[in]segmentSegment string.

Process text segment.

Definition at line 1011 of file GXml.cpp.

References GXmlText.

Referenced by parse().

void GXml::read ( const GUrl url)

Read XML document from URL.

Parameters
[in]urlUnified Resource Locator.

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

Definition at line 603 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]indexChild 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]numNumber 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]rootDocument 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]filenameFile 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 576 of file GXml.cpp.

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

Referenced by GVOClient::publish(), GTestSuites::save(), GObservations::save(), and GModels::save().

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

Set child node in XML document root.

Parameters
[in]indexChild node index [0,...,size()-1].
[in]nodeXML 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]urlUnified Resource Locator.
[in]indentIndentation (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 625 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

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