From cbbda19a1cf93ce8b5d9f0a72db5812db70e15d2 Mon Sep 17 00:00:00 2001 From: Jürgen Knödlseder Date: Sun, 24 Nov 2013 18:05:00 +0100 Subject: [PATCH] Add XML documentation and example file. --- doc/source/user_manual/modules/uml_xml.png | Bin 0 -> 26664 bytes doc/source/user_manual/modules/xml.rst | 2 +- examples/cpp/createxml/Makefile | 8 ++++++++ examples/cpp/createxml/createxml | Bin 0 -> 20840 bytes examples/cpp/createxml/createxml.cpp | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 90 insertions(+), 1 deletion(-) create mode 100644 doc/source/user_manual/modules/uml_xml.png create mode 100644 examples/cpp/createxml/Makefile create mode 100755 examples/cpp/createxml/createxml create mode 100644 examples/cpp/createxml/createxml.cpp diff --git a/doc/source/user_manual/modules/uml_xml.png b/doc/source/user_manual/modules/uml_xml.png new file mode 100644 index 0000000..e8b55e8 Binary files /dev/null and b/doc/source/user_manual/modules/uml_xml.png differ diff --git a/doc/source/user_manual/modules/xml.rst b/doc/source/user_manual/modules/xml.rst index 5330b67..ace2e30 100644 --- a/doc/source/user_manual/modules/xml.rst +++ b/doc/source/user_manual/modules/xml.rst @@ -1 +1 @@ -.. _sec_xml: XML file interface ------------------ \ No newline at end of file +.. _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(""); 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:: Finish with text 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. \ No newline at end of file diff --git a/examples/cpp/createxml/Makefile b/examples/cpp/createxml/Makefile new file mode 100644 index 0000000..a4bf964 --- /dev/null +++ b/examples/cpp/createxml/Makefile @@ -0,0 +1,8 @@ +CXX=g++ +CFLAGS=-I/usr/local/gamma/include/gammalib +LDFLAGS=-L/usr/local/gamma/lib -lgamma +DEPS= +OBJ=createxml.cpp + +createxml: $(OBJ) + $(CXX) -o $@ $^ $(CFLAGS) $(LDFLAGS) diff --git a/examples/cpp/createxml/createxml b/examples/cpp/createxml/createxml new file mode 100755 index 0000000..d244b66 Binary files /dev/null and b/examples/cpp/createxml/createxml differ diff --git a/examples/cpp/createxml/createxml.cpp b/examples/cpp/createxml/createxml.cpp new file mode 100644 index 0000000..b360b33 --- /dev/null +++ b/examples/cpp/createxml/createxml.cpp @@ -0,0 +1,81 @@ +/*************************************************************************** + * createxml.cpp - Create XML file * + * ----------------------------------------------------------------------- * + * copyright (C) 2013 by Juergen Knoedlseder * + * ----------------------------------------------------------------------- * + * * + * This program is free software: you can redistribute it and/or modify * + * it under the terms of the GNU General Public License as published by * + * the Free Software Foundation, either version 3 of the License, or * + * (at your option) any later version. * + * * + * This program is distributed in the hope that it will be useful, * + * but WITHOUT ANY WARRANTY; without even the implied warranty of * + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * + * GNU General Public License for more details. * + * * + * You should have received a copy of the GNU General Public License * + * along with this program. If not, see . * + * * + ***************************************************************************/ +/** + * @file createxml.cpp + * @brief Create XML file + * @author Juergen Knoedlseder + */ + +/* __ Includes ___________________________________________________________ */ +#include "GammaLib.hpp" + + +/***********************************************************************//** + * @brief Create XML file + * + * This code illustrates the creation of a XML file. + ***************************************************************************/ +int main(void) { + + // Allocate XML object + GXml xml; + + // Create base elements + GXmlComment comment("Now 2 nodes with spatial and spectral info"); + GXmlElement spatial("spatial type=\"Position\""); + GXmlElement spectral("spectrum type=\"PowerLaw\""); + GXmlElement text("text"); + GXmlPI pi(""); + + // Append spatial parameters + spatial.append(GXmlElement("parameter ra=\"83.0\"")); + spatial.append(GXmlElement("parameter dec=\"22.0\"")); + + // Append spectral parameters + spectral.append(GXmlElement("parameter prefactor=\"1e-7\"")); + spectral.append(GXmlElement("parameter index=\"-2.1\"")); + + // Append text + text.append(GXmlText("Finish with text")); + + // Append elements + xml.append(comment); + xml.append(spatial); + xml.append(spectral); + xml.append(text); + xml.append(pi); + + // Manipulate source element + xml.element("spatial", 0)->append(GXmlElement("parameter ra=\"83.0\"")); + xml.element("spatial", 0)->append(GXmlElement("parameter dec=\"22.0\"")); + + // Show alternative access + GXmlNode* node = xml.append(spatial); + node->append(GXmlElement("parameter ra=\"83.0\"")); + node->append(GXmlElement("parameter dec=\"22.0\"")); + + // Save XML document to file + xml.save("my_xml_file.xml"); + + // Exit + return 0; +} + -- libgit2 0.21.4