source: rrlib_xml/tDocument.h

17.03 tip
Last change on this file was 63:6e56f95badd3, checked in by Jens Wettach <wettach@…>, 3 years ago

added a function for searching a node in an XML document, added corresponding test cases

File size: 8.6 KB
Line 
1//
2// You received this file as part of RRLib
3// Robotics Research Library
4//
5// Copyright (C) Finroc GbR (finroc.org)
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 2 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 along
18// with this program; if not, write to the Free Software Foundation, Inc.,
19// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
20//
21//----------------------------------------------------------------------
22/*!\file    rrlib/xml/tDocument.h
23 *
24 * \author  Tobias Foehst
25 *
26 * \date    2010-09-18
27 *
28 * \brief   Contains tDocument
29 *
30 * \b tDocument
31 *
32 * If an XML document is loaded for full access to its content, a DOM
33 * tree is generated consisting of nodes of with attributes. This class
34 * implements parsing and validating an XML file as well as accessing
35 * the DOM tree through instances of tNode, featuring lazy evaluation.
36 * That means wrapping instances are not created before they are used.
37 *
38 */
39//----------------------------------------------------------------------
40#ifndef __rrlib__xml__tDocument_h__
41#define __rrlib__xml__tDocument_h__
42
43//----------------------------------------------------------------------
44// External includes (system with <>, local with "")
45//----------------------------------------------------------------------
46#include <string>
47
48extern "C"
49{
50#include <libxml/tree.h>
51}
52//----------------------------------------------------------------------
53// Internal includes with ""
54//----------------------------------------------------------------------
55#include "rrlib/xml/tNode.h"
56
57//----------------------------------------------------------------------
58// Debugging
59//----------------------------------------------------------------------
60
61//----------------------------------------------------------------------
62// Namespace declaration
63//----------------------------------------------------------------------
64namespace rrlib
65{
66namespace xml
67{
68
69//----------------------------------------------------------------------
70// Forward declarations / typedefs / enums
71//----------------------------------------------------------------------
72
73//----------------------------------------------------------------------
74// Class declaration
75//----------------------------------------------------------------------
76//! This class wraps creation and accessing the DOM tree of an XML document
77/*! If an XML document is loaded for full access to its content, a DOM
78 *  tree is generated consisting of nodes with attributes. This class
79 *  implements parsing and validating an XML file as well as accessing
80 *  the DOM tree through instances of tNode, featuring lazy evaluation.
81 *  That means wrapping instances are not created before they are used.
82 *
83 */
84class tDocument
85{
86
87//----------------------------------------------------------------------
88// Public methods and typedefs
89//----------------------------------------------------------------------
90public:
91
92  /*! The ctor of an empty tDocument
93   *
94   * This ctor creates a new xml document
95   */
96  tDocument();
97
98  /*! The ctor of tDocument from a given file
99   *
100   * This ctor reads and parses a file with given name into a XML DOM
101   * representation.
102   * If needed, the XML document is also validated using an included
103   * DTD specification.
104   *
105   * \exception tException is thrown if the file was not found or could not be parsed
106   *
107   * \param file_name   The name of the file to load
108   * \param validate    Whether the validation should be processed or not
109   */
110  explicit tDocument(const std::string &file_name, bool validate = true);
111
112  /*! The ctor of tDocument from a given file with explicit encoding
113   *
114   * This ctor reads and parses a file with given name into a XML DOM
115   * representation.
116   * If needed, the XML document is also validated using an included
117   * DTD specification.
118   *
119   * \exception tException is thrown if the file was not found or could not be parsed
120   *
121   * \param file_name   The name of the file to load
122   * \param encoding    The encoding of the input file
123   * \param validate    Whether the validation should be processed or not
124   */
125  explicit tDocument(const std::string &file_name, const std::string &encoding, bool validate = true);
126
127  /*! The ctor of tDocument from a memory buffer
128   *
129   * This ctor reads and parses XML content given in a memory buffer into a XML DOM
130   * representation.
131   * If needed, the XML document is also validated using an included
132   * DTD specification.
133   *
134   * \exception tException is thrown if the memory buffer could not be parsed
135   *
136   * \param buffer      Pointer to the memory buffer with XML content to be parsed
137   * \param size        Size of the memory buffer
138   * \param validate    Whether the validation should be processed or not
139   */
140  tDocument(const void *buffer, size_t size, bool validate = true);
141
142  /*! The ctor of tDocument from a memory buffer with explicit encoding
143   *
144   * This ctor reads and parses XML content given in a memory buffer into a XML DOM
145   * representation.
146   * If needed, the XML document is also validated using an included
147   * DTD specification.
148   *
149   * \exception tException is thrown if the memory buffer could not be parsed
150   *
151   * \param buffer      Pointer to the memory buffer with XML content to be parsed
152   * \param size        Size of the memory buffer
153   * \param encoding    The encoding of the input file
154   * \param validate    Whether the validation should be processed or not
155   */
156  tDocument(const void *buffer, size_t size, const std::string &encoding, bool validate = true);
157
158  /*!
159   * move constructor
160   */
161  tDocument(tDocument && other);
162
163  /*! The dtor of tDocument
164   */
165  ~tDocument();
166
167  /*! Assign operator for tDocument
168   */
169  tDocument& operator=(const tDocument& other);
170
171  /*! Get the root node of the DOM tree stored for this document
172   *
173   * The XML document is stored as DOM tree in memory. This method
174   * provides node-wise access to this tree starting at its root.
175   *
176   * \returns A reference to the root node
177   */
178  tNode &RootNode();
179
180  inline const tNode &RootNode() const
181  {
182    return const_cast<tDocument *>(this)->RootNode();
183  }
184
185  /*! Add a root node to a new document in DOM representation
186   *
187   * If you create a new XML document the first thing to do is to
188   * add a root node with a specified name. After that, the root node
189   * is fixed and additional calls to this method will throw an exception.
190   *
191   * \exception tException is thrown if the document already had a root node
192   *
193   * \param name   The name of the root node
194   *
195   * \returns A reference to the newly created root node
196   */
197  tNode &AddRootNode(const std::string &name);
198
199
200  /*! Find a node in this XML document via a path in DOM tree representation
201   *
202   * Given a path to the searched node, an xpath query is executed
203   * on the DOM tree representation of this document in order to locate
204   * the respective XML node. If the query is successful, a reference
205   * to the node is returned, otherwise an exception is thrown.
206   *
207   * \exception tException is thrown if the query cannot be executed or the node cannot be found
208   *
209   * \param name   The path to the searched node in the DOM tree of this document
210   *
211   * \returns A reference to the found node
212   */
213  const tNode &FindNode(const std::string &name) const;
214
215
216  /*! Write the XML document to a file
217   *
218   * This method creates or truncates a file with the given name and writes
219   * the documents XML representation into it.
220   *
221   * \param file_name     The name of the file to use
222   * \param compression   Compression level [0-9] where 0 is "no compression"
223   */
224  void WriteToFile(const std::string &file_name, int compression = 0) const;
225
226//----------------------------------------------------------------------
227// Private fields and methods
228//----------------------------------------------------------------------
229private:
230
231  xmlDocPtr document;
232  mutable tNode *root_node;
233
234  tDocument(const tDocument&); // generated copy-constructor is not safe
235
236  void CheckIfDocumentIsValid(const std::string &exception_message);
237
238};
239
240//----------------------------------------------------------------------
241// End of namespace declaration
242//----------------------------------------------------------------------
243}
244}
245
246#endif
Note: See TracBrowser for help on using the repository browser.