1
0

readme.txt 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530
  1. /** @mainpage
  2. <h1> TinyXML </h1>
  3. TinyXML is a simple, small, C++ XML parser that can be easily
  4. integrated into other programs.
  5. <h2> What it does. </h2>
  6. In brief, TinyXML parses an XML document, and builds from that a
  7. Document Object Model (DOM) that can be read, modified, and saved.
  8. XML stands for "eXtensible Markup Language." It allows you to create
  9. your own document markups. Where HTML does a very good job of marking
  10. documents for browsers, XML allows you to define any kind of document
  11. markup, for example a document that describes a "to do" list for an
  12. organizer application. XML is a very structured and convenient format.
  13. All those random file formats created to store application data can
  14. all be replaced with XML. One parser for everything.
  15. The best place for the complete, correct, and quite frankly hard to
  16. read spec is at <a href="http://www.w3.org/TR/2004/REC-xml-20040204/">
  17. http://www.w3.org/TR/2004/REC-xml-20040204/</a>. An intro to XML
  18. (that I really like) can be found at
  19. <a href="http://skew.org/xml/tutorial/">http://skew.org/xml/tutorial</a>.
  20. There are different ways to access and interact with XML data.
  21. TinyXML uses a Document Object Model (DOM), meaning the XML data is parsed
  22. into a C++ objects that can be browsed and manipulated, and then
  23. written to disk or another output stream. You can also construct an XML document
  24. from scratch with C++ objects and write this to disk or another output
  25. stream.
  26. TinyXML is designed to be easy and fast to learn. It is two headers
  27. and four cpp files. Simply add these to your project and off you go.
  28. There is an example file - xmltest.cpp - to get you started.
  29. TinyXML is released under the ZLib license,
  30. so you can use it in open source or commercial code. The details
  31. of the license are at the top of every source file.
  32. TinyXML attempts to be a flexible parser, but with truly correct and
  33. compliant XML output. TinyXML should compile on any reasonably C++
  34. compliant system. It does not rely on exceptions or RTTI. It can be
  35. compiled with or without STL support. TinyXML fully supports
  36. the UTF-8 encoding, and the first 64k character entities.
  37. <h2> What it doesn't do. </h2>
  38. TinyXML doesn't parse or use DTDs (Document Type Definitions) or XSLs
  39. (eXtensible Stylesheet Language.) There are other parsers out there
  40. (check out www.sourceforge.org, search for XML) that are much more fully
  41. featured. But they are also much bigger, take longer to set up in
  42. your project, have a higher learning curve, and often have a more
  43. restrictive license. If you are working with browsers or have more
  44. complete XML needs, TinyXML is not the parser for you.
  45. The following DTD syntax will not parse at this time in TinyXML:
  46. @verbatim
  47. <!DOCTYPE Archiv [
  48. <!ELEMENT Comment (#PCDATA)>
  49. ]>
  50. @endverbatim
  51. because TinyXML sees this as a !DOCTYPE node with an illegally
  52. embedded !ELEMENT node. This may be addressed in the future.
  53. <h2> Tutorials. </h2>
  54. For the impatient, here is a tutorial to get you going. A great way to get started,
  55. but it is worth your time to read this (very short) manual completely.
  56. - @subpage tutorial0
  57. <h2> Code Status. </h2>
  58. TinyXML is mature, tested code. It is very stable. If you find
  59. bugs, please file a bug report on the sourceforge web site
  60. (www.sourceforge.net/projects/tinyxml). We'll get them straightened
  61. out as soon as possible.
  62. There are some areas of improvement; please check sourceforge if you are
  63. interested in working on TinyXML.
  64. <h2> Related Projects </h2>
  65. TinyXML projects you may find useful! (Descriptions provided by the projects.)
  66. <ul>
  67. <li> <b>TinyXPath</b> (http://tinyxpath.sourceforge.net). TinyXPath is a small footprint
  68. XPath syntax decoder, written in C++.</li>
  69. <li> <b>TinyXML++</b> (http://code.google.com/p/ticpp/). TinyXML++ is a completely new
  70. interface to TinyXML that uses MANY of the C++ strengths. Templates,
  71. exceptions, and much better error handling.</li>
  72. </ul>
  73. <h2> Features </h2>
  74. <h3> Using STL </h3>
  75. TinyXML can be compiled to use or not use STL. When using STL, TinyXML
  76. uses the std::string class, and fully supports std::istream, std::ostream,
  77. operator<<, and operator>>. Many API methods have both 'const char*' and
  78. 'const std::string&' forms.
  79. When STL support is compiled out, no STL files are included whatsoever. All
  80. the string classes are implemented by TinyXML itself. API methods
  81. all use the 'const char*' form for input.
  82. Use the compile time #define:
  83. TIXML_USE_STL
  84. to compile one version or the other. This can be passed by the compiler,
  85. or set as the first line of "tinyxml.h".
  86. Note: If compiling the test code in Linux, setting the environment
  87. variable TINYXML_USE_STL=YES/NO will control STL compilation. In the
  88. Windows project file, STL and non STL targets are provided. In your project,
  89. It's probably easiest to add the line "#define TIXML_USE_STL" as the first
  90. line of tinyxml.h.
  91. <h3> UTF-8 </h3>
  92. TinyXML supports UTF-8 allowing to manipulate XML files in any language. TinyXML
  93. also supports "legacy mode" - the encoding used before UTF-8 support and
  94. probably best described as "extended ascii".
  95. Normally, TinyXML will try to detect the correct encoding and use it. However,
  96. by setting the value of TIXML_DEFAULT_ENCODING in the header file, TinyXML
  97. can be forced to always use one encoding.
  98. TinyXML will assume Legacy Mode until one of the following occurs:
  99. <ol>
  100. <li> If the non-standard but common "UTF-8 lead bytes" (0xef 0xbb 0xbf)
  101. begin the file or data stream, TinyXML will read it as UTF-8. </li>
  102. <li> If the declaration tag is read, and it has an encoding="UTF-8", then
  103. TinyXML will read it as UTF-8. </li>
  104. <li> If the declaration tag is read, and it has no encoding specified, then TinyXML will
  105. read it as UTF-8. </li>
  106. <li> If the declaration tag is read, and it has an encoding="something else", then TinyXML
  107. will read it as Legacy Mode. In legacy mode, TinyXML will work as it did before. It's
  108. not clear what that mode does exactly, but old content should keep working.</li>
  109. <li> Until one of the above criteria is met, TinyXML runs in Legacy Mode.</li>
  110. </ol>
  111. What happens if the encoding is incorrectly set or detected? TinyXML will try
  112. to read and pass through text seen as improperly encoded. You may get some strange results or
  113. mangled characters. You may want to force TinyXML to the correct mode.
  114. You may force TinyXML to Legacy Mode by using LoadFile( TIXML_ENCODING_LEGACY ) or
  115. LoadFile( filename, TIXML_ENCODING_LEGACY ). You may force it to use legacy mode all
  116. the time by setting TIXML_DEFAULT_ENCODING = TIXML_ENCODING_LEGACY. Likewise, you may
  117. force it to TIXML_ENCODING_UTF8 with the same technique.
  118. For English users, using English XML, UTF-8 is the same as low-ASCII. You
  119. don't need to be aware of UTF-8 or change your code in any way. You can think
  120. of UTF-8 as a "superset" of ASCII.
  121. UTF-8 is not a double byte format - but it is a standard encoding of Unicode!
  122. TinyXML does not use or directly support wchar, TCHAR, or Microsoft's _UNICODE at this time.
  123. It is common to see the term "Unicode" improperly refer to UTF-16, a wide byte encoding
  124. of unicode. This is a source of confusion.
  125. For "high-ascii" languages - everything not English, pretty much - TinyXML can
  126. handle all languages, at the same time, as long as the XML is encoded
  127. in UTF-8. That can be a little tricky, older programs and operating systems
  128. tend to use the "default" or "traditional" code page. Many apps (and almost all
  129. modern ones) can output UTF-8, but older or stubborn (or just broken) ones
  130. still output text in the default code page.
  131. For example, Japanese systems traditionally use SHIFT-JIS encoding.
  132. Text encoded as SHIFT-JIS can not be read by TinyXML.
  133. A good text editor can import SHIFT-JIS and then save as UTF-8.
  134. The <a href="http://skew.org/xml/tutorial/">Skew.org link</a> does a great
  135. job covering the encoding issue.
  136. The test file "utf8test.xml" is an XML containing English, Spanish, Russian,
  137. and Simplified Chinese. (Hopefully they are translated correctly). The file
  138. "utf8test.gif" is a screen capture of the XML file, rendered in IE. Note that
  139. if you don't have the correct fonts (Simplified Chinese or Russian) on your
  140. system, you won't see output that matches the GIF file even if you can parse
  141. it correctly. Also note that (at least on my Windows machine) console output
  142. is in a Western code page, so that Print() or printf() cannot correctly display
  143. the file. This is not a bug in TinyXML - just an OS issue. No data is lost or
  144. destroyed by TinyXML. The console just doesn't render UTF-8.
  145. <h3> Entities </h3>
  146. TinyXML recognizes the pre-defined "character entities", meaning special
  147. characters. Namely:
  148. @verbatim
  149. &amp; &
  150. &lt; <
  151. &gt; >
  152. &quot; "
  153. &apos; '
  154. @endverbatim
  155. These are recognized when the XML document is read, and translated to there
  156. UTF-8 equivalents. For instance, text with the XML of:
  157. @verbatim
  158. Far &amp; Away
  159. @endverbatim
  160. will have the Value() of "Far & Away" when queried from the TiXmlText object,
  161. and will be written back to the XML stream/file as an ampersand. Older versions
  162. of TinyXML "preserved" character entities, but the newer versions will translate
  163. them into characters.
  164. Additionally, any character can be specified by its Unicode code point:
  165. The syntax "&#xA0;" or "&#160;" are both to the non-breaking space characher.
  166. <h3> Printing </h3>
  167. TinyXML can print output in several different ways that all have strengths and limitations.
  168. - Print( FILE* ). Output to a std-C stream, which includes all C files as well as stdout.
  169. - "Pretty prints", but you don't have control over printing options.
  170. - The output is streamed directly to the FILE object, so there is no memory overhead
  171. in the TinyXML code.
  172. - used by Print() and SaveFile()
  173. - operator<<. Output to a c++ stream.
  174. - Integrates with standart C++ iostreams.
  175. - Outputs in "network printing" mode without line breaks. Good for network transmission
  176. and moving XML between C++ objects, but hard for a human to read.
  177. - TiXmlPrinter. Output to a std::string or memory buffer.
  178. - API is less concise
  179. - Future printing options will be put here.
  180. - Printing may change slightly in future versions as it is refined and expanded.
  181. <h3> Streams </h3>
  182. With TIXML_USE_STL on TinyXML supports C++ streams (operator <<,>>) streams as well
  183. as C (FILE*) streams. There are some differences that you may need to be aware of.
  184. C style output:
  185. - based on FILE*
  186. - the Print() and SaveFile() methods
  187. Generates formatted output, with plenty of white space, intended to be as
  188. human-readable as possible. They are very fast, and tolerant of ill formed
  189. XML documents. For example, an XML document that contains 2 root elements
  190. and 2 declarations, will still print.
  191. C style input:
  192. - based on FILE*
  193. - the Parse() and LoadFile() methods
  194. A fast, tolerant read. Use whenever you don't need the C++ streams.
  195. C++ style output:
  196. - based on std::ostream
  197. - operator<<
  198. Generates condensed output, intended for network transmission rather than
  199. readability. Depending on your system's implementation of the ostream class,
  200. these may be somewhat slower. (Or may not.) Not tolerant of ill formed XML:
  201. a document should contain the correct one root element. Additional root level
  202. elements will not be streamed out.
  203. C++ style input:
  204. - based on std::istream
  205. - operator>>
  206. Reads XML from a stream, making it useful for network transmission. The tricky
  207. part is knowing when the XML document is complete, since there will almost
  208. certainly be other data in the stream. TinyXML will assume the XML data is
  209. complete after it reads the root element. Put another way, documents that
  210. are ill-constructed with more than one root element will not read correctly.
  211. Also note that operator>> is somewhat slower than Parse, due to both
  212. implementation of the STL and limitations of TinyXML.
  213. <h3> White space </h3>
  214. The world simply does not agree on whether white space should be kept, or condensed.
  215. For example, pretend the '_' is a space, and look at "Hello____world". HTML, and
  216. at least some XML parsers, will interpret this as "Hello_world". They condense white
  217. space. Some XML parsers do not, and will leave it as "Hello____world". (Remember
  218. to keep pretending the _ is a space.) Others suggest that __Hello___world__ should become
  219. Hello___world.
  220. It's an issue that hasn't been resolved to my satisfaction. TinyXML supports the
  221. first 2 approaches. Call TiXmlBase::SetCondenseWhiteSpace( bool ) to set the desired behavior.
  222. The default is to condense white space.
  223. If you change the default, you should call TiXmlBase::SetCondenseWhiteSpace( bool )
  224. before making any calls to Parse XML data, and I don't recommend changing it after
  225. it has been set.
  226. <h3> Handles </h3>
  227. Where browsing an XML document in a robust way, it is important to check
  228. for null returns from method calls. An error safe implementation can
  229. generate a lot of code like:
  230. @verbatim
  231. TiXmlElement* root = document.FirstChildElement( "Document" );
  232. if ( root )
  233. {
  234. TiXmlElement* element = root->FirstChildElement( "Element" );
  235. if ( element )
  236. {
  237. TiXmlElement* child = element->FirstChildElement( "Child" );
  238. if ( child )
  239. {
  240. TiXmlElement* child2 = child->NextSiblingElement( "Child" );
  241. if ( child2 )
  242. {
  243. // Finally do something useful.
  244. @endverbatim
  245. Handles have been introduced to clean this up. Using the TiXmlHandle class,
  246. the previous code reduces to:
  247. @verbatim
  248. TiXmlHandle docHandle( &document );
  249. TiXmlElement* child2 = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", 1 ).ToElement();
  250. if ( child2 )
  251. {
  252. // do something useful
  253. @endverbatim
  254. Which is much easier to deal with. See TiXmlHandle for more information.
  255. <h3> Row and Column tracking </h3>
  256. Being able to track nodes and attributes back to their origin location
  257. in source files can be very important for some applications. Additionally,
  258. knowing where parsing errors occured in the original source can be very
  259. time saving.
  260. TinyXML can tracks the row and column origin of all nodes and attributes
  261. in a text file. The TiXmlBase::Row() and TiXmlBase::Column() methods return
  262. the origin of the node in the source text. The correct tabs can be
  263. configured in TiXmlDocument::SetTabSize().
  264. <h2> Using and Installing </h2>
  265. To Compile and Run xmltest:
  266. A Linux Makefile and a Windows Visual C++ .dsw file is provided.
  267. Simply compile and run. It will write the file demotest.xml to your
  268. disk and generate output on the screen. It also tests walking the
  269. DOM by printing out the number of nodes found using different
  270. techniques.
  271. The Linux makefile is very generic and runs on many systems - it
  272. is currently tested on mingw and
  273. MacOSX. You do not need to run 'make depend'. The dependecies have been
  274. hard coded.
  275. <h3>Windows project file for VC6</h3>
  276. <ul>
  277. <li>tinyxml: tinyxml library, non-STL </li>
  278. <li>tinyxmlSTL: tinyxml library, STL </li>
  279. <li>tinyXmlTest: test app, non-STL </li>
  280. <li>tinyXmlTestSTL: test app, STL </li>
  281. </ul>
  282. <h3>Makefile</h3>
  283. At the top of the makefile you can set:
  284. PROFILE, DEBUG, and TINYXML_USE_STL. Details (such that they are) are in
  285. the makefile.
  286. In the tinyxml directory, type "make clean" then "make". The executable
  287. file 'xmltest' will be created.
  288. <h3>To Use in an Application:</h3>
  289. Add tinyxml.cpp, tinyxml.h, tinyxmlerror.cpp, tinyxmlparser.cpp, tinystr.cpp, and tinystr.h to your
  290. project or make file. That's it! It should compile on any reasonably
  291. compliant C++ system. You do not need to enable exceptions or
  292. RTTI for TinyXML.
  293. <h2> How TinyXML works. </h2>
  294. An example is probably the best way to go. Take:
  295. @verbatim
  296. <?xml version="1.0" standalone=no>
  297. <!-- Our to do list data -->
  298. <ToDo>
  299. <Item priority="1"> Go to the <bold>Toy store!</bold></Item>
  300. <Item priority="2"> Do bills</Item>
  301. </ToDo>
  302. @endverbatim
  303. Its not much of a To Do list, but it will do. To read this file
  304. (say "demo.xml") you would create a document, and parse it in:
  305. @verbatim
  306. TiXmlDocument doc( "demo.xml" );
  307. doc.LoadFile();
  308. @endverbatim
  309. And its ready to go. Now lets look at some lines and how they
  310. relate to the DOM.
  311. @verbatim
  312. <?xml version="1.0" standalone=no>
  313. @endverbatim
  314. The first line is a declaration, and gets turned into the
  315. TiXmlDeclaration class. It will be the first child of the
  316. document node.
  317. This is the only directive/special tag parsed by by TinyXML.
  318. Generally directive tags are stored in TiXmlUnknown so the
  319. commands wont be lost when it is saved back to disk.
  320. @verbatim
  321. <!-- Our to do list data -->
  322. @endverbatim
  323. A comment. Will become a TiXmlComment object.
  324. @verbatim
  325. <ToDo>
  326. @endverbatim
  327. The "ToDo" tag defines a TiXmlElement object. This one does not have
  328. any attributes, but does contain 2 other elements.
  329. @verbatim
  330. <Item priority="1">
  331. @endverbatim
  332. Creates another TiXmlElement which is a child of the "ToDo" element.
  333. This element has 1 attribute, with the name "priority" and the value
  334. "1".
  335. @verbatim
  336. Go to the
  337. @endverbatim
  338. A TiXmlText. This is a leaf node and cannot contain other nodes.
  339. It is a child of the "Item" TiXmlElement.
  340. @verbatim
  341. <bold>
  342. @endverbatim
  343. Another TiXmlElement, this one a child of the "Item" element.
  344. Etc.
  345. Looking at the entire object tree, you end up with:
  346. @verbatim
  347. TiXmlDocument "demo.xml"
  348. TiXmlDeclaration "version='1.0'" "standalone=no"
  349. TiXmlComment " Our to do list data"
  350. TiXmlElement "ToDo"
  351. TiXmlElement "Item" Attribtutes: priority = 1
  352. TiXmlText "Go to the "
  353. TiXmlElement "bold"
  354. TiXmlText "Toy store!"
  355. TiXmlElement "Item" Attributes: priority=2
  356. TiXmlText "Do bills"
  357. @endverbatim
  358. <h2> Documentation </h2>
  359. The documentation is build with Doxygen, using the 'dox'
  360. configuration file.
  361. <h2> License </h2>
  362. TinyXML is released under the zlib license:
  363. This software is provided 'as-is', without any express or implied
  364. warranty. In no event will the authors be held liable for any
  365. damages arising from the use of this software.
  366. Permission is granted to anyone to use this software for any
  367. purpose, including commercial applications, and to alter it and
  368. redistribute it freely, subject to the following restrictions:
  369. 1. The origin of this software must not be misrepresented; you must
  370. not claim that you wrote the original software. If you use this
  371. software in a product, an acknowledgment in the product documentation
  372. would be appreciated but is not required.
  373. 2. Altered source versions must be plainly marked as such, and
  374. must not be misrepresented as being the original software.
  375. 3. This notice may not be removed or altered from any source
  376. distribution.
  377. <h2> References </h2>
  378. The World Wide Web Consortium is the definitive standard body for
  379. XML, and there web pages contain huge amounts of information.
  380. The definitive spec: <a href="http://www.w3.org/TR/2004/REC-xml-20040204/">
  381. http://www.w3.org/TR/2004/REC-xml-20040204/</a>
  382. I also recommend "XML Pocket Reference" by Robert Eckstein and published by
  383. OReilly...the book that got the whole thing started.
  384. <h2> Contributors, Contacts, and a Brief History </h2>
  385. Thanks very much to everyone who sends suggestions, bugs, ideas, and
  386. encouragement. It all helps, and makes this project fun. A special thanks
  387. to the contributors on the web pages that keep it lively.
  388. So many people have sent in bugs and ideas, that rather than list here
  389. we try to give credit due in the "changes.txt" file.
  390. TinyXML was originally written by Lee Thomason. (Often the "I" still
  391. in the documentation.) Lee reviews changes and releases new versions,
  392. with the help of Yves Berquin, Andrew Ellerton, and the tinyXml community.
  393. We appreciate your suggestions, and would love to know if you
  394. use TinyXML. Hopefully you will enjoy it and find it useful.
  395. Please post questions, comments, file bugs, or contact us at:
  396. www.sourceforge.net/projects/tinyxml
  397. Lee Thomason, Yves Berquin, Andrew Ellerton
  398. */