1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>Main Page</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head><body bgcolor="#ffffff">
<!-- Generated by Doxygen 1.2.10 -->
<center>
<a class="qindex" href="index.html">Main Page</a> <a class="qindex" href="hierarchy.html">Class Hierarchy</a> <a class="qindex" href="annotated.html">Compound List</a> <a class="qindex" href="files.html">File List</a> <a class="qindex" href="functions.html">Compound Members</a> </center>
<hr><h1>TinyXml Documentation</h1>
<p>
<b> TinyXml </b>
<p>
TinyXml is a simple, small, C++ XML parser that can be easily integrating into other programs.
<p>
<b> What it does. </b>
<p>
In brief, TinyXml parses an XML document, and builds from that a Document Object Model that can be read, modified, and saved.
<p>
XML stands for "eXtensible Markup Language." It allows you to create your own document markups. Where HTML does a very good job of marking documents for browsers, XML allows you to define any kind of document markup, for example a document that describes a "to do" list for an organizer application. XML is a very structured and convenient format. All those random file formats created to store application data can all be replaced with XML. One parser for everything.
<p>
There are different ways to access and interact with XML data. TinyXml uses a Document Object Model, meaning the XML data is parsed into a tree objects that can be browsed and manipulated, and then written back to disk. You can also construct an XML document from scratch with C++ objects and write this to disk.
<p>
TinyXml is designed to be easy and fast. It is one header and three cpp files. Simply add these to your project and off you go. There is an example to get you started. It is released under the ZLib license, so you can use it in open source or commercial code.
<p>
It attempts to be a flexible parser, but with truly correct and compliant XML output (with the exception of the character set, below.) TinyXml should compile on any reasonably C++ system. It does not rely on exceptions or RTTI, and only uses the STL string class.
<p>
<b> What it doesn't do. </b>
<p>
It doesnt parse or use DTDs (Document Type Definitions) or XSLs (eXtensible Stylesheet Language.) It is limited to the ASCII character set. There are other parsers out there (check out www.sourceforge.org, search for XML) that are much more fully featured. But they are also much bigger, take longer to set up in your project, have a higher learning curve, and have a more restrictive license. If you are working with browsers or have more complete XML needs, TinyXml is not the parser for you.
<p>
<b> Code Status. </b>
<p>
Currently in use, TinyXml is looking pretty stable. If you find bugs, send them in and we'll get them straightened out as soon as possible.
<p>
It currently does not recognize "entity references", meaning special characters. This is a missing feature that will hopefully be included soon. Namely: <div class="fragment"><pre>
&amp; &
&lt; <
&gt; >
&quot; "
&apos;
</pre></div>
<p>
<b> Using and Installing </b>
<p>
To Compile and Run xmltest:
<p>
A Linux Makefile and a Windows Visual C++ .dsp file is provided. Simply compile and run. It will write the file demotest.xml to your disk and generate output on the screen. It also tests walking the DOM by printing out the number of nodes found using different techniques.
<p>
The Linux makefile is very generic and will probably run on other systems, but is only tested on Linux. Make sure to run 'make depend' before you make, so you don't pick up incorrect dependencies.
<p>
To Use in an Application:
<p>
Add tinyxml.cpp, tinyxml.h, tinyxmlerror.cpp, and tinyxmlparser.cpp to your project or make file. That's it! It should compile on any reasonably compliant C++ system. You do not need to enable exceptions or RTTI for TinyXml.
<p>
<b> Where it may go. </b>
<p>
At this point, I'm focusing on tightening up remaining issues. Bug fixes (though comfortably rare) and minor interface corrections.
<p>
On the "it would be nice if..." list is:<ul>
<li>More intelligent (and consistent) parsing would be worthwhile; the parser is somewhat "organic" in its current form.<li>Entities.</ul>
I'm not currently working on either; but would ethusiastically welcome a patch!
<p>
In the future, I think it would be great if XSL and DTDs were added in some scalable way. So TinyXml would become a stand-alone core component of say MedXml (adding DTDs) and LargeXml( adding XSL.) :-)
<p>
<b> How TinyXml works. </b>
<p>
An example is probably the best way to go. Take: <div class="fragment"><pre>
<?xml version="1.0" standalone=no>
<?-- Our to do list data -->
<ToDo>
<Item priority="1"> Go to the <bold>Toy store!</bold></Item>
<Item priority="2"> Do bills</Item>
</ToDo>
</pre></div>
<p>
Its not much of a To Do list, but it will do. To read this file (say "demo.xml") you would create a document, and parse it in: <div class="fragment"><pre>
TiXmlDocument doc( "demo.xml" );
doc.LoadFile();
</pre></div>
<p>
And its ready to go. Now lets look at some lines and how they relate to the DOM.
<p>
<?xml version="1.0" standalone=no>
<p>
The first line is a declaration, and gets turned into the <a class="el" href="classTiXmlDeclaration.html">TiXmlDeclaration</a> class. It will be the first child of the document node.
<p>
This is the only directive/special tag parsed by by TinyXml. Generally directive targs are stored in <a class="el" href="classTiXmlUnknown.html">TiXmlUnknown</a> so the commands wont be lost when it is saved back to disk.
<p>
<?-- Our to do list data -->
<p>
A comment. Will become a <a class="el" href="classTiXmlComment.html">TiXmlComment</a> object.
<p>
<ToDo>
<p>
The ToDo tag defines a <a class="el" href="classTiXmlElement.html">TiXmlElement</a> object. This one does not have any attributes, but will contain 2 other elements, both of which are items.
<p>
<Item priority="1">
<p>
Creates another <a class="el" href="classTiXmlElement.html">TiXmlElement</a> which is a child of the "ToDo" element. This element has 1 attribute, with the name priority and the value 1.
<p>
Go to the
<p>
A <a class="el" href="classTiXmlText.html">TiXmlText</a>. This is a leaf node and cannot contain other nodes. It is a child of the Item" Element.
<p>
<bold>
<p>
Another <a class="el" href="classTiXmlElement.html">TiXmlElement</a>, this one a child of the "Item" element.
<p>
Etc.
<p>
Looking at the entire object tree, you end up with: <div class="fragment"><pre>
TiXmlDocument "demo.xml"
TiXmlDeclaration "version='1.0'" "standalone=no"
TiXmlComment " Our to do list data"
TiXmlElement "ToDo"
TiXmlElement "Item" Attribtutes: priority = 1
TiXmlText "Go to the "
TiXmlElement "bold"
TiXmlText "Toy store!"
TiXmlElement "Item" Attributes: priority=2
TiXmlText "bills"
</pre></div>
<p>
<b> Contributors </b>
<p>
Thanks very much to everyone who sends suggestions, bugs, ideas, and encouragement. It all helps.
<p>
Major contributors to the project: <ul>
<li> Lee Thomason wrote the original code and maintains the project. <li> Ayende Rahien presented code, ideas, and changes that became the 1.1.0 version of TinyXml. <li> Ville Nurmi provided ideas, bugs, and feedback. </ul>
<b> Documentation </b>
<p>
The documentation is build with Doxygen, using the 'dox' configuration file.
<p>
<b> License </b>
<p>
TinyXml is released under the zlib license:
<p>
This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.
<p>
Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:
<p>
1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.
<p>
2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
<p>
3. This notice may not be removed or altered from any source distribution.
<p>
<b> References </b>
<p>
The World Wide Web Consortium is the definitive standard body for XML, and there web pages contain huge amounts of information. I also recommend "XML Pocket Reference" by Robert Eckstein and published by OReilly.
<p>
<b> Contact Me: </b>
<p>
Id appreciates your suggestions, and would love to know if you use TinyXml. I hope you enjoy it and find it useful.
<p>
Lee Thomason
<p>
<a href="mailto:leethomason@mindspring.com">leethomason@mindspring.com</a>
<p>
<hr><address><small>Generated at Sun Aug 26 20:37:30 2001 for TinyXml by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.gif" alt="doxygen" align="middle" border=0
width=110 height=53></a>1.2.10 written by <a href="mailto:dimitri@stack.nl">Dimitri van Heesch</a>,
© 1997-2001</small></address>
</body>
</html>
|
