Chameleon

Chameleon Svn Source Tree

Root/branches/xZenu/src/modules/TinyXML/include/tinyxml.h

Source at commit 1307 created 9 years 5 months ago.
By meklort, Add TinyXML as a module
1/*
2www.sourceforge.net/projects/tinyxml
3Original code by Lee Thomason (www.grinninglizard.com)
4
5This software is provided 'as-is', without any express or implied
6warranty. In no event will the authors be held liable for any
7damages arising from the use of this software.
8
9Permission is granted to anyone to use this software for any
10purpose, including commercial applications, and to alter it and
11redistribute it freely, subject to the following restrictions:
12
131. The origin of this software must not be misrepresented; you must
14not claim that you wrote the original software. If you use this
15software in a product, an acknowledgment in the product documentation
16would be appreciated but is not required.
17
182. Altered source versions must be plainly marked as such, and
19must not be misrepresented as being the original software.
20
213. This notice may not be removed or altered from any source
22distribution.
23*/
24
25
26#ifndef TINYXML_INCLUDED
27#define TINYXML_INCLUDED
28
29#ifdef _MSC_VER
30#pragma warning( push )
31#pragma warning( disable : 4530 )
32#pragma warning( disable : 4786 )
33#endif
34
35#include <ctype.h>
36#include <stdio.h>
37#include <stdlib.h>
38#include <string.h>
39#include <assert.h>
40
41// Help out windows:
42#if defined( _DEBUG ) && !defined( DEBUG )
43#define DEBUG
44#endif
45
46#ifdef TIXML_USE_STL
47#include <string>
48 #include <iostream>
49#include <sstream>
50#define TIXML_STRINGstd::string
51#else
52#include "tinystr.h"
53#define TIXML_STRINGTiXmlString
54#endif
55
56// Deprecated library function hell. Compilers want to use the
57// new safe versions. This probably doesn't fully address the problem,
58// but it gets closer. There are too many compilers for me to fully
59// test. If you get compilation troubles, undefine TIXML_SAFE
60#define TIXML_SAFE
61
62#ifdef TIXML_SAFE
63#if defined(_MSC_VER) && (_MSC_VER >= 1400 )
64// Microsoft visual studio, version 2005 and higher.
65#define TIXML_SNPRINTF _snprintf_s
66#define TIXML_SSCANF sscanf_s
67#elif defined(_MSC_VER) && (_MSC_VER >= 1200 )
68// Microsoft visual studio, version 6 and higher.
69//#pragma message( "Using _sn* functions." )
70#define TIXML_SNPRINTF _snprintf
71#define TIXML_SSCANF sscanf
72#elif defined(__GNUC__) && (__GNUC__ >= 3 )
73// GCC version 3 and higher.s
74//#warning( "Using sn* functions." )
75#define TIXML_SNPRINTF snprintf
76#define TIXML_SSCANF sscanf
77#else
78#define TIXML_SNPRINTF snprintf
79#define TIXML_SSCANF sscanf
80#endif
81#endif
82
83class TiXmlDocument;
84class TiXmlElement;
85class TiXmlComment;
86class TiXmlUnknown;
87class TiXmlAttribute;
88class TiXmlText;
89class TiXmlDeclaration;
90class TiXmlParsingData;
91
92const int TIXML_MAJOR_VERSION = 2;
93const int TIXML_MINOR_VERSION = 6;
94const int TIXML_PATCH_VERSION = 2;
95
96/*Internal structure for tracking location of items
97in the XML file.
98*/
99struct TiXmlCursor
100{
101TiXmlCursor(){ Clear(); }
102void Clear(){ row = col = -1; }
103
104int row;// 0 based.
105int col;// 0 based.
106};
107
108
109/**
110Implements the interface to the "Visitor pattern" (see the Accept() method.)
111If you call the Accept() method, it requires being passed a TiXmlVisitor
112class to handle callbacks. For nodes that contain other nodes (Document, Element)
113you will get called with a VisitEnter/VisitExit pair. Nodes that are always leaves
114are simply called with Visit().
115
116If you return 'true' from a Visit method, recursive parsing will continue. If you return
117false, <b>no children of this node or its sibilings</b> will be Visited.
118
119All flavors of Visit methods have a default implementation that returns 'true' (continue
120visiting). You need to only override methods that are interesting to you.
121
122Generally Accept() is called on the TiXmlDocument, although all nodes suppert Visiting.
123
124You should never change the document from a callback.
125
126@sa TiXmlNode::Accept()
127*/
128class TiXmlVisitor
129{
130public:
131virtual ~TiXmlVisitor() {}
132
133/// Visit a document.
134virtual bool VisitEnter( const TiXmlDocument& /*doc*/ ){ return true; }
135/// Visit a document.
136virtual bool VisitExit( const TiXmlDocument& /*doc*/ ){ return true; }
137
138/// Visit an element.
139virtual bool VisitEnter( const TiXmlElement& /*element*/, const TiXmlAttribute* /*firstAttribute*/ ){ return true; }
140/// Visit an element.
141virtual bool VisitExit( const TiXmlElement& /*element*/ ){ return true; }
142
143/// Visit a declaration
144virtual bool Visit( const TiXmlDeclaration& /*declaration*/ ){ return true; }
145/// Visit a text node
146virtual bool Visit( const TiXmlText& /*text*/ ){ return true; }
147/// Visit a comment node
148virtual bool Visit( const TiXmlComment& /*comment*/ ){ return true; }
149/// Visit an unknown node
150virtual bool Visit( const TiXmlUnknown& /*unknown*/ ){ return true; }
151};
152
153// Only used by Attribute::Query functions
154enum
155{
156TIXML_SUCCESS,
157TIXML_NO_ATTRIBUTE,
158TIXML_WRONG_TYPE
159};
160
161
162// Used by the parsing routines.
163enum TiXmlEncoding
164{
165TIXML_ENCODING_UNKNOWN,
166TIXML_ENCODING_UTF8,
167TIXML_ENCODING_LEGACY
168};
169
170const TiXmlEncoding TIXML_DEFAULT_ENCODING = TIXML_ENCODING_UNKNOWN;
171
172/** TiXmlBase is a base class for every class in TinyXml.
173It does little except to establish that TinyXml classes
174can be printed and provide some utility functions.
175
176In XML, the document and elements can contain
177other elements and other types of nodes.
178
179@verbatim
180A Document can contain:Element(container or leaf)
181Comment (leaf)
182Unknown (leaf)
183Declaration( leaf )
184
185An Element can contain:Element (container or leaf)
186Text(leaf)
187Attributes (not on tree)
188Comment (leaf)
189Unknown (leaf)
190
191A Decleration contains: Attributes (not on tree)
192@endverbatim
193*/
194class TiXmlBase
195{
196friend class TiXmlNode;
197friend class TiXmlElement;
198friend class TiXmlDocument;
199
200public:
201TiXmlBase():userData(0){}
202virtual ~TiXmlBase(){}
203
204/**All TinyXml classes can print themselves to a filestream
205or the string class (TiXmlString in non-STL mode, std::string
206in STL mode.) Either or both cfile and str can be null.
207
208This is a formatted print, and will insert
209tabs and newlines.
210
211(For an unformatted stream, use the << operator.)
212*/
213virtual void Print( FILE* cfile, int depth ) const = 0;
214
215/**The world does not agree on whether white space should be kept or
216not. In order to make everyone happy, these global, static functions
217are provided to set whether or not TinyXml will condense all white space
218into a single space or not. The default is to condense. Note changing this
219value is not thread safe.
220*/
221static void SetCondenseWhiteSpace( bool condense ){ condenseWhiteSpace = condense; }
222
223/// Return the current white space setting.
224static bool IsWhiteSpaceCondensed(){ return condenseWhiteSpace; }
225
226/** Return the position, in the original source file, of this node or attribute.
227The row and column are 1-based. (That is the first row and first column is
2281,1). If the returns values are 0 or less, then the parser does not have
229a row and column value.
230
231Generally, the row and column value will be set when the TiXmlDocument::Load(),
232TiXmlDocument::LoadFile(), or any TiXmlNode::Parse() is called. It will NOT be set
233when the DOM was created from operator>>.
234
235The values reflect the initial load. Once the DOM is modified programmatically
236(by adding or changing nodes and attributes) the new values will NOT update to
237reflect changes in the document.
238
239There is a minor performance cost to computing the row and column. Computation
240can be disabled if TiXmlDocument::SetTabSize() is called with 0 as the value.
241
242@sa TiXmlDocument::SetTabSize()
243*/
244int Row() const{ return location.row + 1; }
245int Column() const{ return location.col + 1; }///< See Row()
246
247void SetUserData( void* user ){ userData = user; }///< Set a pointer to arbitrary user data.
248void* GetUserData(){ return userData; }///< Get a pointer to arbitrary user data.
249const void* GetUserData() const { return userData; }///< Get a pointer to arbitrary user data.
250
251// Table that returs, for a given lead byte, the total number of bytes
252// in the UTF-8 sequence.
253static const int utf8ByteTable[256];
254
255virtual const char* Parse(const char* p,
256TiXmlParsingData* data,
257TiXmlEncoding encoding /*= TIXML_ENCODING_UNKNOWN */ ) = 0;
258
259/** Expands entities in a string. Note this should not contian the tag's '<', '>', etc,
260or they will be transformed into entities!
261*/
262static void EncodeString( const TIXML_STRING& str, TIXML_STRING* out );
263
264enum
265{
266TIXML_NO_ERROR = 0,
267TIXML_ERROR,
268TIXML_ERROR_OPENING_FILE,
269TIXML_ERROR_PARSING_ELEMENT,
270TIXML_ERROR_FAILED_TO_READ_ELEMENT_NAME,
271TIXML_ERROR_READING_ELEMENT_VALUE,
272TIXML_ERROR_READING_ATTRIBUTES,
273TIXML_ERROR_PARSING_EMPTY,
274TIXML_ERROR_READING_END_TAG,
275TIXML_ERROR_PARSING_UNKNOWN,
276TIXML_ERROR_PARSING_COMMENT,
277TIXML_ERROR_PARSING_DECLARATION,
278TIXML_ERROR_DOCUMENT_EMPTY,
279TIXML_ERROR_EMBEDDED_NULL,
280TIXML_ERROR_PARSING_CDATA,
281TIXML_ERROR_DOCUMENT_TOP_ONLY,
282
283TIXML_ERROR_STRING_COUNT
284};
285
286protected:
287
288static const char* SkipWhiteSpace( const char*, TiXmlEncoding encoding );
289
290inline static bool IsWhiteSpace( char c )
291{
292return ( isspace( (unsigned char) c ) || c == '\n' || c == '\r' );
293}
294inline static bool IsWhiteSpace( int c )
295{
296if ( c < 256 )
297return IsWhiteSpace( (char) c );
298return false;// Again, only truly correct for English/Latin...but usually works.
299}
300
301#ifdef TIXML_USE_STL
302static boolStreamWhiteSpace( std::istream * in, TIXML_STRING * tag );
303static bool StreamTo( std::istream * in, int character, TIXML_STRING * tag );
304#endif
305
306/*Reads an XML name into the string provided. Returns
307a pointer just past the last character of the name,
308or 0 if the function has an error.
309*/
310static const char* ReadName( const char* p, TIXML_STRING* name, TiXmlEncoding encoding );
311
312/*Reads text. Returns a pointer past the given end tag.
313Wickedly complex options, but it keeps the (sensitive) code in one place.
314*/
315static const char* ReadText(const char* in,// where to start
316TIXML_STRING* text,// the string read
317bool ignoreWhiteSpace,// whether to keep the white space
318const char* endTag,// what ends this text
319bool ignoreCase,// whether to ignore case in the end tag
320TiXmlEncoding encoding );// the current encoding
321
322// If an entity has been found, transform it into a character.
323static const char* GetEntity( const char* in, char* value, int* length, TiXmlEncoding encoding );
324
325// Get a character, while interpreting entities.
326// The length can be from 0 to 4 bytes.
327inline static const char* GetChar( const char* p, char* _value, int* length, TiXmlEncoding encoding )
328{
329assert( p );
330if ( encoding == TIXML_ENCODING_UTF8 )
331{
332*length = utf8ByteTable[ *((const unsigned char*)p) ];
333assert( *length >= 0 && *length < 5 );
334}
335else
336{
337*length = 1;
338}
339
340if ( *length == 1 )
341{
342if ( *p == '&' )
343return GetEntity( p, _value, length, encoding );
344*_value = *p;
345return p+1;
346}
347else if ( *length )
348{
349//strncpy( _value, p, *length );// lots of compilers don't like this function (unsafe),
350// and the null terminator isn't needed
351for( int i=0; p[i] && i<*length; ++i ) {
352_value[i] = p[i];
353}
354return p + (*length);
355}
356else
357{
358// Not valid text.
359return 0;
360}
361}
362
363// Return true if the next characters in the stream are any of the endTag sequences.
364// Ignore case only works for english, and should only be relied on when comparing
365// to English words: StringEqual( p, "version", true ) is fine.
366static bool StringEqual(const char* p,
367const char* endTag,
368bool ignoreCase,
369TiXmlEncoding encoding );
370
371static const char* errorString[ TIXML_ERROR_STRING_COUNT ];
372
373TiXmlCursor location;
374
375 /// Field containing a generic user pointer
376void*userData;
377
378// None of these methods are reliable for any language except English.
379// Good for approximation, not great for accuracy.
380static int IsAlpha( unsigned char anyByte, TiXmlEncoding encoding );
381static int IsAlphaNum( unsigned char anyByte, TiXmlEncoding encoding );
382inline static int ToLower( int v, TiXmlEncoding encoding )
383{
384if ( encoding == TIXML_ENCODING_UTF8 )
385{
386if ( v < 128 ) return tolower( v );
387return v;
388}
389else
390{
391return tolower( v );
392}
393}
394static void ConvertUTF32ToUTF8( unsigned long input, char* output, int* length );
395
396private:
397TiXmlBase( const TiXmlBase& );// not implemented.
398void operator=( const TiXmlBase& base );// not allowed.
399
400struct Entity
401{
402const char* str;
403unsigned intstrLength;
404char chr;
405};
406enum
407{
408NUM_ENTITY = 5,
409MAX_ENTITY_LENGTH = 6
410
411};
412static Entity entity[ NUM_ENTITY ];
413static bool condenseWhiteSpace;
414};
415
416
417/** The parent class for everything in the Document Object Model.
418(Except for attributes).
419Nodes have siblings, a parent, and children. A node can be
420in a document, or stand on its own. The type of a TiXmlNode
421can be queried, and it can be cast to its more defined type.
422*/
423class TiXmlNode : public TiXmlBase
424{
425friend class TiXmlDocument;
426friend class TiXmlElement;
427
428public:
429#ifdef TIXML_USE_STL
430
431 /** An input stream operator, for every class. Tolerant of newlines and
432 formatting, but doesn't expect them.
433 */
434 friend std::istream& operator >> (std::istream& in, TiXmlNode& base);
435
436 /** An output stream operator, for every class. Note that this outputs
437 without any newlines or formatting, as opposed to Print(), which
438 includes tabs and new lines.
439
440 The operator<< and operator>> are not completely symmetric. Writing
441 a node to a stream is very well defined. You'll get a nice stream
442 of output, without any extra whitespace or newlines.
443
444 But reading is not as well defined. (As it always is.) If you create
445 a TiXmlElement (for example) and read that from an input stream,
446 the text needs to define an element or junk will result. This is
447 true of all input streams, but it's worth keeping in mind.
448
449 A TiXmlDocument will read nodes until it reads a root element, and
450all the children of that root element.
451 */
452 friend std::ostream& operator<< (std::ostream& out, const TiXmlNode& base);
453
454/// Appends the XML node or attribute to a std::string.
455friend std::string& operator<< (std::string& out, const TiXmlNode& base );
456
457#endif
458
459/** The types of XML nodes supported by TinyXml. (All the
460unsupported types are picked up by UNKNOWN.)
461*/
462enum NodeType
463{
464TINYXML_DOCUMENT,
465TINYXML_ELEMENT,
466TINYXML_COMMENT,
467TINYXML_UNKNOWN,
468TINYXML_TEXT,
469TINYXML_DECLARATION,
470TINYXML_TYPECOUNT
471};
472
473virtual ~TiXmlNode();
474
475/** The meaning of 'value' changes for the specific type of
476TiXmlNode.
477@verbatim
478Document:filename of the xml file
479Element:name of the element
480Comment:the comment text
481Unknown:the tag contents
482Text:the text string
483@endverbatim
484
485The subclasses will wrap this function.
486*/
487const char *Value() const { return value.c_str (); }
488
489 #ifdef TIXML_USE_STL
490/** Return Value() as a std::string. If you only use STL,
491 this is more efficient than calling Value().
492Only available in STL mode.
493*/
494const std::string& ValueStr() const { return value; }
495#endif
496
497const TIXML_STRING& ValueTStr() const { return value; }
498
499/** Changes the value of the node. Defined as:
500@verbatim
501Document:filename of the xml file
502Element:name of the element
503Comment:the comment text
504Unknown:the tag contents
505Text:the text string
506@endverbatim
507*/
508void SetValue(const char * _value) { value = _value;}
509
510 #ifdef TIXML_USE_STL
511/// STL std::string form.
512void SetValue( const std::string& _value ){ value = _value; }
513#endif
514
515/// Delete all the children of this node. Does not affect 'this'.
516void Clear();
517
518/// One step up the DOM.
519TiXmlNode* Parent(){ return parent; }
520const TiXmlNode* Parent() const{ return parent; }
521
522const TiXmlNode* FirstChild()const{ return firstChild; }///< The first child of this node. Will be null if there are no children.
523TiXmlNode* FirstChild(){ return firstChild; }
524const TiXmlNode* FirstChild( const char * value ) const;///< The first child of this node with the matching 'value'. Will be null if none found.
525/// The first child of this node with the matching 'value'. Will be null if none found.
526TiXmlNode* FirstChild( const char * _value ) {
527// Call through to the const version - safe since nothing is changed. Exiting syntax: cast this to a const (always safe)
528// call the method, cast the return back to non-const.
529return const_cast< TiXmlNode* > ((const_cast< const TiXmlNode* >(this))->FirstChild( _value ));
530}
531const TiXmlNode* LastChild() const{ return lastChild; }/// The last child of this node. Will be null if there are no children.
532TiXmlNode* LastChild(){ return lastChild; }
533
534const TiXmlNode* LastChild( const char * value ) const;/// The last child of this node matching 'value'. Will be null if there are no children.
535TiXmlNode* LastChild( const char * _value ) {
536return const_cast< TiXmlNode* > ((const_cast< const TiXmlNode* >(this))->LastChild( _value ));
537}
538
539 #ifdef TIXML_USE_STL
540const TiXmlNode* FirstChild( const std::string& _value ) const{return FirstChild (_value.c_str ());}///< STL std::string form.
541TiXmlNode* FirstChild( const std::string& _value ){return FirstChild (_value.c_str ());}///< STL std::string form.
542const TiXmlNode* LastChild( const std::string& _value ) const{return LastChild (_value.c_str ());}///< STL std::string form.
543TiXmlNode* LastChild( const std::string& _value ){return LastChild (_value.c_str ());}///< STL std::string form.
544#endif
545
546/** An alternate way to walk the children of a node.
547One way to iterate over nodes is:
548@verbatim
549for( child = parent->FirstChild(); child; child = child->NextSibling() )
550@endverbatim
551
552IterateChildren does the same thing with the syntax:
553@verbatim
554child = 0;
555while( child = parent->IterateChildren( child ) )
556@endverbatim
557
558IterateChildren takes the previous child as input and finds
559the next one. If the previous child is null, it returns the
560first. IterateChildren will return null when done.
561*/
562const TiXmlNode* IterateChildren( const TiXmlNode* previous ) const;
563TiXmlNode* IterateChildren( const TiXmlNode* previous ) {
564return const_cast< TiXmlNode* >( (const_cast< const TiXmlNode* >(this))->IterateChildren( previous ) );
565}
566
567/// This flavor of IterateChildren searches for children with a particular 'value'
568const TiXmlNode* IterateChildren( const char * value, const TiXmlNode* previous ) const;
569TiXmlNode* IterateChildren( const char * _value, const TiXmlNode* previous ) {
570return const_cast< TiXmlNode* >( (const_cast< const TiXmlNode* >(this))->IterateChildren( _value, previous ) );
571}
572
573 #ifdef TIXML_USE_STL
574const TiXmlNode* IterateChildren( const std::string& _value, const TiXmlNode* previous ) const{return IterateChildren (_value.c_str (), previous);}///< STL std::string form.
575TiXmlNode* IterateChildren( const std::string& _value, const TiXmlNode* previous ) {return IterateChildren (_value.c_str (), previous);}///< STL std::string form.
576#endif
577
578/** Add a new node related to this. Adds a child past the LastChild.
579Returns a pointer to the new object or NULL if an error occured.
580*/
581TiXmlNode* InsertEndChild( const TiXmlNode& addThis );
582
583
584/** Add a new node related to this. Adds a child past the LastChild.
585
586NOTE: the node to be added is passed by pointer, and will be
587henceforth owned (and deleted) by tinyXml. This method is efficient
588and avoids an extra copy, but should be used with care as it
589uses a different memory model than the other insert functions.
590
591@sa InsertEndChild
592*/
593TiXmlNode* LinkEndChild( TiXmlNode* addThis );
594
595/** Add a new node related to this. Adds a child before the specified child.
596Returns a pointer to the new object or NULL if an error occured.
597*/
598TiXmlNode* InsertBeforeChild( TiXmlNode* beforeThis, const TiXmlNode& addThis );
599
600/** Add a new node related to this. Adds a child after the specified child.
601Returns a pointer to the new object or NULL if an error occured.
602*/
603TiXmlNode* InsertAfterChild( TiXmlNode* afterThis, const TiXmlNode& addThis );
604
605/** Replace a child of this node.
606Returns a pointer to the new object or NULL if an error occured.
607*/
608TiXmlNode* ReplaceChild( TiXmlNode* replaceThis, const TiXmlNode& withThis );
609
610/// Delete a child of this node.
611bool RemoveChild( TiXmlNode* removeThis );
612
613/// Navigate to a sibling node.
614const TiXmlNode* PreviousSibling() const{ return prev; }
615TiXmlNode* PreviousSibling(){ return prev; }
616
617/// Navigate to a sibling node.
618const TiXmlNode* PreviousSibling( const char * ) const;
619TiXmlNode* PreviousSibling( const char *_prev ) {
620return const_cast< TiXmlNode* >( (const_cast< const TiXmlNode* >(this))->PreviousSibling( _prev ) );
621}
622
623 #ifdef TIXML_USE_STL
624const TiXmlNode* PreviousSibling( const std::string& _value ) const{return PreviousSibling (_value.c_str ());}///< STL std::string form.
625TiXmlNode* PreviousSibling( const std::string& _value ) {return PreviousSibling (_value.c_str ());}///< STL std::string form.
626const TiXmlNode* NextSibling( const std::string& _value) const{return NextSibling (_value.c_str ());}///< STL std::string form.
627TiXmlNode* NextSibling( const std::string& _value) {return NextSibling (_value.c_str ());}///< STL std::string form.
628#endif
629
630/// Navigate to a sibling node.
631const TiXmlNode* NextSibling() const{ return next; }
632TiXmlNode* NextSibling(){ return next; }
633
634/// Navigate to a sibling node with the given 'value'.
635const TiXmlNode* NextSibling( const char * ) const;
636TiXmlNode* NextSibling( const char* _next ) {
637return const_cast< TiXmlNode* >( (const_cast< const TiXmlNode* >(this))->NextSibling( _next ) );
638}
639
640/** Convenience function to get through elements.
641Calls NextSibling and ToElement. Will skip all non-Element
642nodes. Returns 0 if there is not another element.
643*/
644const TiXmlElement* NextSiblingElement() const;
645TiXmlElement* NextSiblingElement() {
646return const_cast< TiXmlElement* >( (const_cast< const TiXmlNode* >(this))->NextSiblingElement() );
647}
648
649/** Convenience function to get through elements.
650Calls NextSibling and ToElement. Will skip all non-Element
651nodes. Returns 0 if there is not another element.
652*/
653const TiXmlElement* NextSiblingElement( const char * ) const;
654TiXmlElement* NextSiblingElement( const char *_next ) {
655return const_cast< TiXmlElement* >( (const_cast< const TiXmlNode* >(this))->NextSiblingElement( _next ) );
656}
657
658 #ifdef TIXML_USE_STL
659const TiXmlElement* NextSiblingElement( const std::string& _value) const{return NextSiblingElement (_value.c_str ());}///< STL std::string form.
660TiXmlElement* NextSiblingElement( const std::string& _value){return NextSiblingElement (_value.c_str ());}///< STL std::string form.
661#endif
662
663/// Convenience function to get through elements.
664const TiXmlElement* FirstChildElement()const;
665TiXmlElement* FirstChildElement() {
666return const_cast< TiXmlElement* >( (const_cast< const TiXmlNode* >(this))->FirstChildElement() );
667}
668
669/// Convenience function to get through elements.
670const TiXmlElement* FirstChildElement( const char * _value ) const;
671TiXmlElement* FirstChildElement( const char * _value ) {
672return const_cast< TiXmlElement* >( (const_cast< const TiXmlNode* >(this))->FirstChildElement( _value ) );
673}
674
675 #ifdef TIXML_USE_STL
676const TiXmlElement* FirstChildElement( const std::string& _value ) const{return FirstChildElement (_value.c_str ());}///< STL std::string form.
677TiXmlElement* FirstChildElement( const std::string& _value ){return FirstChildElement (_value.c_str ());}///< STL std::string form.
678#endif
679
680/** Query the type (as an enumerated value, above) of this node.
681The possible types are: TINYXML_DOCUMENT, TINYXML_ELEMENT, TINYXML_COMMENT,
682TINYXML_UNKNOWN, TINYXML_TEXT, and TINYXML_DECLARATION.
683*/
684int Type() const{ return type; }
685
686/** Return a pointer to the Document this node lives in.
687Returns null if not in a document.
688*/
689const TiXmlDocument* GetDocument() const;
690TiXmlDocument* GetDocument() {
691return const_cast< TiXmlDocument* >( (const_cast< const TiXmlNode* >(this))->GetDocument() );
692}
693
694/// Returns true if this node has no children.
695bool NoChildren() const{ return !firstChild; }
696
697virtual const TiXmlDocument* ToDocument() const { return 0; } ///< Cast to a more defined type. Will return null if not of the requested type.
698virtual const TiXmlElement* ToElement() const { return 0; } ///< Cast to a more defined type. Will return null if not of the requested type.
699virtual const TiXmlComment* ToComment() const { return 0; } ///< Cast to a more defined type. Will return null if not of the requested type.
700virtual const TiXmlUnknown* ToUnknown() const { return 0; } ///< Cast to a more defined type. Will return null if not of the requested type.
701virtual const TiXmlText* ToText() const { return 0; } ///< Cast to a more defined type. Will return null if not of the requested type.
702virtual const TiXmlDeclaration* ToDeclaration() const { return 0; } ///< Cast to a more defined type. Will return null if not of the requested type.
703
704virtual TiXmlDocument* ToDocument() { return 0; } ///< Cast to a more defined type. Will return null if not of the requested type.
705virtual TiXmlElement* ToElement() { return 0; } ///< Cast to a more defined type. Will return null if not of the requested type.
706virtual TiXmlComment* ToComment() { return 0; } ///< Cast to a more defined type. Will return null if not of the requested type.
707virtual TiXmlUnknown* ToUnknown() { return 0; } ///< Cast to a more defined type. Will return null if not of the requested type.
708virtual TiXmlText* ToText() { return 0; } ///< Cast to a more defined type. Will return null if not of the requested type.
709virtual TiXmlDeclaration* ToDeclaration() { return 0; } ///< Cast to a more defined type. Will return null if not of the requested type.
710
711/** Create an exact duplicate of this node and return it. The memory must be deleted
712by the caller.
713*/
714virtual TiXmlNode* Clone() const = 0;
715
716/** Accept a hierchical visit the nodes in the TinyXML DOM. Every node in the
717XML tree will be conditionally visited and the host will be called back
718via the TiXmlVisitor interface.
719
720This is essentially a SAX interface for TinyXML. (Note however it doesn't re-parse
721the XML for the callbacks, so the performance of TinyXML is unchanged by using this
722interface versus any other.)
723
724The interface has been based on ideas from:
725
726- http://www.saxproject.org/
727- http://c2.com/cgi/wiki?HierarchicalVisitorPattern
728
729Which are both good references for "visiting".
730
731An example of using Accept():
732@verbatim
733TiXmlPrinter printer;
734tinyxmlDoc.Accept( &printer );
735const char* xmlcstr = printer.CStr();
736@endverbatim
737*/
738virtual bool Accept( TiXmlVisitor* visitor ) const = 0;
739
740protected:
741TiXmlNode( NodeType _type );
742
743// Copy to the allocated object. Shared functionality between Clone, Copy constructor,
744// and the assignment operator.
745void CopyTo( TiXmlNode* target ) const;
746
747#ifdef TIXML_USE_STL
748 // The real work of the input operator.
749virtual void StreamIn( std::istream* in, TIXML_STRING* tag ) = 0;
750#endif
751
752// Figure out what is at *p, and parse it. Returns null if it is not an xml node.
753TiXmlNode* Identify( const char* start, TiXmlEncoding encoding );
754
755TiXmlNode*parent;
756NodeTypetype;
757
758TiXmlNode*firstChild;
759TiXmlNode*lastChild;
760
761TIXML_STRINGvalue;
762
763TiXmlNode*prev;
764TiXmlNode*next;
765
766private:
767TiXmlNode( const TiXmlNode& );// not implemented.
768void operator=( const TiXmlNode& base );// not allowed.
769};
770
771
772/** An attribute is a name-value pair. Elements have an arbitrary
773number of attributes, each with a unique name.
774
775@note The attributes are not TiXmlNodes, since they are not
776 part of the tinyXML document object model. There are other
777 suggested ways to look at this problem.
778*/
779class TiXmlAttribute : public TiXmlBase
780{
781friend class TiXmlAttributeSet;
782
783public:
784/// Construct an empty attribute.
785TiXmlAttribute() : TiXmlBase()
786{
787document = 0;
788prev = next = 0;
789}
790
791#ifdef TIXML_USE_STL
792/// std::string constructor.
793TiXmlAttribute( const std::string& _name, const std::string& _value )
794{
795name = _name;
796value = _value;
797document = 0;
798prev = next = 0;
799}
800#endif
801
802/// Construct an attribute with a name and value.
803TiXmlAttribute( const char * _name, const char * _value )
804{
805name = _name;
806value = _value;
807document = 0;
808prev = next = 0;
809}
810
811const char*Name() const{ return name.c_str(); }///< Return the name of this attribute.
812const char*Value() const{ return value.c_str(); }///< Return the value of this attribute.
813#ifdef TIXML_USE_STL
814const std::string& ValueStr() const{ return value; }///< Return the value of this attribute.
815#endif
816intIntValue() const;///< Return the value of this attribute, converted to an integer.
817doubleDoubleValue() const;///< Return the value of this attribute, converted to a double.
818
819// Get the tinyxml string representation
820const TIXML_STRING& NameTStr() const { return name; }
821
822/** QueryIntValue examines the value string. It is an alternative to the
823IntValue() method with richer error checking.
824If the value is an integer, it is stored in 'value' and
825the call returns TIXML_SUCCESS. If it is not
826an integer, it returns TIXML_WRONG_TYPE.
827
828A specialized but useful call. Note that for success it returns 0,
829which is the opposite of almost all other TinyXml calls.
830*/
831int QueryIntValue( int* _value ) const;
832/// QueryDoubleValue examines the value string. See QueryIntValue().
833int QueryDoubleValue( double* _value ) const;
834
835void SetName( const char* _name ){ name = _name; }///< Set the name of this attribute.
836void SetValue( const char* _value ){ value = _value; }///< Set the value.
837
838void SetIntValue( int _value );///< Set the value from an integer.
839void SetDoubleValue( double _value );///< Set the value from a double.
840
841 #ifdef TIXML_USE_STL
842/// STL std::string form.
843void SetName( const std::string& _name ){ name = _name; }
844/// STL std::string form.
845void SetValue( const std::string& _value ){ value = _value; }
846#endif
847
848/// Get the next sibling attribute in the DOM. Returns null at end.
849const TiXmlAttribute* Next() const;
850TiXmlAttribute* Next() {
851return const_cast< TiXmlAttribute* >( (const_cast< const TiXmlAttribute* >(this))->Next() );
852}
853
854/// Get the previous sibling attribute in the DOM. Returns null at beginning.
855const TiXmlAttribute* Previous() const;
856TiXmlAttribute* Previous() {
857return const_cast< TiXmlAttribute* >( (const_cast< const TiXmlAttribute* >(this))->Previous() );
858}
859
860bool operator==( const TiXmlAttribute& rhs ) const { return rhs.name == name; }
861bool operator<( const TiXmlAttribute& rhs ) const { return name < rhs.name; }
862bool operator>( const TiXmlAttribute& rhs ) const { return name > rhs.name; }
863
864/*Attribute parsing starts: first letter of the name
865 returns: the next char after the value end quote
866*/
867virtual const char* Parse( const char* p, TiXmlParsingData* data, TiXmlEncoding encoding );
868
869// Prints this Attribute to a FILE stream.
870virtual void Print( FILE* cfile, int depth ) const {
871Print( cfile, depth, 0 );
872}
873void Print( FILE* cfile, int depth, TIXML_STRING* str ) const;
874
875// [internal use]
876// Set the document pointer so the attribute can report errors.
877void SetDocument( TiXmlDocument* doc ){ document = doc; }
878
879private:
880TiXmlAttribute( const TiXmlAttribute& );// not implemented.
881void operator=( const TiXmlAttribute& base );// not allowed.
882
883TiXmlDocument*document;// A pointer back to a document, for error reporting.
884TIXML_STRING name;
885TIXML_STRING value;
886TiXmlAttribute*prev;
887TiXmlAttribute*next;
888};
889
890
891/*A class used to manage a group of attributes.
892It is only used internally, both by the ELEMENT and the DECLARATION.
893
894The set can be changed transparent to the Element and Declaration
895classes that use it, but NOT transparent to the Attribute
896which has to implement a next() and previous() method. Which makes
897it a bit problematic and prevents the use of STL.
898
899This version is implemented with circular lists because:
900- I like circular lists
901- it demonstrates some independence from the (typical) doubly linked list.
902*/
903class TiXmlAttributeSet
904{
905public:
906TiXmlAttributeSet();
907~TiXmlAttributeSet();
908
909void Add( TiXmlAttribute* attribute );
910void Remove( TiXmlAttribute* attribute );
911
912const TiXmlAttribute* First()const{ return ( sentinel.next == &sentinel ) ? 0 : sentinel.next; }
913TiXmlAttribute* First(){ return ( sentinel.next == &sentinel ) ? 0 : sentinel.next; }
914const TiXmlAttribute* Last() const{ return ( sentinel.prev == &sentinel ) ? 0 : sentinel.prev; }
915TiXmlAttribute* Last(){ return ( sentinel.prev == &sentinel ) ? 0 : sentinel.prev; }
916
917TiXmlAttribute*Find( const char* _name ) const;
918TiXmlAttribute* FindOrCreate( const char* _name );
919
920#ifdef TIXML_USE_STL
921TiXmlAttribute*Find( const std::string& _name ) const;
922TiXmlAttribute* FindOrCreate( const std::string& _name );
923#endif
924
925
926private:
927//*ME:Because of hidden/disabled copy-construktor in TiXmlAttribute (sentinel-element),
928//*ME:this class must be also use a hidden/disabled copy-constructor !!!
929TiXmlAttributeSet( const TiXmlAttributeSet& );// not allowed
930void operator=( const TiXmlAttributeSet& );// not allowed (as TiXmlAttribute)
931
932TiXmlAttribute sentinel;
933};
934
935
936/** The element is a container class. It has a value, the element name,
937and can contain other elements, text, comments, and unknowns.
938Elements also contain an arbitrary number of attributes.
939*/
940class TiXmlElement : public TiXmlNode
941{
942public:
943/// Construct an element.
944TiXmlElement (const char * in_value);
945
946#ifdef TIXML_USE_STL
947/// std::string constructor.
948TiXmlElement( const std::string& _value );
949#endif
950
951TiXmlElement( const TiXmlElement& );
952
953TiXmlElement& operator=( const TiXmlElement& base );
954
955virtual ~TiXmlElement();
956
957/** Given an attribute name, Attribute() returns the value
958for the attribute of that name, or null if none exists.
959*/
960const char* Attribute( const char* name ) const;
961
962/** Given an attribute name, Attribute() returns the value
963for the attribute of that name, or null if none exists.
964If the attribute exists and can be converted to an integer,
965the integer value will be put in the return 'i', if 'i'
966is non-null.
967*/
968const char* Attribute( const char* name, int* i ) const;
969
970/** Given an attribute name, Attribute() returns the value
971for the attribute of that name, or null if none exists.
972If the attribute exists and can be converted to an double,
973the double value will be put in the return 'd', if 'd'
974is non-null.
975*/
976const char* Attribute( const char* name, double* d ) const;
977
978/** QueryIntAttribute examines the attribute - it is an alternative to the
979Attribute() method with richer error checking.
980If the attribute is an integer, it is stored in 'value' and
981the call returns TIXML_SUCCESS. If it is not
982an integer, it returns TIXML_WRONG_TYPE. If the attribute
983does not exist, then TIXML_NO_ATTRIBUTE is returned.
984*/
985int QueryIntAttribute( const char* name, int* _value ) const;
986/// QueryUnsignedAttribute examines the attribute - see QueryIntAttribute().
987int QueryUnsignedAttribute( const char* name, unsigned* _value ) const;
988/** QueryBoolAttribute examines the attribute - see QueryIntAttribute().
989Note that '1', 'true', or 'yes' are considered true, while '0', 'false'
990and 'no' are considered false.
991*/
992int QueryBoolAttribute( const char* name, bool* _value ) const;
993/// QueryDoubleAttribute examines the attribute - see QueryIntAttribute().
994int QueryDoubleAttribute( const char* name, double* _value ) const;
995/// QueryFloatAttribute examines the attribute - see QueryIntAttribute().
996int QueryFloatAttribute( const char* name, float* _value ) const {
997double d;
998int result = QueryDoubleAttribute( name, &d );
999if ( result == TIXML_SUCCESS ) {
1000*_value = (float)d;
1001}
1002return result;
1003}
1004
1005 #ifdef TIXML_USE_STL
1006/// QueryStringAttribute examines the attribute - see QueryIntAttribute().
1007int QueryStringAttribute( const char* name, std::string* _value ) const {
1008const char* cstr = Attribute( name );
1009if ( cstr ) {
1010*_value = std::string( cstr );
1011return TIXML_SUCCESS;
1012}
1013return TIXML_NO_ATTRIBUTE;
1014}
1015
1016/** Template form of the attribute query which will try to read the
1017attribute into the specified type. Very easy, very powerful, but
1018be careful to make sure to call this with the correct type.
1019
1020NOTE: This method doesn't work correctly for 'string' types that contain spaces.
1021
1022@return TIXML_SUCCESS, TIXML_WRONG_TYPE, or TIXML_NO_ATTRIBUTE
1023*/
1024template< typename T > int QueryValueAttribute( const std::string& name, T* outValue ) const
1025{
1026const TiXmlAttribute* node = attributeSet.Find( name );
1027if ( !node )
1028return TIXML_NO_ATTRIBUTE;
1029
1030std::stringstream sstream( node->ValueStr() );
1031sstream >> *outValue;
1032if ( !sstream.fail() )
1033return TIXML_SUCCESS;
1034return TIXML_WRONG_TYPE;
1035}
1036
1037int QueryValueAttribute( const std::string& name, std::string* outValue ) const
1038{
1039const TiXmlAttribute* node = attributeSet.Find( name );
1040if ( !node )
1041return TIXML_NO_ATTRIBUTE;
1042*outValue = node->ValueStr();
1043return TIXML_SUCCESS;
1044}
1045#endif
1046
1047/** Sets an attribute of name to a given value. The attribute
1048will be created if it does not exist, or changed if it does.
1049*/
1050void SetAttribute( const char* name, const char * _value );
1051
1052 #ifdef TIXML_USE_STL
1053const std::string* Attribute( const std::string& name ) const;
1054const std::string* Attribute( const std::string& name, int* i ) const;
1055const std::string* Attribute( const std::string& name, double* d ) const;
1056int QueryIntAttribute( const std::string& name, int* _value ) const;
1057int QueryDoubleAttribute( const std::string& name, double* _value ) const;
1058
1059/// STL std::string form.
1060void SetAttribute( const std::string& name, const std::string& _value );
1061///< STL std::string form.
1062void SetAttribute( const std::string& name, int _value );
1063///< STL std::string form.
1064void SetDoubleAttribute( const std::string& name, double value );
1065#endif
1066
1067/** Sets an attribute of name to a given value. The attribute
1068will be created if it does not exist, or changed if it does.
1069*/
1070void SetAttribute( const char * name, int value );
1071
1072/** Sets an attribute of name to a given value. The attribute
1073will be created if it does not exist, or changed if it does.
1074*/
1075void SetDoubleAttribute( const char * name, double value );
1076
1077/** Deletes an attribute with the given name.
1078*/
1079void RemoveAttribute( const char * name );
1080 #ifdef TIXML_USE_STL
1081void RemoveAttribute( const std::string& name ){RemoveAttribute (name.c_str ());}///< STL std::string form.
1082#endif
1083
1084const TiXmlAttribute* FirstAttribute() const{ return attributeSet.First(); }///< Access the first attribute in this element.
1085TiXmlAttribute* FirstAttribute() { return attributeSet.First(); }
1086const TiXmlAttribute* LastAttribute()const { return attributeSet.Last(); }///< Access the last attribute in this element.
1087TiXmlAttribute* LastAttribute(){ return attributeSet.Last(); }
1088
1089/** Convenience function for easy access to the text inside an element. Although easy
1090and concise, GetText() is limited compared to getting the TiXmlText child
1091and accessing it directly.
1092
1093If the first child of 'this' is a TiXmlText, the GetText()
1094returns the character string of the Text node, else null is returned.
1095
1096This is a convenient method for getting the text of simple contained text:
1097@verbatim
1098<foo>This is text</foo>
1099const char* str = fooElement->GetText();
1100@endverbatim
1101
1102'str' will be a pointer to "This is text".
1103
1104Note that this function can be misleading. If the element foo was created from
1105this XML:
1106@verbatim
1107<foo><b>This is text</b></foo>
1108@endverbatim
1109
1110then the value of str would be null. The first child node isn't a text node, it is
1111another element. From this XML:
1112@verbatim
1113<foo>This is <b>text</b></foo>
1114@endverbatim
1115GetText() will return "This is ".
1116
1117WARNING: GetText() accesses a child node - don't become confused with the
1118 similarly named TiXmlHandle::Text() and TiXmlNode::ToText() which are
1119 safe type casts on the referenced node.
1120*/
1121const char* GetText() const;
1122
1123/// Creates a new Element and returns it - the returned element is a copy.
1124virtual TiXmlNode* Clone() const;
1125// Print the Element to a FILE stream.
1126virtual void Print( FILE* cfile, int depth ) const;
1127
1128/*Attribtue parsing starts: next char past '<'
1129 returns: next char past '>'
1130*/
1131virtual const char* Parse( const char* p, TiXmlParsingData* data, TiXmlEncoding encoding );
1132
1133virtual const TiXmlElement* ToElement() const { return this; } ///< Cast to a more defined type. Will return null not of the requested type.
1134virtual TiXmlElement* ToElement() { return this; } ///< Cast to a more defined type. Will return null not of the requested type.
1135
1136/** Walk the XML tree visiting this node and all of its children.
1137*/
1138virtual bool Accept( TiXmlVisitor* visitor ) const;
1139
1140protected:
1141
1142void CopyTo( TiXmlElement* target ) const;
1143void ClearThis();// like clear, but initializes 'this' object as well
1144
1145// Used to be public [internal use]
1146#ifdef TIXML_USE_STL
1147virtual void StreamIn( std::istream * in, TIXML_STRING * tag );
1148#endif
1149/*[internal use]
1150Reads the "value" of the element -- another element, or text.
1151This should terminate with the current end tag.
1152*/
1153const char* ReadValue( const char* in, TiXmlParsingData* prevData, TiXmlEncoding encoding );
1154
1155private:
1156TiXmlAttributeSet attributeSet;
1157};
1158
1159
1160/**An XML comment.
1161*/
1162class TiXmlComment : public TiXmlNode
1163{
1164public:
1165/// Constructs an empty comment.
1166TiXmlComment() : TiXmlNode( TiXmlNode::TINYXML_COMMENT ) {}
1167/// Construct a comment from text.
1168TiXmlComment( const char* _value ) : TiXmlNode( TiXmlNode::TINYXML_COMMENT ) {
1169SetValue( _value );
1170}
1171TiXmlComment( const TiXmlComment& );
1172TiXmlComment& operator=( const TiXmlComment& base );
1173
1174virtual ~TiXmlComment(){}
1175
1176/// Returns a copy of this Comment.
1177virtual TiXmlNode* Clone() const;
1178// Write this Comment to a FILE stream.
1179virtual void Print( FILE* cfile, int depth ) const;
1180
1181/*Attribtue parsing starts: at the ! of the !--
1182 returns: next char past '>'
1183*/
1184virtual const char* Parse( const char* p, TiXmlParsingData* data, TiXmlEncoding encoding );
1185
1186virtual const TiXmlComment* ToComment() const{ return this; } ///< Cast to a more defined type. Will return null not of the requested type.
1187virtual TiXmlComment* ToComment(){ return this; } ///< Cast to a more defined type. Will return null not of the requested type.
1188
1189/** Walk the XML tree visiting this node and all of its children.
1190*/
1191virtual bool Accept( TiXmlVisitor* visitor ) const;
1192
1193protected:
1194void CopyTo( TiXmlComment* target ) const;
1195
1196// used to be public
1197#ifdef TIXML_USE_STL
1198virtual void StreamIn( std::istream * in, TIXML_STRING * tag );
1199#endif
1200//virtual void StreamOut( TIXML_OSTREAM * out ) const;
1201
1202private:
1203
1204};
1205
1206
1207/** XML text. A text node can have 2 ways to output the next. "normal" output
1208and CDATA. It will default to the mode it was parsed from the XML file and
1209you generally want to leave it alone, but you can change the output mode with
1210SetCDATA() and query it with CDATA().
1211*/
1212class TiXmlText : public TiXmlNode
1213{
1214friend class TiXmlElement;
1215public:
1216/** Constructor for text element. By default, it is treated as
1217normal, encoded text. If you want it be output as a CDATA text
1218element, set the parameter _cdata to 'true'
1219*/
1220TiXmlText (const char * initValue ) : TiXmlNode (TiXmlNode::TINYXML_TEXT)
1221{
1222SetValue( initValue );
1223cdata = false;
1224}
1225virtual ~TiXmlText() {}
1226
1227#ifdef TIXML_USE_STL
1228/// Constructor.
1229TiXmlText( const std::string& initValue ) : TiXmlNode (TiXmlNode::TINYXML_TEXT)
1230{
1231SetValue( initValue );
1232cdata = false;
1233}
1234#endif
1235
1236TiXmlText( const TiXmlText& copy ) : TiXmlNode( TiXmlNode::TINYXML_TEXT ){ copy.CopyTo( this ); }
1237TiXmlText& operator=( const TiXmlText& base ) { base.CopyTo( this ); return *this; }
1238
1239// Write this text object to a FILE stream.
1240virtual void Print( FILE* cfile, int depth ) const;
1241
1242/// Queries whether this represents text using a CDATA section.
1243bool CDATA() const{ return cdata; }
1244/// Turns on or off a CDATA representation of text.
1245void SetCDATA( bool _cdata ){ cdata = _cdata; }
1246
1247virtual const char* Parse( const char* p, TiXmlParsingData* data, TiXmlEncoding encoding );
1248
1249virtual const TiXmlText* ToText() const { return this; } ///< Cast to a more defined type. Will return null not of the requested type.
1250virtual TiXmlText* ToText() { return this; } ///< Cast to a more defined type. Will return null not of the requested type.
1251
1252/** Walk the XML tree visiting this node and all of its children.
1253*/
1254virtual bool Accept( TiXmlVisitor* content ) const;
1255
1256protected :
1257/// [internal use] Creates a new Element and returns it.
1258virtual TiXmlNode* Clone() const;
1259void CopyTo( TiXmlText* target ) const;
1260
1261bool Blank() const;// returns true if all white space and new lines
1262// [internal use]
1263#ifdef TIXML_USE_STL
1264virtual void StreamIn( std::istream * in, TIXML_STRING * tag );
1265#endif
1266
1267private:
1268bool cdata;// true if this should be input and output as a CDATA style text element
1269};
1270
1271
1272/** In correct XML the declaration is the first entry in the file.
1273@verbatim
1274<?xml version="1.0" standalone="yes"?>
1275@endverbatim
1276
1277TinyXml will happily read or write files without a declaration,
1278however. There are 3 possible attributes to the declaration:
1279version, encoding, and standalone.
1280
1281Note: In this version of the code, the attributes are
1282handled as special cases, not generic attributes, simply
1283because there can only be at most 3 and they are always the same.
1284*/
1285class TiXmlDeclaration : public TiXmlNode
1286{
1287public:
1288/// Construct an empty declaration.
1289TiXmlDeclaration() : TiXmlNode( TiXmlNode::TINYXML_DECLARATION ) {}
1290
1291#ifdef TIXML_USE_STL
1292/// Constructor.
1293TiXmlDeclaration(const std::string& _version,
1294const std::string& _encoding,
1295const std::string& _standalone );
1296#endif
1297
1298/// Construct.
1299TiXmlDeclaration(const char* _version,
1300const char* _encoding,
1301const char* _standalone );
1302
1303TiXmlDeclaration( const TiXmlDeclaration& copy );
1304TiXmlDeclaration& operator=( const TiXmlDeclaration& copy );
1305
1306virtual ~TiXmlDeclaration(){}
1307
1308/// Version. Will return an empty string if none was found.
1309const char *Version() const{ return version.c_str (); }
1310/// Encoding. Will return an empty string if none was found.
1311const char *Encoding() const{ return encoding.c_str (); }
1312/// Is this a standalone document?
1313const char *Standalone() const{ return standalone.c_str (); }
1314
1315/// Creates a copy of this Declaration and returns it.
1316virtual TiXmlNode* Clone() const;
1317// Print this declaration to a FILE stream.
1318virtual void Print( FILE* cfile, int depth, TIXML_STRING* str ) const;
1319virtual void Print( FILE* cfile, int depth ) const {
1320Print( cfile, depth, 0 );
1321}
1322
1323virtual const char* Parse( const char* p, TiXmlParsingData* data, TiXmlEncoding encoding );
1324
1325virtual const TiXmlDeclaration* ToDeclaration() const { return this; } ///< Cast to a more defined type. Will return null not of the requested type.
1326virtual TiXmlDeclaration* ToDeclaration() { return this; } ///< Cast to a more defined type. Will return null not of the requested type.
1327
1328/** Walk the XML tree visiting this node and all of its children.
1329*/
1330virtual bool Accept( TiXmlVisitor* visitor ) const;
1331
1332protected:
1333void CopyTo( TiXmlDeclaration* target ) const;
1334// used to be public
1335#ifdef TIXML_USE_STL
1336virtual void StreamIn( std::istream * in, TIXML_STRING * tag );
1337#endif
1338
1339private:
1340
1341TIXML_STRING version;
1342TIXML_STRING encoding;
1343TIXML_STRING standalone;
1344};
1345
1346
1347/** Any tag that tinyXml doesn't recognize is saved as an
1348unknown. It is a tag of text, but should not be modified.
1349It will be written back to the XML, unchanged, when the file
1350is saved.
1351
1352DTD tags get thrown into TiXmlUnknowns.
1353*/
1354class TiXmlUnknown : public TiXmlNode
1355{
1356public:
1357TiXmlUnknown() : TiXmlNode( TiXmlNode::TINYXML_UNKNOWN ){}
1358virtual ~TiXmlUnknown() {}
1359
1360TiXmlUnknown( const TiXmlUnknown& copy ) : TiXmlNode( TiXmlNode::TINYXML_UNKNOWN ){ copy.CopyTo( this ); }
1361TiXmlUnknown& operator=( const TiXmlUnknown& copy ){ copy.CopyTo( this ); return *this; }
1362
1363/// Creates a copy of this Unknown and returns it.
1364virtual TiXmlNode* Clone() const;
1365// Print this Unknown to a FILE stream.
1366virtual void Print( FILE* cfile, int depth ) const;
1367
1368virtual const char* Parse( const char* p, TiXmlParsingData* data, TiXmlEncoding encoding );
1369
1370virtual const TiXmlUnknown* ToUnknown() const{ return this; } ///< Cast to a more defined type. Will return null not of the requested type.
1371virtual TiXmlUnknown* ToUnknown(){ return this; } ///< Cast to a more defined type. Will return null not of the requested type.
1372
1373/** Walk the XML tree visiting this node and all of its children.
1374*/
1375virtual bool Accept( TiXmlVisitor* content ) const;
1376
1377protected:
1378void CopyTo( TiXmlUnknown* target ) const;
1379
1380#ifdef TIXML_USE_STL
1381virtual void StreamIn( std::istream * in, TIXML_STRING * tag );
1382#endif
1383
1384private:
1385
1386};
1387
1388
1389/** Always the top level node. A document binds together all the
1390XML pieces. It can be saved, loaded, and printed to the screen.
1391The 'value' of a document node is the xml file name.
1392*/
1393class TiXmlDocument : public TiXmlNode
1394{
1395public:
1396/// Create an empty document, that has no name.
1397TiXmlDocument();
1398/// Create a document with a name. The name of the document is also the filename of the xml.
1399TiXmlDocument( const char * documentName );
1400
1401#ifdef TIXML_USE_STL
1402/// Constructor.
1403TiXmlDocument( const std::string& documentName );
1404#endif
1405
1406TiXmlDocument( const TiXmlDocument& copy );
1407TiXmlDocument& operator=( const TiXmlDocument& copy );
1408
1409virtual ~TiXmlDocument() {}
1410
1411/** Load a file using the current document value.
1412Returns true if successful. Will delete any existing
1413document data before loading.
1414*/
1415bool LoadFile( TiXmlEncoding encoding = TIXML_DEFAULT_ENCODING );
1416/// Save a file using the current document value. Returns true if successful.
1417bool SaveFile() const;
1418/// Load a file using the given filename. Returns true if successful.
1419bool LoadFile( const char * filename, TiXmlEncoding encoding = TIXML_DEFAULT_ENCODING );
1420/// Save a file using the given filename. Returns true if successful.
1421bool SaveFile( const char * filename ) const;
1422/** Load a file using the given FILE*. Returns true if successful. Note that this method
1423doesn't stream - the entire object pointed at by the FILE*
1424will be interpreted as an XML file. TinyXML doesn't stream in XML from the current
1425file location. Streaming may be added in the future.
1426*/
1427bool LoadFile( FILE*, TiXmlEncoding encoding = TIXML_DEFAULT_ENCODING );
1428/// Save a file using the given FILE*. Returns true if successful.
1429bool SaveFile( FILE* ) const;
1430
1431#ifdef TIXML_USE_STL
1432bool LoadFile( const std::string& filename, TiXmlEncoding encoding = TIXML_DEFAULT_ENCODING )///< STL std::string version.
1433{
1434return LoadFile( filename.c_str(), encoding );
1435}
1436bool SaveFile( const std::string& filename ) const///< STL std::string version.
1437{
1438return SaveFile( filename.c_str() );
1439}
1440#endif
1441
1442/** Parse the given null terminated block of xml data. Passing in an encoding to this
1443method (either TIXML_ENCODING_LEGACY or TIXML_ENCODING_UTF8 will force TinyXml
1444to use that encoding, regardless of what TinyXml might otherwise try to detect.
1445*/
1446virtual const char* Parse( const char* p, TiXmlParsingData* data = 0, TiXmlEncoding encoding = TIXML_DEFAULT_ENCODING );
1447
1448/** Get the root element -- the only top level element -- of the document.
1449In well formed XML, there should only be one. TinyXml is tolerant of
1450multiple elements at the document level.
1451*/
1452const TiXmlElement* RootElement() const{ return FirstChildElement(); }
1453TiXmlElement* RootElement(){ return FirstChildElement(); }
1454
1455/** If an error occurs, Error will be set to true. Also,
1456- The ErrorId() will contain the integer identifier of the error (not generally useful)
1457- The ErrorDesc() method will return the name of the error. (very useful)
1458- The ErrorRow() and ErrorCol() will return the location of the error (if known)
1459*/
1460bool Error() const{ return error; }
1461
1462/// Contains a textual (english) description of the error if one occurs.
1463const char * ErrorDesc() const{ return errorDesc.c_str (); }
1464
1465/** Generally, you probably want the error string ( ErrorDesc() ). But if you
1466prefer the ErrorId, this function will fetch it.
1467*/
1468int ErrorId()const{ return errorId; }
1469
1470/** Returns the location (if known) of the error. The first column is column 1,
1471and the first row is row 1. A value of 0 means the row and column wasn't applicable
1472(memory errors, for example, have no row/column) or the parser lost the error. (An
1473error in the error reporting, in that case.)
1474
1475@sa SetTabSize, Row, Column
1476*/
1477int ErrorRow() const{ return errorLocation.row+1; }
1478int ErrorCol() const{ return errorLocation.col+1; }///< The column where the error occured. See ErrorRow()
1479
1480/** SetTabSize() allows the error reporting functions (ErrorRow() and ErrorCol())
1481to report the correct values for row and column. It does not change the output
1482or input in any way.
1483
1484By calling this method, with a tab size
1485greater than 0, the row and column of each node and attribute is stored
1486when the file is loaded. Very useful for tracking the DOM back in to
1487the source file.
1488
1489The tab size is required for calculating the location of nodes. If not
1490set, the default of 4 is used. The tabsize is set per document. Setting
1491the tabsize to 0 disables row/column tracking.
1492
1493Note that row and column tracking is not supported when using operator>>.
1494
1495The tab size needs to be enabled before the parse or load. Correct usage:
1496@verbatim
1497TiXmlDocument doc;
1498doc.SetTabSize( 8 );
1499doc.Load( "myfile.xml" );
1500@endverbatim
1501
1502@sa Row, Column
1503*/
1504void SetTabSize( int _tabsize ){ tabsize = _tabsize; }
1505
1506int TabSize() const{ return tabsize; }
1507
1508/** If you have handled the error, it can be reset with this call. The error
1509state is automatically cleared if you Parse a new XML block.
1510*/
1511void ClearError(){error = false;
1512errorId = 0;
1513errorDesc = "";
1514errorLocation.row = errorLocation.col = 0;
1515//errorLocation.last = 0;
1516}
1517
1518/** Write the document to standard out using formatted printing ("pretty print"). */
1519void Print() const{ Print( stdout, 0 ); }
1520
1521/* Write the document to a string using formatted printing ("pretty print"). This
1522will allocate a character array (new char[]) and return it as a pointer. The
1523calling code pust call delete[] on the return char* to avoid a memory leak.
1524*/
1525//char* PrintToMemory() const;
1526
1527/// Print this Document to a FILE stream.
1528virtual void Print( FILE* cfile, int depth = 0 ) const;
1529// [internal use]
1530void SetError( int err, const char* errorLocation, TiXmlParsingData* prevData, TiXmlEncoding encoding );
1531
1532virtual const TiXmlDocument* ToDocument() const { return this; } ///< Cast to a more defined type. Will return null not of the requested type.
1533virtual TiXmlDocument* ToDocument() { return this; } ///< Cast to a more defined type. Will return null not of the requested type.
1534
1535/** Walk the XML tree visiting this node and all of its children.
1536*/
1537virtual bool Accept( TiXmlVisitor* content ) const;
1538
1539protected :
1540// [internal use]
1541virtual TiXmlNode* Clone() const;
1542#ifdef TIXML_USE_STL
1543virtual void StreamIn( std::istream * in, TIXML_STRING * tag );
1544#endif
1545
1546private:
1547void CopyTo( TiXmlDocument* target ) const;
1548
1549bool error;
1550int errorId;
1551TIXML_STRING errorDesc;
1552int tabsize;
1553TiXmlCursor errorLocation;
1554bool useMicrosoftBOM;// the UTF-8 BOM were found when read. Note this, and try to write.
1555};
1556
1557
1558/**
1559A TiXmlHandle is a class that wraps a node pointer with null checks; this is
1560an incredibly useful thing. Note that TiXmlHandle is not part of the TinyXml
1561DOM structure. It is a separate utility class.
1562
1563Take an example:
1564@verbatim
1565<Document>
1566<Element attributeA = "valueA">
1567<Child attributeB = "value1" />
1568<Child attributeB = "value2" />
1569</Element>
1570<Document>
1571@endverbatim
1572
1573Assuming you want the value of "attributeB" in the 2nd "Child" element, it's very
1574easy to write a *lot* of code that looks like:
1575
1576@verbatim
1577TiXmlElement* root = document.FirstChildElement( "Document" );
1578if ( root )
1579{
1580TiXmlElement* element = root->FirstChildElement( "Element" );
1581if ( element )
1582{
1583TiXmlElement* child = element->FirstChildElement( "Child" );
1584if ( child )
1585{
1586TiXmlElement* child2 = child->NextSiblingElement( "Child" );
1587if ( child2 )
1588{
1589// Finally do something useful.
1590@endverbatim
1591
1592And that doesn't even cover "else" cases. TiXmlHandle addresses the verbosity
1593of such code. A TiXmlHandle checks for nullpointers so it is perfectly safe
1594and correct to use:
1595
1596@verbatim
1597TiXmlHandle docHandle( &document );
1598TiXmlElement* child2 = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", 1 ).ToElement();
1599if ( child2 )
1600{
1601// do something useful
1602@endverbatim
1603
1604Which is MUCH more concise and useful.
1605
1606It is also safe to copy handles - internally they are nothing more than node pointers.
1607@verbatim
1608TiXmlHandle handleCopy = handle;
1609@endverbatim
1610
1611What they should not be used for is iteration:
1612
1613@verbatim
1614int i=0;
1615while ( true )
1616{
1617TiXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", i ).ToElement();
1618if ( !child )
1619break;
1620// do something
1621++i;
1622}
1623@endverbatim
1624
1625It seems reasonable, but it is in fact two embedded while loops. The Child method is
1626a linear walk to find the element, so this code would iterate much more than it needs
1627to. Instead, prefer:
1628
1629@verbatim
1630TiXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).FirstChild( "Child" ).ToElement();
1631
1632for( child; child; child=child->NextSiblingElement() )
1633{
1634// do something
1635}
1636@endverbatim
1637*/
1638class TiXmlHandle
1639{
1640public:
1641/// Create a handle from any node (at any depth of the tree.) This can be a null pointer.
1642TiXmlHandle( TiXmlNode* _node ){ this->node = _node; }
1643/// Copy constructor
1644TiXmlHandle( const TiXmlHandle& ref ){ this->node = ref.node; }
1645TiXmlHandle operator=( const TiXmlHandle& ref ) { if ( &ref != this ) this->node = ref.node; return *this; }
1646
1647/// Return a handle to the first child node.
1648TiXmlHandle FirstChild() const;
1649/// Return a handle to the first child node with the given name.
1650TiXmlHandle FirstChild( const char * value ) const;
1651/// Return a handle to the first child element.
1652TiXmlHandle FirstChildElement() const;
1653/// Return a handle to the first child element with the given name.
1654TiXmlHandle FirstChildElement( const char * value ) const;
1655
1656/** Return a handle to the "index" child with the given name.
1657The first child is 0, the second 1, etc.
1658*/
1659TiXmlHandle Child( const char* value, int index ) const;
1660/** Return a handle to the "index" child.
1661The first child is 0, the second 1, etc.
1662*/
1663TiXmlHandle Child( int index ) const;
1664/** Return a handle to the "index" child element with the given name.
1665The first child element is 0, the second 1, etc. Note that only TiXmlElements
1666are indexed: other types are not counted.
1667*/
1668TiXmlHandle ChildElement( const char* value, int index ) const;
1669/** Return a handle to the "index" child element.
1670The first child element is 0, the second 1, etc. Note that only TiXmlElements
1671are indexed: other types are not counted.
1672*/
1673TiXmlHandle ChildElement( int index ) const;
1674
1675#ifdef TIXML_USE_STL
1676TiXmlHandle FirstChild( const std::string& _value ) const{ return FirstChild( _value.c_str() ); }
1677TiXmlHandle FirstChildElement( const std::string& _value ) const{ return FirstChildElement( _value.c_str() ); }
1678
1679TiXmlHandle Child( const std::string& _value, int index ) const{ return Child( _value.c_str(), index ); }
1680TiXmlHandle ChildElement( const std::string& _value, int index ) const{ return ChildElement( _value.c_str(), index ); }
1681#endif
1682
1683/** Return the handle as a TiXmlNode. This may return null.
1684*/
1685TiXmlNode* ToNode() const{ return node; }
1686/** Return the handle as a TiXmlElement. This may return null.
1687*/
1688TiXmlElement* ToElement() const{ return ( ( node && node->ToElement() ) ? node->ToElement() : 0 ); }
1689/**Return the handle as a TiXmlText. This may return null.
1690*/
1691TiXmlText* ToText() const{ return ( ( node && node->ToText() ) ? node->ToText() : 0 ); }
1692/** Return the handle as a TiXmlUnknown. This may return null.
1693*/
1694TiXmlUnknown* ToUnknown() const{ return ( ( node && node->ToUnknown() ) ? node->ToUnknown() : 0 ); }
1695
1696/** @deprecated use ToNode.
1697Return the handle as a TiXmlNode. This may return null.
1698*/
1699TiXmlNode* Node() const{ return ToNode(); }
1700/** @deprecated use ToElement.
1701Return the handle as a TiXmlElement. This may return null.
1702*/
1703TiXmlElement* Element() const{ return ToElement(); }
1704/**@deprecated use ToText()
1705Return the handle as a TiXmlText. This may return null.
1706*/
1707TiXmlText* Text() const{ return ToText(); }
1708/** @deprecated use ToUnknown()
1709Return the handle as a TiXmlUnknown. This may return null.
1710*/
1711TiXmlUnknown* Unknown() const{ return ToUnknown(); }
1712
1713private:
1714TiXmlNode* node;
1715};
1716
1717
1718/** Print to memory functionality. The TiXmlPrinter is useful when you need to:
1719
1720-# Print to memory (especially in non-STL mode)
1721-# Control formatting (line endings, etc.)
1722
1723When constructed, the TiXmlPrinter is in its default "pretty printing" mode.
1724Before calling Accept() you can call methods to control the printing
1725of the XML document. After TiXmlNode::Accept() is called, the printed document can
1726be accessed via the CStr(), Str(), and Size() methods.
1727
1728TiXmlPrinter uses the Visitor API.
1729@verbatim
1730TiXmlPrinter printer;
1731printer.SetIndent( "\t" );
1732
1733doc.Accept( &printer );
1734fprintf( stdout, "%s", printer.CStr() );
1735@endverbatim
1736*/
1737class TiXmlPrinter : public TiXmlVisitor
1738{
1739public:
1740TiXmlPrinter() : depth( 0 ), simpleTextPrint( false ),
1741 buffer(), indent( " " ), lineBreak( "\n" ) {}
1742
1743virtual bool VisitEnter( const TiXmlDocument& doc );
1744virtual bool VisitExit( const TiXmlDocument& doc );
1745
1746virtual bool VisitEnter( const TiXmlElement& element, const TiXmlAttribute* firstAttribute );
1747virtual bool VisitExit( const TiXmlElement& element );
1748
1749virtual bool Visit( const TiXmlDeclaration& declaration );
1750virtual bool Visit( const TiXmlText& text );
1751virtual bool Visit( const TiXmlComment& comment );
1752virtual bool Visit( const TiXmlUnknown& unknown );
1753
1754/** Set the indent characters for printing. By default 4 spaces
1755but tab (\t) is also useful, or null/empty string for no indentation.
1756*/
1757void SetIndent( const char* _indent ){ indent = _indent ? _indent : "" ; }
1758/// Query the indention string.
1759const char* Indent(){ return indent.c_str(); }
1760/** Set the line breaking string. By default set to newline (\n).
1761Some operating systems prefer other characters, or can be
1762set to the null/empty string for no indenation.
1763*/
1764void SetLineBreak( const char* _lineBreak ){ lineBreak = _lineBreak ? _lineBreak : ""; }
1765/// Query the current line breaking string.
1766const char* LineBreak(){ return lineBreak.c_str(); }
1767
1768/** Switch over to "stream printing" which is the most dense formatting without
1769linebreaks. Common when the XML is needed for network transmission.
1770*/
1771void SetStreamPrinting(){ indent = "";
1772 lineBreak = "";
1773}
1774/// Return the result.
1775const char* CStr(){ return buffer.c_str(); }
1776/// Return the length of the result string.
1777size_t Size(){ return buffer.size(); }
1778
1779#ifdef TIXML_USE_STL
1780/// Return the result.
1781const std::string& Str(){ return buffer; }
1782#endif
1783
1784private:
1785void DoIndent(){
1786for( int i=0; i<depth; ++i )
1787buffer += indent;
1788}
1789void DoLineBreak() {
1790buffer += lineBreak;
1791}
1792
1793int depth;
1794bool simpleTextPrint;
1795TIXML_STRING buffer;
1796TIXML_STRING indent;
1797TIXML_STRING lineBreak;
1798};
1799
1800
1801#ifdef _MSC_VER
1802#pragma warning( pop )
1803#endif
1804
1805#endif
1806

Archive Download this file

Revision: 1307