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