NameDateSize

..10-Aug-201812 KiB

.gitignore10-Aug-2018207

.travis.yml10-Aug-2018126

Android.bp10-Aug-2018822

appveyor.yml10-Aug-2018279

biicode.conf10-Aug-201893

cmake_uninstall.cmake.in10-Aug-20181 KiB

CMakeLists.txt10-Aug-20185.8 KiB

dox10-Aug-2018106.5 KiB

Makefile10-Aug-2018620

MODULE_LICENSE_BSD_LIKE10-Aug-20180

NOTICE10-Aug-2018808

readme.md10-Aug-201811.4 KiB

README.version10-Aug-2018108

resources/10-Aug-20184 KiB

setversion.py10-Aug-20183 KiB

tinyxml2/10-Aug-20184 KiB

tinyxml2.cpp10-Aug-201871 KiB

tinyxml2.h10-Aug-201868.1 KiB

tinyxml2.pc.in10-Aug-2018263

TinyXML2_small.png10-Aug-2018209.9 KiB

xmltest.cpp10-Aug-201875.4 KiB

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 unless you have a requirement to maintain TinyXML-1 code.
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 for STL, but has also dropped all STL support. All
74strings are query and set as 'const char*'. This allows the use of internal 
75allocators, and keeps the code much simpler.
76
77Both parsers:
78
791.  Simple to use with similar APIs.
802.  DOM based parser.
813.  UTF-8 Unicode support. http://en.wikipedia.org/wiki/UTF-8
82
83Advantages of TinyXML-2
84
851.  The focus of all future dev.
862.  Many fewer memory allocation (1/10th to 1/100th), uses less memory
87    (about 40% of TinyXML-1), and faster.
883.  No STL requirement.
894.  More modern C++, including a proper namespace.
905.  Proper and useful handling of whitespace
91
92Advantages of TinyXML-1
93
941.  Support for some C++ STL conventions: streams and strings
952.  Very mature and well debugged code base.
96
97Features
98--------
99
100### Memory Model
101
102An XMLDocument is a C++ object like any other, that can be on the stack, or
103new'd and deleted on the heap.
104
105However, any sub-node of the Document, XMLElement, XMLText, etc, can only
106be created by calling the appropriate XMLDocument::NewElement, NewText, etc.
107method. Although you have pointers to these objects, they are still owned
108by the Document. When the Document is deleted, so are all the nodes it contains.
109
110### White Space
111
112#### Whitespace Preservation (default)
113
114Microsoft has an excellent article on white space: http://msdn.microsoft.com/en-us/library/ms256097.aspx
115
116By default, TinyXML-2 preserves white space in a (hopefully) sane way that is almost compliant with the
117spec. (TinyXML-1 used a completely different model, much more similar to 'collapse', below.)
118
119As a first step, all newlines / carriage-returns / line-feeds are normalized to a
120line-feed character, as required by the XML spec.
121
122White space in text is preserved. For example:
123
124	<element> Hello,  World</element>
125
126The leading space before the "Hello" and the double space after the comma are 
127preserved. Line-feeds are preserved, as in this example:
128
129	<element> Hello again,  
130	          World</element>
131
132However, white space between elements is **not** preserved. Although not strictly 
133compliant, tracking and reporting inter-element space is awkward, and not normally
134valuable. TinyXML-2 sees these as the same XML:
135
136	<document>
137		<data>1</data>
138		<data>2</data>
139		<data>3</data>
140	</document>
141
142	<document><data>1</data><data>2</data><data>3</data></document>
143
144#### Whitespace Collapse
145
146For some applications, it is preferable to collapse whitespace. Collapsing
147whitespace gives you "HTML-like" behavior, which is sometimes more suitable
148for hand typed documents. 
149
150TinyXML-2 supports this with the 'whitespace' parameter to the XMLDocument constructor.
151(The default is to preserve whitespace, as described above.)
152
153However, you may also use COLLAPSE_WHITESPACE, which will:
154
155* Remove leading and trailing whitespace
156* Convert newlines and line-feeds into a space character
157* Collapse a run of any number of space characters into a single space character
158
159Note that (currently) there is a performance impact for using COLLAPSE_WHITESPACE.
160It essentially causes the XML to be parsed twice.
161
162#### Error Reporting
163
164TinyXML-2 reports the line number of any errors in an XML document that
165cannot be parsed correctly. In addition, all nodes (elements, declarations,
166text, comments etc.) and attributes have a line number recorded as they are parsed.
167This allows an application that performs additional validation of the parsed
168XML document (e.g. application-implemented DTD validation) to report
169line number information in it's errors.
170
171### Entities
172
173TinyXML-2 recognizes the pre-defined "character entities", meaning special
174characters. Namely:
175
176	&amp;	&
177	&lt;	<
178	&gt;	>
179	&quot;	"
180	&apos;	'
181
182These are recognized when the XML document is read, and translated to their
183UTF-8 equivalents. For instance, text with the XML of:
184
185	Far &amp; Away
186
187will have the Value() of "Far & Away" when queried from the XMLText object,
188and will be written back to the XML stream/file as an ampersand. 
189
190Additionally, any character can be specified by its Unicode code point:
191The syntax `&#xA0;` or `&#160;` are both to the non-breaking space character. 
192This is called a 'numeric character reference'. Any numeric character reference
193that isn't one of the special entities above, will be read, but written as a
194regular code point. The output is correct, but the entity syntax isn't preserved.
195
196### Printing
197
198#### Print to file
199You can directly use the convenience function:
200
201	XMLDocument doc;
202	...
203	doc.SaveFile( "foo.xml" );
204
205Or the XMLPrinter class:
206
207	XMLPrinter printer( fp );
208	doc.Print( &printer );
209
210#### Print to memory
211Printing to memory is supported by the XMLPrinter.
212
213	XMLPrinter printer;
214	doc.Print( &printer );
215	// printer.CStr() has a const char* to the XML
216
217#### Print without an XMLDocument
218
219When loading, an XML parser is very useful. However, sometimes
220when saving, it just gets in the way. The code is often set up
221for streaming, and constructing the DOM is just overhead.
222
223The Printer supports the streaming case. The following code
224prints out a trivially simple XML file without ever creating
225an XML document.
226
227	XMLPrinter printer( fp );
228	printer.OpenElement( "foo" );
229	printer.PushAttribute( "foo", "bar" );
230	printer.CloseElement();
231
232Examples
233--------
234
235#### Load and parse an XML file.
236
237	/* ------ Example 1: Load and parse an XML file. ---- */	
238	{
239		XMLDocument doc;
240		doc.LoadFile( "dream.xml" );
241	}
242
243#### Lookup information.
244
245	/* ------ Example 2: Lookup information. ---- */	
246	{
247		XMLDocument doc;
248		doc.LoadFile( "dream.xml" );
249
250		// Structure of the XML file:
251		// - Element "PLAY"      the root Element, which is the 
252		//                       FirstChildElement of the Document
253		// - - Element "TITLE"   child of the root PLAY Element
254		// - - - Text            child of the TITLE Element
255		
256		// Navigate to the title, using the convenience function,
257		// with a dangerous lack of error checking.
258		const char* title = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->GetText();
259		printf( "Name of play (1): %s\n", title );
260		
261		// Text is just another Node to TinyXML-2. The more
262		// general way to get to the XMLText:
263		XMLText* textNode = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->FirstChild()->ToText();
264		title = textNode->Value();
265		printf( "Name of play (2): %s\n", title );
266	}
267
268Using and Installing
269--------------------
270
271There are 2 files in TinyXML-2:
272* tinyxml2.cpp
273* tinyxml2.h
274
275And additionally a test file:
276* xmltest.cpp
277
278Simply compile and run. There is a visual studio 2015 project included, a simple Makefile, 
279an Xcode project, a Code::Blocks project, and a cmake CMakeLists.txt included to help you. 
280The top of tinyxml.h even has a simple g++ command line if you are are *nix and don't want 
281to use a build system.
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 build 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

README.version

1URL: https://github.com/leethomason/tinyxml2/releases
2Version: 6.0.0
3BugComponent: 24950
4AllAdvisories: yes
5