mirror of
https://github.com/TorqueGameEngines/Torque3D.git
synced 2026-07-11 06:34:36 +00:00
Replace TinyXML library with version 9.0.0 of TinyXML2
This commit is contained in:
Lukas Aldershaab
parent
8d2e806413
commit
cd170910b2
300 changed files with 23287 additions and 16967 deletions
|
|
@ -1,275 +1,222 @@
|
|||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||||
<title>TinyXml: Main Page</title>
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
||||
<meta name="generator" content="Doxygen 1.9.1"/>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
||||
<title>TinyXML-2: TinyXML-2</title>
|
||||
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
||||
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
|
||||
<script type="text/javascript" src="jquery.js"></script>
|
||||
<script type="text/javascript" src="dynsections.js"></script>
|
||||
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
||||
<script type="text/javascript" src="search/searchdata.js"></script>
|
||||
<script type="text/javascript" src="search/search.js"></script>
|
||||
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
||||
</head>
|
||||
<body>
|
||||
<!-- Generated by Doxygen 1.6.2 -->
|
||||
<div class="navigation" id="top">
|
||||
<div class="tabs">
|
||||
<ul>
|
||||
<li class="current"><a href="index.html"><span>Main Page</span></a></li>
|
||||
<li><a href="pages.html"><span>Related Pages</span></a></li>
|
||||
<li><a href="annotated.html"><span>Classes</span></a></li>
|
||||
<li><a href="files.html"><span>Files</span></a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
||||
<div id="titlearea">
|
||||
<table cellspacing="0" cellpadding="0">
|
||||
<tbody>
|
||||
<tr style="height: 56px;">
|
||||
<td id="projectalign" style="padding-left: 0.5em;">
|
||||
<div id="projectname">TinyXML-2
|
||||
 <span id="projectnumber">9.0.0</span>
|
||||
</div>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
<!-- end header part -->
|
||||
<!-- Generated by Doxygen 1.9.1 -->
|
||||
<script type="text/javascript">
|
||||
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
||||
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
|
||||
/* @license-end */
|
||||
</script>
|
||||
<script type="text/javascript" src="menudata.js"></script>
|
||||
<script type="text/javascript" src="menu.js"></script>
|
||||
<script type="text/javascript">
|
||||
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
||||
$(function() {
|
||||
initMenu('',true,false,'search.php','Search');
|
||||
$(document).ready(function() { init_search(); });
|
||||
});
|
||||
/* @license-end */</script>
|
||||
<div id="main-nav"></div>
|
||||
</div><!-- top -->
|
||||
<!-- window showing the filter options -->
|
||||
<div id="MSearchSelectWindow"
|
||||
onmouseover="return searchBox.OnSearchSelectShow()"
|
||||
onmouseout="return searchBox.OnSearchSelectHide()"
|
||||
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
||||
</div>
|
||||
|
||||
<!-- iframe showing the search results (closed by default) -->
|
||||
<div id="MSearchResultsWindow">
|
||||
<iframe src="javascript:void(0)" frameborder="0"
|
||||
name="MSearchResults" id="MSearchResults">
|
||||
</iframe>
|
||||
</div>
|
||||
|
||||
<div class="PageDoc"><div class="header">
|
||||
<div class="headertitle">
|
||||
<div class="title">TinyXML-2 </div> </div>
|
||||
</div><!--header-->
|
||||
<div class="contents">
|
||||
<h1>TinyXml Documentation</h1><h3 class="version">2.6.2 </h3><h1>TinyXML </h1>
|
||||
<p>TinyXML is a simple, small, C++ XML parser that can be easily integrated into other programs.</p>
|
||||
<h2>What it does. </h2>
|
||||
<p>In brief, TinyXML parses an XML document, and builds from that a Document Object Model (DOM) that can be read, modified, and saved.</p>
|
||||
<p>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>
|
||||
<p>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>
|
||||
<p>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>
|
||||
<p>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>
|
||||
<p>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>
|
||||
<p>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>
|
||||
<h2>What it doesn't do. </h2>
|
||||
<p>TinyXML doesn't 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>
|
||||
<p>The following DTD syntax will not parse at this time in TinyXML:</p>
|
||||
<div class="fragment"><pre class="fragment">
|
||||
<!DOCTYPE Archiv [
|
||||
<!ELEMENT Comment (#PCDATA)>
|
||||
]>
|
||||
</pre></div><p>because TinyXML sees this as a !DOCTYPE node with an illegally embedded !ELEMENT node. This may be addressed in the future.</p>
|
||||
<h2>Tutorials. </h2>
|
||||
<p>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>
|
||||
<div class="textblock"><p><a class="anchor" id="md_readme"></a></p>
|
||||
<p><img src="https://github.com/leethomason/tinyxml2/actions/workflows/test.yml/badge.svg" alt="Build" style="pointer-events: none;" class="inline"/></p>
|
||||
<p><img src="http://www.grinninglizard.com/tinyxml2/TinyXML2_small.png" alt="TinyXML-2 Logo" class="inline"/></p>
|
||||
<p>TinyXML-2 is a simple, small, efficient, C++ XML parser that can be easily integrated into other programs.</p>
|
||||
<p>The master is hosted on github: <a href="https://github.com/leethomason/tinyxml2">https://github.com/leethomason/tinyxml2</a></p>
|
||||
<p>The online HTML version of these docs: <a href="http://leethomason.github.io/tinyxml2/">http://leethomason.github.io/tinyxml2/</a></p>
|
||||
<p>Examples are in the "related pages" tab of the HTML docs.</p>
|
||||
<h1>What it does. </h1>
|
||||
<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>
|
||||
<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>
|
||||
<p><a href="http://en.wikipedia.org/wiki/XML">http://en.wikipedia.org/wiki/XML</a></p>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
<h1>What it doesn't do. </h1>
|
||||
<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>
|
||||
<h1>TinyXML-1 vs. TinyXML-2 </h1>
|
||||
<p>TinyXML-2 long been the focus of all development. It is well tested and should be used instead of TinyXML-1.</p>
|
||||
<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>
|
||||
<p>TinyXML-2 has no requirement or support for STL.</p>
|
||||
<h1>Features </h1>
|
||||
<h2>Code Page</h2>
|
||||
<p>TinyXML-2 uses UTF-8 exclusively when interpreting XML. All XML is assumed to be UTF-8.</p>
|
||||
<p>Filenames for loading / saving are passed unchanged to the underlying OS.</p>
|
||||
<h2>Memory Model</h2>
|
||||
<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>
|
||||
<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>
|
||||
<h2>White Space</h2>
|
||||
<h3>Whitespace Preservation (default)</h3>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
<p>White space in text is preserved. For example: </p><pre class="fragment"><element> Hello, World</element>
|
||||
</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,
|
||||
World</element>
|
||||
</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>
|
||||
<data>1</data>
|
||||
<data>2</data>
|
||||
<data>3</data>
|
||||
</document>
|
||||
|
||||
<document><data>1</data><data>2</data><data>3</data></document>
|
||||
</pre> <h3>Whitespace Collapse</h3>
|
||||
<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>
|
||||
<p>TinyXML-2 supports this with the 'whitespace' parameter to the XMLDocument constructor. (The default is to preserve whitespace, as described above.)</p>
|
||||
<p>However, you may also use COLLAPSE_WHITESPACE, which will:</p>
|
||||
<ul>
|
||||
<li><a class="el" href="tutorial0.html">TinyXML Tutorial</a></li>
|
||||
<li>Remove leading and trailing whitespace</li>
|
||||
<li>Convert newlines and line-feeds into a space character</li>
|
||||
<li>Collapse a run of any number of space characters into a single space character</li>
|
||||
</ul>
|
||||
<h2>Code Status. </h2>
|
||||
<p>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>
|
||||
<p>There are some areas of improvement; please check sourceforge if you are interested in working on TinyXML.</p>
|
||||
<h2>Related Projects </h2>
|
||||
<p>TinyXML projects you may find useful! (Descriptions provided by the projects.)</p>
|
||||
<ul>
|
||||
<li>
|
||||
<b>TinyXPath</b> (<a href="http://tinyxpath.sourceforge.net">http://tinyxpath.sourceforge.net</a>). TinyXPath is a small footprint XPath syntax decoder, written in C++. </li>
|
||||
<li>
|
||||
<b>TinyXML++</b> (<a href="http://code.google.com/p/ticpp/">http://code.google.com/p/ticpp/</a>). TinyXML++ is a completely new interface to TinyXML that uses MANY of the C++ strengths. Templates, exceptions, and much better error handling. </li>
|
||||
</ul>
|
||||
<h2>Features </h2>
|
||||
<h3>Using STL </h3>
|
||||
<p>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>
|
||||
<p>When STL support is compiled out, no STL files are included whatsoever. All the string classes are implemented by TinyXML itself. API methods all use the 'const char*' form for input.</p>
|
||||
<p>Use the compile time define:</p>
|
||||
<p>TIXML_USE_STL</p>
|
||||
<p>to compile one version or the other. This can be passed by the compiler, or set as the first line of "tinyxml.h".</p>
|
||||
<p>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, It's 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>
|
||||
<h3>UTF-8 </h3>
|
||||
<p>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>
|
||||
<p>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>
|
||||
<p>TinyXML will assume Legacy Mode until one of the following occurs: </p>
|
||||
<ol>
|
||||
<li>
|
||||
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>
|
||||
<li>
|
||||
If the declaration tag is read, and it has an encoding="UTF-8", then TinyXML will read it as UTF-8. </li>
|
||||
<li>
|
||||
If the declaration tag is read, and it has no encoding specified, then TinyXML will read it as UTF-8. </li>
|
||||
<li>
|
||||
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>
|
||||
<li>
|
||||
Until one of the above criteria is met, TinyXML runs in Legacy Mode. </li>
|
||||
</ol>
|
||||
<p>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>
|
||||
<p>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.</p>
|
||||
<p>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>
|
||||
<p>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 Microsoft's _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>
|
||||
<p>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>
|
||||
<p>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>
|
||||
<p>The <a href="http://skew.org/xml/tutorial/">Skew.org link</a> does a great job covering the encoding issue.</p>
|
||||
<p>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>
|
||||
<h3>Entities </h3>
|
||||
<p>TinyXML recognizes the pre-defined "character entities", meaning special characters. Namely:</p>
|
||||
<div class="fragment"><pre class="fragment">
|
||||
&amp; &
|
||||
&lt; <
|
||||
&gt; >
|
||||
&quot; "
|
||||
&apos; '
|
||||
</pre></div><p>These are recognized when the XML document is read, and translated to there UTF-8 equivalents. For instance, text with the XML of:</p>
|
||||
<div class="fragment"><pre class="fragment">
|
||||
Far &amp; Away
|
||||
</pre></div><p>will have the Value() of "Far & Away" when queried from the <a class="el" href="classTiXmlText.html" title="XML text.">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>
|
||||
<p>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>
|
||||
<h3>Printing </h3>
|
||||
<p>TinyXML can print output in several different ways that all have strengths and limitations.</p>
|
||||
<ul>
|
||||
<li>Print( FILE* ). Output to a std-C stream, which includes all C files as well as stdout.<ul>
|
||||
<li>"Pretty prints", but you don't have control over printing options.</li>
|
||||
<li>The output is streamed directly to the FILE object, so there is no memory overhead in the TinyXML code.</li>
|
||||
<li>used by Print() and SaveFile()</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li>operator<<. Output to a c++ stream.<ul>
|
||||
<li>Integrates with standart C++ iostreams.</li>
|
||||
<li>Outputs in "network printing" mode without line breaks. Good for network transmission and moving XML between C++ objects, but hard for a human to read.</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li><a class="el" href="classTiXmlPrinter.html" title="Print to memory functionality.">TiXmlPrinter</a>. Output to a std::string or memory buffer.<ul>
|
||||
<li>API is less concise</li>
|
||||
<li>Future printing options will be put here.</li>
|
||||
<li>Printing may change slightly in future versions as it is refined and expanded.</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<h3>Streams </h3>
|
||||
<p>With TIXML_USE_STL on TinyXML supports C++ streams (operator <<,>>) streams as well as C (FILE*) streams. There are some differences that you may need to be aware of.</p>
|
||||
<p>C style output:</p>
|
||||
<ul>
|
||||
<li>based on FILE*</li>
|
||||
<li>the Print() and SaveFile() methods</li>
|
||||
</ul>
|
||||
<p>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>
|
||||
<p>C style input:</p>
|
||||
<ul>
|
||||
<li>based on FILE*</li>
|
||||
<li>the Parse() and LoadFile() methods</li>
|
||||
</ul>
|
||||
<p>A fast, tolerant read. Use whenever you don't need the C++ streams.</p>
|
||||
<p>C++ style output:</p>
|
||||
<ul>
|
||||
<li>based on std::ostream</li>
|
||||
<li>operator<<</li>
|
||||
</ul>
|
||||
<p>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>
|
||||
<p>C++ style input:</p>
|
||||
<ul>
|
||||
<li>based on std::istream</li>
|
||||
<li>operator>></li>
|
||||
</ul>
|
||||
<p>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>
|
||||
<h3>White space </h3>
|
||||
<p>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>
|
||||
<p>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#a0f799ec645bfb8d8a969e83478f379c1" title="The world does not agree on whether white space should be kept or not.">TiXmlBase::SetCondenseWhiteSpace( bool )</a> to set the desired behavior. The default is to condense white space.</p>
|
||||
<p>If you change the default, you should call <a class="el" href="classTiXmlBase.html#a0f799ec645bfb8d8a969e83478f379c1" title="The world does not agree on whether white space should be kept or not.">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>
|
||||
<h3>Handles </h3>
|
||||
<p>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>
|
||||
<div class="fragment"><pre class="fragment">
|
||||
TiXmlElement* root = document.FirstChildElement( "Document" );
|
||||
if ( root )
|
||||
<p>Note that (currently) there is a performance impact for using COLLAPSE_WHITESPACE. It essentially causes the XML to be parsed twice.</p>
|
||||
<h3>Error Reporting</h3>
|
||||
<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>
|
||||
<h2>Entities</h2>
|
||||
<p>TinyXML-2 recognizes the pre-defined "character entities", meaning special characters. Namely: </p><pre class="fragment">&amp; &
|
||||
&lt; <
|
||||
&gt; >
|
||||
&quot; "
|
||||
&apos; '
|
||||
</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
|
||||
</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>
|
||||
<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>
|
||||
<h2>Printing</h2>
|
||||
<h3>Print to file</h3>
|
||||
<p>You can directly use the convenience function: </p><pre class="fragment">XMLDocument doc;
|
||||
...
|
||||
doc.SaveFile( "foo.xml" );
|
||||
</pre><p> Or the XMLPrinter class: </p><pre class="fragment">XMLPrinter printer( fp );
|
||||
doc.Print( &printer );
|
||||
</pre> <h3>Print to memory</h3>
|
||||
<p>Printing to memory is supported by the XMLPrinter. </p><pre class="fragment">XMLPrinter printer;
|
||||
doc.Print( &printer );
|
||||
// printer.CStr() has a const char* to the XML
|
||||
</pre> <h3>Print without an XMLDocument</h3>
|
||||
<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>
|
||||
<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 );
|
||||
printer.OpenElement( "foo" );
|
||||
printer.PushAttribute( "foo", "bar" );
|
||||
printer.CloseElement();
|
||||
</pre> <h1>Examples </h1>
|
||||
<h3>Load and parse an XML file.</h3>
|
||||
<pre class="fragment">/* ------ Example 1: Load and parse an XML file. ---- */
|
||||
{
|
||||
TiXmlElement* element = root->FirstChildElement( "Element" );
|
||||
if ( element )
|
||||
{
|
||||
TiXmlElement* child = element->FirstChildElement( "Child" );
|
||||
if ( child )
|
||||
{
|
||||
TiXmlElement* child2 = child->NextSiblingElement( "Child" );
|
||||
if ( child2 )
|
||||
{
|
||||
// Finally do something useful.
|
||||
</pre></div><p>Handles have been introduced to clean this up. Using the <a class="el" href="classTiXmlHandle.html" title="A TiXmlHandle is a class that wraps a node pointer with null checks; this is an incredibly...">TiXmlHandle</a> class, the previous code reduces to:</p>
|
||||
<div class="fragment"><pre class="fragment">
|
||||
TiXmlHandle docHandle( &document );
|
||||
TiXmlElement* child2 = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", 1 ).ToElement();
|
||||
if ( child2 )
|
||||
XMLDocument doc;
|
||||
doc.LoadFile( "dream.xml" );
|
||||
}
|
||||
</pre> <h3>Lookup information.</h3>
|
||||
<pre class="fragment">/* ------ Example 2: Lookup information. ---- */
|
||||
{
|
||||
// do something useful
|
||||
</pre></div><p>Which is much easier to deal with. See <a class="el" href="classTiXmlHandle.html" title="A TiXmlHandle is a class that wraps a node pointer with null checks; this is an incredibly...">TiXmlHandle</a> for more information.</p>
|
||||
<h3>Row and Column tracking </h3>
|
||||
<p>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>
|
||||
<p>TinyXML can tracks the row and column origin of all nodes and attributes in a text file. The <a class="el" href="classTiXmlBase.html#a024bceb070188df92c2a8d8852dd0853" title="Return the position, in the original source file, of this node or attribute.">TiXmlBase::Row()</a> and <a class="el" href="classTiXmlBase.html#ab54bfb9b70fe6dd276e7b279cab7f003" title="See Row().">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#a51dac56316f89b35bdb7d0d433ba988e" title="SetTabSize() allows the error reporting functions (ErrorRow() and ErrorCol()) to...">TiXmlDocument::SetTabSize()</a>.</p>
|
||||
<h2>Using and Installing </h2>
|
||||
<p>To Compile and Run xmltest:</p>
|
||||
<p>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>
|
||||
<p>The Linux makefile is very generic and runs on many systems - it is currently tested on mingw and MacOSX. You do not need to run 'make depend'. The dependecies have been hard coded.</p>
|
||||
<h3>Windows project file for VC6</h3>
|
||||
<ul>
|
||||
<li>
|
||||
tinyxml: tinyxml library, non-STL </li>
|
||||
<li>
|
||||
tinyxmlSTL: tinyxml library, STL </li>
|
||||
<li>
|
||||
tinyXmlTest: test app, non-STL </li>
|
||||
<li>
|
||||
tinyXmlTestSTL: test app, STL </li>
|
||||
XMLDocument doc;
|
||||
doc.LoadFile( "dream.xml" );
|
||||
|
||||
// Structure of the XML file:
|
||||
// - Element "PLAY" the root Element, which is the
|
||||
// FirstChildElement of the Document
|
||||
// - - Element "TITLE" child of the root PLAY Element
|
||||
// - - - Text child of the TITLE Element
|
||||
|
||||
// Navigate to the title, using the convenience function,
|
||||
// with a dangerous lack of error checking.
|
||||
const char* title = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->GetText();
|
||||
printf( "Name of play (1): %s\n", title );
|
||||
|
||||
// Text is just another Node to TinyXML-2. The more
|
||||
// general way to get to the XMLText:
|
||||
XMLText* textNode = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->FirstChild()->ToText();
|
||||
title = textNode->Value();
|
||||
printf( "Name of play (2): %s\n", title );
|
||||
}
|
||||
</pre> <h1>Using and Installing </h1>
|
||||
<p>There are 2 files in TinyXML-2:</p><ul>
|
||||
<li>tinyxml2.cpp</li>
|
||||
<li><a class="el" href="tinyxml2_8h_source.html">tinyxml2.h</a></li>
|
||||
</ul>
|
||||
<h3>Makefile</h3>
|
||||
<p>At the top of the makefile you can set:</p>
|
||||
<p>PROFILE, DEBUG, and TINYXML_USE_STL. Details (such that they are) are in the makefile.</p>
|
||||
<p>In the tinyxml directory, type "make clean" then "make". The executable file 'xmltest' will be created.</p>
|
||||
<h3>To Use in an Application:</h3>
|
||||
<p>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>
|
||||
<h2>How TinyXML works. </h2>
|
||||
<p>An example is probably the best way to go. Take: </p>
|
||||
<div class="fragment"><pre class="fragment">
|
||||
<?xml version="1.0" standalone=no>
|
||||
<!-- Our to do list data -->
|
||||
<ToDo>
|
||||
<Item priority="1"> Go to the <bold>Toy store!</bold></Item>
|
||||
<Item priority="2"> Do bills</Item>
|
||||
</ToDo>
|
||||
</pre></div><p>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: </p>
|
||||
<div class="fragment"><pre class="fragment">
|
||||
TiXmlDocument doc( "demo.xml" );
|
||||
doc.LoadFile();
|
||||
</pre></div><p>And its ready to go. Now lets look at some lines and how they relate to the DOM.</p>
|
||||
<div class="fragment"><pre class="fragment">
|
||||
<?xml version="1.0" standalone=no>
|
||||
</pre></div><p>The first line is a declaration, and gets turned into the <a class="el" href="classTiXmlDeclaration.html" title="In correct XML the declaration is the first entry in the file.">TiXmlDeclaration</a> class. It will be the first child of the document node.</p>
|
||||
<p>This is the only directive/special tag parsed by TinyXML. Generally directive tags are stored in <a class="el" href="classTiXmlUnknown.html" title="Any tag that tinyXml doesn't recognize is saved as an unknown.">TiXmlUnknown</a> so the commands wont be lost when it is saved back to disk.</p>
|
||||
<div class="fragment"><pre class="fragment">
|
||||
<!-- Our to do list data -->
|
||||
</pre></div><p>A comment. Will become a <a class="el" href="classTiXmlComment.html" title="An XML comment.">TiXmlComment</a> object.</p>
|
||||
<div class="fragment"><pre class="fragment">
|
||||
<ToDo>
|
||||
</pre></div><p>The "ToDo" tag defines a <a class="el" href="classTiXmlElement.html" title="The element is a container class.">TiXmlElement</a> object. This one does not have any attributes, but does contain 2 other elements.</p>
|
||||
<div class="fragment"><pre class="fragment">
|
||||
<Item priority="1">
|
||||
</pre></div><p>Creates another <a class="el" href="classTiXmlElement.html" title="The element is a container class.">TiXmlElement</a> which is a child of the "ToDo" element. This element has 1 attribute, with the name "priority" and the value "1".</p>
|
||||
<div class="fragment"><pre class="fragment">
|
||||
Go to the
|
||||
</pre></div><p>A <a class="el" href="classTiXmlText.html" title="XML text.">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" title="The element is a container class.">TiXmlElement</a>.</p>
|
||||
<div class="fragment"><pre class="fragment">
|
||||
<bold>
|
||||
</pre></div><p>Another <a class="el" href="classTiXmlElement.html" title="The element is a container class.">TiXmlElement</a>, this one a child of the "Item" element.</p>
|
||||
<p>Etc.</p>
|
||||
<p>Looking at the entire object tree, you end up with: </p>
|
||||
<div class="fragment"><pre class="fragment">
|
||||
TiXmlDocument "demo.xml"
|
||||
TiXmlDeclaration "version='1.0'" "standalone=no"
|
||||
TiXmlComment " Our to do list data"
|
||||
TiXmlElement "ToDo"
|
||||
TiXmlElement "Item" Attribtutes: priority = 1
|
||||
TiXmlText "Go to the "
|
||||
TiXmlElement "bold"
|
||||
TiXmlText "Toy store!"
|
||||
TiXmlElement "Item" Attributes: priority=2
|
||||
TiXmlText "Do bills"
|
||||
</pre></div><h2>Documentation </h2>
|
||||
<p>The documentation is build with Doxygen, using the 'dox' configuration file.</p>
|
||||
<h2>License </h2>
|
||||
<p>TinyXML is released under the zlib license:</p>
|
||||
<p>And additionally a test file:</p><ul>
|
||||
<li>xmltest.cpp</li>
|
||||
</ul>
|
||||
<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>
|
||||
<p>There is also a CMake build included. CMake is the general build for TinyXML-2. Additional build systems are costly to maintain, and tend to bit-rot.</p>
|
||||
<p>A Visual Studio project is included, but that is largely for developer convenience, and is not intended to integrate well with other builds.</p>
|
||||
<h1>Building TinyXML-2 - Using vcpkg </h1>
|
||||
<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
|
||||
cd vcpkg
|
||||
./bootstrap-vcpkg.sh
|
||||
./vcpkg integrate install
|
||||
./vcpkg install tinyxml2
|
||||
</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>
|
||||
<h1>Versioning </h1>
|
||||
<p>TinyXML-2 uses semantic versioning. <a href="http://semver.org/">http://semver.org/</a> Releases are now tagged in github.</p>
|
||||
<p>Note that the major version will (probably) change fairly rapidly. API changes are fairly common.</p>
|
||||
<h1>License </h1>
|
||||
<p>TinyXML-2 is released under the zlib license:</p>
|
||||
<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>
|
||||
<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>
|
||||
<p>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>
|
||||
<p>2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.</p>
|
||||
<p>3. This notice may not be removed or altered from any source distribution.</p>
|
||||
<h2>References </h2>
|
||||
<p>The World Wide Web Consortium is the definitive standard body for XML, and their web pages contain huge amounts of information.</p>
|
||||
<p>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>
|
||||
<p>I also recommend "XML Pocket Reference" by Robert Eckstein and published by OReilly...the book that got the whole thing started.</p>
|
||||
<h2>Contributors, Contacts, and a Brief History </h2>
|
||||
<p>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>
|
||||
<p>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>
|
||||
<p>TinyXML was originally written by Lee Thomason. (Often the "I" still in the documentation.) Lee reviews changes and releases new versions, with the help of Yves Berquin, Andrew Ellerton, and the tinyXml community.</p>
|
||||
<p>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>
|
||||
<p>www.sourceforge.net/projects/tinyxml</p>
|
||||
<p>Lee Thomason, Yves Berquin, Andrew Ellerton </p>
|
||||
</div>
|
||||
<hr size="1"/><address style="text-align: right;"><small>Generated by
|
||||
<a href="http://www.doxygen.org/index.html">
|
||||
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.2 </small></address>
|
||||
<ol type="1">
|
||||
<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>
|
||||
<li>Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.</li>
|
||||
<li>This notice may not be removed or altered from any source distribution.</li>
|
||||
</ol>
|
||||
<h1>Contributors </h1>
|
||||
<p>Thanks very much to everyone who sends suggestions, bugs, ideas, and encouragement. It all helps, and makes this project fun.</p>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
</div></div><!-- PageDoc -->
|
||||
</div><!-- contents -->
|
||||
<!-- start footer part -->
|
||||
<hr class="footer"/><address class="footer"><small>
|
||||
Generated on Sun Jun 6 2021 17:10:05 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.9.1
|
||||
</small></address>
|
||||
</body>
|
||||
</html>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue