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