diff options
Diffstat (limited to 'src/external/tinyxml')
25 files changed, 10251 insertions, 0 deletions
diff --git a/src/external/tinyxml/MakeHeader b/src/external/tinyxml/MakeHeader new file mode 100644 index 0000000..725efc6 --- /dev/null +++ b/src/external/tinyxml/MakeHeader @@ -0,0 +1,32 @@ +# This file is part of the OpenLB library +# +# Copyright (C) 2007 Mathias Krause +# E-mail contact: info@openlb.net +# The most recent release of OpenLB can be downloaded at +# <http://www.openlb.net/> +# +# This program is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License +# as published by the Free Software Foundation; either version 2 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public +# License along with this program; if not, write to the Free +# Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +# Boston, MA 02110-1301, USA. + + +generic := tinyxml \ + tinyxmlerror \ + tinyxmlparser \ + tinystr + +precompiled := tinyxml \ + tinyxmlerror \ + tinyxmlparser \ + tinystr diff --git a/src/external/tinyxml/changes.txt b/src/external/tinyxml/changes.txt new file mode 100644 index 0000000..1ea21ad --- /dev/null +++ b/src/external/tinyxml/changes.txt @@ -0,0 +1,290 @@ +Changes in version 1.0.1: +- Fixed comment tags which were outputing as '<?--' instead of + the correct '<!--'. +- Implemented the Next and Prev methods of the TiXmlAttribute class. +- Renamed 'LastAttribtute' to 'LastAttribute' +- Fixed bad pointer to 'isspace' that could occur while parsing text. +- Errors finding beginning and end of tags no longer throw it into an + infinite loop. (Hopefully.) + +Changes in version 1.0.2 +- Minor documentation fixes. + +Changes in version 1.0.3 +- After nodes are added to a document, they return a pointer + to the new node instead of a bool for success. +- Elements can be constructed with a value, which is the + element name. Every element must have a value or it will be + invalid, but the code changes to enforce this are not fully + in place. + +Changes in version 1.1.0 +- Added the TiXmlAttributeSet class to pull the attributes into + a seperate container. +- Moved the doubly liked list out of XmlBase. Now XmlBase only + requires the Print() function and defines some utility functions. +- Moved errors into a seperate file. (With the idea of internationalization + to the other latin-1 languages.) +- Added the "NodeType" +- Fixed white space parsing in text to conform with the standard. + Basically, all white space becomes just one space. +- Added the TiXmlDeclaration class to read xml declarations. + +Changes in version 1.2.0 +- Removed the factory. The factory was not really in the spirit + of small and simple, confused the code, and was of limited value. +- Added FirstChildElement and NextSiblingElement, because they + are such common functions. +- Re-wrote the example to test and demonstrate more functionality. + +Changes in version 1.2.1 +- Fixed a bug where comments couldn't be inside elements. +- Loading now clears out existing XML rather than appending. +- Added the "Clear" method on a node to delete all its children. + +Changes in version 1.2.2 +- Fixed TiXmlAttribute::Previous actually returning "next." Thanks + to Rickard Troedsson for the bug fix. + +Changes in version 1.2.3 +- Added the TIXML prefix to the error strings to resolve conflicts + with #defines in OS headers. Thanks to Steve Lhomme. +- Fixed a delete buf that should be a delete [] buf. + Thanks to Ephi Sinowitz. + +Changes in version 1.2.4 +- ReplaceChild() was almost guarenteed to fail. Should be fixed, + thanks to Joe Smith. Joe also pointed out that the Print() functions + should take stream references: I agree, and would like to overload + the Print() method to take either format, but I don't want to do + this in a dot release. +- Some compilers seem to need an extra <ctype.h> include. Thanks + to Steve Lhomme for that. + +Changes in version 2.0.0 BETA +- Made the ToXXX() casts safe if 'this' is null. + When "LoadFile" is called with a filename, the value will correctly get set. + Thanks to Brian Yoder. +- Fixed bug where isalpha() and isalnum() would get called with a negative value for + high ascii numbers. Thanks to Alesky Aksenov. +- Fixed some errors codes that were not getting set. +- Made methods "const" that were not. +- Added a switch to enable or disable the ignoring of white space. ( TiXmlDocument::SetIgnoreWhiteSpace() ) +- Greater standardization and code re-use in the parser. +- Added a stream out operator. +- Added a stream in operator. +- Entity support, of predefined entites. &#x entities are untouched by input or output. +- Improved text out formatting. +- Fixed ReplaceChild bug, thanks to Tao Chen. + +Changes in version 2.0.1 +- Fixed hanging on loading a 0 length file. Thanks to Jeff Scozzafava. +- Fixed crashing on InsertBeforeChild and InsertAfterChild. Also possibility of bad links being + created by same function. Thanks to Frank De prins. +- Added missing licence text. Thanks to Lars Willemsens. +- Added <ctype.h> include, at the suggestion of Steve Walters. + +Changes in version 2.1.0 +- Yves Berquin brings us the STL switch. The forum on SourceForge, and various emails to + me, have long debated all out STL vs. no STL at all. And now you can have it both ways. + TinyXml will compile either way. + +Changes in version 2.1.1 +- Compilation warnings. + +Changes in version 2.1.2 +- Uneeded code is not compiled in the STL case. +- Changed headers so that STL can be turned on or off in tinyxml.h + +Changes in version 2.1.3 +- Fixed non-const reference in API; now uses a pointer. +- Copy constructor of TiXmlString not checking for assignment to self. +- Nimrod Cohen found a truly evil bug in the STL implementation that occurs + when a string is converted to a c_str and then assigned to self. Search for + STL_STRING_BUG for a full description. I'm asserting this is a Microsoft STL + bug, since &string and string.c_str() should never be the same. Nevertheless, + the code works around it. +- Urivan Saaib pointed out a compiler conflict, where the C headers define + the isblank macro, which was wiping out the TiXmlString::isblank() method. + The method was unused and has been removed. + +Changes in version 2.1.4 +- Reworked the entity code. Entities were not correctly surving round trip input and output. + Will now automatically create entities for high ascii in output. + +Changes in version 2.1.5 +- Bug fix by kylotan : infinite loop on some input (tinyxmlparser.cpp rev 1.27) +- Contributed by Ivica Aracic (bytelord) : 1 new VC++ project to compile versions as static libraries (tinyxml_lib.dsp), + and an example usage in xmltest.dsp + (Patch request ID 678605) +- A suggestion by Ronald Fenner Jr (dormlock) to add #include <istream> and <ostream> for Apple's Project Builder + (Patch request ID 697642) +- A patch from ohommes that allows to parse correctly dots in element names and attribute names + (Patch request 602600 and kylotan 701728) +- A patch from hermitgeek ( James ) and wasteland for improper error reporting +- Reviewed by Lee, with the following changes: + - Got sick of fighting the STL/non-STL thing in the windows build. Broke + them out as seperate projects. + - I have too long not included the dsw. Added. + - TinyXmlText had a protected Print. Odd. + - Made LinkEndChild public, with docs and appropriate warnings. + - Updated the docs. + +2.2.0 +- Fixed an uninitialized pointer in the TiXmlAttributes +- Fixed STL compilation problem in MinGW (and gcc 3?) - thanks Brian Yoder for finding this one +- Fixed a syntax error in TiXmlDeclaration - thanks Brian Yoder +- Fletcher Dunn proposed and submitted new error handling that tracked the row and column. Lee + modified it to not have performance impact. +- General cleanup suggestions from Fletcher Dunn. +- In error handling, general errors will no longer clear the error state of specific ones. +- Fix error in documentation : comments starting with "<?--" instead of "<!--" (thanks ion_pulse) +- Added the TiXmlHandle. An easy, safe way to browse XML DOMs with less code. +- Added QueryAttribute calls which have better error messaging. (Proposed by Fletcher Dunn) +- Nodes and attributes can now print themselves to strings. (Yves suggestion) +- Fixed bug where entities with one character would confuse parser. (Thanks Roman) + +2.2.1 +- Additional testing (no more bugs found to be fixed in this release) +- Significant performance improvement to the cursor code. + +2.3.0 +- User Data are now defined in TiXmlBase instead of TiXmlNode +- Character Entities are now UCS-2 +- Character Entities can be decimal or hexadecimal +- UTF-8 conversion. +- Fixed many, many bugs. + +2.3.1 +- Fixed bug in handling nulls embedded in the input. +- Make UTF-8 parser tolerant of bad text encoding. +- Added encoding detection. +- Many fixes and input from John-Philip Leonard Johansson (JP) and Ellers, + including UTF-8 feedback, bug reports, and patches. Thanks! +- Added version # constants - a suggestion from JP and Ellers. +- [ 979180 ] Missing ; in entity reference, fix from Rob Laveaux. +- Copy constructors and assignment have been a long time coming. Thanks to + Fokke and JP. + +2.3.2 +- Made the IsAlpha and IsAlphaNum much more tolerant of non-UTF-8 encodings. Thanks + Volker Boerchers for finding the issue. +- Ran the program though the magnificent Valgrind - http://valgrind.kde.org - to check + for memory errors. Fixed some minor issues. + +2.3.3 +- Fixed crash when test program was run from incorrect directory. +- Fixed bug 1070717 - empty document not returned correctly - thanks Katsuhisa Yuasa. +- Bug 1079301 resolved - deprecated stdlib calls. Thanks Adrian Boeing. +- Bug 1035218 fixed - documentation errors. Xunji Luo +- Other bug fixes have accumulated and been fixed on the way as well; my apologies to + authors not credited! +- Big fix / addition is to correctly return const values. TinyXml could basically + remove const in a method like this: TiXmlElement* Foo() const, where the returned element + was a pointer to internal data. That is now: const TiXmlElement* Foo() const and + TiXmlElement* Foo(). + +2.3.4 +- Fixed additional const errors, thanks Kent Gibson. +- Correctly re-enable warnings after tinyxml header. Thanks Cory Nelson. +- Variety of type cleanup and warning fixes. Thanks Warren Stevens. +- Cleaned up unneeded constructor calls in TinyString - thanks to Geoff Carlton and + the discussion group on sourceforge. + +2.4.0 +- Improved string class, thanks Tyge Lovset (whose name gets mangled in English - sorry) +- Type cast compiler warning, thanks Rob van den Bogaard +- Added GetText() convenience function. Thanks Ilya Parniuk & Andrew Ellers for input. +- Many thanks to marlonism for finding an infinite loop in bad xml. +- A patch to cleanup warnings from Robert Gebis. +- Added ValueStr() to get the value of a node as a string. +- TiXmlText can now parse and output as CDATA +- Additional string improvement from James (z2895) +- Removed extraneous 'const', thanks David Aldrich +- First pass at switching to the "safe" stdlib functions. Many people have suggested and + pushed on this, but Warren Stevens put together the first proposal. +- TinyXml now will do EOL normalization before parsing, consistent with the W3C XML spec. +- Documents loaded with the UTF-8 BOM will now save with the UTF-8 BOM. Good suggestion + from 'instructor_' +- Ellers submitted his very popular tutorials, which have been added to the distribution. + +2.4.1 +- Fixed CDATA output formatting +- Fixed memory allocators in TinyString to work with overloaded new/delete + +2.4.2 +- solosnake pointed out that TIXML_LOG causes problems on an XBOX. The definition in the header + was superflous and was moved inside of DEBUG_PARSING + +2.4.3 +- Fixed a test bug that caused a crash in 'xmltest'. TinyXML was fine, but it isn't good + to ship with a broken test suite. +- Started converting some functions to not cast between std::string and const char* + quite as often. +- Added FILE* versions of the document loads - good suggestion from Wade Brainerd +- Empty documents might not always return the errors they should. [1398915] Thanks to igor v. +- Added some asserts for multiply adding a node, regardng bug [1391937] suggested by Paco Arjonilla. + +2.4.4 +- Bug find thanks to andre-gross found a memory leak that occured when a document failed to load. +- Bug find (and good analysis) by VirtualJim who found a case where attribute parsing + should be throwing an error and wasn't. +- Steve Hyatt suggested the QueryValueAttribute method, which is now implemented. +- DavidA identified a chunk of dead code. +- Andrew Baxter sent in some compiler warnings that were good clean up points. + +2.5 +- Added the Visit() API. Many thanks to both Andrew Ellerton and John-Philip for all their + work, code, suggestion, and just general pushing that it should be done. +- Removed existing streaming code and use TiXmlPrinter instead. +- [ tinyxml-Bugs-1527079 ] Compile error in tinystr.cpp fixed, thanks to Paul Suggs +- [ tinyxml-Bugs-1522890 ] SaveFile has no error checks fixed, thanks to Ivan Dobrokotov +- Ivan Dobrokotov also reported redundant memory allocation in the Attribute() method, which + upon investigation was a mess. The attribute should now be fixed for both const char* and + std::string, and the return types match the input parameters. +- Feature [ 1511105 ] Make TiXmlComment constructor accept a string / char*, implemented. + Thanks to Karl Itschen for the feedback. +- [ 1480108 ] Stream parsing fails when CDATA contains tags was found by Tobias Grimm, who also + submitted a test case and patch. A significant bug in CDATA streaming (operator>>) has now + been fixed. + +2.5.2 +- Lieven, and others, pointed out a missing const-cast that upset the Open Watcom compiler. + Should now be fixed. +- ErrorRow and ErrorCol should have been const, and weren't. Fixed thanks to Dmitry Polutov. + +2.5.3 +- zloe_zlo identified a missing string specialization for QueryValueAttribute() [ 1695429 ]. Worked + on this bug, but not sure how to fix it in a safe, cross-compiler way. +- increased warning level to 4 and turned on detect 64 bit portability issues for VC2005. + May address [ 1677737 ] VS2005: /Wp64 warnings +- grosheck identified several problems with the Document copy. Many thanks for [ 1660367 ] +- Nice catch, and suggested fix, be Gilad Novik on the Printer dropping entities. + "[ 1600650 ] Bug when printing xml text" is now fixed. +- A subtle fix from Nicos Gollan in the tinystring initializer: + [ 1581449 ] Fix initialiser of TiXmlString::nullrep_ +- Great catch, although there isn't a submitter for the bug. [ 1475201 ] TinyXML parses entities in comments. + Comments should not, in fact, parse entities. Fixed the code path and added tests. +- We were not catching all the returns from ftell. Thanks to Bernard for catching that. + +2.5.4 +- A TiXMLDocument can't be a sub-node. Block this from happening in the 'replace'. Thanks Noam. +- [ 1714831 ] TiXmlBase::location is not copied by copy-ctors, fix reported and suggested by Nicola Civran. +- Fixed possible memory overrun in the comment reading code - thanks gcarlton77 + +2.5.5 +- Alex van der Wal spotted incorrect types (lf) being used in print and scan. robertnestor pointed out some problems with the simple solution. Types updated. +- Johannes Hillert pointed out some bug typos. +- Christian Mueller identified inconsistent error handling with Attributes. +- olivier barthelemy also reported a problem with double truncation, also related to the %lf issue. +- zaelsius came up with a great (and simple) suggestion to fix QueryValueAttribute truncating strings. +- added some null pointer checks suggested by hansenk +- Sami Väisänen found a (rare) buffer overrun that could occur in parsing. +- vi tri filed a bug that led to a refactoring of the attribute setting mess (as well as adding a missing SetDoubleAttribute() ) +- removed TIXML_ERROR_OUT_OF_MEMORY. TinyXML does not systematically address OOO, and the notion it does is misleading. +- vanneto, keithmarshall, others all reported the warning from IsWhiteSpace() usage. Cleaned this up - many thanks to everyone who reported this one. +- tibur found a bug in end tag parsing + + + + diff --git a/src/external/tinyxml/echo.dsp b/src/external/tinyxml/echo.dsp new file mode 100644 index 0000000..d81db12 --- /dev/null +++ b/src/external/tinyxml/echo.dsp @@ -0,0 +1,113 @@ +# Microsoft Developer Studio Project File - Name="echo" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Console Application" 0x0103 + +CFG=echo - Win32 Debug +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "echo.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "echo.mak" CFG="echo - Win32 Debug" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "echo - Win32 Release" (based on "Win32 (x86) Console Application") +!MESSAGE "echo - Win32 Debug" (based on "Win32 (x86) Console Application") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +RSC=rc.exe + +!IF "$(CFG)" == "echo - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "echoRelease" +# PROP Intermediate_Dir "echoRelease" +# PROP Target_Dir "" +# ADD BASE CPP /nologo /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /c +# ADD CPP /nologo /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_CONSOLE" /D "_MBCS" /D "TIXML_USE_STL" /YX /FD /c +# ADD BASE RSC /l 0x409 /d "NDEBUG" +# ADD RSC /l 0x409 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /machine:I386 +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /machine:I386 + +!ELSEIF "$(CFG)" == "echo - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "echo___Win32_Debug" +# PROP BASE Intermediate_Dir "echo___Win32_Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "echoDebug" +# PROP Intermediate_Dir "echoDebug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_CONSOLE" /D "_MBCS" /YX /FD /GZ /c +# ADD CPP /nologo /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_CONSOLE" /D "_MBCS" /D "TIXML_USE_STL" /FR /YX /FD /GZ /c +# ADD BASE RSC /l 0x409 /d "_DEBUG" +# ADD RSC /l 0x409 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /pdbtype:sept +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:console /debug /machine:I386 /pdbtype:sept + +!ENDIF + +# Begin Target + +# Name "echo - Win32 Release" +# Name "echo - Win32 Debug" +# Begin Source File + +SOURCE=.\xmltester\bugtest.cpp +# End Source File +# Begin Source File + +SOURCE=.\tinystr.cpp +# End Source File +# Begin Source File + +SOURCE=.\tinystr.h +# End Source File +# Begin Source File + +SOURCE=.\tinyxml.cpp +# End Source File +# Begin Source File + +SOURCE=.\tinyxml.h +# End Source File +# Begin Source File + +SOURCE=.\tinyxmlerror.cpp +# End Source File +# Begin Source File + +SOURCE=.\tinyxmlparser.cpp +# End Source File +# End Target +# End Project diff --git a/src/external/tinyxml/module.mk b/src/external/tinyxml/module.mk new file mode 100644 index 0000000..6e42e3e --- /dev/null +++ b/src/external/tinyxml/module.mk @@ -0,0 +1,27 @@ +# This file is part of the OpenLB library +# +# Copyright (C) 2017 Markus Mohrhard +# E-mail contact: info@openlb.net +# The most recent release of OpenLB can be downloaded at +# <http://www.openlb.net/> +# +# This program is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License +# as published by the Free Software Foundation; either version 2 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public +# License along with this program; if not, write to the Free +# Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +# Boston, MA 02110-1301, USA. + +current_dir := $(dir $(word $(words $(MAKEFILE_LIST)),$(MAKEFILE_LIST))) + +include $(addsuffix /MakeHeader, $(current_dir)) + +LIB_OBJECTS += $(foreach file, $($(BUILDTYPE)), $(OBJDIR)/$(current_dir)$(file).o) diff --git a/src/external/tinyxml/readme.txt b/src/external/tinyxml/readme.txt new file mode 100644 index 0000000..89d9e8d --- /dev/null +++ b/src/external/tinyxml/readme.txt @@ -0,0 +1,530 @@ +/** @mainpage + +<h1> TinyXML </h1> + +TinyXML is a simple, small, C++ XML parser that can be easily +integrated into other programs. + +<h2> What it does. </h2> + +In brief, TinyXML parses an XML document, and builds from that a +Document Object Model (DOM) that can be read, modified, and saved. + +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. + +The best place for the complete, correct, and quite frankly hard to +read spec is at <a href="http://www.w3.org/TR/2004/REC-xml-20040204/"> +http://www.w3.org/TR/2004/REC-xml-20040204/</a>. An intro to XML +(that I really like) can be found at +<a href="http://skew.org/xml/tutorial/">http://skew.org/xml/tutorial</a>. + +There are different ways to access and interact with XML data. +TinyXML uses a Document Object Model (DOM), meaning the XML data is parsed +into a C++ objects that can be browsed and manipulated, and then +written to disk or another output stream. You can also construct an XML document +from scratch with C++ objects and write this to disk or another output +stream. + +TinyXML is designed to be easy and fast to learn. It is two headers +and four cpp files. Simply add these to your project and off you go. +There is an example file - xmltest.cpp - to get you started. + +TinyXML is released under the ZLib license, +so you can use it in open source or commercial code. The details +of the license are at the top of every source file. + +TinyXML attempts to be a flexible parser, but with truly correct and +compliant XML output. TinyXML should compile on any reasonably C++ +compliant system. It does not rely on exceptions or RTTI. It can be +compiled with or without STL support. TinyXML fully supports +the UTF-8 encoding, and the first 64k character entities. + + +<h2> What it doesn't do. </h2> + +TinyXML doesn't parse or use DTDs (Document Type Definitions) or XSLs +(eXtensible Stylesheet Language.) 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 often have a more +restrictive license. If you are working with browsers or have more +complete XML needs, TinyXML is not the parser for you. + +The following DTD syntax will not parse at this time in TinyXML: + +@verbatim + <!DOCTYPE Archiv [ + <!ELEMENT Comment (#PCDATA)> + ]> +@endverbatim + +because TinyXML sees this as a !DOCTYPE node with an illegally +embedded !ELEMENT node. This may be addressed in the future. + +<h2> Tutorials. </h2> + +For the impatient, here is a tutorial to get you going. A great way to get started, +but it is worth your time to read this (very short) manual completely. + +- @subpage tutorial0 + +<h2> Code Status. </h2> + +TinyXML is mature, tested code. It is very stable. If you find +bugs, please file a bug report on the sourceforge web site +(www.sourceforge.net/projects/tinyxml). We'll get them straightened +out as soon as possible. + +There are some areas of improvement; please check sourceforge if you are +interested in working on TinyXML. + +<h2> Related Projects </h2> + +TinyXML projects you may find useful! (Descriptions provided by the projects.) + +<ul> +<li> <b>TinyXPath</b> (http://tinyxpath.sourceforge.net). TinyXPath is a small footprint + XPath syntax decoder, written in C++.</li> +<li> <b>TinyXML++</b> (http://code.google.com/p/ticpp/). TinyXML++ is a completely new + interface to TinyXML that uses MANY of the C++ strengths. Templates, + exceptions, and much better error handling.</li> +</ul> + +<h2> Features </h2> + +<h3> Using STL </h3> + +TinyXML can be compiled to use or not use STL. When using STL, TinyXML +uses the std::string class, and fully supports std::istream, std::ostream, +operator<<, and operator>>. Many API methods have both 'const char*' and +'const std::string&' forms. + +When STL support is compiled out, no STL files are included whatsoever. All +the string classes are implemented by TinyXML itself. API methods +all use the 'const char*' form for input. + +Use the compile time #define: + + TIXML_USE_STL + +to compile one version or the other. This can be passed by the compiler, +or set as the first line of "tinyxml.h". + +Note: If compiling the test code in Linux, setting the environment +variable TINYXML_USE_STL=YES/NO will control STL compilation. In the +Windows project file, STL and non STL targets are provided. In your project, +It's probably easiest to add the line "#define TIXML_USE_STL" as the first +line of tinyxml.h. + +<h3> UTF-8 </h3> + +TinyXML supports UTF-8 allowing to manipulate XML files in any language. TinyXML +also supports "legacy mode" - the encoding used before UTF-8 support and +probably best described as "extended ascii". + +Normally, TinyXML will try to detect the correct encoding and use it. However, +by setting the value of TIXML_DEFAULT_ENCODING in the header file, TinyXML +can be forced to always use one encoding. + +TinyXML will assume Legacy Mode until one of the following occurs: +<ol> + <li> If the non-standard but common "UTF-8 lead bytes" (0xef 0xbb 0xbf) + begin the file or data stream, TinyXML will read it as UTF-8. </li> + <li> If the declaration tag is read, and it has an encoding="UTF-8", then + TinyXML will read it as UTF-8. </li> + <li> If the declaration tag is read, and it has no encoding specified, then TinyXML will + read it as UTF-8. </li> + <li> If the declaration tag is read, and it has an encoding="something else", then TinyXML + will read it as Legacy Mode. In legacy mode, TinyXML will work as it did before. It's + not clear what that mode does exactly, but old content should keep working.</li> + <li> Until one of the above criteria is met, TinyXML runs in Legacy Mode.</li> +</ol> + +What happens if the encoding is incorrectly set or detected? TinyXML will try +to read and pass through text seen as improperly encoded. You may get some strange results or +mangled characters. You may want to force TinyXML to the correct mode. + +You may force TinyXML to Legacy Mode by using LoadFile( TIXML_ENCODING_LEGACY ) or +LoadFile( filename, TIXML_ENCODING_LEGACY ). You may force it to use legacy mode all +the time by setting TIXML_DEFAULT_ENCODING = TIXML_ENCODING_LEGACY. Likewise, you may +force it to TIXML_ENCODING_UTF8 with the same technique. + +For English users, using English XML, UTF-8 is the same as low-ASCII. You +don't need to be aware of UTF-8 or change your code in any way. You can think +of UTF-8 as a "superset" of ASCII. + +UTF-8 is not a double byte format - but it is a standard encoding of Unicode! +TinyXML does not use or directly support wchar, TCHAR, or Microsoft's _UNICODE at this time. +It is common to see the term "Unicode" improperly refer to UTF-16, a wide byte encoding +of unicode. This is a source of confusion. + +For "high-ascii" languages - everything not English, pretty much - TinyXML can +handle all languages, at the same time, as long as the XML is encoded +in UTF-8. That can be a little tricky, older programs and operating systems +tend to use the "default" or "traditional" code page. Many apps (and almost all +modern ones) can output UTF-8, but older or stubborn (or just broken) ones +still output text in the default code page. + +For example, Japanese systems traditionally use SHIFT-JIS encoding. +Text encoded as SHIFT-JIS can not be read by TinyXML. +A good text editor can import SHIFT-JIS and then save as UTF-8. + +The <a href="http://skew.org/xml/tutorial/">Skew.org link</a> does a great +job covering the encoding issue. + +The test file "utf8test.xml" is an XML containing English, Spanish, Russian, +and Simplified Chinese. (Hopefully they are translated correctly). The file +"utf8test.gif" is a screen capture of the XML file, rendered in IE. Note that +if you don't have the correct fonts (Simplified Chinese or Russian) on your +system, you won't see output that matches the GIF file even if you can parse +it correctly. Also note that (at least on my Windows machine) console output +is in a Western code page, so that Print() or printf() cannot correctly display +the file. This is not a bug in TinyXML - just an OS issue. No data is lost or +destroyed by TinyXML. The console just doesn't render UTF-8. + + +<h3> Entities </h3> +TinyXML recognizes the pre-defined "character entities", meaning special +characters. Namely: + +@verbatim + & & + < < + > > + " " + ' ' +@endverbatim + +These are recognized when the XML document is read, and translated to there +UTF-8 equivalents. For instance, text with the XML of: + +@verbatim + Far & Away +@endverbatim + +will have the Value() of "Far & Away" when queried from the TiXmlText object, +and will be written back to the XML stream/file as an ampersand. Older versions +of TinyXML "preserved" character entities, but the newer versions will translate +them into characters. + +Additionally, any character can be specified by its Unicode code point: +The syntax " " or " " are both to the non-breaking space characher. + +<h3> Printing </h3> +TinyXML can print output in several different ways that all have strengths and limitations. + +- Print( FILE* ). Output to a std-C stream, which includes all C files as well as stdout. + - "Pretty prints", but you don't have control over printing options. + - The output is streamed directly to the FILE object, so there is no memory overhead + in the TinyXML code. + - used by Print() and SaveFile() + +- operator<<. Output to a c++ stream. + - Integrates with standart C++ iostreams. + - Outputs in "network printing" mode without line breaks. Good for network transmission + and moving XML between C++ objects, but hard for a human to read. + +- TiXmlPrinter. Output to a std::string or memory buffer. + - API is less conci |