Jürgen Knödlseder / gammalib

Commit cbbda19a1cf93ce8b5d9f0a72db5812db70e15d2

Authored by Jürgen Knödlseder
1 parent ddd6fc57

Add XML documentation and example file.

Inline Side-by-side
Showing 5 changed files with 90 additions and 1 deletions
doc/source/user_manual/modules/uml_xml.png 0 → 100644
View file @cbbda19

26 KB
doc/source/user_manual/modules/xml.rst
  View file @cbbda19
1   -.. _sec_xml: XML file interface ------------------
2 1 \ No newline at end of file
  2 +.. _sec_xml: XML file interface ------------------ Overview ~~~~~~~~ :ref:`fig_uml_xml` present an overview over the C++ classes of the XML module and their relations. .. _fig_uml_xml: .. figure:: uml_xml.png :width: 100% XML module The XML module provides classes that allow creation, writing and reading of files in the Extensible Markup Language (XML) format. The central class of the XML module is the abstract ``GXmlNode`` base class which represent a node of the XML document. The essential property of ``GXmlNode`` is that it may contain a list of ``GXmlNode`` objects, allowing creating a complex tree of data structures. Nodes in a XML document may be either elements, comments, some text of a processing instruction. These different node types are implemented by the ``GXmlElement``, ``GXmlComment``, ``GXmlText`` and ``GXmlPI`` classes, respectively. A special node if the ``GXmlDocument`` node which provides the root node of a XML document. This node must exist only once in a XML tree. The XML file is implement by the ``GXml`` class which contains one instance of ``GXmlDocument``. Creating a XML file ~~~~~~~~~~~~~~~~~~~ The following example illustrates the creation of a XML file (see ``examples/createxml.cpp`` for the source code; the line numbers are for reference and are not part of the source code):: 1 GXml xml; 2 GXmlComment comment("Now 2 nodes with spatial and spectral info"); 3 GXmlElement spatial("spatial type=\"Position\""); 4 GXmlElement spectral("spectrum type=\"PowerLaw\""); 5 GXmlElement text("text"); 6 GXmlPI pi("<?process now?>"); 7 spatial.append(GXmlElement("parameter ra=\"83.0\"")); 8 spatial.append(GXmlElement("parameter dec=\"22.0\"")); 9 spectral.append(GXmlElement("parameter prefactor=\"1e-7\"")); 10 spectral.append(GXmlElement("parameter index=\"-2.1\"")); 11 text.append(GXmlText("Finish with text")); 12 xml.append(comment); 13 xml.append(spatial); 14 xml.append(spectral); 15 xml.append(text); 16 xml.append(pi); 17 xml.save("my_xml_file.xml"); Below the content of the XML file that will be created by this code:: <?xml version="1.0" encoding="UTF-8" standalone="no"?> <!--Now 2 nodes with spatial and spectral info--> <spatial type="Position"> <parameter ra="83.0" /> <parameter dec="22.0" /> </spatial> <spectrum type="PowerLaw"> <parameter prefactor="1e-7" /> <parameter index="-2.1" /> </spectrum> <text>Finish with text</text> <?process now?> In line 1 a XML object if allocated. In lines 2-6, one comment node, three element nodes and one processing instruction node are created. For the comment node, the comment text is provided in the ``GXmlComment`` constructor. For the element nodes, the element tag as well as any attributes (separated by whitespace characters) are provided in the ``GElement`` constructor. For the processing instruction node, the instruction including the brackets are provided in the ``GXmlPI`` constructor. In lines 7-8, two element nodes providing spatial parameters are appended to the ``spatial`` node. In lines 9-10, parameters are appended to the ``spectral`` node. And in line 11, a text node is appended to the ``text`` node. Finally, the nodes are appended in lines 12-16 to the document root, and the XML file is saved in line 17. Note that in the above example the entire XML tree has been constructed before the nodes were appended to the document root. The reason behind this approach is that the ``append`` method creates deep copies of the nodes provided in the argument, hence manipulation of the node once appended requires to retrieve the pointers to the deep copies in the XML document. The following example illustrates how this can be done:: xml.append(GXmlElement("source type=\"PointSource\"")); xml.element("spatial", 0)->append(GXmlElement("parameter ra=\"83.0\"")); xml.element("spatial", 0)->append(GXmlElement("parameter dec=\"22.0\"")); The ``xml.element("spatial", 0)`` method returns a pointer to the first ``GXmlElement`` node with tag ``spatial`` in the XML document. Now that we have a pointer to the nodes, elements can be appended to the XML document using the ``append`` method. Alternatively, one can also retrieve the node pointer when the node is appended to the XML document:: GXmlNode* node = xml.append(GXmlElement("source type=\"PointSource\"")); node->append(GXmlElement("parameter ra=\"83.0\"")); node->append(GXmlElement("parameter dec=\"22.0\"")); The ``append`` method returns in fact the pointer to the deep copy of the element that has been appended. This pointer can then be used to manipulate directly the nodes in the XML document.
3 3 \ No newline at end of file
... ...
examples/cpp/createxml/Makefile 0 → 100644
  View file @cbbda19
  1 +CXX=g++
  2 +CFLAGS=-I/usr/local/gamma/include/gammalib
  3 +LDFLAGS=-L/usr/local/gamma/lib -lgamma
  4 +DEPS=
  5 +OBJ=createxml.cpp
  6 +
  7 +createxml: $(OBJ)
  8 + $(CXX) -o $@ $^ $(CFLAGS) $(LDFLAGS)
... ...
examples/cpp/createxml/createxml 0 → 100755
View file @cbbda19
No preview for this file type
examples/cpp/createxml/createxml.cpp 0 → 100644
  View file @cbbda19
  1 +/***************************************************************************
  2 + * createxml.cpp - Create XML file *
  3 + * ----------------------------------------------------------------------- *
  4 + * copyright (C) 2013 by Juergen Knoedlseder *
  5 + * ----------------------------------------------------------------------- *
  6 + * *
  7 + * This program is free software: you can redistribute it and/or modify *
  8 + * it under the terms of the GNU General Public License as published by *
  9 + * the Free Software Foundation, either version 3 of the License, or *
  10 + * (at your option) any later version. *
  11 + * *
  12 + * This program is distributed in the hope that it will be useful, *
  13 + * but WITHOUT ANY WARRANTY; without even the implied warranty of *
  14 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
  15 + * GNU General Public License for more details. *
  16 + * *
  17 + * You should have received a copy of the GNU General Public License *
  18 + * along with this program. If not, see <http://www.gnu.org/licenses/>. *
  19 + * *
  20 + ***************************************************************************/
  21 +/**
  22 + * @file createxml.cpp
  23 + * @brief Create XML file
  24 + * @author Juergen Knoedlseder
  25 + */
  26 +
  27 +/* __ Includes ___________________________________________________________ */
  28 +#include "GammaLib.hpp"
  29 +
  30 +
  31 +/***********************************************************************//**
  32 + * @brief Create XML file
  33 + *
  34 + * This code illustrates the creation of a XML file.
  35 + ***************************************************************************/
  36 +int main(void) {
  37 +
  38 + // Allocate XML object
  39 + GXml xml;
  40 +
  41 + // Create base elements
  42 + GXmlComment comment("Now 2 nodes with spatial and spectral info");
  43 + GXmlElement spatial("spatial type=\"Position\"");
  44 + GXmlElement spectral("spectrum type=\"PowerLaw\"");
  45 + GXmlElement text("text");
  46 + GXmlPI pi("<?process now?>");
  47 +
  48 + // Append spatial parameters
  49 + spatial.append(GXmlElement("parameter ra=\"83.0\""));
  50 + spatial.append(GXmlElement("parameter dec=\"22.0\""));
  51 +
  52 + // Append spectral parameters
  53 + spectral.append(GXmlElement("parameter prefactor=\"1e-7\""));
  54 + spectral.append(GXmlElement("parameter index=\"-2.1\""));
  55 +
  56 + // Append text
  57 + text.append(GXmlText("Finish with text"));
  58 +
  59 + // Append elements
  60 + xml.append(comment);
  61 + xml.append(spatial);
  62 + xml.append(spectral);
  63 + xml.append(text);
  64 + xml.append(pi);
  65 +
  66 + // Manipulate source element
  67 + xml.element("spatial", 0)->append(GXmlElement("parameter ra=\"83.0\""));
  68 + xml.element("spatial", 0)->append(GXmlElement("parameter dec=\"22.0\""));
  69 +
  70 + // Show alternative access
  71 + GXmlNode* node = xml.append(spatial);
  72 + node->append(GXmlElement("parameter ra=\"83.0\""));
  73 + node->append(GXmlElement("parameter dec=\"22.0\""));
  74 +
  75 + // Save XML document to file
  76 + xml.save("my_xml_file.xml");
  77 +
  78 + // Exit
  79 + return 0;
  80 +}
  81 +
... ...