1*7485b225SElliott Hughes<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 2*7485b225SElliott Hughes<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US"> 3*7485b225SElliott Hughes<head> 4*7485b225SElliott Hughes<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> 5*7485b225SElliott Hughes<meta http-equiv="X-UA-Compatible" content="IE=11"/> 6*7485b225SElliott Hughes<meta name="generator" content="Doxygen 1.10.0"/> 7*7485b225SElliott Hughes<meta name="viewport" content="width=device-width, initial-scale=1"/> 8*7485b225SElliott Hughes<title>TinyXML-2: TinyXML-2</title> 9*7485b225SElliott Hughes<link href="tabs.css" rel="stylesheet" type="text/css"/> 10*7485b225SElliott Hughes<script type="text/javascript" src="jquery.js"></script> 11*7485b225SElliott Hughes<script type="text/javascript" src="dynsections.js"></script> 12*7485b225SElliott Hughes<script type="text/javascript" src="clipboard.js"></script> 13*7485b225SElliott Hughes<script type="text/javascript" src="cookie.js"></script> 14*7485b225SElliott Hughes<link href="search/search.css" rel="stylesheet" type="text/css"/> 15*7485b225SElliott Hughes<script type="text/javascript" src="search/searchdata.js"></script> 16*7485b225SElliott Hughes<script type="text/javascript" src="search/search.js"></script> 17*7485b225SElliott Hughes<link href="doxygen.css" rel="stylesheet" type="text/css" /> 18*7485b225SElliott Hughes</head> 19*7485b225SElliott Hughes<body> 20*7485b225SElliott Hughes<div id="top"><!-- do not remove this div, it is closed by doxygen! --> 21*7485b225SElliott Hughes<div id="titlearea"> 22*7485b225SElliott Hughes<table cellspacing="0" cellpadding="0"> 23*7485b225SElliott Hughes <tbody> 24*7485b225SElliott Hughes <tr id="projectrow"> 25*7485b225SElliott Hughes <td id="projectalign"> 26*7485b225SElliott Hughes <div id="projectname">TinyXML-2<span id="projectnumber"> 10.0.0</span> 27*7485b225SElliott Hughes </div> 28*7485b225SElliott Hughes </td> 29*7485b225SElliott Hughes </tr> 30*7485b225SElliott Hughes </tbody> 31*7485b225SElliott Hughes</table> 32*7485b225SElliott Hughes</div> 33*7485b225SElliott Hughes<!-- end header part --> 34*7485b225SElliott Hughes<!-- Generated by Doxygen 1.10.0 --> 35*7485b225SElliott Hughes<script type="text/javascript"> 36*7485b225SElliott Hughes/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */ 37*7485b225SElliott Hughesvar searchBox = new SearchBox("searchBox", "search/",'.html'); 38*7485b225SElliott Hughes/* @license-end */ 39*7485b225SElliott Hughes</script> 40*7485b225SElliott Hughes<script type="text/javascript" src="menudata.js"></script> 41*7485b225SElliott Hughes<script type="text/javascript" src="menu.js"></script> 42*7485b225SElliott Hughes<script type="text/javascript"> 43*7485b225SElliott Hughes/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */ 44*7485b225SElliott Hughes$(function() { 45*7485b225SElliott Hughes initMenu('',true,false,'search.php','Search'); 46*7485b225SElliott Hughes $(function() { init_search(); }); 47*7485b225SElliott Hughes}); 48*7485b225SElliott Hughes/* @license-end */ 49*7485b225SElliott Hughes</script> 50*7485b225SElliott Hughes<div id="main-nav"></div> 51*7485b225SElliott Hughes</div><!-- top --> 52*7485b225SElliott Hughes<!-- window showing the filter options --> 53*7485b225SElliott Hughes<div id="MSearchSelectWindow" 54*7485b225SElliott Hughes onmouseover="return searchBox.OnSearchSelectShow()" 55*7485b225SElliott Hughes onmouseout="return searchBox.OnSearchSelectHide()" 56*7485b225SElliott Hughes onkeydown="return searchBox.OnSearchSelectKey(event)"> 57*7485b225SElliott Hughes</div> 58*7485b225SElliott Hughes 59*7485b225SElliott Hughes<!-- iframe showing the search results (closed by default) --> 60*7485b225SElliott Hughes<div id="MSearchResultsWindow"> 61*7485b225SElliott Hughes<div id="MSearchResults"> 62*7485b225SElliott Hughes<div class="SRPage"> 63*7485b225SElliott Hughes<div id="SRIndex"> 64*7485b225SElliott Hughes<div id="SRResults"></div> 65*7485b225SElliott Hughes<div class="SRStatus" id="Loading">Loading...</div> 66*7485b225SElliott Hughes<div class="SRStatus" id="Searching">Searching...</div> 67*7485b225SElliott Hughes<div class="SRStatus" id="NoMatches">No Matches</div> 68*7485b225SElliott Hughes</div> 69*7485b225SElliott Hughes</div> 70*7485b225SElliott Hughes</div> 71*7485b225SElliott Hughes</div> 72*7485b225SElliott Hughes 73*7485b225SElliott Hughes<div><div class="header"> 74*7485b225SElliott Hughes <div class="headertitle"><div class="title">TinyXML-2 </div></div> 75*7485b225SElliott Hughes</div><!--header--> 76*7485b225SElliott Hughes<div class="contents"> 77*7485b225SElliott Hughes<div class="textblock"><p><a class="anchor" id="md_readme"></a></p> 78*7485b225SElliott Hughes<p><a href="https://github.com/leethomason/tinyxml2/actions/workflows/test.yml"><img src="https://github.com/leethomason/tinyxml2/actions/workflows/test.yml/badge.svg" alt="Test" style="pointer-events: none;" class="inline"/></a></p> 79*7485b225SElliott Hughes<p>TinyXML-2 is a simple, small, efficient, C++ XML parser that can be easily integrated into other programs.</p> 80*7485b225SElliott Hughes<p>The master is hosted on github: <a href="https://github.com/leethomason/tinyxml2">https://github.com/leethomason/tinyxml2</a></p> 81*7485b225SElliott Hughes<p>The online HTML version of these docs: <a href="http://leethomason.github.io/tinyxml2/">http://leethomason.github.io/tinyxml2/</a></p> 82*7485b225SElliott Hughes<p>Examples are in the "related pages" tab of the HTML docs.</p> 83*7485b225SElliott Hughes<h1>What it does. </h1> 84*7485b225SElliott Hughes<p>In brief, TinyXML-2 parses an XML document, and builds from that a Document Object Model (DOM) that can be read, modified, and saved.</p> 85*7485b225SElliott Hughes<p>XML stands for "eXtensible Markup Language." It is a general purpose human and machine readable markup language to describe arbitrary data. All those random file formats created to store application data can all be replaced with XML. One parser for everything.</p> 86*7485b225SElliott Hughes<p><a href="http://en.wikipedia.org/wiki/XML">http://en.wikipedia.org/wiki/XML</a></p> 87*7485b225SElliott Hughes<p>There are different ways to access and interact with XML data. TinyXML-2 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. You can even use TinyXML-2 to stream XML programmatically from code without creating a document first.</p> 88*7485b225SElliott Hughes<p>TinyXML-2 is designed to be easy and fast to learn. It is one header and one cpp file. Simply add these to your project and off you go. There is an example file - xmltest.cpp - to get you started.</p> 89*7485b225SElliott Hughes<p>TinyXML-2 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> 90*7485b225SElliott Hughes<p>TinyXML-2 attempts to be a flexible parser, but with truly correct and compliant XML output. TinyXML-2 should compile on any reasonably C++ compliant system. It does not rely on exceptions, RTTI, or the STL.</p> 91*7485b225SElliott Hughes<h1>What it doesn't do. </h1> 92*7485b225SElliott Hughes<p>TinyXML-2 doesn't parse or use DTDs (Document Type Definitions) or XSLs (eXtensible Stylesheet Language.) There are other parsers out there that are much more fully featured. But they are generally bigger and more difficult to use. If you are working with browsers or have more complete XML needs, TinyXML-2 is not the parser for you.</p> 93*7485b225SElliott Hughes<h1>TinyXML-1 vs. TinyXML-2 </h1> 94*7485b225SElliott Hughes<p>TinyXML-2 long been the focus of all development. It is well tested and should be used instead of TinyXML-1.</p> 95*7485b225SElliott Hughes<p>TinyXML-2 uses a similar API to TinyXML-1 and the same rich test cases. But the implementation of the parser is completely re-written to make it more appropriate for use in a game. It uses less memory, is faster, and uses far fewer memory allocations.</p> 96*7485b225SElliott Hughes<p>TinyXML-2 has no requirement or support for STL.</p> 97*7485b225SElliott Hughes<h1>Features </h1> 98*7485b225SElliott Hughes<h2>Code Page</h2> 99*7485b225SElliott Hughes<p>TinyXML-2 uses UTF-8 exclusively when interpreting XML. All XML is assumed to be UTF-8.</p> 100*7485b225SElliott Hughes<p>Filenames for loading / saving are passed unchanged to the underlying OS.</p> 101*7485b225SElliott Hughes<h2>Memory Model</h2> 102*7485b225SElliott Hughes<p>An XMLDocument is a C++ object like any other, that can be on the stack, or new'd and deleted on the heap.</p> 103*7485b225SElliott Hughes<p>However, any sub-node of the Document, XMLElement, XMLText, etc, can only be created by calling the appropriate XMLDocument::NewElement, NewText, etc. method. Although you have pointers to these objects, they are still owned by the Document. When the Document is deleted, so are all the nodes it contains.</p> 104*7485b225SElliott Hughes<h2>White Space</h2> 105*7485b225SElliott Hughes<h3>Whitespace Preservation (default, PRESERVE_WHITESPACE)</h3> 106*7485b225SElliott Hughes<p>Microsoft has an excellent article on white space: <a href="http://msdn.microsoft.com/en-us/library/ms256097.aspx">http://msdn.microsoft.com/en-us/library/ms256097.aspx</a></p> 107*7485b225SElliott Hughes<p>By default, TinyXML-2 preserves white space in a (hopefully) sane way that is almost compliant with the spec. (TinyXML-1 used a completely different model, much more similar to 'collapse', below.)</p> 108*7485b225SElliott Hughes<p>As a first step, all newlines / carriage-returns / line-feeds are normalized to a line-feed character, as required by the XML spec.</p> 109*7485b225SElliott Hughes<p>White space in text is preserved. For example: </p><pre class="fragment"><element> Hello, World</element> 110*7485b225SElliott Hughes</pre><p> The leading space before the "Hello" and the double space after the comma are preserved. Line-feeds are preserved, as in this example: </p><pre class="fragment"><element> Hello again, 111*7485b225SElliott Hughes World</element> 112*7485b225SElliott Hughes</pre><p> However, white space between elements is <b>not</b> preserved. Although not strictly compliant, tracking and reporting inter-element space is awkward, and not normally valuable. TinyXML-2 sees these as the same XML: </p><pre class="fragment"><document> 113*7485b225SElliott Hughes <data>1</data> 114*7485b225SElliott Hughes <data>2</data> 115*7485b225SElliott Hughes <data>3</data> 116*7485b225SElliott Hughes</document> 117*7485b225SElliott Hughes 118*7485b225SElliott Hughes<document><data>1</data><data>2</data><data>3</data></document> 119*7485b225SElliott Hughes</pre> <h3>Whitespace Collapse (COLLAPSE_WHITESPACE)</h3> 120*7485b225SElliott Hughes<p>For some applications, it is preferable to collapse whitespace. Collapsing whitespace gives you "HTML-like" behavior, which is sometimes more suitable for hand typed documents.</p> 121*7485b225SElliott Hughes<p>TinyXML-2 supports this with the 'whitespace' parameter to the XMLDocument constructor. (The default is to preserve whitespace, as described above.)</p> 122*7485b225SElliott Hughes<p>However, you may also use COLLAPSE_WHITESPACE, which will:</p> 123*7485b225SElliott Hughes<ul> 124*7485b225SElliott Hughes<li>Remove leading and trailing whitespace</li> 125*7485b225SElliott Hughes<li>Convert newlines and line-feeds into a space character</li> 126*7485b225SElliott Hughes<li>Collapse a run of any number of space characters into a single space character</li> 127*7485b225SElliott Hughes</ul> 128*7485b225SElliott Hughes<p>Note that (currently) there is a performance impact for using COLLAPSE_WHITESPACE. It essentially causes the XML to be parsed twice.</p> 129*7485b225SElliott Hughes<h3>Pedantic Whitespace (PEDANTIC_WHITESPACE)</h3> 130*7485b225SElliott Hughes<p>For applications that need to know about text nodes that are composed entirely of whitespace, PEDANTIC_WHITESPACE is available. PEDANTIC_WHITESPACE maintains all the whilespace between elements.</p> 131*7485b225SElliott Hughes<p>PEDANTIC_WHITESPACE is a new mode and not as tested as the other whitespace modes.</p> 132*7485b225SElliott Hughes<h2>Error Reporting</h2> 133*7485b225SElliott Hughes<p>TinyXML-2 reports the line number of any errors in an XML document that cannot be parsed correctly. In addition, all nodes (elements, declarations, text, comments etc.) and attributes have a line number recorded as they are parsed. This allows an application that performs additional validation of the parsed XML document (e.g. application-implemented DTD validation) to report line number information for error messages.</p> 134*7485b225SElliott Hughes<h2>Entities</h2> 135*7485b225SElliott Hughes<p>TinyXML-2 recognizes the pre-defined "character entities", meaning special characters. Namely: </p><pre class="fragment">&amp; & 136*7485b225SElliott Hughes&lt; < 137*7485b225SElliott Hughes&gt; > 138*7485b225SElliott Hughes&quot; " 139*7485b225SElliott Hughes&apos; ' 140*7485b225SElliott Hughes</pre><p> These are recognized when the XML document is read, and translated to their UTF-8 equivalents. For instance, text with the XML of: </p><pre class="fragment">Far &amp; Away 141*7485b225SElliott Hughes</pre><p> will have the Value() of "Far & Away" when queried from the XMLText object, and will be written back to the XML stream/file as an ampersand.</p> 142*7485b225SElliott Hughes<p>Additionally, any character can be specified by its Unicode code point: The syntax <code>&#xA0;</code> or <code>&#160;</code> are both to the non-breaking space character. This is called a 'numeric character reference'. Any numeric character reference that isn't one of the special entities above, will be read, but written as a regular code point. The output is correct, but the entity syntax isn't preserved.</p> 143*7485b225SElliott Hughes<h2>Printing</h2> 144*7485b225SElliott Hughes<h3>Print to file</h3> 145*7485b225SElliott Hughes<p>You can directly use the convenience function: </p><pre class="fragment">XMLDocument doc; 146*7485b225SElliott Hughes... 147*7485b225SElliott Hughesdoc.SaveFile( "foo.xml" ); 148*7485b225SElliott Hughes</pre><p> Or the XMLPrinter class: </p><pre class="fragment">XMLPrinter printer( fp ); 149*7485b225SElliott Hughesdoc.Print( &printer ); 150*7485b225SElliott Hughes</pre> <h3>Print to memory</h3> 151*7485b225SElliott Hughes<p>Printing to memory is supported by the XMLPrinter. </p><pre class="fragment">XMLPrinter printer; 152*7485b225SElliott Hughesdoc.Print( &printer ); 153*7485b225SElliott Hughes// printer.CStr() has a const char* to the XML 154*7485b225SElliott Hughes</pre> <h3>Print without an XMLDocument</h3> 155*7485b225SElliott Hughes<p>When loading, an XML parser is very useful. However, sometimes when saving, it just gets in the way. The code is often set up for streaming, and constructing the DOM is just overhead.</p> 156*7485b225SElliott Hughes<p>The Printer supports the streaming case. The following code prints out a trivially simple XML file without ever creating an XML document. </p><pre class="fragment">XMLPrinter printer( fp ); 157*7485b225SElliott Hughesprinter.OpenElement( "foo" ); 158*7485b225SElliott Hughesprinter.PushAttribute( "foo", "bar" ); 159*7485b225SElliott Hughesprinter.CloseElement(); 160*7485b225SElliott Hughes</pre> <h1>Examples </h1> 161*7485b225SElliott Hughes<h3>Load and parse an XML file.</h3> 162*7485b225SElliott Hughes<pre class="fragment">/* ------ Example 1: Load and parse an XML file. ---- */ 163*7485b225SElliott Hughes{ 164*7485b225SElliott Hughes XMLDocument doc; 165*7485b225SElliott Hughes doc.LoadFile( "dream.xml" ); 166*7485b225SElliott Hughes} 167*7485b225SElliott Hughes</pre> <h3>Lookup information.</h3> 168*7485b225SElliott Hughes<pre class="fragment">/* ------ Example 2: Lookup information. ---- */ 169*7485b225SElliott Hughes{ 170*7485b225SElliott Hughes XMLDocument doc; 171*7485b225SElliott Hughes doc.LoadFile( "dream.xml" ); 172*7485b225SElliott Hughes 173*7485b225SElliott Hughes // Structure of the XML file: 174*7485b225SElliott Hughes // - Element "PLAY" the root Element, which is the 175*7485b225SElliott Hughes // FirstChildElement of the Document 176*7485b225SElliott Hughes // - - Element "TITLE" child of the root PLAY Element 177*7485b225SElliott Hughes // - - - Text child of the TITLE Element 178*7485b225SElliott Hughes 179*7485b225SElliott Hughes // Navigate to the title, using the convenience function, 180*7485b225SElliott Hughes // with a dangerous lack of error checking. 181*7485b225SElliott Hughes const char* title = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->GetText(); 182*7485b225SElliott Hughes printf( "Name of play (1): %s\n", title ); 183*7485b225SElliott Hughes 184*7485b225SElliott Hughes // Text is just another Node to TinyXML-2. The more 185*7485b225SElliott Hughes // general way to get to the XMLText: 186*7485b225SElliott Hughes XMLText* textNode = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->FirstChild()->ToText(); 187*7485b225SElliott Hughes title = textNode->Value(); 188*7485b225SElliott Hughes printf( "Name of play (2): %s\n", title ); 189*7485b225SElliott Hughes} 190*7485b225SElliott Hughes</pre> <h1>Using and Installing </h1> 191*7485b225SElliott Hughes<p>There are 2 files in TinyXML-2:</p><ul> 192*7485b225SElliott Hughes<li>tinyxml2.cpp</li> 193*7485b225SElliott Hughes<li><a class="el" href="tinyxml2_8h_source.html">tinyxml2.h</a></li> 194*7485b225SElliott Hughes</ul> 195*7485b225SElliott Hughes<p>And additionally a test file:</p><ul> 196*7485b225SElliott Hughes<li>xmltest.cpp</li> 197*7485b225SElliott Hughes</ul> 198*7485b225SElliott Hughes<p>Generally speaking, the intent is that you simply include the tinyxml2.cpp and <a class="el" href="tinyxml2_8h_source.html">tinyxml2.h</a> files in your project and build with your other source code.</p> 199*7485b225SElliott Hughes<p>There is also a CMake build included. CMake is the general build for TinyXML-2.</p> 200*7485b225SElliott Hughes<p>(Additional build systems are costly to maintain, and tend to bit-rot. They are being removed over time.)</p> 201*7485b225SElliott Hughes<h1>Building TinyXML-2 - Using vcpkg </h1> 202*7485b225SElliott Hughes<p>You can download and install TinyXML-2 using the <a href="https://github.com/Microsoft/vcpkg">vcpkg</a> dependency manager: </p><pre class="fragment">git clone https://github.com/Microsoft/vcpkg.git 203*7485b225SElliott Hughescd vcpkg 204*7485b225SElliott Hughes./bootstrap-vcpkg.sh 205*7485b225SElliott Hughes./vcpkg integrate install 206*7485b225SElliott Hughes./vcpkg install tinyxml2 207*7485b225SElliott Hughes</pre><p> The TinyXML-2 port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please <a href="https://github.com/Microsoft/vcpkg">create an issue or pull request</a> on the vcpkg repository.</p> 208*7485b225SElliott Hughes<h1>Versioning </h1> 209*7485b225SElliott Hughes<p>TinyXML-2 uses semantic versioning. <a href="http://semver.org/">http://semver.org/</a> Releases are now tagged in github.</p> 210*7485b225SElliott Hughes<p>Note that the major version will (probably) change fairly rapidly. API changes are fairly common.</p> 211*7485b225SElliott Hughes<h1>License </h1> 212*7485b225SElliott Hughes<p>TinyXML-2 is released under the zlib license:</p> 213*7485b225SElliott Hughes<p>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> 214*7485b225SElliott Hughes<p>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> 215*7485b225SElliott Hughes<ol type="1"> 216*7485b225SElliott Hughes<li>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.</li> 217*7485b225SElliott Hughes<li>Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.</li> 218*7485b225SElliott Hughes<li>This notice may not be removed or altered from any source distribution.</li> 219*7485b225SElliott Hughes</ol> 220*7485b225SElliott Hughes<h1>Contributors </h1> 221*7485b225SElliott Hughes<p>Thanks very much to everyone who sends suggestions, bugs, ideas, and encouragement. It all helps, and makes this project fun.</p> 222*7485b225SElliott Hughes<p>The original TinyXML-1 has many contributors, who all deserve thanks in shaping what is a very successful library. Extra thanks to Yves Berquin and Andrew Ellerton who were key contributors.</p> 223*7485b225SElliott Hughes<p>TinyXML-2 grew from that effort. Lee Thomason is the original author of TinyXML-2 (and TinyXML-1) but TinyXML-2 has been and is being improved by many contributors.</p> 224*7485b225SElliott Hughes<p>Thanks to John Mackay at <a href="http://john.mackay.rosalilastudio.com">http://john.mackay.rosalilastudio.com</a> for the TinyXML-2 logo! </p> 225*7485b225SElliott Hughes</div></div><!-- PageDoc --> 226*7485b225SElliott Hughes<a href="doxygen_crawl.html"/> 227*7485b225SElliott Hughes</div><!-- contents --> 228*7485b225SElliott Hughes<!-- start footer part --> 229*7485b225SElliott Hughes<hr class="footer"/><address class="footer"><small> 230*7485b225SElliott HughesGenerated on Sat Dec 30 2023 18:02:36 for TinyXML-2 by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.10.0 231*7485b225SElliott Hughes</small></address> 232*7485b225SElliott Hughes</body> 233*7485b225SElliott Hughes</html> 234
