MezzanineEngine 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
document.h
Go to the documentation of this file.
1 // © Copyright 2010 - 2014 BlackTopp Studios Inc.
2 /* This file is part of The Mezzanine Engine.
3 
4  The Mezzanine Engine is free software: you can redistribute it and/or modify
5  it under the terms of the GNU General Public License as published by
6  the Free Software Foundation, either version 3 of the License, or
7  (at your option) any later version.
8 
9  The Mezzanine Engine is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY; without even the implied warranty of
11  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12  GNU General Public License for more details.
13 
14  You should have received a copy of the GNU General Public License
15  along with The Mezzanine Engine. If not, see <http://www.gnu.org/licenses/>.
16 */
17 /* The original authors have included a copy of the license specified above in the
18  'Docs' folder. See 'gpl.txt'
19 */
20 /* We welcome the use of the Mezzanine engine to anyone, including companies who wish to
21  Build professional software and charge for their product.
22 
23  However there are some practical restrictions, so if your project involves
24  any of the following you should contact us and we will try to work something
25  out:
26  - DRM or Copy Protection of any kind(except Copyrights)
27  - Software Patents You Do Not Wish to Freely License
28  - Any Kind of Linking to Non-GPL licensed Works
29  - Are Currently In Violation of Another Copyright Holder's GPL License
30  - If You want to change our code and not add a few hundred MB of stuff to
31  your distribution
32 
33  These and other limitations could cause serious legal problems if you ignore
34  them, so it is best to simply contact us or the Free Software Foundation, if
35  you have any questions.
36 
37  Joseph Toppi - toppij@gmail.com
38  John Blackwood - makoenergy02@gmail.com
39 */
40 /*
41  *
42  * Software, Files, Libraries and all other items referenced in this clause refers only
43  * to the contents of this file and associated documentation.
44  *
45  * Pugixml parser - version 1.0
46  * --------------------------------------------------------
47  * Copyright © 2006-2012, by Arseny Kapoulkine (arseny.kapoulkine@gmail.com)
48  * Report bugs and download new versions at http://pugixml.org/
49  *
50  * This library is distributed under the MIT License. See notice at the end
51  * of this file.
52  *
53  * This work is based on the pugxml parser, which is:
54  * Copyright © 2003, by Kristen Wegner (kristen@tima.net)
55  */
56 #ifndef _xmldocument_h
57 #define _xmldocument_h
58 
59 /// @file
60 /// @brief The definition of the XML::Document Class
61 
62 #include "datatypes.h"
63 
64 #include "XML/xmlenumerations.h"
65 #include "XML/parseresult.h"
66 #include "XML/node.h"
67 #include "XML/writer.h"
68 
69 
70 #ifndef SWIG
71 #include "Resource/datastream.h"
72 #endif
73 
74 
75 
76 namespace Mezzanine
77 {
78  namespace XML
79  {
80  /// @brief The root node of any xml hierarchy is a @ref Document
81  /// @details This has all the same features as a Node and include a few features for saving, loading, streaming
82  /// and to a limited degree managing the document declaration.
83  class MEZZ_LIB Document: public Node
84  {
85  private:
86  /// @internal
87  /// @brief Almost all of the XML Text is stored in this.
88  Char8* _buffer;
89 
90  /// @internal
91  /// @brief Used when initializining for storing parts of pages
92  char _memory[192];
93 
94 
95  /// @brief Private copy constructor to make this non-copyable.
96  Document(const Document&);
97 
98  /// @brief Private assignment operator enforces non-assignability.
99  const Document& operator=(const Document&);
100 
101  /// @internal
102  /// @brief Performs all required memory allocation for construction.
103  void create();
104 
105  /// @internal
106  /// @brief De-allocates Every allocated durign normal use and the Document::create funciton.
107  void destroy();
108 
109  /// @internal
110  /// @brief The implementation for the different functions that load rom buffers.
111  /// @param contents The Buffer
112  /// @param size The size of the buffer in bytes
113  /// @param options A bitmask of parsing options as declared in @ref xmlenumerations.h
114  /// @param DocumentEncoding Value used to determine if we need to guess encoding or use this or a variant of this.
115  /// @param is_mutable can we changethe buffer or do we need to write changes elsewhere
116  /// @param own Does the XML system own this now?
117  ParseResult LoadBufferImpl(void* contents, size_t size, unsigned int options, Encoding DocumentEncoding, bool is_mutable, bool own);
118 
119  public:
120  /// @brief Creates an empty document with just a root Node
121  Document();
122 
123  /// @brief Tears down a document, and incidentally invalidates all Node and Attribute handles to this document.
124  virtual ~Document();
125 
126  /// @brief Removes all nodes, leaving the empty document.
127  void Reset();
128 
129  /// @brief Removes all nodes, then copies the entire contents of the specified document
130  /// @param proto The Document to copy.
131  void Reset(const Document& proto);
132 
133  #ifndef SWIG_SAFE
134  /// @brief Load a document from a data stream.
135  /// @param stream The stream to load from.
136  /// @param options A bitset of parse options that should be set using the Parse variables. This Defaults to ParseDefault.
137  /// @param DocumentEncoding What kind of text is in the stream, this defaults to Encoding::EncodingAuto
138  /// @return A ParseResult that stores the the outcome of attempting to load the document.
139  /// @note Not available in the 'Safe' scripting languages because of the file access it provides
140  ParseResult Load(Resource::DataStream& stream, unsigned int options = ParseDefault, Encoding DocumentEncoding = EncodingAuto);
141 
142  /// @brief Load XML from a stream.
143  /// @param stream An std::istream which has xml text in it.
144  /// @param options A bitset of parse options that should be set using the Parse variables. This Defaults to ParseDefault.
145  /// @param DocumentEncoding What kind of text is in the stream, this defaults to Encoding::EncodingAuto
146  /// @return A ParseResult that stores the the outcome of attempting to load the document.
147  /// @note Not available in the 'Safe' scripting languages because of the file access it could provide.
148  ParseResult Load(std::basic_istream<char, std::char_traits<char> >& stream, unsigned int options = ParseDefault, Encoding DocumentEncoding = EncodingAuto);
149 
150  /// @brief Load XML from a wide stream.
151  /// @param stream An std::basic_istream which has xml wide character text in it.
152  /// @param options A bitset of parse options that should be set using the Parse variables. This Defaults to ParseDefault.
153  /// @return A ParseResult that stores the the outcome of attempting to load the document.
154  /// @note Not available in the 'Safe' scripting languages because of the file access it could provide.
155  ParseResult Load(std::basic_istream<wchar_t, std::char_traits<wchar_t> >& stream, unsigned int options = ParseDefault);
156  #endif
157 
158  /// @brief Load XML from a C-style string.
159  /// @param contents A pointer to the Null terminated array of Characters.
160  /// @param options A bitset of parse options that should be set using the Parse variables. This Defaults to ParseDefault.
161  /// @return A ParseResult that stores the the outcome of attempting to load the document.
162  /// @note The only Load method available in the 'Safe' scripting languages.
163  ParseResult Load(const Char8* contents, unsigned int options = ParseDefault);
164 
165  #ifndef SWIG_SAFE
166  // Load document from file
167  /// @brief Load document from file
168  /// @param Path An c-style char array that contains the path and filename of the xml document to load.
169  /// @param options A bitset of parse options that should be set using the Parse variables. This Defaults to ParseDefault.
170  /// @param DocumentEncoding What kind of text is in the stream, this defaults to Encoding::EncodingAuto
171  /// @return A ParseResult that stores the the outcome of attempting to load the document.
172  /// @note Not available in the 'Safe' scripting languages because of the file access it could provide.
173  ParseResult LoadFile(const char* Path, unsigned int options = ParseDefault, Encoding DocumentEncoding = EncodingAuto);
174 
175  /// @brief Load document from file
176  /// @param Path An c-style wide char array that contains the path and filename of the xml document to load.
177  /// @param options A bitset of parse options that should be set using the Parse variables. This Defaults to ParseDefault.
178  /// @param DocumentEncoding What kind of text is in the stream, this defaults to Encoding::EncodingAuto
179  /// @return A ParseResult that stores the the outcome of attempting to load the document.
180  /// @note Not available in the 'Safe' scripting languages because of the file access it could provide.
181  ParseResult LoadFile(const wchar_t* Path, unsigned int options = ParseDefault, Encoding DocumentEncoding = EncodingAuto);
182  #endif
183 
184  /// @brief Load document from buffer. Copies/converts the buffer, so it may be deleted or changed after the function returns.
185  /// @param contents A pointer to buffer containing the xml document to be parsed, that will remain unchanged.
186  /// @param size The size of the buffer.
187  /// @param options A bitset of parse options that should be set using the Parse variables. This Defaults to ParseDefault.
188  /// @param DocumentEncoding What kind of text is in the stream, this defaults to Encoding::EncodingAuto
189  /// @return A ParseResult that stores the the outcome of attempting to load the document.
190  /// @note All buffer loading Methods of the XML::Document are made available to all scripting languages libraries.
191  ParseResult LoadBuffer(const void* contents, size_t size, unsigned int options = ParseDefault, Encoding DocumentEncoding = EncodingAuto);
192 
193  // Load document from buffer, using the buffer for in-place parsing (the buffer is modified and used for storage of document data).
194  // You should ensure that buffer data will persist throughout the document's lifetime, and free the buffer memory manually once document is destroyed.
195  /// @brief Load document from buffer, using the buffer for in-place parsing (the buffer is modified and used for storage of document data).
196  /// @details You should ensure that buffer data will persist throughout the documents lifetime, and free the buffer memory manually once document is destroyed.
197  /// @param contents A pointer to buffer containing the xml document to be parsed, that must remain for the lifecycle of the XML::Document.
198  /// @param size The size of the buffer.
199  /// @param options A bitset of parse options that should be set using the Parse variables. This Defaults to ParseDefault.
200  /// @param DocumentEncoding What kind of text is in the stream, this defaults to Encoding::EncodingAuto
201  /// @return A ParseResult that stores the the outcome of attempting to load the document.
202  /// @note All buffer loading Methods of the XML::Document are made available to all scripting languages libraries.
203  ParseResult LoadBufferInplace(void* contents, size_t size, unsigned int options = ParseDefault, Encoding DocumentEncoding = EncodingAuto);
204 
205  // Load document from buffer, using the buffer for in-place parsing (the buffer is modified and used for storage of document data).
206  // You should allocate the buffer with pugixml allocation function; document will free the buffer when it is no longer needed (you can't use it anymore).
207  /// @brief Load document from buffer, using the buffer for in-place parsing (the buffer is modified and used for storage of document data).
208  /// @details You should allocate the buffer with pugixml allocation function; XML::Document will free the buffer when it is no longer needed (you can not use it anymore).
209  /// @param contents A pointer to buffer containing the xml document to be parsed.
210  /// @param size The size of the buffer.
211  /// @param options A bitset of parse options that should be set using the Parse variables. This Defaults to ParseDefault.
212  /// @param DocumentEncoding What kind of text is in the stream, this defaults to Encoding::EncodingAuto.
213  /// @return A ParseResult that stores the the outcome of attempting to load the document.
214  /// @note All buffer loading Methods of the XML::Document are made available to all scripting languages libraries.
215  ParseResult LoadBufferInplaceOwn(void* contents, size_t size, unsigned int options = ParseDefault, Encoding DocumentEncoding = EncodingAuto);
216 
217  #ifndef SWIG_SAFE
218  /// @brief Save XML document to a stream.
219  /// @param stream The stream to save this document to.
220  /// @param indent The Character(s) used to represent a tab in the output, this defaults to one tab character.
221  /// @param flags The output format flags, this is a bitfield that defaults to XML::FormatDefault.
222  /// @param DocumentEncoding What kind of text is in the stream, this defaults to Encoding::EncodingAuto.
223  /// @note Not available in the 'Safe' scripting languages because of the file access it could provide.
224  void Save(Resource::DataStream& stream, const Char8* indent = "\t", unsigned int flags = FormatDefault, Encoding DocumentEncoding = EncodingAuto) const;
225 
226  /// @brief Save XML document to WriterInstance.
227  /// @param WriterInstance The Writer that will be used to output the xml text.
228  /// @param indent The Character(s) used to represent a tab in the output, this defaults to one tab character.
229  /// @param flags The output format flags, this is a bitfield that defaults to XML::FormatDefault.
230  /// @param DocumentEncoding What kind of text is in the stream, this defaults to Encoding::EncodingAuto.
231  /// @note Not available in the 'Safe' scripting languages because of the file access it could provide.
232  void Save(Writer& WriterInstance, const Char8* indent = "\t", unsigned int flags = FormatDefault, Encoding DocumentEncoding = EncodingAuto) const;
233 
234  /// @brief Save XML document to a stream of characters.
235  /// @param stream The output stream of wide characters to send the XML document to.
236  /// @param indent The Character(s) used to represent a tab in the output, this defaults to one tab character.
237  /// @param flags The output format flags, this is a bitfield that defaults to XML::FormatDefault.
238  /// @param DocumentEncoding The Type of encoding to use when saving the document.
239  /// @note Not available in the 'Safe' scripting languages because of the file access it could provide.
240  void Save(std::basic_ostream<char, std::char_traits<char> >& stream, const Char8* indent = "\t", unsigned int flags = FormatDefault, Encoding DocumentEncoding = EncodingAuto) const;
241 
242  /// @brief Save XML document to a stream of wide characters.
243  /// @param stream The output stream of wide characters to send the XML document to.
244  /// @param indent The Character(s) used to represent a tab in the output, this defaults to one tab character.
245  /// @param flags The output format flags, this is a bitfield that defaults to XML::FormatDefault.
246  /// @note Not available in the 'Safe' scripting languages because of the file access it could provide.
247  void Save(std::basic_ostream<wchar_t, std::char_traits<wchar_t> >& stream, const Char8* indent = "\t", unsigned int flags = FormatDefault) const;
248 
249  /// @brief Save XML to file.
250  /// @param Path A c-style array of chars that contain the filename (and any path) of the file to be output.
251  /// @param indent The Character(s) used to represent a tab in the output, this defaults to one tab character.
252  /// @param flags The output format flags, this is a bitfield that defaults to XML::FormatDefault.
253  /// @param DocumentEncoding What kind of text is in the stream, this defaults to Encoding::EncodingAuto.
254  /// @return False if the target file could not be opened for writing
255  /// @note Not available in the 'Safe' scripting languages because of the file access it could provide.
256  bool SaveFile(const char* Path, const Char8* indent = "\t", unsigned int flags = FormatDefault, Encoding DocumentEncoding = EncodingAuto) const;
257 
258  /// @brief Save XML to file.
259  /// @param Path A c-style array of wide chars that contain the filename (and any path) of the file to be output.
260  /// @param indent The Character(s) used to represent a tab in the output, this defaults to one tab character.
261  /// @param flags The output format flags, this is a bitfield that defaults to XML::FormatDefault.
262  /// @param DocumentEncoding What kind of text is in the stream, this defaults to Encoding::EncodingAuto.
263  /// @return False if the target file could not be opened for writing
264  /// @note Not available in the 'Safe' scripting languages because of the file access it could provide.
265  bool SaveFile(const wchar_t* Path, const Char8* indent = "\t", unsigned int flags = FormatDefault, Encoding DocumentEncoding = EncodingAuto) const;
266  #endif
267 
268  // Get document element
269  /// @brief Get document element
270  /// @return An XML::Node that is the root element of the xml Document
271  Node DocumentElement() const;
272  };
273 
274  }
275 } // /namespace Mezzanine
276 
277 
278 
279 #endif // Include guard
280 
281 
282 /*
283  *
284  * Software, Files, Libraries and all other items referenced in this clause refers only
285  * to the contents of this file and associated documentation.
286  *
287  * Copyright © 2006-2012 Arseny Kapoulkine
288  *
289  * Permission is hereby granted, free of charge, to any person
290  * obtaining a copy of this software and associated documentation
291  * files (the "Software"), to deal in the Software without
292  * restriction, including without limitation the rights to use,
293  * copy, modify, merge, publish, distribute, sublicense, and/or sell
294  * copies of the Software, and to permit persons to whom the
295  * Software is furnished to do so, subject to the following
296  * conditions:
297  *
298  * The above copyright notice and this permission notice shall be
299  * included in all copies or substantial portions of the Software.
300  *
301  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
302  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
303  * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
304  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
305  * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
306  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
307  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
308  * OTHER DEALINGS IN THE SOFTWARE.
309  */