source: rrlib_xml/tDocument.h @ 67:eb1176488313

17.03
Last change on this file since 67:eb1176488313 was 67:eb1176488313, checked in by Max Reichardt <mreichardt@…>, 3 years ago

Merge with 14.08

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