index.html revision bc0ee9afa1072f1943b18f74560cb71840470597
15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"> 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<title>TinyXml: Main Page</title> 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<link href="doxygen.css" rel="stylesheet" type="text/css"> 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)</head><body> 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<!-- Generated by Doxygen 1.4.4 --> 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<div class="qindex"><a class="qindexHL" href="index.html">Main Page</a> | <a class="qindex" href="hierarchy.html">Class Hierarchy</a> | <a class="qindex" href="annotated.html">Class List</a> | <a class="qindex" href="files.html">File List</a> | <a class="qindex" href="functions.html">Class Members</a></div> 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<h1>TinyXml Documentation</h1> 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<p> 10d0247b1b59f9c528cb6df88b4f2b9afaf80d181eTorne (Richard Coles)<h3 align="center">2.4.0 </h3><h1>TinyXml </h1> 11d0247b1b59f9c528cb6df88b4f2b9afaf80d181eTorne (Richard Coles)<p> 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)TinyXml is a simple, small, C++ XML parser that can be easily integrating into other programs.<p> 13d0247b1b59f9c528cb6df88b4f2b9afaf80d181eTorne (Richard Coles)<h2>What it does. </h2> 14c5cede9ae108bb15f6b7a8aea21c7e1fefa2834cBen Murdoch<p> 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)In brief, TinyXml parses an XML document, and builds from that a Document Object Model (DOM) that can be read, modified, and saved.<p> 164e180b6a0b4720a9b8e9e959a882386f690f08ffTorne (Richard Coles)XML stands for "eXtensible Markup Language." It allows you to create your own document markups. Where HTML does a very good job of marking documents for browsers, XML allows you to define any kind of document markup, for example a document that describes a "to do" list for an organizer application. XML is a very structured and convenient format. All those random file formats created to store application data can all be replaced with XML. One parser for everything.<p> 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)The best place for the complete, correct, and quite frankly hard to read spec is at <a href="http://www.w3.org/TR/2004/REC-xml-20040204/">http://www.w3.org/TR/2004/REC-xml-20040204/</a>. An intro to XML (that I really like) can be found at <a href="http://skew.org/xml/tutorial/">http://skew.org/xml/tutorial</a>.<p> 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)There are different ways to access and interact with XML data. TinyXml uses a Document Object Model (DOM), meaning the XML data is parsed into a C++ objects that can be browsed and manipulated, and then written to disk or another output stream. You can also construct an XML document from scratch with C++ objects and write this to disk or another output stream.<p> 192a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)TinyXml is designed to be easy and fast to learn. It is two headers and four cpp files. Simply add these to your project and off you go. There is an example file - xmltest.cpp - to get you started.<p> 205d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles)TinyXml is released under the ZLib license, so you can use it in open source or commercial code. The details of the license are at the top of every source file.<p> 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)TinyXml attempts to be a flexible parser, but with truly correct and compliant XML output. TinyXml should compile on any reasonably C++ compliant system. It does not rely on exceptions or RTTI. It can be compiled with or without STL support. TinyXml fully supports the UTF-8 encoding, and the first 64k character entities.<p> 222a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)<h2>What it doesn't do. </h2> 232a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)<p> 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)It doesnt parse or use DTDs (Document Type Definitions) or XSLs (eXtensible Stylesheet Language.) There are other parsers out there (check out www.sourceforge.org, search for XML) that are much more fully featured. But they are also much bigger, take longer to set up in your project, have a higher learning curve, and often have a more restrictive license. If you are working with browsers or have more complete XML needs, TinyXml is not the parser for you.<p> 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)The following DTD syntax will not parse at this time in TinyXml:<p> 26f2477e01787aa58f445919b809d89e252beef54fTorne (Richard Coles)<div class="fragment"><pre class="fragment"> <!DOCTYPE Archiv [ 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) <!ELEMENT Comment (#PCDATA)> 288bcbed890bc3ce4d7a057a8f32cab53fa534672eTorne (Richard Coles) ]> 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)</pre></div><p> 30a1401311d1ab56c4ed0a474bd38c108f75cb0cd9Torne (Richard Coles)because TinyXml sees this as a !DOCTYPE node with an illegally embedded !ELEMENT node. This may be addressed in the future.<p> 315d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles)<h2>Tutorials. </h2> 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<p> 335d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles)For the impatient, here is a tutorial to get you going. A great way to get started, but it is worth your time to read this (very short) manual completely.<p> 344e180b6a0b4720a9b8e9e959a882386f690f08ffTorne (Richard Coles)<ul> 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<li><a class="el" href="tutorial0.html">TinyXML Tutorial</a></li></ul> 362a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)<p> 370f1bc08d4cfcc34181b0b5cbf065c40f687bf740Torne (Richard Coles)<h2>Code Status. </h2> 381e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles)<p> 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)TinyXml is mature, tested code. It is very stable. If you find bugs, please file a bug report on the sourceforge web site (www.sourceforge.net/projects/tinyxml). We'll get them straightened out as soon as possible.<p> 40c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)There are some areas of improvement; please check sourceforge if you are interested in working on TinyXml.<p> 4168043e1e95eeb07d5cae7aca370b26518b0867d6Torne (Richard Coles)<h2>Features </h2> 42a3f6a49ab37290eeeb8db0f41ec0f1cb74a68be7Torne (Richard Coles)<p> 43a3f6a49ab37290eeeb8db0f41ec0f1cb74a68be7Torne (Richard Coles)<h3>Using STL </h3> 44a3f6a49ab37290eeeb8db0f41ec0f1cb74a68be7Torne (Richard Coles)<p> 452a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)TinyXml can be compiled to use or not use STL. When using STL, TinyXml uses the std::string class, and fully supports std::istream, std::ostream, operator<<, and operator>>. Many API methods have both 'const char*' and 'const std::string&' forms.<p> 46f2477e01787aa58f445919b809d89e252beef54fTorne (Richard Coles)When STL support is compiled out, no STL files are included whatsover. All the string classes are implemented by TinyXml itself. API methods all use the 'const char*' form for input.<p> 472a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)Use the compile time define:<p> 48a3f6a49ab37290eeeb8db0f41ec0f1cb74a68be7Torne (Richard Coles)TIXML_USE_STL<p> 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)to compile one version or the other. This can be passed by the compiler, or set as the first line of "tinyxml.h".<p> 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Note: If compiling the test code in Linux, setting the environment variable TINYXML_USE_STL=YES/NO will control STL compilation. In the Windows project file, STL and non STL targets are provided. In your project, its probably easiest to add the line "#define TIXML_USE_STL" as the first line of <a class="el" href="tinyxml_8h-source.html">tinyxml.h</a>.<p> 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<h3>UTF-8 </h3> 52a36e5920737c6adbddd3e43b760e5de8431db6e0Torne (Richard Coles)<p> 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)TinyXml supports UTF-8 allowing to manipulate XML files in any language. TinyXml also supports "legacy mode" - the encoding used before UTF-8 support and probably best described as "extended ascii".<p> 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Normally, TinyXml will try to detect the correct encoding and use it. However, by setting the value of TIXML_DEFAULT_ENCODING in the header file, TinyXml can be forced to always use one encoding.<p> 552a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)TinyXml will assume Legacy Mode until one of the following occurs: <ol> 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<li> 572a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)If the non-standard but common "UTF-8 lead bytes" (0xef 0xbb 0xbf) begin the file or data stream, TinyXml will read it as UTF-8. </li> 582a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)<li> 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)If the declaration tag is read, and it has an encoding="UTF-8", then TinyXml will read it as UTF-8. </li> 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<li> 61868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles)If the declaration tag is read, and it has no encoding specified, then TinyXml will read it as UTF-8. </li> 62c5cede9ae108bb15f6b7a8aea21c7e1fefa2834cBen Murdoch<li> 63a1401311d1ab56c4ed0a474bd38c108f75cb0cd9Torne (Richard Coles)If the declaration tag is read, and it has an encoding="something else", then TinyXml will read it as Legacy Mode. In legacy mode, TinyXml will work as it did before. It's not clear what that mode does exactly, but old content should keep working. </li> 64a36e5920737c6adbddd3e43b760e5de8431db6e0Torne (Richard Coles)<li> 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Until one of the above criteria is met, TinyXml runs in Legacy Mode. </li> 663551c9c881056c480085172ff9840cab31610854Torne (Richard Coles)</ol> 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<p> 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)What happens if the encoding is incorrectly set or detected? TinyXml will try to read and pass through text seen as improperly encoded. You may get some strange results or mangled characters. You may want to force TinyXml to the correct mode.<p> 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<b> You may force TinyXml to Legacy Mode by using LoadFile( TIXML_ENCODING_LEGACY ) or LoadFile( filename, TIXML_ENCODING_LEGACY ). You may force it to use legacy mode all the time by setting TIXML_DEFAULT_ENCODING = TIXML_ENCODING_LEGACY. Likewise, you may force it to TIXML_ENCODING_UTF8 with the same technique.</b><p> 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)For English users, using English XML, UTF-8 is the same as low-ASCII. You don't need to be aware of UTF-8 or change your code in any way. You can think of UTF-8 as a "superset" of ASCII.<p> 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)UTF-8 is not a double byte format - but it is a standard encoding of Unicode! TinyXml does not use or directly support wchar, TCHAR, or Microsofts _UNICODE at this time. It is common to see the term "Unicode" improperly refer to UTF-16, a wide byte encoding of unicode. This is a source of confusion.<p> 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)For "high-ascii" languages - everything not English, pretty much - TinyXml can handle all languages, at the same time, as long as the XML is encoded in UTF-8. That can be a little tricky, older programs and operating systems tend to use the "default" or "traditional" code page. Many apps (and almost all modern ones) can output UTF-8, but older or stubborn (or just broken) ones still output text in the default code page.<p> 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)For example, Japanese systems traditionally use SHIFT-JIS encoding. Text encoded as SHIFT-JIS can not be read by tinyxml. A good text editor can import SHIFT-JIS and then save as UTF-8.<p> 745d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles)The <a href="http://skew.org/xml/tutorial/">Skew.org link</a> does a great job covering the encoding issue.<p> 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)The test file "utf8test.xml" is an XML containing English, Spanish, Russian, and Simplified Chinese. (Hopefully they are translated correctly). The file "utf8test.gif" is a screen capture of the XML file, rendered in IE. Note that if you don't have the correct fonts (Simplified Chinese or Russian) on your system, you won't see output that matches the GIF file even if you can parse it correctly. Also note that (at least on my Windows machine) console output is in a Western code page, so that Print() or printf() cannot correctly display the file. This is not a bug in TinyXml - just an OS issue. No data is lost or destroyed by TinyXml. The console just doesn't render UTF-8.<p> 762a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)<h3>Entities </h3> 774e180b6a0b4720a9b8e9e959a882386f690f08ffTorne (Richard Coles)<p> 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)TinyXml recognizes the pre-defined "character entities", meaning special characters. Namely:<p> 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<div class="fragment"><pre class="fragment"> &amp; & 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) &lt; < 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) &gt; > 8258537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) &quot; " 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) &apos; ' 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)</pre></div><p> 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)These are recognized when the XML document is read, and translated to there UTF-8 equivalents. For instance, text with the XML of:<p> 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<div class="fragment"><pre class="fragment"> Far &amp; Away 87a1401311d1ab56c4ed0a474bd38c108f75cb0cd9Torne (Richard Coles)</pre></div><p> 882a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)will have the Value() of "Far & Away" when queried from the <a class="el" href="classTiXmlText.html">TiXmlText</a> object, and will be written back to the XML stream/file as an ampersand. Older versions of TinyXml "preserved" character entities, but the newer versions will translate them into characters.<p> 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Additionally, any character can be specified by its Unicode code point: The syntax "&#xA0;" or "&#160;" are both to the non-breaking space characher.<p> 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<h3>Streams </h3> 91a3f6a49ab37290eeeb8db0f41ec0f1cb74a68be7Torne (Richard Coles)<p> 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)With TIXML_USE_STL on, TiXml has been modified to support both C (FILE) and C++ (operator <<,>>) streams. There are some differences that you may need to be aware of.<p> 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)C style output:<ul> 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<li>based on FILE*</li><li>the Print() and SaveFile() methods</li></ul> 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<p> 96c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)Generates formatted output, with plenty of white space, intended to be as human-readable as possible. They are very fast, and tolerant of ill formed XML documents. For example, an XML document that contains 2 root elements and 2 declarations, will still print.<p> 974e180b6a0b4720a9b8e9e959a882386f690f08ffTorne (Richard Coles)C style input:<ul> 981e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles)<li>based on FILE*</li><li>the Parse() and LoadFile() methods</li></ul> 99c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)<p> 1002a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)A fast, tolerant read. Use whenever you don't need the C++ streams.<p> 1014e180b6a0b4720a9b8e9e959a882386f690f08ffTorne (Richard Coles)C++ style ouput:<ul> 1022a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)<li>based on std::ostream</li><li>operator<<</li></ul> 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<p> 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Generates condensed output, intended for network transmission rather than readability. Depending on your system's implementation of the ostream class, these may be somewhat slower. (Or may not.) Not tolerant of ill formed XML: a document should contain the correct one root element. Additional root level elements will not be streamed out.<p> 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)C++ style input:<ul> 106a1401311d1ab56c4ed0a474bd38c108f75cb0cd9Torne (Richard Coles)<li>based on std::istream</li><li>operator>></li></ul> 107a1401311d1ab56c4ed0a474bd38c108f75cb0cd9Torne (Richard Coles)<p> 108a1401311d1ab56c4ed0a474bd38c108f75cb0cd9Torne (Richard Coles)Reads XML from a stream, making it useful for network transmission. The tricky part is knowing when the XML document is complete, since there will almost certainly be other data in the stream. TinyXml will assume the XML data is complete after it reads the root element. Put another way, documents that are ill-constructed with more than one root element will not read correctly. Also note that operator>> is somewhat slower than Parse, due to both implementation of the STL and limitations of TinyXml.<p> 109a1401311d1ab56c4ed0a474bd38c108f75cb0cd9Torne (Richard Coles)<h3>White space </h3> 110c5cede9ae108bb15f6b7a8aea21c7e1fefa2834cBen Murdoch<p> 111a1401311d1ab56c4ed0a474bd38c108f75cb0cd9Torne (Richard Coles)The world simply does not agree on whether white space should be kept, or condensed. For example, pretend the '_' is a space, and look at "Hello____world". HTML, and at least some XML parsers, will interpret this as "Hello_world". They condense white space. Some XML parsers do not, and will leave it as "Hello____world". (Remember to keep pretending the _ is a space.) Others suggest that __Hello___world__ should become Hello___world.<p> 112a1401311d1ab56c4ed0a474bd38c108f75cb0cd9Torne (Richard Coles)It's an issue that hasn't been resolved to my satisfaction. TinyXml supports the first 2 approaches. Call <a class="el" href="classTiXmlBase.html#e0">TiXmlBase::SetCondenseWhiteSpace( bool )</a> to set the desired behavior. The default is to condense white space.<p> 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)If you change the default, you should call <a class="el" href="classTiXmlBase.html#e0">TiXmlBase::SetCondenseWhiteSpace( bool )</a> before making any calls to Parse XML data, and I don't recommend changing it after it has been set.<p> 114eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch<h3>Handles </h3> 115eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch<p> 1165d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles)Where browsing an XML document in a robust way, it is important to check for null returns from method calls. An error safe implementation can generate a lot of code like:<p> 1175d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles)<div class="fragment"><pre class="fragment">TiXmlElement* root = document.FirstChildElement( "Document" ); 118effb81e5f8246d0db0270817048dc992db66e9fbBen Murdochif ( root ) 119effb81e5f8246d0db0270817048dc992db66e9fbBen Murdoch{ 1202a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) TiXmlElement* element = root->FirstChildElement( "Element" ); 1213551c9c881056c480085172ff9840cab31610854Torne (Richard Coles) if ( element ) 1223551c9c881056c480085172ff9840cab31610854Torne (Richard Coles) { 1235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) TiXmlElement* child = element->FirstChildElement( "Child" ); 1245d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) if ( child ) 1255d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) { 1265d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) TiXmlElement* child2 = child->NextSiblingElement( "Child" ); 127a1401311d1ab56c4ed0a474bd38c108f75cb0cd9Torne (Richard Coles) if ( child2 ) 1284e180b6a0b4720a9b8e9e959a882386f690f08ffTorne (Richard Coles) { 1294e180b6a0b4720a9b8e9e959a882386f690f08ffTorne (Richard Coles) // Finally do something useful. 130eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch</pre></div><p> 1314e180b6a0b4720a9b8e9e959a882386f690f08ffTorne (Richard Coles)Handles have been introduced to clean this up. Using the <a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> class, the previous code reduces to:<p> 132effb81e5f8246d0db0270817048dc992db66e9fbBen Murdoch<div class="fragment"><pre class="fragment">TiXmlHandle docHandle( &document ); 133a1401311d1ab56c4ed0a474bd38c108f75cb0cd9Torne (Richard Coles)TiXmlElement* child2 = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", 1 ).Element(); 134a1401311d1ab56c4ed0a474bd38c108f75cb0cd9Torne (Richard Coles)if ( child2 ) 135effb81e5f8246d0db0270817048dc992db66e9fbBen Murdoch{ 136c5cede9ae108bb15f6b7a8aea21c7e1fefa2834cBen Murdoch // do something useful 137c5cede9ae108bb15f6b7a8aea21c7e1fefa2834cBen Murdoch</pre></div><p> 1385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Which is much easier to deal with. See <a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> for more information.<p> 1395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<h3>Row and Column tracking </h3> 1405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<p> 1415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Being able to track nodes and attributes back to their origin location in source files can be very important for some applications. Additionally, knowing where parsing errors occured in the original source can be very time saving.<p> 1425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)TinyXml can tracks the row and column origin of all nodes and attributes in a text file. The <a class="el" href="classTiXmlBase.html#a3">TiXmlBase::Row()</a> and <a class="el" href="classTiXmlBase.html#a4">TiXmlBase::Column()</a> methods return the origin of the node in the source text. The correct tabs can be configured in <a class="el" href="classTiXmlDocument.html#a20">TiXmlDocument::SetTabSize()</a>.<p> 1435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<h2>Using and Installing </h2> 1445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<p> 1455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)To Compile and Run xmltest:<p> 1465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)A Linux Makefile and a Windows Visual C++ .dsw file is provided. Simply compile and run. It will write the file demotest.xml to your disk and generate output on the screen. It also tests walking the DOM by printing out the number of nodes found using different techniques.<p> 1472a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)The Linux makefile is very generic and will probably run on other systems, but is only tested on Linux. You no longer need to run 'make depend'. The dependecies have been hard coded.<p> 1482a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)<h3>Windows project file for VC6</h3> 149a1401311d1ab56c4ed0a474bd38c108f75cb0cd9Torne (Richard Coles)<p> 1502a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)<ul> 1512a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)<li> 1522a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)tinyxml: tinyxml library, non-STL </li> 1532a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)<li> 1542a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)tinyxmlSTL: tinyxml library, STL </li> 155a1401311d1ab56c4ed0a474bd38c108f75cb0cd9Torne (Richard Coles)<li> 1562a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)tinyXmlTest: test app, non-STL </li> 1572a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)<li> 1582a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)tinyXmlTestSTL: test app, STL </li> 1592a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)</ul> 1602a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)<p> 1612a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)<h3>Linux Make file</h3> 1622a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)<p> 1632a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)At the top of the makefile you can set:<p> 1642a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)PROFILE, DEBUG, and TINYXML_USE_STL. Details (such that they are) are in the makefile.<p> 1655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)In the tinyxml directory, type "make clean" then "make". The executable file 'xmltest' will be created.<p> 1665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<h3>To Use in an Application:</h3> 1675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<p> 1685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Add tinyxml.cpp, <a class="el" href="tinyxml_8h-source.html">tinyxml.h</a>, tinyxmlerror.cpp, tinyxmlparser.cpp, tinystr.cpp, and <a class="el" href="tinystr_8h-source.html">tinystr.h</a> to your project or make file. That's it! It should compile on any reasonably compliant C++ system. You do not need to enable exceptions or RTTI for TinyXml.<p> 1695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<h2>How TinyXml works. </h2> 1705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<p> 1715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)An example is probably the best way to go. Take: <div class="fragment"><pre class="fragment"> <?xml version="1.0" standalone=no> 1725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) <!-- Our to do list data --> 1735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) <ToDo> 1745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) <Item priority="1"> Go to the <bold>Toy store!</bold></Item> 1755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) <Item priority="2"> Do bills</Item> 1765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) </ToDo> 1775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)</pre></div><p> 1785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Its not much of a To Do list, but it will do. To read this file (say "demo.xml") you would create a document, and parse it in: <div class="fragment"><pre class="fragment"> TiXmlDocument doc( "demo.xml" ); 1795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) doc.LoadFile(); 1805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)</pre></div><p> 1815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)And its ready to go. Now lets look at some lines and how they relate to the DOM.<p> 1825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<div class="fragment"><pre class="fragment"><?xml version="1.0" standalone=no> 1835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)</pre></div><p> 1845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)The first line is a declaration, and gets turned into the <a class="el" href="classTiXmlDeclaration.html">TiXmlDeclaration</a> class. It will be the first child of the document node.<p> 1855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)This is the only directive/special tag parsed by by TinyXml. Generally directive targs are stored in <a class="el" href="classTiXmlUnknown.html">TiXmlUnknown</a> so the commands wont be lost when it is saved back to disk.<p> 1865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<div class="fragment"><pre class="fragment"><!-- Our to do list data --> 1875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)</pre></div><p> 1885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)A comment. Will become a <a class="el" href="classTiXmlComment.html">TiXmlComment</a> object.<p> 1895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<div class="fragment"><pre class="fragment"><ToDo> 1905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)</pre></div><p> 1915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)The "ToDo" tag defines a <a class="el" href="classTiXmlElement.html">TiXmlElement</a> object. This one does not have any attributes, but does contain 2 other elements.<p> 1925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<div class="fragment"><pre class="fragment"><Item priority="1"> 1935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)</pre></div><p> 1945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Creates another <a class="el" href="classTiXmlElement.html">TiXmlElement</a> which is a child of the "ToDo" element. This element has 1 attribute, with the name "priority" and the value "1".<p> 1955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Go to the<p> 1965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)A <a class="el" href="classTiXmlText.html">TiXmlText</a>. This is a leaf node and cannot contain other nodes. It is a child of the "Item" <a class="el" href="classTiXmlElement.html">TiXmlElement</a>.<p> 1975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<div class="fragment"><pre class="fragment"><bold> 1985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)</pre></div><p> 1995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Another <a class="el" href="classTiXmlElement.html">TiXmlElement</a>, this one a child of the "Item" element.<p> 2005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Etc.<p> 201c5cede9ae108bb15f6b7a8aea21c7e1fefa2834cBen MurdochLooking at the entire object tree, you end up with: <div class="fragment"><pre class="fragment">TiXmlDocument "demo.xml" 202c5cede9ae108bb15f6b7a8aea21c7e1fefa2834cBen Murdoch TiXmlDeclaration "version='1.0'" "standalone=no" 2035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) TiXmlComment " Our to do list data" 2045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) TiXmlElement "ToDo" 2055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) TiXmlElement "Item" Attribtutes: priority = 1 2065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) TiXmlText "Go to the " 2075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) TiXmlElement "bold" 2085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) TiXmlText "Toy store!" 2095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) TiXmlElement "Item" Attributes: priority=2 2105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) TiXmlText "Do bills" 2115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)</pre></div><p> 2121e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles)<h2>Documentation </h2> 2135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<p> 2145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)The documentation is build with Doxygen, using the 'dox' configuration file.<p> 2155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<h2>License </h2> 2165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<p> 2171e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles)TinyXml is released under the zlib license:<p> 218a36e5920737c6adbddd3e43b760e5de8431db6e0Torne (Richard Coles)This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.<p> 219a36e5920737c6adbddd3e43b760e5de8431db6e0Torne (Richard Coles)Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:<p> 220a36e5920737c6adbddd3e43b760e5de8431db6e0Torne (Richard Coles)1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.<p> 221a36e5920737c6adbddd3e43b760e5de8431db6e0Torne (Richard Coles)2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.<p> 2225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)3. This notice may not be removed or altered from any source distribution.<p> 2235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<h2>References </h2> 2245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<p> 2255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)The World Wide Web Consortium is the definitive standard body for XML, and there web pages contain huge amounts of information.<p> 2265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)The definitive spec: <a href="http://www.w3.org/TR/2004/REC-xml-20040204/">http://www.w3.org/TR/2004/REC-xml-20040204/</a><p> 2275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)I also recommend "XML Pocket Reference" by Robert Eckstein and published by OReilly...the book that got the whole thing started.<p> 2285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<h2>Contributors, Contacts, and a Brief History </h2> 2295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<p> 230f2477e01787aa58f445919b809d89e252beef54fTorne (Richard Coles)Thanks very much to everyone who sends suggestions, bugs, ideas, and encouragement. It all helps, and makes this project fun. A special thanks to the contributors on the web pages that keep it lively.<p> 2315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)So many people have sent in bugs and ideas, that rather than list here we try to give credit due in the "changes.txt" file.<p> 2325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)TinyXml was originally written be Lee Thomason. (Often the "I" still in the documenation.) Lee reviews changes and releases new versions, with the help of Yves Berquin and the tinyXml community.<p> 2335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)We appreciate your suggestions, and would love to know if you use TinyXml. Hopefully you will enjoy it and find it useful. Please post questions, comments, file bugs, or contact us at:<p> 2345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)www.sourceforge.net/projects/tinyxml<p> 2355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Lee Thomason, Yves Berquin <hr size="1"><address style="align: right;"><small>Generated on Sat Oct 8 14:15:30 2005 for TinyXml by 2361e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles)<a href="http://www.doxygen.org/index.html"> 2375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.4.4 </small></address> 2385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)</body> 2395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)</html> 2405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
