1TinyXML-2 2========= 3 4 5 6 7 8TinyXML-2 is a simple, small, efficient, C++ XML parser that can be 9easily integrated into other programs. 10 11The master is hosted on github: 12https://github.com/leethomason/tinyxml2 13 14The online HTML version of these docs: 15http://leethomason.github.io/tinyxml2/ 16 17Examples are in the "related pages" tab of the HTML docs. 18 19What it does. 20------------- 21 22In brief, TinyXML-2 parses an XML document, and builds from that a 23Document Object Model (DOM) that can be read, modified, and saved. 24 25XML stands for "eXtensible Markup Language." It is a general purpose 26human and machine readable markup language to describe arbitrary data. 27All those random file formats created to store application data can 28all be replaced with XML. One parser for everything. 29 30http://en.wikipedia.org/wiki/XML 31 32There are different ways to access and interact with XML data. 33TinyXML-2 uses a Document Object Model (DOM), meaning the XML data is parsed 34into a C++ objects that can be browsed and manipulated, and then 35written to disk or another output stream. You can also construct an XML document 36from scratch with C++ objects and write this to disk or another output 37stream. You can even use TinyXML-2 to stream XML programmatically from 38code without creating a document first. 39 40TinyXML-2 is designed to be easy and fast to learn. It is one header and 41one cpp file. Simply add these to your project and off you go. 42There is an example file - xmltest.cpp - to get you started. 43 44TinyXML-2 is released under the ZLib license, 45so you can use it in open source or commercial code. The details 46of the license are at the top of every source file. 47 48TinyXML-2 attempts to be a flexible parser, but with truly correct and 49compliant XML output. TinyXML-2 should compile on any reasonably C++ 50compliant system. It does not rely on exceptions, RTTI, or the STL. 51 52What it doesn't do. 53------------------- 54 55TinyXML-2 doesn't parse or use DTDs (Document Type Definitions) or XSLs 56(eXtensible Stylesheet Language.) There are other parsers out there 57that are much more fully featured. But they are generally bigger and 58more difficult to use. If you are working with 59browsers or have more complete XML needs, TinyXML-2 is not the parser for you. 60 61TinyXML-1 vs. TinyXML-2 62----------------------- 63 64TinyXML-2 long been the focus of all development. It is well tested 65and should be used instead of TinyXML-1. 66 67TinyXML-2 uses a similar API to TinyXML-1 and the same 68rich test cases. But the implementation of the parser is completely re-written 69to make it more appropriate for use in a game. It uses less memory, is faster, 70and uses far fewer memory allocations. 71 72TinyXML-2 has no requirement or support for STL. 73 74Features 75-------- 76 77### Code Page 78 79TinyXML-2 uses UTF-8 exclusively when interpreting XML. All XML is assumed to 80be UTF-8. 81 82Filenames for loading / saving are passed unchanged to the underlying OS. 83 84### Memory Model 85 86An XMLDocument is a C++ object like any other, that can be on the stack, or 87new'd and deleted on the heap. 88 89However, any sub-node of the Document, XMLElement, XMLText, etc, can only 90be created by calling the appropriate XMLDocument::NewElement, NewText, etc. 91method. Although you have pointers to these objects, they are still owned 92by the Document. When the Document is deleted, so are all the nodes it contains. 93 94### White Space 95 96#### Whitespace Preservation (default) 97 98Microsoft has an excellent article on white space: http://msdn.microsoft.com/en-us/library/ms256097.aspx 99 100By default, TinyXML-2 preserves white space in a (hopefully) sane way that is almost compliant with the 101spec. (TinyXML-1 used a completely different model, much more similar to 'collapse', below.) 102 103As a first step, all newlines / carriage-returns / line-feeds are normalized to a 104line-feed character, as required by the XML spec. 105 106White space in text is preserved. For example: 107 108 <element> Hello, World</element> 109 110The leading space before the "Hello" and the double space after the comma are 111preserved. Line-feeds are preserved, as in this example: 112 113 <element> Hello again, 114 World</element> 115 116However, white space between elements is **not** preserved. Although not strictly 117compliant, tracking and reporting inter-element space is awkward, and not normally 118valuable. TinyXML-2 sees these as the same XML: 119 120 <document> 121 <data>1</data> 122 <data>2</data> 123 <data>3</data> 124 </document> 125 126 <document><data>1</data><data>2</data><data>3</data></document> 127 128#### Whitespace Collapse 129 130For some applications, it is preferable to collapse whitespace. Collapsing 131whitespace gives you "HTML-like" behavior, which is sometimes more suitable 132for hand typed documents. 133 134TinyXML-2 supports this with the 'whitespace' parameter to the XMLDocument constructor. 135(The default is to preserve whitespace, as described above.) 136 137However, you may also use COLLAPSE_WHITESPACE, which will: 138 139* Remove leading and trailing whitespace 140* Convert newlines and line-feeds into a space character 141* Collapse a run of any number of space characters into a single space character 142 143Note that (currently) there is a performance impact for using COLLAPSE_WHITESPACE. 144It essentially causes the XML to be parsed twice. 145 146#### Error Reporting 147 148TinyXML-2 reports the line number of any errors in an XML document that 149cannot be parsed correctly. In addition, all nodes (elements, declarations, 150text, comments etc.) and attributes have a line number recorded as they are parsed. 151This allows an application that performs additional validation of the parsed 152XML document (e.g. application-implemented DTD validation) to report 153line number information for error messages. 154 155### Entities 156 157TinyXML-2 recognizes the pre-defined "character entities", meaning special 158characters. Namely: 159 160 & & 161 < < 162 > > 163 " " 164 ' ' 165 166These are recognized when the XML document is read, and translated to their 167UTF-8 equivalents. For instance, text with the XML of: 168 169 Far & Away 170 171will have the Value() of "Far & Away" when queried from the XMLText object, 172and will be written back to the XML stream/file as an ampersand. 173 174Additionally, any character can be specified by its Unicode code point: 175The syntax ` ` or ` ` are both to the non-breaking space character. 176This is called a 'numeric character reference'. Any numeric character reference 177that isn't one of the special entities above, will be read, but written as a 178regular code point. The output is correct, but the entity syntax isn't preserved. 179 180### Printing 181 182#### Print to file 183You can directly use the convenience function: 184 185 XMLDocument doc; 186 ... 187 doc.SaveFile( "foo.xml" ); 188 189Or the XMLPrinter class: 190 191 XMLPrinter printer( fp ); 192 doc.Print( &printer ); 193 194#### Print to memory 195Printing to memory is supported by the XMLPrinter. 196 197 XMLPrinter printer; 198 doc.Print( &printer ); 199 // printer.CStr() has a const char* to the XML 200 201#### Print without an XMLDocument 202 203When loading, an XML parser is very useful. However, sometimes 204when saving, it just gets in the way. The code is often set up 205for streaming, and constructing the DOM is just overhead. 206 207The Printer supports the streaming case. The following code 208prints out a trivially simple XML file without ever creating 209an XML document. 210 211 XMLPrinter printer( fp ); 212 printer.OpenElement( "foo" ); 213 printer.PushAttribute( "foo", "bar" ); 214 printer.CloseElement(); 215 216Examples 217-------- 218 219#### Load and parse an XML file. 220 221 /* ------ Example 1: Load and parse an XML file. ---- */ 222 { 223 XMLDocument doc; 224 doc.LoadFile( "dream.xml" ); 225 } 226 227#### Lookup information. 228 229 /* ------ Example 2: Lookup information. ---- */ 230 { 231 XMLDocument doc; 232 doc.LoadFile( "dream.xml" ); 233 234 // Structure of the XML file: 235 // - Element "PLAY" the root Element, which is the 236 // FirstChildElement of the Document 237 // - - Element "TITLE" child of the root PLAY Element 238 // - - - Text child of the TITLE Element 239 240 // Navigate to the title, using the convenience function, 241 // with a dangerous lack of error checking. 242 const char* title = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->GetText(); 243 printf( "Name of play (1): %s\n", title ); 244 245 // Text is just another Node to TinyXML-2. The more 246 // general way to get to the XMLText: 247 XMLText* textNode = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->FirstChild()->ToText(); 248 title = textNode->Value(); 249 printf( "Name of play (2): %s\n", title ); 250 } 251 252Using and Installing 253-------------------- 254 255There are 2 files in TinyXML-2: 256* tinyxml2.cpp 257* tinyxml2.h 258 259And additionally a test file: 260* xmltest.cpp 261 262Generally speaking, the intent is that you simply include the tinyxml2.cpp and 263tinyxml2.h files in your project and build with your other source code. 264 265There is also a CMake build included. CMake is the general build for TinyXML-2. 266Additional build systems are costly to maintain, and tend to bit-rot. 267 268A Visual Studio project is included, but that is largely for developer convenience, 269and is not intended to integrate well with other builds. 270 271Building TinyXML-2 - Using vcpkg 272-------------------------------- 273 274You can download and install TinyXML-2 using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager: 275 276 git clone https://github.com/Microsoft/vcpkg.git 277 cd vcpkg 278 ./bootstrap-vcpkg.sh 279 ./vcpkg integrate install 280 ./vcpkg install tinyxml2 281 282The 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 [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository. 283 284Versioning 285---------- 286 287TinyXML-2 uses semantic versioning. http://semver.org/ Releases are now tagged in github. 288 289Note that the major version will (probably) change fairly rapidly. API changes are fairly 290common. 291 292License 293------- 294 295TinyXML-2 is released under the zlib license: 296 297This software is provided 'as-is', without any express or implied 298warranty. In no event will the authors be held liable for any 299damages arising from the use of this software. 300 301Permission is granted to anyone to use this software for any 302purpose, including commercial applications, and to alter it and 303redistribute it freely, subject to the following restrictions: 304 3051. The origin of this software must not be misrepresented; you must 306not claim that you wrote the original software. If you use this 307software in a product, an acknowledgment in the product documentation 308would be appreciated but is not required. 3092. Altered source versions must be plainly marked as such, and 310must not be misrepresented as being the original software. 3113. This notice may not be removed or altered from any source 312distribution. 313 314Contributors 315------------ 316 317Thanks very much to everyone who sends suggestions, bugs, ideas, and 318encouragement. It all helps, and makes this project fun. 319 320The original TinyXML-1 has many contributors, who all deserve thanks 321in shaping what is a very successful library. Extra thanks to Yves 322Berquin and Andrew Ellerton who were key contributors. 323 324TinyXML-2 grew from that effort. Lee Thomason is the original author 325of TinyXML-2 (and TinyXML-1) but TinyXML-2 has been and is being improved 326by many contributors. 327 328Thanks to John Mackay at http://john.mackay.rosalilastudio.com for the TinyXML-2 logo! 329 330 331
){kind=link}
){kind=link}