2 www.sourceforge.net/projects/tinyxml
\r
3 Original code by Lee Thomason (www.grinninglizard.com)
\r
5 This software is provided 'as-is', without any express or implied
\r
6 warranty. In no event will the authors be held liable for any
\r
7 damages arising from the use of this software.
\r
9 Permission is granted to anyone to use this software for any
\r
10 purpose, including commercial applications, and to alter it and
\r
11 redistribute it freely, subject to the following restrictions:
\r
13 1. The origin of this software must not be misrepresented; you must
\r
14 not claim that you wrote the original software. If you use this
\r
15 software in a product, an acknowledgment in the product documentation
\r
16 would be appreciated but is not required.
\r
18 2. Altered source versions must be plainly marked as such, and
\r
19 must not be misrepresented as being the original software.
\r
21 3. This notice may not be removed or altered from any source
\r
25 #ifndef TINYXML_INCLUDED
\r
26 #define TINYXML_INCLUDED
\r
29 #pragma warning(push)
\r
30 #pragma warning(disable : 4530)
\r
31 #pragma warning(disable : 4786)
\r
40 // Help out windows:
\r
41 #if defined(_DEBUG) && !defined(DEBUG)
\r
45 #ifdef TIXML_USE_STL
\r
49 #define TIXML_STRING std::string
\r
51 #include "tinystr.h"
\r
52 #define TIXML_STRING TiXmlString
\r
55 // Deprecated library function hell. Compilers want to use the
\r
56 // new safe versions. This probably doesn't fully address the problem,
\r
57 // but it gets closer. There are too many compilers for me to fully
\r
58 // test. If you get compilation troubles, undefine TIXML_SAFE
\r
62 #if defined(_MSC_VER) && (_MSC_VER >= 1400)
\r
63 // Microsoft visual studio, version 2005 and higher.
\r
64 #define TIXML_SNPRINTF _snprintf_s
\r
65 #define TIXML_SSCANF sscanf_s
\r
66 #elif defined(_MSC_VER) && (_MSC_VER >= 1200)
\r
67 // Microsoft visual studio, version 6 and higher.
\r
68 //#pragma message( "Using _sn* functions." )
\r
69 #define TIXML_SNPRINTF _snprintf
\r
70 #define TIXML_SSCANF sscanf
\r
71 #elif defined(__GNUC__) && (__GNUC__ >= 3)
\r
72 // GCC version 3 and higher.s
\r
73 //#warning( "Using sn* functions." )
\r
74 #define TIXML_SNPRINTF snprintf
\r
75 #define TIXML_SSCANF sscanf
\r
77 #define TIXML_SNPRINTF snprintf
\r
78 #define TIXML_SSCANF sscanf
\r
82 class TiXmlDocument;
\r
86 class TiXmlAttribute;
\r
88 class TiXmlDeclaration;
\r
89 class TiXmlParsingData;
\r
91 const int TIXML_MAJOR_VERSION = 2;
\r
92 const int TIXML_MINOR_VERSION = 6;
\r
93 const int TIXML_PATCH_VERSION = 2;
\r
95 /* Internal structure for tracking location of items
\r
109 int row; // 0 based.
\r
110 int col; // 0 based.
\r
114 Implements the interface to the "Visitor pattern" (see the Accept() method.)
\r
115 If you call the Accept() method, it requires being passed a TiXmlVisitor
\r
116 class to handle callbacks. For nodes that contain other nodes (Document, Element)
\r
117 you will get called with a VisitEnter/VisitExit pair. Nodes that are always leaves
\r
118 are simply called with Visit().
\r
120 If you return 'true' from a Visit method, recursive parsing will continue. If you return
\r
121 false, <b>no children of this node or its sibilings</b> will be Visited.
\r
123 All flavors of Visit methods have a default implementation that returns 'true' (continue
\r
124 visiting). You need to only override methods that are interesting to you.
\r
126 Generally Accept() is called on the TiXmlDocument, although all nodes suppert Visiting.
\r
128 You should never change the document from a callback.
\r
130 @sa TiXmlNode::Accept()
\r
135 virtual ~TiXmlVisitor()
\r
139 /// Visit a document.
\r
140 virtual bool VisitEnter(const TiXmlDocument & /*doc*/)
\r
144 /// Visit a document.
\r
145 virtual bool VisitExit(const TiXmlDocument & /*doc*/)
\r
150 /// Visit an element.
\r
151 virtual bool VisitEnter(const TiXmlElement & /*element*/, const TiXmlAttribute * /*firstAttribute*/)
\r
155 /// Visit an element.
\r
156 virtual bool VisitExit(const TiXmlElement & /*element*/)
\r
161 /// Visit a declaration
\r
162 virtual bool Visit(const TiXmlDeclaration & /*declaration*/)
\r
166 /// Visit a text node
\r
167 virtual bool Visit(const TiXmlText & /*text*/)
\r
171 /// Visit a comment node
\r
172 virtual bool Visit(const TiXmlComment & /*comment*/)
\r
176 /// Visit an unknown node
\r
177 virtual bool Visit(const TiXmlUnknown & /*unknown*/)
\r
183 // Only used by Attribute::Query functions
\r
187 TIXML_NO_ATTRIBUTE,
\r
191 // Used by the parsing routines.
\r
194 TIXML_ENCODING_UNKNOWN,
\r
195 TIXML_ENCODING_UTF8,
\r
196 TIXML_ENCODING_LEGACY
\r
199 const TiXmlEncoding TIXML_DEFAULT_ENCODING = TIXML_ENCODING_UNKNOWN;
\r
201 /** TiXmlBase is a base class for every class in TinyXml.
\r
202 It does little except to establish that TinyXml classes
\r
203 can be printed and provide some utility functions.
\r
205 In XML, the document and elements can contain
\r
206 other elements and other types of nodes.
\r
209 A Document can contain: Element (container or leaf)
\r
212 Declaration( leaf )
\r
214 An Element can contain: Element (container or leaf)
\r
216 Attributes (not on tree)
\r
220 A Decleration contains: Attributes (not on tree)
\r
225 friend class TiXmlNode;
\r
226 friend class TiXmlElement;
\r
227 friend class TiXmlDocument;
\r
234 virtual ~TiXmlBase()
\r
238 /** All TinyXml classes can print themselves to a filestream
\r
239 or the string class (TiXmlString in non-STL mode, std::string
\r
240 in STL mode.) Either or both cfile and str can be null.
\r
242 This is a formatted print, and will insert
\r
245 (For an unformatted stream, use the << operator.)
\r
247 virtual void Print(FILE *cfile, int depth) const = 0;
\r
249 /** The world does not agree on whether white space should be kept or
\r
250 not. In order to make everyone happy, these global, static functions
\r
251 are provided to set whether or not TinyXml will condense all white space
\r
252 into a single space or not. The default is to condense. Note changing this
\r
253 value is not thread safe.
\r
255 static void SetCondenseWhiteSpace(bool condense)
\r
257 condenseWhiteSpace = condense;
\r
260 /// Return the current white space setting.
\r
261 static bool IsWhiteSpaceCondensed()
\r
263 return condenseWhiteSpace;
\r
266 /** Return the position, in the original source file, of this node or attribute.
\r
267 The row and column are 1-based. (That is the first row and first column is
\r
268 1,1). If the returns values are 0 or less, then the parser does not have
\r
269 a row and column value.
\r
271 Generally, the row and column value will be set when the TiXmlDocument::Load(),
\r
272 TiXmlDocument::LoadFile(), or any TiXmlNode::Parse() is called. It will NOT be set
\r
273 when the DOM was created from operator>>.
\r
275 The values reflect the initial load. Once the DOM is modified programmatically
\r
276 (by adding or changing nodes and attributes) the new values will NOT update to
\r
277 reflect changes in the document.
\r
279 There is a minor performance cost to computing the row and column. Computation
\r
280 can be disabled if TiXmlDocument::SetTabSize() is called with 0 as the value.
\r
282 @sa TiXmlDocument::SetTabSize()
\r
286 return location.row + 1;
\r
290 return location.col + 1; ///< See Row()
\r
293 void SetUserData(void *user)
\r
295 userData = user; ///< Set a pointer to arbitrary user data.
\r
297 void *GetUserData()
\r
299 return userData; ///< Get a pointer to arbitrary user data.
\r
301 const void *GetUserData() const
\r
303 return userData; ///< Get a pointer to arbitrary user data.
\r
306 // Table that returs, for a given lead byte, the total number of bytes
\r
307 // in the UTF-8 sequence.
\r
308 static const int utf8ByteTable[256];
\r
310 virtual const char *Parse(const char *p,
\r
311 TiXmlParsingData *data,
\r
312 TiXmlEncoding encoding /*= TIXML_ENCODING_UNKNOWN */) = 0;
\r
314 /** Expands entities in a string. Note this should not contian the tag's '<', '>', etc,
\r
315 or they will be transformed into entities!
\r
317 static void EncodeString(const TIXML_STRING &str, TIXML_STRING *out);
\r
321 TIXML_NO_ERROR = 0,
\r
323 TIXML_ERROR_OPENING_FILE,
\r
324 TIXML_ERROR_PARSING_ELEMENT,
\r
325 TIXML_ERROR_FAILED_TO_READ_ELEMENT_NAME,
\r
326 TIXML_ERROR_READING_ELEMENT_VALUE,
\r
327 TIXML_ERROR_READING_ATTRIBUTES,
\r
328 TIXML_ERROR_PARSING_EMPTY,
\r
329 TIXML_ERROR_READING_END_TAG,
\r
330 TIXML_ERROR_PARSING_UNKNOWN,
\r
331 TIXML_ERROR_PARSING_COMMENT,
\r
332 TIXML_ERROR_PARSING_DECLARATION,
\r
333 TIXML_ERROR_DOCUMENT_EMPTY,
\r
334 TIXML_ERROR_EMBEDDED_NULL,
\r
335 TIXML_ERROR_PARSING_CDATA,
\r
336 TIXML_ERROR_DOCUMENT_TOP_ONLY,
\r
337 TIXML_ERROR_STRING_COUNT
\r
341 static const char *SkipWhiteSpace(const char *, TiXmlEncoding encoding);
\r
343 inline static bool IsWhiteSpace(char c)
\r
345 return (isspace((unsigned char)c) || c == '\n' || c == '\r');
\r
347 inline static bool IsWhiteSpace(int c)
\r
350 return IsWhiteSpace((char)c);
\r
351 return false; // Again, only truly correct for English/Latin...but usually works.
\r
354 #ifdef TIXML_USE_STL
\r
355 static bool StreamWhiteSpace(std::istream *in, TIXML_STRING *tag);
\r
356 static bool StreamTo(std::istream *in, int character, TIXML_STRING *tag);
\r
359 /* Reads an XML name into the string provided. Returns
\r
360 a pointer just past the last character of the name,
\r
361 or 0 if the function has an error.
\r
363 static const char *ReadName(const char *p, TIXML_STRING *name, TiXmlEncoding encoding);
\r
365 /* Reads text. Returns a pointer past the given end tag.
\r
366 Wickedly complex options, but it keeps the (sensitive) code in one place.
\r
368 static const char *ReadText(const char *in, // where to start
\r
369 TIXML_STRING *text, // the string read
\r
370 bool ignoreWhiteSpace, // whether to keep the white space
\r
371 const char *endTag, // what ends this text
\r
372 bool ignoreCase, // whether to ignore case in the end tag
\r
373 TiXmlEncoding encoding); // the current encoding
\r
375 // If an entity has been found, transform it into a character.
\r
376 static const char *GetEntity(const char *in, char *value, int *length, TiXmlEncoding encoding);
\r
378 // Get a character, while interpreting entities.
\r
379 // The length can be from 0 to 4 bytes.
\r
380 inline static const char *GetChar(const char *p, char *_value, int *length, TiXmlEncoding encoding)
\r
383 if (encoding == TIXML_ENCODING_UTF8)
\r
385 *length = utf8ByteTable[*((const unsigned char *)p)];
\r
386 assert(*length >= 0 && *length < 5);
\r
396 return GetEntity(p, _value, length, encoding);
\r
402 //strncpy( _value, p, *length ); // lots of compilers don't like this function (unsafe),
\r
403 // and the null terminator isn't needed
\r
404 for (int i = 0; p[i] && i < *length; ++i)
\r
408 return p + (*length);
\r
417 // Return true if the next characters in the stream are any of the endTag sequences.
\r
418 // Ignore case only works for english, and should only be relied on when comparing
\r
419 // to English words: StringEqual( p, "version", true ) is fine.
\r
420 static bool StringEqual(const char *p,
\r
421 const char *endTag,
\r
423 TiXmlEncoding encoding);
\r
425 static const char *errorString[TIXML_ERROR_STRING_COUNT];
\r
427 TiXmlCursor location;
\r
429 /// Field containing a generic user pointer
\r
432 // None of these methods are reliable for any language except English.
\r
433 // Good for approximation, not great for accuracy.
\r
434 static int IsAlpha(unsigned char anyByte, TiXmlEncoding encoding);
\r
435 static int IsAlphaNum(unsigned char anyByte, TiXmlEncoding encoding);
\r
436 inline static int ToLower(int v, TiXmlEncoding encoding)
\r
438 if (encoding == TIXML_ENCODING_UTF8)
\r
449 static void ConvertUTF32ToUTF8(unsigned long input, char *output, int *length);
\r
452 TiXmlBase(const TiXmlBase &); // not implemented.
\r
453 void operator=(const TiXmlBase &base); // not allowed.
\r
458 unsigned int strLength;
\r
464 MAX_ENTITY_LENGTH = 6
\r
466 static Entity entity[NUM_ENTITY];
\r
467 static bool condenseWhiteSpace;
\r
470 /** The parent class for everything in the Document Object Model.
\r
471 (Except for attributes).
\r
472 Nodes have siblings, a parent, and children. A node can be
\r
473 in a document, or stand on its own. The type of a TiXmlNode
\r
474 can be queried, and it can be cast to its more defined type.
\r
476 class TiXmlNode : public TiXmlBase
\r
478 friend class TiXmlDocument;
\r
479 friend class TiXmlElement;
\r
482 #ifdef TIXML_USE_STL
\r
484 /** An input stream operator, for every class. Tolerant of newlines and
\r
485 formatting, but doesn't expect them.
\r
487 friend std::istream &operator>>(std::istream &in, TiXmlNode &base);
\r
489 /** An output stream operator, for every class. Note that this outputs
\r
490 without any newlines or formatting, as opposed to Print(), which
\r
491 includes tabs and new lines.
\r
493 The operator<< and operator>> are not completely symmetric. Writing
\r
494 a node to a stream is very well defined. You'll get a nice stream
\r
495 of output, without any extra whitespace or newlines.
\r
497 But reading is not as well defined. (As it always is.) If you create
\r
498 a TiXmlElement (for example) and read that from an input stream,
\r
499 the text needs to define an element or junk will result. This is
\r
500 true of all input streams, but it's worth keeping in mind.
\r
502 A TiXmlDocument will read nodes until it reads a root element, and
\r
503 all the children of that root element.
\r
505 friend std::ostream &operator<<(std::ostream &out, const TiXmlNode &base);
\r
507 /// Appends the XML node or attribute to a std::string.
\r
508 friend std::string &operator<<(std::string &out, const TiXmlNode &base);
\r
512 /** The types of XML nodes supported by TinyXml. (All the
\r
513 unsupported types are picked up by UNKNOWN.)
\r
522 TINYXML_DECLARATION,
\r
526 virtual ~TiXmlNode();
\r
528 /** The meaning of 'value' changes for the specific type of
\r
531 Document: filename of the xml file
\r
532 Element: name of the element
\r
533 Comment: the comment text
\r
534 Unknown: the tag contents
\r
535 Text: the text string
\r
538 The subclasses will wrap this function.
\r
540 const char *Value() const
\r
542 return value.c_str();
\r
545 #ifdef TIXML_USE_STL
\r
546 /** Return Value() as a std::string. If you only use STL,
\r
547 this is more efficient than calling Value().
\r
548 Only available in STL mode.
\r
550 const std::string &ValueStr() const
\r
556 const TIXML_STRING &ValueTStr() const
\r
561 /** Changes the value of the node. Defined as:
\r
563 Document: filename of the xml file
\r
564 Element: name of the element
\r
565 Comment: the comment text
\r
566 Unknown: the tag contents
\r
567 Text: the text string
\r
570 void SetValue(const char *_value)
\r
575 #ifdef TIXML_USE_STL
\r
576 /// STL std::string form.
\r
577 void SetValue(const std::string &_value)
\r
583 /// Delete all the children of this node. Does not affect 'this'.
\r
586 /// One step up the DOM.
\r
587 TiXmlNode *Parent()
\r
591 const TiXmlNode *Parent() const
\r
596 const TiXmlNode *FirstChild() const
\r
598 return firstChild; ///< The first child of this node. Will be null if there are no children.
\r
600 TiXmlNode *FirstChild()
\r
604 const TiXmlNode *FirstChild(const char *value) const; ///< The first child of this node with the matching 'value'. Will be null if none found.
\r
605 /// The first child of this node with the matching 'value'. Will be null if none found.
\r
606 TiXmlNode *FirstChild(const char *_value)
\r
608 // Call through to the const version - safe since nothing is changed. Exiting syntax: cast this to a const (always safe)
\r
609 // call the method, cast the return back to non-const.
\r
610 return const_cast<TiXmlNode *>((const_cast<const TiXmlNode *>(this))->FirstChild(_value));
\r
612 const TiXmlNode *LastChild() const
\r
614 return lastChild; /// The last child of this node. Will be null if there are no children.
\r
616 TiXmlNode *LastChild()
\r
621 const TiXmlNode *LastChild(const char *value) const; /// The last child of this node matching 'value'. Will be null if there are no children.
\r
622 TiXmlNode *LastChild(const char *_value)
\r
624 return const_cast<TiXmlNode *>((const_cast<const TiXmlNode *>(this))->LastChild(_value));
\r
627 #ifdef TIXML_USE_STL
\r
628 const TiXmlNode *FirstChild(const std::string &_value) const
\r
630 return FirstChild(_value.c_str()); ///< STL std::string form.
\r
632 TiXmlNode *FirstChild(const std::string &_value)
\r
634 return FirstChild(_value.c_str()); ///< STL std::string form.
\r
636 const TiXmlNode *LastChild(const std::string &_value) const
\r
638 return LastChild(_value.c_str()); ///< STL std::string form.
\r
640 TiXmlNode *LastChild(const std::string &_value)
\r
642 return LastChild(_value.c_str()); ///< STL std::string form.
\r
646 /** An alternate way to walk the children of a node.
\r
647 One way to iterate over nodes is:
\r
649 for( child = parent->FirstChild(); child; child = child->NextSibling() )
\r
652 IterateChildren does the same thing with the syntax:
\r
655 while( child = parent->IterateChildren( child ) )
\r
658 IterateChildren takes the previous child as input and finds
\r
659 the next one. If the previous child is null, it returns the
\r
660 first. IterateChildren will return null when done.
\r
662 const TiXmlNode *IterateChildren(const TiXmlNode *previous) const;
\r
663 TiXmlNode *IterateChildren(const TiXmlNode *previous)
\r
665 return const_cast<TiXmlNode *>((const_cast<const TiXmlNode *>(this))->IterateChildren(previous));
\r
668 /// This flavor of IterateChildren searches for children with a particular 'value'
\r
669 const TiXmlNode *IterateChildren(const char *value, const TiXmlNode *previous) const;
\r
670 TiXmlNode *IterateChildren(const char *_value, const TiXmlNode *previous)
\r
672 return const_cast<TiXmlNode *>((const_cast<const TiXmlNode *>(this))->IterateChildren(_value, previous));
\r
675 #ifdef TIXML_USE_STL
\r
676 const TiXmlNode *IterateChildren(const std::string &_value, const TiXmlNode *previous) const
\r
678 return IterateChildren(_value.c_str(), previous); ///< STL std::string form.
\r
680 TiXmlNode *IterateChildren(const std::string &_value, const TiXmlNode *previous)
\r
682 return IterateChildren(_value.c_str(), previous); ///< STL std::string form.
\r
686 /** Add a new node related to this. Adds a child past the LastChild.
\r
687 Returns a pointer to the new object or NULL if an error occured.
\r
689 TiXmlNode *InsertEndChild(const TiXmlNode &addThis);
\r
691 /** Add a new node related to this. Adds a child past the LastChild.
\r
693 NOTE: the node to be added is passed by pointer, and will be
\r
694 henceforth owned (and deleted) by tinyXml. This method is efficient
\r
695 and avoids an extra copy, but should be used with care as it
\r
696 uses a different memory model than the other insert functions.
\r
700 TiXmlNode *LinkEndChild(TiXmlNode *addThis);
\r
702 /** Add a new node related to this. Adds a child before the specified child.
\r
703 Returns a pointer to the new object or NULL if an error occured.
\r
705 TiXmlNode *InsertBeforeChild(TiXmlNode *beforeThis, const TiXmlNode &addThis);
\r
707 /** Add a new node related to this. Adds a child after the specified child.
\r
708 Returns a pointer to the new object or NULL if an error occured.
\r
710 TiXmlNode *InsertAfterChild(TiXmlNode *afterThis, const TiXmlNode &addThis);
\r
712 /** Replace a child of this node.
\r
713 Returns a pointer to the new object or NULL if an error occured.
\r
715 TiXmlNode *ReplaceChild(TiXmlNode *replaceThis, const TiXmlNode &withThis);
\r
717 /// Delete a child of this node.
\r
718 bool RemoveChild(TiXmlNode *removeThis);
\r
720 /// Navigate to a sibling node.
\r
721 const TiXmlNode *PreviousSibling() const
\r
725 TiXmlNode *PreviousSibling()
\r
730 /// Navigate to a sibling node.
\r
731 const TiXmlNode *PreviousSibling(const char *) const;
\r
732 TiXmlNode *PreviousSibling(const char *_prev)
\r
734 return const_cast<TiXmlNode *>((const_cast<const TiXmlNode *>(this))->PreviousSibling(_prev));
\r
737 #ifdef TIXML_USE_STL
\r
738 const TiXmlNode *PreviousSibling(const std::string &_value) const
\r
740 return PreviousSibling(_value.c_str()); ///< STL std::string form.
\r
742 TiXmlNode *PreviousSibling(const std::string &_value)
\r
744 return PreviousSibling(_value.c_str()); ///< STL std::string form.
\r
746 const TiXmlNode *NextSibling(const std::string &_value) const
\r
748 return NextSibling(_value.c_str()); ///< STL std::string form.
\r
750 TiXmlNode *NextSibling(const std::string &_value)
\r
752 return NextSibling(_value.c_str()); ///< STL std::string form.
\r
756 /// Navigate to a sibling node.
\r
757 const TiXmlNode *NextSibling() const
\r
761 TiXmlNode *NextSibling()
\r
766 /// Navigate to a sibling node with the given 'value'.
\r
767 const TiXmlNode *NextSibling(const char *) const;
\r
768 TiXmlNode *NextSibling(const char *_next)
\r
770 return const_cast<TiXmlNode *>((const_cast<const TiXmlNode *>(this))->NextSibling(_next));
\r
773 /** Convenience function to get through elements.
\r
774 Calls NextSibling and ToElement. Will skip all non-Element
\r
775 nodes. Returns 0 if there is not another element.
\r
777 const TiXmlElement *NextSiblingElement() const;
\r
778 TiXmlElement *NextSiblingElement()
\r
780 return const_cast<TiXmlElement *>((const_cast<const TiXmlNode *>(this))->NextSiblingElement());
\r
783 /** Convenience function to get through elements.
\r
784 Calls NextSibling and ToElement. Will skip all non-Element
\r
785 nodes. Returns 0 if there is not another element.
\r
787 const TiXmlElement *NextSiblingElement(const char *) const;
\r
788 TiXmlElement *NextSiblingElement(const char *_next)
\r
790 return const_cast<TiXmlElement *>((const_cast<const TiXmlNode *>(this))->NextSiblingElement(_next));
\r
793 #ifdef TIXML_USE_STL
\r
794 const TiXmlElement *NextSiblingElement(const std::string &_value) const
\r
796 return NextSiblingElement(_value.c_str()); ///< STL std::string form.
\r
798 TiXmlElement *NextSiblingElement(const std::string &_value)
\r
800 return NextSiblingElement(_value.c_str()); ///< STL std::string form.
\r
804 /// Convenience function to get through elements.
\r
805 const TiXmlElement *FirstChildElement() const;
\r
806 TiXmlElement *FirstChildElement()
\r
808 return const_cast<TiXmlElement *>((const_cast<const TiXmlNode *>(this))->FirstChildElement());
\r
811 /// Convenience function to get through elements.
\r
812 const TiXmlElement *FirstChildElement(const char *_value) const;
\r
813 TiXmlElement *FirstChildElement(const char *_value)
\r
815 return const_cast<TiXmlElement *>((const_cast<const TiXmlNode *>(this))->FirstChildElement(_value));
\r
818 #ifdef TIXML_USE_STL
\r
819 const TiXmlElement *FirstChildElement(const std::string &_value) const
\r
821 return FirstChildElement(_value.c_str()); ///< STL std::string form.
\r
823 TiXmlElement *FirstChildElement(const std::string &_value)
\r
825 return FirstChildElement(_value.c_str()); ///< STL std::string form.
\r
829 /** Query the type (as an enumerated value, above) of this node.
\r
830 The possible types are: TINYXML_DOCUMENT, TINYXML_ELEMENT, TINYXML_COMMENT,
\r
831 TINYXML_UNKNOWN, TINYXML_TEXT, and TINYXML_DECLARATION.
\r
838 /** Return a pointer to the Document this node lives in.
\r
839 Returns null if not in a document.
\r
841 const TiXmlDocument *GetDocument() const;
\r
842 TiXmlDocument *GetDocument()
\r
844 return const_cast<TiXmlDocument *>((const_cast<const TiXmlNode *>(this))->GetDocument());
\r
847 /// Returns true if this node has no children.
\r
848 bool NoChildren() const
\r
850 return !firstChild;
\r
853 virtual const TiXmlDocument *ToDocument() const
\r
855 return 0; ///< Cast to a more defined type. Will return null if not of the requested type.
\r
857 virtual const TiXmlElement *ToElement() const
\r
859 return 0; ///< Cast to a more defined type. Will return null if not of the requested type.
\r
861 virtual const TiXmlComment *ToComment() const
\r
863 return 0; ///< Cast to a more defined type. Will return null if not of the requested type.
\r
865 virtual const TiXmlUnknown *ToUnknown() const
\r
867 return 0; ///< Cast to a more defined type. Will return null if not of the requested type.
\r
869 virtual const TiXmlText *ToText() const
\r
871 return 0; ///< Cast to a more defined type. Will return null if not of the requested type.
\r
873 virtual const TiXmlDeclaration *ToDeclaration() const
\r
875 return 0; ///< Cast to a more defined type. Will return null if not of the requested type.
\r
878 virtual TiXmlDocument *ToDocument()
\r
880 return 0; ///< Cast to a more defined type. Will return null if not of the requested type.
\r
882 virtual TiXmlElement *ToElement()
\r
884 return 0; ///< Cast to a more defined type. Will return null if not of the requested type.
\r
886 virtual TiXmlComment *ToComment()
\r
888 return 0; ///< Cast to a more defined type. Will return null if not of the requested type.
\r
890 virtual TiXmlUnknown *ToUnknown()
\r
892 return 0; ///< Cast to a more defined type. Will return null if not of the requested type.
\r
894 virtual TiXmlText *ToText()
\r
896 return 0; ///< Cast to a more defined type. Will return null if not of the requested type.
\r
898 virtual TiXmlDeclaration *ToDeclaration()
\r
900 return 0; ///< Cast to a more defined type. Will return null if not of the requested type.
\r
903 /** Create an exact duplicate of this node and return it. The memory must be deleted
\r
906 virtual TiXmlNode *Clone() const = 0;
\r
908 /** Accept a hierchical visit the nodes in the TinyXML DOM. Every node in the
\r
909 XML tree will be conditionally visited and the host will be called back
\r
910 via the TiXmlVisitor interface.
\r
912 This is essentially a SAX interface for TinyXML. (Note however it doesn't re-parse
\r
913 the XML for the callbacks, so the performance of TinyXML is unchanged by using this
\r
914 interface versus any other.)
\r
916 The interface has been based on ideas from:
\r
918 - http://www.saxproject.org/
\r
919 - http://c2.com/cgi/wiki?HierarchicalVisitorPattern
\r
921 Which are both good references for "visiting".
\r
923 An example of using Accept():
\r
925 TiXmlPrinter printer;
\r
926 tinyxmlDoc.Accept( &printer );
\r
927 const char* xmlcstr = printer.CStr();
\r
930 virtual bool Accept(TiXmlVisitor *visitor) const = 0;
\r
933 TiXmlNode(NodeType _type);
\r
935 // Copy to the allocated object. Shared functionality between Clone, Copy constructor,
\r
936 // and the assignment operator.
\r
937 void CopyTo(TiXmlNode *target) const;
\r
939 #ifdef TIXML_USE_STL
\r
940 // The real work of the input operator.
\r
941 virtual void StreamIn(std::istream *in, TIXML_STRING *tag) = 0;
\r
944 // Figure out what is at *p, and parse it. Returns null if it is not an xml node.
\r
945 TiXmlNode *Identify(const char *start, TiXmlEncoding encoding);
\r
950 TiXmlNode *firstChild;
\r
951 TiXmlNode *lastChild;
\r
953 TIXML_STRING value;
\r
959 TiXmlNode(const TiXmlNode &); // not implemented.
\r
960 void operator=(const TiXmlNode &base); // not allowed.
\r
963 /** An attribute is a name-value pair. Elements have an arbitrary
\r
964 number of attributes, each with a unique name.
\r
966 @note The attributes are not TiXmlNodes, since they are not
\r
967 part of the tinyXML document object model. There are other
\r
968 suggested ways to look at this problem.
\r
970 class TiXmlAttribute : public TiXmlBase
\r
972 friend class TiXmlAttributeSet;
\r
975 /// Construct an empty attribute.
\r
983 #ifdef TIXML_USE_STL
\r
984 /// std::string constructor.
\r
985 TiXmlAttribute(const std::string &_name, const std::string &_value)
\r
994 /// Construct an attribute with a name and value.
\r
995 TiXmlAttribute(const char *_name, const char *_value)
\r
1003 const char *Name() const
\r
1005 return name.c_str(); ///< Return the name of this attribute.
\r
1007 const char *Value() const
\r
1009 return value.c_str(); ///< Return the value of this attribute.
\r
1011 #ifdef TIXML_USE_STL
\r
1012 const std::string &ValueStr() const
\r
1014 return value; ///< Return the value of this attribute.
\r
1017 int IntValue() const; ///< Return the value of this attribute, converted to an integer.
\r
1018 double DoubleValue() const; ///< Return the value of this attribute, converted to a double.
\r
1020 // Get the tinyxml string representation
\r
1021 const TIXML_STRING &NameTStr() const
\r
1026 /** QueryIntValue examines the value string. It is an alternative to the
\r
1027 IntValue() method with richer error checking.
\r
1028 If the value is an integer, it is stored in 'value' and
\r
1029 the call returns TIXML_SUCCESS. If it is not
\r
1030 an integer, it returns TIXML_WRONG_TYPE.
\r
1032 A specialized but useful call. Note that for success it returns 0,
\r
1033 which is the opposite of almost all other TinyXml calls.
\r
1035 int QueryIntValue(int *_value) const;
\r
1036 /// QueryDoubleValue examines the value string. See QueryIntValue().
\r
1037 int QueryDoubleValue(double *_value) const;
\r
1039 void SetName(const char *_name)
\r
1041 name = _name; ///< Set the name of this attribute.
\r
1043 void SetValue(const char *_value)
\r
1045 value = _value; ///< Set the value.
\r
1048 void SetIntValue(int _value); ///< Set the value from an integer.
\r
1049 void SetDoubleValue(double _value); ///< Set the value from a double.
\r
1051 #ifdef TIXML_USE_STL
\r
1052 /// STL std::string form.
\r
1053 void SetName(const std::string &_name)
\r
1057 /// STL std::string form.
\r
1058 void SetValue(const std::string &_value)
\r
1064 /// Get the next sibling attribute in the DOM. Returns null at end.
\r
1065 const TiXmlAttribute *Next() const;
\r
1066 TiXmlAttribute *Next()
\r
1068 return const_cast<TiXmlAttribute *>((const_cast<const TiXmlAttribute *>(this))->Next());
\r
1071 /// Get the previous sibling attribute in the DOM. Returns null at beginning.
\r
1072 const TiXmlAttribute *Previous() const;
\r
1073 TiXmlAttribute *Previous()
\r
1075 return const_cast<TiXmlAttribute *>((const_cast<const TiXmlAttribute *>(this))->Previous());
\r
1078 bool operator==(const TiXmlAttribute &rhs) const
\r
1080 return rhs.name == name;
\r
1082 bool operator<(const TiXmlAttribute &rhs) const
\r
1084 return name < rhs.name;
\r
1086 bool operator>(const TiXmlAttribute &rhs) const
\r
1088 return name > rhs.name;
\r
1091 /* Attribute parsing starts: first letter of the name
\r
1092 returns: the next char after the value end quote
\r
1094 virtual const char *Parse(const char *p, TiXmlParsingData *data, TiXmlEncoding encoding);
\r
1096 // Prints this Attribute to a FILE stream.
\r
1097 virtual void Print(FILE *cfile, int depth) const
\r
1099 Print(cfile, depth, 0);
\r
1101 void Print(FILE *cfile, int depth, TIXML_STRING *str) const;
\r
1104 // Set the document pointer so the attribute can report errors.
\r
1105 void SetDocument(TiXmlDocument *doc)
\r
1111 TiXmlAttribute(const TiXmlAttribute &); // not implemented.
\r
1112 void operator=(const TiXmlAttribute &base); // not allowed.
\r
1114 TiXmlDocument *document; // A pointer back to a document, for error reporting.
\r
1115 TIXML_STRING name;
\r
1116 TIXML_STRING value;
\r
1117 TiXmlAttribute *prev;
\r
1118 TiXmlAttribute *next;
\r
1121 /* A class used to manage a group of attributes.
\r
1122 It is only used internally, both by the ELEMENT and the DECLARATION.
\r
1124 The set can be changed transparent to the Element and Declaration
\r
1125 classes that use it, but NOT transparent to the Attribute
\r
1126 which has to implement a next() and previous() method. Which makes
\r
1127 it a bit problematic and prevents the use of STL.
\r
1129 This version is implemented with circular lists because:
\r
1130 - I like circular lists
\r
1131 - it demonstrates some independence from the (typical) doubly linked list.
\r
1133 class TiXmlAttributeSet
\r
1136 TiXmlAttributeSet();
\r
1137 ~TiXmlAttributeSet();
\r
1139 void Add(TiXmlAttribute *attribute);
\r
1140 void Remove(TiXmlAttribute *attribute);
\r
1142 const TiXmlAttribute *First() const
\r
1144 return (sentinel.next == &sentinel) ? 0 : sentinel.next;
\r
1146 TiXmlAttribute *First()
\r
1148 return (sentinel.next == &sentinel) ? 0 : sentinel.next;
\r
1150 const TiXmlAttribute *Last() const
\r
1152 return (sentinel.prev == &sentinel) ? 0 : sentinel.prev;
\r
1154 TiXmlAttribute *Last()
\r
1156 return (sentinel.prev == &sentinel) ? 0 : sentinel.prev;
\r
1159 TiXmlAttribute *Find(const char *_name) const;
\r
1160 TiXmlAttribute *FindOrCreate(const char *_name);
\r
1162 #ifdef TIXML_USE_STL
\r
1163 TiXmlAttribute *Find(const std::string &_name) const;
\r
1164 TiXmlAttribute *FindOrCreate(const std::string &_name);
\r
1168 //*ME: Because of hidden/disabled copy-construktor in TiXmlAttribute (sentinel-element),
\r
1169 //*ME: this class must be also use a hidden/disabled copy-constructor !!!
\r
1170 TiXmlAttributeSet(const TiXmlAttributeSet &); // not allowed
\r
1171 void operator=(const TiXmlAttributeSet &); // not allowed (as TiXmlAttribute)
\r
1173 TiXmlAttribute sentinel;
\r
1176 /** The element is a container class. It has a value, the element name,
\r
1177 and can contain other elements, text, comments, and unknowns.
\r
1178 Elements also contain an arbitrary number of attributes.
\r
1180 class TiXmlElement : public TiXmlNode
\r
1183 /// Construct an element.
\r
1184 TiXmlElement(const char *in_value);
\r
1186 #ifdef TIXML_USE_STL
\r
1187 /// std::string constructor.
\r
1188 TiXmlElement(const std::string &_value);
\r
1191 TiXmlElement(const TiXmlElement &);
\r
1193 TiXmlElement &operator=(const TiXmlElement &base);
\r
1195 virtual ~TiXmlElement();
\r
1197 /** Given an attribute name, Attribute() returns the value
\r
1198 for the attribute of that name, or null if none exists.
\r
1200 const char *Attribute(const char *name) const;
\r
1202 /** Given an attribute name, Attribute() returns the value
\r
1203 for the attribute of that name, or null if none exists.
\r
1204 If the attribute exists and can be converted to an integer,
\r
1205 the integer value will be put in the return 'i', if 'i'
\r
1208 const char *Attribute(const char *name, int *i) const;
\r
1210 /** Given an attribute name, Attribute() returns the value
\r
1211 for the attribute of that name, or null if none exists.
\r
1212 If the attribute exists and can be converted to an double,
\r
1213 the double value will be put in the return 'd', if 'd'
\r
1216 const char *Attribute(const char *name, double *d) const;
\r
1218 /** QueryIntAttribute examines the attribute - it is an alternative to the
\r
1219 Attribute() method with richer error checking.
\r
1220 If the attribute is an integer, it is stored in 'value' and
\r
1221 the call returns TIXML_SUCCESS. If it is not
\r
1222 an integer, it returns TIXML_WRONG_TYPE. If the attribute
\r
1223 does not exist, then TIXML_NO_ATTRIBUTE is returned.
\r
1225 int QueryIntAttribute(const char *name, int *_value) const;
\r
1226 /// QueryUnsignedAttribute examines the attribute - see QueryIntAttribute().
\r
1227 int QueryUnsignedAttribute(const char *name, unsigned *_value) const;
\r
1228 /** QueryBoolAttribute examines the attribute - see QueryIntAttribute().
\r
1229 Note that '1', 'true', or 'yes' are considered true, while '0', 'false'
\r
1230 and 'no' are considered false.
\r
1232 int QueryBoolAttribute(const char *name, bool *_value) const;
\r
1233 /// QueryDoubleAttribute examines the attribute - see QueryIntAttribute().
\r
1234 int QueryDoubleAttribute(const char *name, double *_value) const;
\r
1235 /// QueryFloatAttribute examines the attribute - see QueryIntAttribute().
\r
1236 int QueryFloatAttribute(const char *name, float *_value) const
\r
1239 int result = QueryDoubleAttribute(name, &d);
\r
1240 if (result == TIXML_SUCCESS)
\r
1242 *_value = (float)d;
\r
1247 #ifdef TIXML_USE_STL
\r
1248 /// QueryStringAttribute examines the attribute - see QueryIntAttribute().
\r
1249 int QueryStringAttribute(const char *name, std::string *_value) const
\r
1251 const char *cstr = Attribute(name);
\r
1254 *_value = std::string(cstr);
\r
1255 return TIXML_SUCCESS;
\r
1257 return TIXML_NO_ATTRIBUTE;
\r
1260 /** Template form of the attribute query which will try to read the
\r
1261 attribute into the specified type. Very easy, very powerful, but
\r
1262 be careful to make sure to call this with the correct type.
\r
1264 NOTE: This method doesn't work correctly for 'string' types that contain spaces.
\r
1266 @return TIXML_SUCCESS, TIXML_WRONG_TYPE, or TIXML_NO_ATTRIBUTE
\r
1268 template <typename T>
\r
1269 int QueryValueAttribute(const std::string &name, T *outValue) const
\r
1271 const TiXmlAttribute *node = attributeSet.Find(name);
\r
1273 return TIXML_NO_ATTRIBUTE;
\r
1275 std::stringstream sstream(node->ValueStr());
\r
1276 sstream >> *outValue;
\r
1277 if (!sstream.fail())
\r
1278 return TIXML_SUCCESS;
\r
1279 return TIXML_WRONG_TYPE;
\r
1282 int QueryValueAttribute(const std::string &name, std::string *outValue) const
\r
1284 const TiXmlAttribute *node = attributeSet.Find(name);
\r
1286 return TIXML_NO_ATTRIBUTE;
\r
1287 *outValue = node->ValueStr();
\r
1288 return TIXML_SUCCESS;
\r
1292 /** Sets an attribute of name to a given value. The attribute
\r
1293 will be created if it does not exist, or changed if it does.
\r
1295 void SetAttribute(const char *name, const char *_value);
\r
1297 #ifdef TIXML_USE_STL
\r
1298 const std::string *Attribute(const std::string &name) const;
\r
1299 const std::string *Attribute(const std::string &name, int *i) const;
\r
1300 const std::string *Attribute(const std::string &name, double *d) const;
\r
1301 int QueryIntAttribute(const std::string &name, int *_value) const;
\r
1302 int QueryDoubleAttribute(const std::string &name, double *_value) const;
\r
1304 /// STL std::string form.
\r
1305 void SetAttribute(const std::string &name, const std::string &_value);
\r
1306 ///< STL std::string form.
\r
1307 void SetAttribute(const std::string &name, int _value);
\r
1308 ///< STL std::string form.
\r
1309 void SetDoubleAttribute(const std::string &name, double value);
\r
1312 /** Sets an attribute of name to a given value. The attribute
\r
1313 will be created if it does not exist, or changed if it does.
\r
1315 void SetAttribute(const char *name, int value);
\r
1317 /** Sets an attribute of name to a given value. The attribute
\r
1318 will be created if it does not exist, or changed if it does.
\r
1320 void SetDoubleAttribute(const char *name, double value);
\r
1322 /** Deletes an attribute with the given name.
\r
1324 void RemoveAttribute(const char *name);
\r
1325 #ifdef TIXML_USE_STL
\r
1326 void RemoveAttribute(const std::string &name)
\r
1328 RemoveAttribute(name.c_str()); ///< STL std::string form.
\r
1332 const TiXmlAttribute *FirstAttribute() const
\r
1334 return attributeSet.First(); ///< Access the first attribute in this element.
\r
1336 TiXmlAttribute *FirstAttribute()
\r
1338 return attributeSet.First();
\r
1340 const TiXmlAttribute *LastAttribute() const
\r
1342 return attributeSet.Last(); ///< Access the last attribute in this element.
\r
1344 TiXmlAttribute *LastAttribute()
\r
1346 return attributeSet.Last();
\r
1349 /** Convenience function for easy access to the text inside an element. Although easy
\r
1350 and concise, GetText() is limited compared to getting the TiXmlText child
\r
1351 and accessing it directly.
\r
1353 If the first child of 'this' is a TiXmlText, the GetText()
\r
1354 returns the character string of the Text node, else null is returned.
\r
1356 This is a convenient method for getting the text of simple contained text:
\r
1358 <foo>This is text</foo>
\r
1359 const char* str = fooElement->GetText();
\r
1362 'str' will be a pointer to "This is text".
\r
1364 Note that this function can be misleading. If the element foo was created from
\r
1367 <foo><b>This is text</b></foo>
\r
1370 then the value of str would be null. The first child node isn't a text node, it is
\r
1371 another element. From this XML:
\r
1373 <foo>This is <b>text</b></foo>
\r
1375 GetText() will return "This is ".
\r
1377 WARNING: GetText() accesses a child node - don't become confused with the
\r
1378 similarly named TiXmlHandle::Text() and TiXmlNode::ToText() which are
\r
1379 safe type casts on the referenced node.
\r
1381 const char *GetText() const;
\r
1383 /// Creates a new Element and returns it - the returned element is a copy.
\r
1384 virtual TiXmlNode *Clone() const;
\r
1385 // Print the Element to a FILE stream.
\r
1386 virtual void Print(FILE *cfile, int depth) const;
\r
1388 /* Attribtue parsing starts: next char past '<'
\r
1389 returns: next char past '>'
\r
1391 virtual const char *Parse(const char *p, TiXmlParsingData *data, TiXmlEncoding encoding);
\r
1393 virtual const TiXmlElement *ToElement() const
\r
1395 return this; ///< Cast to a more defined type. Will return null not of the requested type.
\r
1397 virtual TiXmlElement *ToElement()
\r
1399 return this; ///< Cast to a more defined type. Will return null not of the requested type.
\r
1402 /** Walk the XML tree visiting this node and all of its children.
\r
1404 virtual bool Accept(TiXmlVisitor *visitor) const;
\r
1407 void CopyTo(TiXmlElement *target) const;
\r
1408 void ClearThis(); // like clear, but initializes 'this' object as well
\r
1410 // Used to be public [internal use]
\r
1411 #ifdef TIXML_USE_STL
\r
1412 virtual void StreamIn(std::istream *in, TIXML_STRING *tag);
\r
1415 Reads the "value" of the element -- another element, or text.
\r
1416 This should terminate with the current end tag.
\r
1418 const char *ReadValue(const char *in, TiXmlParsingData *prevData, TiXmlEncoding encoding);
\r
1421 TiXmlAttributeSet attributeSet;
\r
1424 /** An XML comment.
\r
1426 class TiXmlComment : public TiXmlNode
\r
1429 /// Constructs an empty comment.
\r
1431 : TiXmlNode(TiXmlNode::TINYXML_COMMENT)
\r
1434 /// Construct a comment from text.
\r
1435 TiXmlComment(const char *_value)
\r
1436 : TiXmlNode(TiXmlNode::TINYXML_COMMENT)
\r
1440 TiXmlComment(const TiXmlComment &);
\r
1441 TiXmlComment &operator=(const TiXmlComment &base);
\r
1443 virtual ~TiXmlComment()
\r
1447 /// Returns a copy of this Comment.
\r
1448 virtual TiXmlNode *Clone() const;
\r
1449 // Write this Comment to a FILE stream.
\r
1450 virtual void Print(FILE *cfile, int depth) const;
\r
1452 /* Attribtue parsing starts: at the ! of the !--
\r
1453 returns: next char past '>'
\r
1455 virtual const char *Parse(const char *p, TiXmlParsingData *data, TiXmlEncoding encoding);
\r
1457 virtual const TiXmlComment *ToComment() const
\r
1459 return this; ///< Cast to a more defined type. Will return null not of the requested type.
\r
1461 virtual TiXmlComment *ToComment()
\r
1463 return this; ///< Cast to a more defined type. Will return null not of the requested type.
\r
1466 /** Walk the XML tree visiting this node and all of its children.
\r
1468 virtual bool Accept(TiXmlVisitor *visitor) const;
\r
1471 void CopyTo(TiXmlComment *target) const;
\r
1473 // used to be public
\r
1474 #ifdef TIXML_USE_STL
\r
1475 virtual void StreamIn(std::istream *in, TIXML_STRING *tag);
\r
1477 // virtual void StreamOut( TIXML_OSTREAM * out ) const;
\r
1482 /** XML text. A text node can have 2 ways to output the next. "normal" output
\r
1483 and CDATA. It will default to the mode it was parsed from the XML file and
\r
1484 you generally want to leave it alone, but you can change the output mode with
\r
1485 SetCDATA() and query it with CDATA().
\r
1487 class TiXmlText : public TiXmlNode
\r
1489 friend class TiXmlElement;
\r
1492 /** Constructor for text element. By default, it is treated as
\r
1493 normal, encoded text. If you want it be output as a CDATA text
\r
1494 element, set the parameter _cdata to 'true'
\r
1496 TiXmlText(const char *initValue)
\r
1497 : TiXmlNode(TiXmlNode::TINYXML_TEXT)
\r
1499 SetValue(initValue);
\r
1502 virtual ~TiXmlText()
\r
1506 #ifdef TIXML_USE_STL
\r
1508 TiXmlText(const std::string &initValue)
\r
1509 : TiXmlNode(TiXmlNode::TINYXML_TEXT)
\r
1511 SetValue(initValue);
\r
1516 TiXmlText(const TiXmlText ©)
\r
1517 : TiXmlNode(TiXmlNode::TINYXML_TEXT)
\r
1519 copy.CopyTo(this);
\r
1521 TiXmlText &operator=(const TiXmlText &base)
\r
1523 base.CopyTo(this);
\r
1527 // Write this text object to a FILE stream.
\r
1528 virtual void Print(FILE *cfile, int depth) const;
\r
1530 /// Queries whether this represents text using a CDATA section.
\r
1531 bool CDATA() const
\r
1535 /// Turns on or off a CDATA representation of text.
\r
1536 void SetCDATA(bool _cdata)
\r
1541 virtual const char *Parse(const char *p, TiXmlParsingData *data, TiXmlEncoding encoding);
\r
1543 virtual const TiXmlText *ToText() const
\r
1545 return this; ///< Cast to a more defined type. Will return null not of the requested type.
\r
1547 virtual TiXmlText *ToText()
\r
1549 return this; ///< Cast to a more defined type. Will return null not of the requested type.
\r
1552 /** Walk the XML tree visiting this node and all of its children.
\r
1554 virtual bool Accept(TiXmlVisitor *content) const;
\r
1557 /// [internal use] Creates a new Element and returns it.
\r
1558 virtual TiXmlNode *Clone() const;
\r
1559 void CopyTo(TiXmlText *target) const;
\r
1561 bool Blank() const; // returns true if all white space and new lines
\r
1563 #ifdef TIXML_USE_STL
\r
1564 virtual void StreamIn(std::istream *in, TIXML_STRING *tag);
\r
1568 bool cdata; // true if this should be input and output as a CDATA style text element
\r
1571 /** In correct XML the declaration is the first entry in the file.
\r
1573 <?xml version="1.0" standalone="yes"?>
\r
1576 TinyXml will happily read or write files without a declaration,
\r
1577 however. There are 3 possible attributes to the declaration:
\r
1578 version, encoding, and standalone.
\r
1580 Note: In this version of the code, the attributes are
\r
1581 handled as special cases, not generic attributes, simply
\r
1582 because there can only be at most 3 and they are always the same.
\r
1584 class TiXmlDeclaration : public TiXmlNode
\r
1587 /// Construct an empty declaration.
\r
1588 TiXmlDeclaration()
\r
1589 : TiXmlNode(TiXmlNode::TINYXML_DECLARATION)
\r
1593 #ifdef TIXML_USE_STL
\r
1595 TiXmlDeclaration(const std::string &_version,
\r
1596 const std::string &_encoding,
\r
1597 const std::string &_standalone);
\r
1601 TiXmlDeclaration(const char *_version,
\r
1602 const char *_encoding,
\r
1603 const char *_standalone);
\r
1605 TiXmlDeclaration(const TiXmlDeclaration ©);
\r
1606 TiXmlDeclaration &operator=(const TiXmlDeclaration ©);
\r
1608 virtual ~TiXmlDeclaration()
\r
1612 /// Version. Will return an empty string if none was found.
\r
1613 const char *Version() const
\r
1615 return version.c_str();
\r
1617 /// Encoding. Will return an empty string if none was found.
\r
1618 const char *Encoding() const
\r
1620 return encoding.c_str();
\r
1622 /// Is this a standalone document?
\r
1623 const char *Standalone() const
\r
1625 return standalone.c_str();
\r
1628 /// Creates a copy of this Declaration and returns it.
\r
1629 virtual TiXmlNode *Clone() const;
\r
1630 // Print this declaration to a FILE stream.
\r
1631 virtual void Print(FILE *cfile, int depth, TIXML_STRING *str) const;
\r
1632 virtual void Print(FILE *cfile, int depth) const
\r
1634 Print(cfile, depth, 0);
\r
1637 virtual const char *Parse(const char *p, TiXmlParsingData *data, TiXmlEncoding encoding);
\r
1639 virtual const TiXmlDeclaration *ToDeclaration() const
\r
1641 return this; ///< Cast to a more defined type. Will return null not of the requested type.
\r
1643 virtual TiXmlDeclaration *ToDeclaration()
\r
1645 return this; ///< Cast to a more defined type. Will return null not of the requested type.
\r
1648 /** Walk the XML tree visiting this node and all of its children.
\r
1650 virtual bool Accept(TiXmlVisitor *visitor) const;
\r
1653 void CopyTo(TiXmlDeclaration *target) const;
\r
1654 // used to be public
\r
1655 #ifdef TIXML_USE_STL
\r
1656 virtual void StreamIn(std::istream *in, TIXML_STRING *tag);
\r
1660 TIXML_STRING version;
\r
1661 TIXML_STRING encoding;
\r
1662 TIXML_STRING standalone;
\r
1665 /** Any tag that tinyXml doesn't recognize is saved as an
\r
1666 unknown. It is a tag of text, but should not be modified.
\r
1667 It will be written back to the XML, unchanged, when the file
\r
1670 DTD tags get thrown into TiXmlUnknowns.
\r
1672 class TiXmlUnknown : public TiXmlNode
\r
1676 : TiXmlNode(TiXmlNode::TINYXML_UNKNOWN)
\r
1679 virtual ~TiXmlUnknown()
\r
1683 TiXmlUnknown(const TiXmlUnknown ©)
\r
1684 : TiXmlNode(TiXmlNode::TINYXML_UNKNOWN)
\r
1686 copy.CopyTo(this);
\r
1688 TiXmlUnknown &operator=(const TiXmlUnknown ©)
\r
1690 copy.CopyTo(this);
\r
1694 /// Creates a copy of this Unknown and returns it.
\r
1695 virtual TiXmlNode *Clone() const;
\r
1696 // Print this Unknown to a FILE stream.
\r
1697 virtual void Print(FILE *cfile, int depth) const;
\r
1699 virtual const char *Parse(const char *p, TiXmlParsingData *data, TiXmlEncoding encoding);
\r
1701 virtual const TiXmlUnknown *ToUnknown() const
\r
1703 return this; ///< Cast to a more defined type. Will return null not of the requested type.
\r
1705 virtual TiXmlUnknown *ToUnknown()
\r
1707 return this; ///< Cast to a more defined type. Will return null not of the requested type.
\r
1710 /** Walk the XML tree visiting this node and all of its children.
\r
1712 virtual bool Accept(TiXmlVisitor *content) const;
\r
1715 void CopyTo(TiXmlUnknown *target) const;
\r
1717 #ifdef TIXML_USE_STL
\r
1718 virtual void StreamIn(std::istream *in, TIXML_STRING *tag);
\r
1724 /** Always the top level node. A document binds together all the
\r
1725 XML pieces. It can be saved, loaded, and printed to the screen.
\r
1726 The 'value' of a document node is the xml file name.
\r
1728 class TiXmlDocument : public TiXmlNode
\r
1731 /// Create an empty document, that has no name.
\r
1733 /// Create a document with a name. The name of the document is also the filename of the xml.
\r
1734 TiXmlDocument(const char *documentName);
\r
1736 #ifdef TIXML_USE_STL
\r
1738 TiXmlDocument(const std::string &documentName);
\r
1741 TiXmlDocument(const TiXmlDocument ©);
\r
1742 TiXmlDocument &operator=(const TiXmlDocument ©);
\r
1744 virtual ~TiXmlDocument()
\r
1748 /** Load a file using the current document value.
\r
1749 Returns true if successful. Will delete any existing
\r
1750 document data before loading.
\r
1752 bool LoadFile(TiXmlEncoding encoding = TIXML_DEFAULT_ENCODING);
\r
1753 /// Save a file using the current document value. Returns true if successful.
\r
1754 bool SaveFile() const;
\r
1755 /// Load a file using the given filename. Returns true if successful.
\r
1756 bool LoadFile(const char *filename, TiXmlEncoding encoding = TIXML_DEFAULT_ENCODING);
\r
1757 /// Save a file using the given filename. Returns true if successful.
\r
1758 bool SaveFile(const char *filename) const;
\r
1759 /** Load a file using the given FILE*. Returns true if successful. Note that this method
\r
1760 doesn't stream - the entire object pointed at by the FILE*
\r
1761 will be interpreted as an XML file. TinyXML doesn't stream in XML from the current
\r
1762 file location. Streaming may be added in the future.
\r
1764 bool LoadFile(FILE *, TiXmlEncoding encoding = TIXML_DEFAULT_ENCODING);
\r
1765 /// Save a file using the given FILE*. Returns true if successful.
\r
1766 bool SaveFile(FILE *) const;
\r
1768 #ifdef TIXML_USE_STL
\r
1769 bool LoadFile(const std::string &filename, TiXmlEncoding encoding = TIXML_DEFAULT_ENCODING) ///< STL std::string version.
\r
1771 return LoadFile(filename.c_str(), encoding);
\r
1773 bool SaveFile(const std::string &filename) const ///< STL std::string version.
\r
1775 return SaveFile(filename.c_str());
\r
1779 /** Parse the given null terminated block of xml data. Passing in an encoding to this
\r
1780 method (either TIXML_ENCODING_LEGACY or TIXML_ENCODING_UTF8 will force TinyXml
\r
1781 to use that encoding, regardless of what TinyXml might otherwise try to detect.
\r
1783 virtual const char *Parse(const char *p, TiXmlParsingData *data = 0, TiXmlEncoding encoding = TIXML_DEFAULT_ENCODING);
\r
1785 /** Get the root element -- the only top level element -- of the document.
\r
1786 In well formed XML, there should only be one. TinyXml is tolerant of
\r
1787 multiple elements at the document level.
\r
1789 const TiXmlElement *RootElement() const
\r
1791 return FirstChildElement();
\r
1793 TiXmlElement *RootElement()
\r
1795 return FirstChildElement();
\r
1798 /** If an error occurs, Error will be set to true. Also,
\r
1799 - The ErrorId() will contain the integer identifier of the error (not generally useful)
\r
1800 - The ErrorDesc() method will return the name of the error. (very useful)
\r
1801 - The ErrorRow() and ErrorCol() will return the location of the error (if known)
\r
1803 bool Error() const
\r
1808 /// Contains a textual (english) description of the error if one occurs.
\r
1809 const char *ErrorDesc() const
\r
1811 return errorDesc.c_str();
\r
1814 /** Generally, you probably want the error string ( ErrorDesc() ). But if you
\r
1815 prefer the ErrorId, this function will fetch it.
\r
1817 int ErrorId() const
\r
1822 /** Returns the location (if known) of the error. The first column is column 1,
\r
1823 and the first row is row 1. A value of 0 means the row and column wasn't applicable
\r
1824 (memory errors, for example, have no row/column) or the parser lost the error. (An
\r
1825 error in the error reporting, in that case.)
\r
1827 @sa SetTabSize, Row, Column
\r
1829 int ErrorRow() const
\r
1831 return errorLocation.row + 1;
\r
1833 int ErrorCol() const
\r
1835 return errorLocation.col + 1; ///< The column where the error occured. See ErrorRow()
\r
1838 /** SetTabSize() allows the error reporting functions (ErrorRow() and ErrorCol())
\r
1839 to report the correct values for row and column. It does not change the output
\r
1840 or input in any way.
\r
1842 By calling this method, with a tab size
\r
1843 greater than 0, the row and column of each node and attribute is stored
\r
1844 when the file is loaded. Very useful for tracking the DOM back in to
\r
1847 The tab size is required for calculating the location of nodes. If not
\r
1848 set, the default of 4 is used. The tabsize is set per document. Setting
\r
1849 the tabsize to 0 disables row/column tracking.
\r
1851 Note that row and column tracking is not supported when using operator>>.
\r
1853 The tab size needs to be enabled before the parse or load. Correct usage:
\r
1855 TiXmlDocument doc;
\r
1856 doc.SetTabSize( 8 );
\r
1857 doc.Load( "myfile.xml" );
\r
1862 void SetTabSize(int _tabsize)
\r
1864 tabsize = _tabsize;
\r
1867 int TabSize() const
\r
1872 /** If you have handled the error, it can be reset with this call. The error
\r
1873 state is automatically cleared if you Parse a new XML block.
\r
1880 errorLocation.row = errorLocation.col = 0;
\r
1881 //errorLocation.last = 0;
\r
1884 /** Write the document to standard out using formatted printing ("pretty print"). */
\r
1885 void Print() const
\r
1890 /* Write the document to a string using formatted printing ("pretty print"). This
\r
1891 will allocate a character array (new char[]) and return it as a pointer. The
\r
1892 calling code pust call delete[] on the return char* to avoid a memory leak.
\r
1894 //char* PrintToMemory() const;
\r
1896 /// Print this Document to a FILE stream.
\r
1897 virtual void Print(FILE *cfile, int depth = 0) const;
\r
1899 void SetError(int err, const char *errorLocation, TiXmlParsingData *prevData, TiXmlEncoding encoding);
\r
1901 virtual const TiXmlDocument *ToDocument() const
\r
1903 return this; ///< Cast to a more defined type. Will return null not of the requested type.
\r
1905 virtual TiXmlDocument *ToDocument()
\r
1907 return this; ///< Cast to a more defined type. Will return null not of the requested type.
\r
1910 /** Walk the XML tree visiting this node and all of its children.
\r
1912 virtual bool Accept(TiXmlVisitor *content) const;
\r
1916 virtual TiXmlNode *Clone() const;
\r
1917 #ifdef TIXML_USE_STL
\r
1918 virtual void StreamIn(std::istream *in, TIXML_STRING *tag);
\r
1922 void CopyTo(TiXmlDocument *target) const;
\r
1926 TIXML_STRING errorDesc;
\r
1928 TiXmlCursor errorLocation;
\r
1929 bool useMicrosoftBOM; // the UTF-8 BOM were found when read. Note this, and try to write.
\r
1933 A TiXmlHandle is a class that wraps a node pointer with null checks; this is
\r
1934 an incredibly useful thing. Note that TiXmlHandle is not part of the TinyXml
\r
1935 DOM structure. It is a separate utility class.
\r
1940 <Element attributeA = "valueA">
\r
1941 <Child attributeB = "value1" />
\r
1942 <Child attributeB = "value2" />
\r
1947 Assuming you want the value of "attributeB" in the 2nd "Child" element, it's very
\r
1948 easy to write a *lot* of code that looks like:
\r
1951 TiXmlElement* root = document.FirstChildElement( "Document" );
\r
1954 TiXmlElement* element = root->FirstChildElement( "Element" );
\r
1957 TiXmlElement* child = element->FirstChildElement( "Child" );
\r
1960 TiXmlElement* child2 = child->NextSiblingElement( "Child" );
\r
1963 // Finally do something useful.
\r
1966 And that doesn't even cover "else" cases. TiXmlHandle addresses the verbosity
\r
1967 of such code. A TiXmlHandle checks for null pointers so it is perfectly safe
\r
1968 and correct to use:
\r
1971 TiXmlHandle docHandle( &document );
\r
1972 TiXmlElement* child2 = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", 1 ).ToElement();
\r
1975 // do something useful
\r
1978 Which is MUCH more concise and useful.
\r
1980 It is also safe to copy handles - internally they are nothing more than node pointers.
\r
1982 TiXmlHandle handleCopy = handle;
\r
1985 What they should not be used for is iteration:
\r
1991 TiXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", i ).ToElement();
\r
1999 It seems reasonable, but it is in fact two embedded while loops. The Child method is
\r
2000 a linear walk to find the element, so this code would iterate much more than it needs
\r
2001 to. Instead, prefer:
\r
2004 TiXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).FirstChild( "Child" ).ToElement();
\r
2006 for( child; child; child=child->NextSiblingElement() )
\r
2015 /// Create a handle from any node (at any depth of the tree.) This can be a null pointer.
\r
2016 TiXmlHandle(TiXmlNode *_node)
\r
2018 this->node = _node;
\r
2020 /// Copy constructor
\r
2021 TiXmlHandle(const TiXmlHandle &ref)
\r
2023 this->node = ref.node;
\r
2025 TiXmlHandle operator=(const TiXmlHandle &ref)
\r
2028 this->node = ref.node;
\r
2032 /// Return a handle to the first child node.
\r
2033 TiXmlHandle FirstChild() const;
\r
2034 /// Return a handle to the first child node with the given name.
\r
2035 TiXmlHandle FirstChild(const char *value) const;
\r
2036 /// Return a handle to the first child element.
\r
2037 TiXmlHandle FirstChildElement() const;
\r
2038 /// Return a handle to the first child element with the given name.
\r
2039 TiXmlHandle FirstChildElement(const char *value) const;
\r
2041 /** Return a handle to the "index" child with the given name.
\r
2042 The first child is 0, the second 1, etc.
\r
2044 TiXmlHandle Child(const char *value, int index) const;
\r
2045 /** Return a handle to the "index" child.
\r
2046 The first child is 0, the second 1, etc.
\r
2048 TiXmlHandle Child(int index) const;
\r
2049 /** Return a handle to the "index" child element with the given name.
\r
2050 The first child element is 0, the second 1, etc. Note that only TiXmlElements
\r
2051 are indexed: other types are not counted.
\r
2053 TiXmlHandle ChildElement(const char *value, int index) const;
\r
2054 /** Return a handle to the "index" child element.
\r
2055 The first child element is 0, the second 1, etc. Note that only TiXmlElements
\r
2056 are indexed: other types are not counted.
\r
2058 TiXmlHandle ChildElement(int index) const;
\r
2060 #ifdef TIXML_USE_STL
\r
2061 TiXmlHandle FirstChild(const std::string &_value) const
\r
2063 return FirstChild(_value.c_str());
\r
2065 TiXmlHandle FirstChildElement(const std::string &_value) const
\r
2067 return FirstChildElement(_value.c_str());
\r
2070 TiXmlHandle Child(const std::string &_value, int index) const
\r
2072 return Child(_value.c_str(), index);
\r
2074 TiXmlHandle ChildElement(const std::string &_value, int index) const
\r
2076 return ChildElement(_value.c_str(), index);
\r
2080 /** Return the handle as a TiXmlNode. This may return null.
\r
2082 TiXmlNode *ToNode() const
\r
2086 /** Return the handle as a TiXmlElement. This may return null.
\r
2088 TiXmlElement *ToElement() const
\r
2090 return ((node && node->ToElement()) ? node->ToElement() : 0);
\r
2092 /** Return the handle as a TiXmlText. This may return null.
\r
2094 TiXmlText *ToText() const
\r
2096 return ((node && node->ToText()) ? node->ToText() : 0);
\r
2098 /** Return the handle as a TiXmlUnknown. This may return null.
\r
2100 TiXmlUnknown *ToUnknown() const
\r
2102 return ((node && node->ToUnknown()) ? node->ToUnknown() : 0);
\r
2105 /** @deprecated use ToNode.
\r
2106 Return the handle as a TiXmlNode. This may return null.
\r
2108 TiXmlNode *Node() const
\r
2112 /** @deprecated use ToElement.
\r
2113 Return the handle as a TiXmlElement. This may return null.
\r
2115 TiXmlElement *Element() const
\r
2117 return ToElement();
\r
2119 /** @deprecated use ToText()
\r
2120 Return the handle as a TiXmlText. This may return null.
\r
2122 TiXmlText *Text() const
\r
2126 /** @deprecated use ToUnknown()
\r
2127 Return the handle as a TiXmlUnknown. This may return null.
\r
2129 TiXmlUnknown *Unknown() const
\r
2131 return ToUnknown();
\r
2138 /** Print to memory functionality. The TiXmlPrinter is useful when you need to:
\r
2140 -# Print to memory (especially in non-STL mode)
\r
2141 -# Control formatting (line endings, etc.)
\r
2143 When constructed, the TiXmlPrinter is in its default "pretty printing" mode.
\r
2144 Before calling Accept() you can call methods to control the printing
\r
2145 of the XML document. After TiXmlNode::Accept() is called, the printed document can
\r
2146 be accessed via the CStr(), Str(), and Size() methods.
\r
2148 TiXmlPrinter uses the Visitor API.
\r
2150 TiXmlPrinter printer;
\r
2151 printer.SetIndent( "\t" );
\r
2153 doc.Accept( &printer );
\r
2154 fprintf( stdout, "%s", printer.CStr() );
\r
2157 class TiXmlPrinter : public TiXmlVisitor
\r
2161 : depth(0), simpleTextPrint(false),
\r
2162 buffer(), indent(" "), lineBreak("\n")
\r
2166 virtual bool VisitEnter(const TiXmlDocument &doc);
\r
2167 virtual bool VisitExit(const TiXmlDocument &doc);
\r
2169 virtual bool VisitEnter(const TiXmlElement &element, const TiXmlAttribute *firstAttribute);
\r
2170 virtual bool VisitExit(const TiXmlElement &element);
\r
2172 virtual bool Visit(const TiXmlDeclaration &declaration);
\r
2173 virtual bool Visit(const TiXmlText &text);
\r
2174 virtual bool Visit(const TiXmlComment &comment);
\r
2175 virtual bool Visit(const TiXmlUnknown &unknown);
\r
2177 /** Set the indent characters for printing. By default 4 spaces
\r
2178 but tab (\t) is also useful, or null/empty string for no indentation.
\r
2180 void SetIndent(const char *_indent)
\r
2182 indent = _indent ? _indent : "";
\r
2184 /// Query the indention string.
\r
2185 const char *Indent()
\r
2187 return indent.c_str();
\r
2189 /** Set the line breaking string. By default set to newline (\n).
\r
2190 Some operating systems prefer other characters, or can be
\r
2191 set to the null/empty string for no indenation.
\r
2193 void SetLineBreak(const char *_lineBreak)
\r
2195 lineBreak = _lineBreak ? _lineBreak : "";
\r
2197 /// Query the current line breaking string.
\r
2198 const char *LineBreak()
\r
2200 return lineBreak.c_str();
\r
2203 /** Switch over to "stream printing" which is the most dense formatting without
\r
2204 linebreaks. Common when the XML is needed for network transmission.
\r
2206 void SetStreamPrinting()
\r
2211 /// Return the result.
\r
2212 const char *CStr()
\r
2214 return buffer.c_str();
\r
2216 /// Return the length of the result string.
\r
2219 return buffer.size();
\r
2222 #ifdef TIXML_USE_STL
\r
2223 /// Return the result.
\r
2224 const std::string &Str()
\r
2233 for (int i = 0; i < depth; ++i)
\r
2236 void DoLineBreak()
\r
2238 buffer += lineBreak;
\r
2242 bool simpleTextPrint;
\r
2243 TIXML_STRING buffer;
\r
2244 TIXML_STRING indent;
\r
2245 TIXML_STRING lineBreak;
\r
2249 #pragma warning(pop)
\r