1TinyXML-2 2========= 3 4[](https://travis-ci.org/leethomason/tinyxml2) [](https://ci.appveyor.com/project/leethomason/tinyxml2) 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 is now the focus of all development, well tested, and your 65best choice between the two APIs. At this point, unless you are maintaining 66legacy code, you should choose TinyXML-2. 67 68TinyXML-2 uses a similar API to TinyXML-1 and the same 69rich test cases. But the implementation of the parser is completely re-written 70to make it more appropriate for use in a game. It uses less memory, is faster, 71and uses far fewer memory allocations. 72 73TinyXML-2 has no requirement or support for STL. By returning `const char*` 74TinyXML-2 can be much more efficient with memory usage. (TinyXML-1 did support 75and use STL, but consumed much more memory for the DOM representation.) 76 77Features 78-------- 79 80### Code Page 81 82TinyXML-2 uses UTF-8 exclusively when interpreting XML. All XML is assumed to 83be UTF-8. 84 85Filenames for loading / saving are passed unchanged to the underlying OS. 86 87### Memory Model 88 89An XMLDocument is a C++ object like any other, that can be on the stack, or 90new'd and deleted on the heap. 91 92However, any sub-node of the Document, XMLElement, XMLText, etc, can only 93be created by calling the appropriate XMLDocument::NewElement, NewText, etc. 94method. Although you have pointers to these objects, they are still owned 95by the Document. When the Document is deleted, so are all the nodes it contains. 96 97### White Space 98 99#### Whitespace Preservation (default) 100 101Microsoft has an excellent article on white space: http://msdn.microsoft.com/en-us/library/ms256097.aspx 102 103By default, TinyXML-2 preserves white space in a (hopefully) sane way that is almost compliant with the 104spec. (TinyXML-1 used a completely different model, much more similar to 'collapse', below.) 105 106As a first step, all newlines / carriage-returns / line-feeds are normalized to a 107line-feed character, as required by the XML spec. 108 109White space in text is preserved. For example: 110 111 <element> Hello, World</element> 112 113The leading space before the "Hello" and the double space after the comma are 114preserved. Line-feeds are preserved, as in this example: 115 116 <element> Hello again, 117 World</element> 118 119However, white space between elements is **not** preserved. Although not strictly 120compliant, tracking and reporting inter-element space is awkward, and not normally 121valuable. TinyXML-2 sees these as the same XML: 122 123 <document> 124 <data>1</data> 125 <data>2</data> 126 <data>3</data> 127 </document> 128 129 <document><data>1</data><data>2</data><data>3</data></document> 130 131#### Whitespace Collapse 132 133For some applications, it is preferable to collapse whitespace. Collapsing 134whitespace gives you "HTML-like" behavior, which is sometimes more suitable 135for hand typed documents. 136 137TinyXML-2 supports this with the 'whitespace' parameter to the XMLDocument constructor. 138(The default is to preserve whitespace, as described above.) 139 140However, you may also use COLLAPSE_WHITESPACE, which will: 141 142* Remove leading and trailing whitespace 143* Convert newlines and line-feeds into a space character 144* Collapse a run of any number of space characters into a single space character 145 146Note that (currently) there is a performance impact for using COLLAPSE_WHITESPACE. 147It essentially causes the XML to be parsed twice. 148 149#### Error Reporting 150 151TinyXML-2 reports the line number of any errors in an XML document that 152cannot be parsed correctly. In addition, all nodes (elements, declarations, 153text, comments etc.) and attributes have a line number recorded as they are parsed. 154This allows an application that performs additional validation of the parsed 155XML document (e.g. application-implemented DTD validation) to report 156line number information for error messages. 157 158### Entities 159 160TinyXML-2 recognizes the pre-defined "character entities", meaning special 161characters. Namely: 162 163 & & 164 < < 165 > > 166 " " 167 ' ' 168 169These are recognized when the XML document is read, and translated to their 170UTF-8 equivalents. For instance, text with the XML of: 171 172 Far & Away 173 174will have the Value() of "Far & Away" when queried from the XMLText object, 175and will be written back to the XML stream/file as an ampersand. 176 177Additionally, any character can be specified by its Unicode code point: 178The syntax ` ` or ` ` are both to the non-breaking space character. 179This is called a 'numeric character reference'. Any numeric character reference 180that isn't one of the special entities above, will be read, but written as a 181regular code point. The output is correct, but the entity syntax isn't preserved. 182 183### Printing 184 185#### Print to file 186You can directly use the convenience function: 187 188 XMLDocument doc; 189 ... 190 doc.SaveFile( "foo.xml" ); 191 192Or the XMLPrinter class: 193 194 XMLPrinter printer( fp ); 195 doc.Print( &printer ); 196 197#### Print to memory 198Printing to memory is supported by the XMLPrinter. 199 200 XMLPrinter printer; 201 doc.Print( &printer ); 202 // printer.CStr() has a const char* to the XML 203 204#### Print without an XMLDocument 205 206When loading, an XML parser is very useful. However, sometimes 207when saving, it just gets in the way. The code is often set up 208for streaming, and constructing the DOM is just overhead. 209 210The Printer supports the streaming case. The following code 211prints out a trivially simple XML file without ever creating 212an XML document. 213 214 XMLPrinter printer( fp ); 215 printer.OpenElement( "foo" ); 216 printer.PushAttribute( "foo", "bar" ); 217 printer.CloseElement(); 218 219Examples 220-------- 221 222#### Load and parse an XML file. 223 224 /* ------ Example 1: Load and parse an XML file. ---- */ 225 { 226 XMLDocument doc; 227 doc.LoadFile( "dream.xml" ); 228 } 229 230#### Lookup information. 231 232 /* ------ Example 2: Lookup information. ---- */ 233 { 234 XMLDocument doc; 235 doc.LoadFile( "dream.xml" ); 236 237 // Structure of the XML file: 238 // - Element "PLAY" the root Element, which is the 239 // FirstChildElement of the Document 240 // - - Element "TITLE" child of the root PLAY Element 241 // - - - Text child of the TITLE Element 242 243 // Navigate to the title, using the convenience function, 244 // with a dangerous lack of error checking. 245 const char* title = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->GetText(); 246 printf( "Name of play (1): %s\n", title ); 247 248 // Text is just another Node to TinyXML-2. The more 249 // general way to get to the XMLText: 250 XMLText* textNode = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->FirstChild()->ToText(); 251 title = textNode->Value(); 252 printf( "Name of play (2): %s\n", title ); 253 } 254 255Using and Installing 256-------------------- 257 258There are 2 files in TinyXML-2: 259* tinyxml2.cpp 260* tinyxml2.h 261 262And additionally a test file: 263* xmltest.cpp 264 265Simply compile and run. There is a visual studio 2019 project included, a simple Makefile, 266an Xcode project, a Code::Blocks project, and a cmake CMakeLists.txt included to help you. 267The top of tinyxml.h even has a simple g++ command line if you are using Unix/Linux/BSD and 268don't want to use a build system. 269 270Building TinyXML-2 - Using vcpkg 271-------------------------------- 272 273You can download and install TinyXML-2 using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager: 274 275 git clone https://github.com/Microsoft/vcpkg.git 276 cd vcpkg 277 ./bootstrap-vcpkg.sh 278 ./vcpkg integrate install 279 ./vcpkg install tinyxml2 280 281The 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. 282 283Versioning 284---------- 285 286TinyXML-2 uses semantic versioning. http://semver.org/ Releases are now tagged in github. 287 288Note that the major version will (probably) change fairly rapidly. API changes are fairly 289common. 290 291Documentation 292------------- 293 294The documentation is built with Doxygen, using the 'dox' 295configuration file. 296 297License 298------- 299 300TinyXML-2 is released under the zlib license: 301 302This software is provided 'as-is', without any express or implied 303warranty. In no event will the authors be held liable for any 304damages arising from the use of this software. 305 306Permission is granted to anyone to use this software for any 307purpose, including commercial applications, and to alter it and 308redistribute it freely, subject to the following restrictions: 309 3101. The origin of this software must not be misrepresented; you must 311not claim that you wrote the original software. If you use this 312software in a product, an acknowledgment in the product documentation 313would be appreciated but is not required. 3142. Altered source versions must be plainly marked as such, and 315must not be misrepresented as being the original software. 3163. This notice may not be removed or altered from any source 317distribution. 318 319Contributors 320------------ 321 322Thanks very much to everyone who sends suggestions, bugs, ideas, and 323encouragement. It all helps, and makes this project fun. 324 325The original TinyXML-1 has many contributors, who all deserve thanks 326in shaping what is a very successful library. Extra thanks to Yves 327Berquin and Andrew Ellerton who were key contributors. 328 329TinyXML-2 grew from that effort. Lee Thomason is the original author 330of TinyXML-2 (and TinyXML-1) but TinyXML-2 has been and is being improved 331by many contributors. 332 333Thanks to John Mackay at http://john.mackay.rosalilastudio.com for the TinyXML-2 logo! 334 335 336
){kind=link}
){kind=link}