Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / tinyxml / 973b9695a088751f06967715c1a9bfb4f6d73a05 / . / docs / tutorial0.html
blob: 9625d370199f0945096104dd785fd84ce4d80968 [file] [log] [blame]
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]3<title>TinyXml: TinyXML Tutorial</title>
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]4<link href="doxygen.css" rel="stylesheet" type="text/css">
5</head><body>
6<!-- Generated by Doxygen 1.4.4 -->
7<div class="qindex"><a class="qindex" href="index.html">Main&nbsp;Page</a> | <a class="qindex" href="hierarchy.html">Class&nbsp;Hierarchy</a> | <a class="qindex" href="annotated.html">Class&nbsp;List</a> | <a class="qindex" href="files.html">File&nbsp;List</a> | <a class="qindex" href="functions.html">Class&nbsp;Members</a></div>
8<div class="nav">
9<a class="el" href="index.html">index</a></div>
10<h1><a class="anchor" name="tutorial0">TinyXML Tutorial</a></h1><h1>Tutorial Preliminary </h1>
11<p>
12These pages contains a bunch of examples of using TinyXml.<p>
13Each demo is written in a standalone function. If you want to try the code, all you need to do is copy/paste the code into a file, then have a main to call it.<p>
14So if the example has a function:<p>
15<div class="fragment"><pre class="fragment"> void write_simple_doc()
16 {
17 ...
18 }
19 </pre></div><p>
20then the *complete* program you need to try it is:<p>
21<div class="fragment"><pre class="fragment"> #include "stdafx.h" // &lt;-- you MIGHT need this
22 #include "tinyxml.h" // &lt;-- you definitely need this ;)
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]23
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]24 void write_simple_doc()
25 {
26 ...
27 }
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]28
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]29 void main( void )
30 {
31 write_simple_doc();
32 }
33 </pre></div><p>
34Two example XML datasets/files will be used. The first looks like this:<p>
35<div class="fragment"><pre class="fragment"> &lt;?xml version="1.0" ?&gt;
36 &lt;Hello&gt;World&lt;/Hello&gt;
37 </pre></div><p>
38The other:<p>
39<div class="fragment"><pre class="fragment"> &lt;?xml version="1.0" ?&gt;
40 &lt;poetry&gt;
41 &lt;verse&gt;
42 Alas
43 Great Whatever
44 Alas (again)
45 &lt;/verse&gt;
46 &lt;/poetry&gt;
47 </pre></div><p>
48<h1>Getting Started </h1>
49<p>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]50<h2>Load XML from a file </h2>
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]51<p>
52Loading a file is as simple as:<p>
53<div class="fragment"><pre class="fragment"> void load_file( )
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]54 {
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]55 TiXmlDocument doc( "demo.xml" );
56 bool loadOkay = doc.LoadFile();
57
58 if ( loadOkay )
59 {
60 // Your document is loaded - do what you like
61 // with it.
62 //
63 // Here we'll dump the structure to STDOUT,
64 // just for example
65 dump_to_stdout( &amp;doc );
66 }
67 else
68 {
69 // load failed
70 }
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]71 }
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]72 </pre></div><p>
73The ``dump_to_stdout`` function is defined in the section `Dump structure of a Document to STDOUT` below. If you run this program with this XML:<p>
74<div class="fragment"><pre class="fragment"> &lt;?xml version="1.0" ?&gt;
75 &lt;Hello&gt;World&lt;/Hello&gt;
76 </pre></div><p>
77You'll see this:<p>
78<div class="fragment"><pre class="fragment"> DOCUMENT
79 + DECLARATION
80 + ELEMENT Hello
81 + TEXT[World]
82 </pre></div><p>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]83<h2>Building Documents Programatically </h2>
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]84<p>
85Example:<p>
86<div class="fragment"><pre class="fragment"> void write_simple_doc( )
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]87 {
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]88 // Make xml: &lt;?xml ..&gt;&lt;Hello&gt;World&lt;/Hello&gt;
89 TiXmlDocument doc;
90 TiXmlDeclaration * decl = new TiXmlDeclaration( "1.0", "", "" );
91 TiXmlElement * element = new TiXmlElement( "Hello" );
92 TiXmlText * text = new TiXmlText( "World" );
93 element-&gt;LinkEndChild( text );
94 doc.LinkEndChild( decl );
95 doc.LinkEndChild( element );
96
97 dump_to_stdout( &amp;doc );
98 doc.SaveFile( "madeByHand.xml" );
99 }
100 </pre></div><p>
101Alternatively:<p>
102<div class="fragment"><pre class="fragment"> void write_simple_doc2( )
103 {
104 // same as write_simple_doc1 but add each node
105 // as early as possible into the tree.
106
107 TiXmlDocument doc;
108 TiXmlDeclaration * decl = new TiXmlDeclaration( "1.0", "", "" );
109 doc.LinkEndChild( decl );
110
111 TiXmlElement * element = new TiXmlElement( "Hello" );
112 doc.LinkEndChild( element );
113
114 TiXmlText * text = new TiXmlText( "World" );
115 element-&gt;LinkEndChild( text );
116
117 dump_to_stdout( &amp;doc );
118 doc.SaveFile( "madeByHand2.xml" );
119 }
120 </pre></div><p>
121Both of these produce the same XML, namely:<p>
122<div class="fragment"><pre class="fragment"> &lt;?xml version="1.0" ?&gt;
123 &lt;Hello&gt;World&lt;/Hello&gt;
124 </pre></div><p>
125Or in structure form:<p>
126<div class="fragment"><pre class="fragment"> DOCUMENT
127 + DECLARATION
128 + ELEMENT Hello
129 + TEXT[World]
130 </pre></div><p>
131<h2>Saving Documents to File </h2>
132<p>
133This function:<p>
134<div class="fragment"><pre class="fragment"> void write_simple_doc3( )
135 {
136 // This example courtesy of polocolege
137
138 TiXmlDocument doc;
139 TiXmlDeclaration * decl = new TiXmlDeclaration( "1.0", "", "" );
140 doc.LinkEndChild( decl );
141
142 TiXmlElement * element = new TiXmlElement( "Hello" );
143 doc.LinkEndChild( element );
144
145 TiXmlText * text = new TiXmlText( "Opening a new salutation" );
146 element-&gt;LinkEndChild( text );
147
148 TiXmlElement * element2 = new TiXmlElement( "Greeting" );
149 element-&gt;LinkEndChild( element2 );
150
151 TiXmlText * text2 = new TiXmlText( "How are you?" );
152 element2-&gt;LinkEndChild( text2 );
153
154 TiXmlElement * element3 = new TiXmlElement( "Language" );
155 element2-&gt;LinkEndChild( element3 );
156
157 TiXmlText * text3 = new TiXmlText( "English" );
158 element3-&gt;LinkEndChild( text3 );
159
160 TiXmlElement * element4 = new TiXmlElement( "Exclamation" );
161 element-&gt;LinkEndChild( element4 );
162
163 TiXmlText * text4 = new TiXmlText( "You have children!" );
164 element4-&gt;LinkEndChild( text4 );
165
166 dump_to_stdout( &amp;doc );
167 doc.SaveFile( "madeByHand3.xml" );
168 }
169 </pre></div><p>
170Produces this structure:<p>
171<div class="fragment"><pre class="fragment"> Document
172 + Declaration
173 + Element "Hello"
174 + Text: [Opening a new salutation]
175 + Element "Greeting"
176 + Text: [How are you?]
177 + Element "Language"
178 + Text: [English]
179 + Element "Exclamation"
180 + Text: [You have children!]
181 </pre></div><p>
182The file ``madeByHand3.xml`` looks exactly like this (including indents):<p>
183<div class="fragment"><pre class="fragment"> &lt;?xml version="1.0" ?&gt;
184 &lt;Hello&gt;Opening a new salutation
185 &lt;Greeting&gt;How are you?
186 &lt;Language&gt;English&lt;/Language&gt;
187 &lt;/Greeting&gt;
188 &lt;Exclamation&gt;You have children!&lt;/Exclamation&gt;
189 &lt;/Hello&gt;
190 </pre></div><p>
191I was surprised that TinyXml, by default, writes the XML in what other APIs call a "pretty" format - it modifies the whitespace of text of elements that contain other nodes so that writing the tree includes an indication of nesting level.<p>
192I haven't looked yet to see if there is a way to turn off indenting when writing a file - its bound to be easy.<p>
193[Lee: It's easy in STL mode, just use cout &lt;&lt; myDoc. Non-STL mode is always in "pretty" format. Adding a switch would be a nice feature and has been requested.]<p>
194<h1>Iterating Over Documents </h1>
195<p>
196<h2>Dump structure of a Document to STDOUT </h2>
197<p>
198Often when you're starting its helpful and reassuring to know that you're document got loaded as you expect it to.<p>
199Below I've defined a function to walk a document and write contents to STDOUT:<p>
200<div class="fragment"><pre class="fragment"> // a utility function defining a very simple method to indent a line of text
201 const char * getIndent( unsigned int numIndents )
202 {
203 static const char * pINDENT = " + ";
204 static const unsigned int LENGTH = strlen( pINDENT );
205
206 if ( numIndents &gt; LENGTH ) numIndents = LENGTH;
207
208 return &amp;pINDENT[ LENGTH-numIndents ];
209 }
210
211 void dump_to_stdout( TiXmlNode * pParent, unsigned int indent = 0 )
212 {
213 if ( !pParent ) return;
214
215 TiXmlText *pText;
216 int t = pParent-&gt;Type();
217 printf( "%s", getIndent( indent));
218
219 switch ( t )
220 {
221 case TiXmlNode::DOCUMENT:
222 printf( "Document" );
223 break;
224
225 case TiXmlNode::ELEMENT:
226 printf( "Element \"%s\"", pParent-&gt;Value() );
227 break;
228
229 case TiXmlNode::COMMENT:
230 printf( "Comment: \"%s\"", pParent-&gt;Value());
231 break;
232
233 case TiXmlNode::UNKNOWN:
234 printf( "Unknown" );
235 break;
236
237 case TiXmlNode::TEXT:
238 pText = pParent-&gt;ToText();
239 printf( "Text: [%s]", pText-&gt;Value() );
240 break;
241
242 case TiXmlNode::DECLARATION:
243 printf( "Declaration" );
244 break;
245 default:
246 break;
247 }
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]248 printf( "\n" );
Dan Albertc3bbea32014-08-21 15:48:37 -0700[diff] [blame]249
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]250 TiXmlNode * pChild;
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]251
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]252 for ( pChild = pParent-&gt;FirstChild(); pChild != 0; pChild = pChild-&gt;NextSibling())
253 {
254 dump_to_stdout( pChild, indent+2 );
255 }
Dan Albertc3bbea32014-08-21 15:48:37 -0700[diff] [blame]256 }
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]257 </pre></div><p>
258To load a file and dump its structure:<p>
259<div class="fragment"><pre class="fragment"> void load_and_display( )
260 {
261 // important for the poetry demo, but you may not need this
262 // in your own projects
263 TiXmlBase::SetCondenseWhiteSpace( false );
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]264
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]265 TiXmlDocument doc( "demo.xml" );
266 bool loadOkay = doc.LoadFile();
Dan Albertc3bbea32014-08-21 15:48:37 -0700[diff] [blame]267
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]268 if ( loadOkay )
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]269 {
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]270 dump_to_stdout( &amp;doc );
271 }
272 else
273 {
274 printf( "Something went wrong\n" );
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]275 }
276 }
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]277 </pre></div><p>
278If you run this with the first XML file you'll see this on STDOUT:<p>
279<div class="fragment"><pre class="fragment"> DOCUMENT
280 + DECLARATION
281 + ELEMENT Hello
282 + TEXT[World]
283 </pre></div><p>
284and on the second XML file:<p>
285<div class="fragment"><pre class="fragment"> DOCUMENT
286 + DECLARATION
287 + ELEMENT poetry
288 + COMMENT: my great work of art
289 + ELEMENT verse
290 + TEXT[
291 Alas
292 Great Whatever
293 Alas (again)
294 ]
295 </pre></div><p>
296Note that if you call dump_to_stdout like this:<p>
297<div class="fragment"><pre class="fragment"> dump_to_stdout( doc.RootElement());
298 </pre></div><p>
299You'll see this instead:<p>
300<div class="fragment"><pre class="fragment"> ELEMENT Hello
301 + TEXT[World]
302 </pre></div><p>
303and:<p>
304<div class="fragment"><pre class="fragment"> ELEMENT poetry
305 + COMMENT: my great work of art
306 + ELEMENT verse
307 + TEXT[
308 Alas
309 Great Whatever
310 Alas (again)
311 ]
312 </pre></div><p>
313<em> Authors and Changes <ul>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]314<li>
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]315Written by Ellers, April 2005 </li>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]316<li>
317Minor edits and integration into doc system, Lee Thomason September 2005 </li>
318</ul>
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]319</em> <hr size="1"><address style="align: right;"><small>Generated on Sat Oct 8 14:15:30 2005 for TinyXml by&nbsp;
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]320<a href="http://www.doxygen.org/index.html">
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]321<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.4.4 </small></address>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]322</body>
323</html>