1 TinyXML-2 [![TravisCI Status](https://travis-ci.org/leethomason/tinyxml2.svg?branch=master)](https://travis-ci.org/leethomason/tinyxml2) [![AppVeyor Status](https://ci.appveyor.com/api/projects/status/github/leethomason/tinyxml2?branch=master&svg=true)](https://ci.appveyor.com/project/leethomason/tinyxml2)
3 ![TinyXML-2 Logo](http://www.grinninglizard.com/tinyxml2/TinyXML2_small.png)
5 TinyXML-2 is a simple, small, efficient, C++ XML parser that can be
6 easily integrated into other programs.
8 The master is hosted on github:
9 https://github.com/leethomason/tinyxml2
11 The online HTML version of these docs:
12 http://grinninglizard.com/tinyxml2docs/index.html
14 Examples are in the "related pages" tab of the HTML docs.
19 In brief, TinyXML-2 parses an XML document, and builds from that a
20 Document Object Model (DOM) that can be read, modified, and saved.
22 XML stands for "eXtensible Markup Language." It is a general purpose
23 human and machine readable markup language to describe arbitrary data.
24 All those random file formats created to store application data can
25 all be replaced with XML. One parser for everything.
27 http://en.wikipedia.org/wiki/XML
29 There are different ways to access and interact with XML data.
30 TinyXML-2 uses a Document Object Model (DOM), meaning the XML data is parsed
31 into a C++ objects that can be browsed and manipulated, and then
32 written to disk or another output stream. You can also construct an XML document
33 from scratch with C++ objects and write this to disk or another output
34 stream. You can even use TinyXML-2 to stream XML programmatically from
35 code without creating a document first.
37 TinyXML-2 is designed to be easy and fast to learn. It is one header and
38 one cpp file. Simply add these to your project and off you go.
39 There is an example file - xmltest.cpp - to get you started.
41 TinyXML-2 is released under the ZLib license,
42 so you can use it in open source or commercial code. The details
43 of the license are at the top of every source file.
45 TinyXML-2 attempts to be a flexible parser, but with truly correct and
46 compliant XML output. TinyXML-2 should compile on any reasonably C++
47 compliant system. It does not rely on exceptions, RTTI, or the STL.
52 TinyXML-2 doesn't parse or use DTDs (Document Type Definitions) or XSLs
53 (eXtensible Stylesheet Language.) There are other parsers out there
54 that are much more fully featured. But they are also much bigger,
55 take longer to set up in your project, have a higher learning curve,
56 and often have a more restrictive license. If you are working with
57 browsers or have more complete XML needs, TinyXML-2 is not the parser for you.
59 TinyXML-1 vs. TinyXML-2
60 -----------------------
62 TinyXML-2 is now the focus of all development, well tested, and your
63 best choice unless you have a requirement to maintain TinyXML-1 code.
65 TinyXML-2 uses a similar API to TinyXML-1 and the same
66 rich test cases. But the implementation of the parser is completely re-written
67 to make it more appropriate for use in a game. It uses less memory, is faster,
68 and uses far fewer memory allocations.
70 TinyXML-2 has no requirement for STL, but has also dropped all STL support. All
71 strings are query and set as 'const char*'. This allows the use of internal
72 allocators, and keeps the code much simpler.
76 1. Simple to use with similar APIs.
78 3. UTF-8 Unicode support. http://en.wikipedia.org/wiki/UTF-8
80 Advantages of TinyXML-2
82 1. The focus of all future dev.
83 2. Many fewer memory allocation (1/10th to 1/100th), uses less memory
84 (about 40% of TinyXML-1), and faster.
85 3. No STL requirement.
86 4. More modern C++, including a proper namespace.
87 5. Proper and useful handling of whitespace
89 Advantages of TinyXML-1
91 1. Can report the location of parsing errors.
92 2. Support for some C++ STL conventions: streams and strings
93 3. Very mature and well debugged code base.
100 An XMLDocument is a C++ object like any other, that can be on the stack, or
101 new'd and deleted on the heap.
103 However, any sub-node of the Document, XMLElement, XMLText, etc, can only
104 be created by calling the appropriate XMLDocument::NewElement, NewText, etc.
105 method. Although you have pointers to these objects, they are still owned
106 by the Document. When the Document is deleted, so are all the nodes it contains.
110 #### Whitespace Preservation (default)
112 Microsoft has an excellent article on white space: http://msdn.microsoft.com/en-us/library/ms256097.aspx
114 By default, TinyXML-2 preserves white space in a (hopefully) sane way that is almost complient with the
115 spec. (TinyXML-1 used a completely different model, much more similar to 'collapse', below.)
117 As a first step, all newlines / carriage-returns / line-feeds are normalized to a
118 line-feed character, as required by the XML spec.
120 White space in text is preserved. For example:
122 <element> Hello, World</element>
124 The leading space before the "Hello" and the double space after the comma are
125 preserved. Line-feeds are preserved, as in this example:
127 <element> Hello again,
130 However, white space between elements is **not** preserved. Although not strictly
131 compliant, tracking and reporting inter-element space is awkward, and not normally
132 valuable. TinyXML-2 sees these as the same XML:
140 <document><data>1</data><data>2</data><data>3</data></document>
142 #### Whitespace Collapse
144 For some applications, it is preferable to collapse whitespace. Collapsing
145 whitespace gives you "HTML-like" behavior, which is sometimes more suitable
146 for hand typed documents.
148 TinyXML-2 supports this with the 'whitespace' parameter to the XMLDocument constructor.
149 (The default is to preserve whitespace, as described above.)
151 However, you may also use COLLAPSE_WHITESPACE, which will:
153 * Remove leading and trailing whitespace
154 * Convert newlines and line-feeds into a space character
155 * Collapse a run of any number of space characters into a single space character
157 Note that (currently) there is a performance impact for using COLLAPSE_WHITESPACE.
158 It essentially causes the XML to be parsed twice.
162 TinyXML-2 recognizes the pre-defined "character entities", meaning special
171 These are recognized when the XML document is read, and translated to their
172 UTF-8 equivalents. For instance, text with the XML of:
176 will have the Value() of "Far & Away" when queried from the XMLText object,
177 and will be written back to the XML stream/file as an ampersand.
179 Additionally, any character can be specified by its Unicode code point:
180 The syntax ` ` or ` ` are both to the non-breaking space character.
181 This is called a 'numeric character reference'. Any numeric character reference
182 that isn't one of the special entities above, will be read, but written as a
183 regular code point. The output is correct, but the entity syntax isn't preserved.
188 You can directly use the convenience function:
192 doc.SaveFile( "foo.xml" );
194 Or the XMLPrinter class:
196 XMLPrinter printer( fp );
197 doc.Print( &printer );
200 Printing to memory is supported by the XMLPrinter.
203 doc.Print( &printer );
204 // printer.CStr() has a const char* to the XML
206 #### Print without an XMLDocument
208 When loading, an XML parser is very useful. However, sometimes
209 when saving, it just gets in the way. The code is often set up
210 for streaming, and constructing the DOM is just overhead.
212 The Printer supports the streaming case. The following code
213 prints out a trivially simple XML file without ever creating
216 XMLPrinter printer( fp );
217 printer.OpenElement( "foo" );
218 printer.PushAttribute( "foo", "bar" );
219 printer.CloseElement();
224 #### Load and parse an XML file.
226 /* ------ Example 1: Load and parse an XML file. ---- */
229 doc.LoadFile( "dream.xml" );
232 #### Lookup information.
234 /* ------ Example 2: Lookup information. ---- */
237 doc.LoadFile( "dream.xml" );
239 // Structure of the XML file:
240 // - Element "PLAY" the root Element, which is the
241 // FirstChildElement of the Document
242 // - - Element "TITLE" child of the root PLAY Element
243 // - - - Text child of the TITLE Element
245 // Navigate to the title, using the convenience function,
246 // with a dangerous lack of error checking.
247 const char* title = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->GetText();
248 printf( "Name of play (1): %s\n", title );
250 // Text is just another Node to TinyXML-2. The more
251 // general way to get to the XMLText:
252 XMLText* textNode = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->FirstChild()->ToText();
253 title = textNode->Value();
254 printf( "Name of play (2): %s\n", title );
260 There are 2 files in TinyXML-2:
264 And additionally a test file:
267 Simply compile and run. There is a visual studio 2010 project included, a simple Makefile,
268 an XCode project, a Code::Blocks project, and a cmake CMakeLists.txt included to help you.
269 The top of tinyxml.h even has a simple g++ command line if you are are *nix and don't want
270 to use a build system.
275 TinyXML-2 uses semantic versioning. http://semver.org/ Releases are now tagged in github.
277 Note that the major version will (probably) change fairly rapidly. API changes are fairly
283 The documentation is build with Doxygen, using the 'dox'
289 TinyXML-2 is released under the zlib license:
291 This software is provided 'as-is', without any express or implied
292 warranty. In no event will the authors be held liable for any
293 damages arising from the use of this software.
295 Permission is granted to anyone to use this software for any
296 purpose, including commercial applications, and to alter it and
297 redistribute it freely, subject to the following restrictions:
299 1. The origin of this software must not be misrepresented; you must
300 not claim that you wrote the original software. If you use this
301 software in a product, an acknowledgment in the product documentation
302 would be appreciated but is not required.
303 2. Altered source versions must be plainly marked as such, and
304 must not be misrepresented as being the original software.
305 3. This notice may not be removed or altered from any source
311 Thanks very much to everyone who sends suggestions, bugs, ideas, and
312 encouragement. It all helps, and makes this project fun.
314 The original TinyXML-1 has many contributors, who all deserve thanks
315 in shaping what is a very successful library. Extra thanks to Yves
316 Berquin and Andrew Ellerton who were key contributors.
318 TinyXML-2 grew from that effort. Lee Thomason is the original author
319 of TinyXML-2 (and TinyXML-1) but TinyXML-2 has been and is being improved
320 by many contributors.
322 Thanks to John Mackay at http://john.mackay.rosalilastudio.com for the TinyXML-2 logo!