lame-3.99.5.tar.gz

/** @mainpage <h1> TinyXml </h1> TinyXml is a simple, small, C++ XML parser that can be easily integrating into other programs. <h2> What it does. </h2> In brief, TinyXml parses an XML document, and builds from that a Document Object Model 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. 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. 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. 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. <h2> What it doesn't do. </h2> It doesn’t parse or use DTDs (Document Type Definitions) or XSL’s (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 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. <h2> Code Status. </h2> 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. There are some areas of improvement; please check sourceforge if you are interested in working on TinxXml. <h2> Changes between version 1 and 2 </h2> <h3> Entities </h3> TinyXml recognizes the pre-defined "entity references", meaning special characters. Namely: @verbatim &amp; & &lt; < &gt; > &quot; " &apos; ‘ @endverbatim These are recognized when the XML document is read, and translated to there ASCII equivalents. For instance, text with the XML of: @verbatim Far &amp; Away @endverbatim will have the Value() of "Far & Away" when queried from the TiXmlText object, but will be written back to the XML stream/file as an entitity. TiXml will ignore unknown entities and the @verbatim "&#x" @endverbatim entities, and leave them unprocessed. <h3> Streams </h3> TiXml has been modified to support both C (FILE) and C++ (operator <<,>>) streams. There are some differences that you may need to be aware of. C style output: - based on FILE* - the Print() and SaveFile() methods Generates formatted output, with plenty of white space, intended to be as human-readable as possible. They are very fast, and tolerant of ill formed XML documents. For example, an XML document that contains 2 root elements and 2 declarations, will print. C style input: - based on FILE* - the Parse() and LoadFile() methods A fast, tolerant read. Use whenever you don't need the C++ streams. C++ style ouput: - based on std::ostream - operator<< Generates condensed output, intended for network transmission rather than readability. Depending on your system's implementation of the ostream class, these may be somewhat slower. (Or may not.) Not tolerant of ill formed XML: a document should contain the correct one root element. Additional root level elements will not be streamed out. C++ style input: - based on std::istream - operator>> Reads XML from a stream, making it useful for network transmission. The tricky part is knowing when the XML document is complete, since there will almost certainly be other data in the stream. TinyXml will assume the XML data is complete after it reads the root element. Also not that operator>> is somewhat slower than Parse, due to both implementation of the STL and limitations of TinyXml. <h3> White space </h3> The world simply does not agree on whether white space should be kept, or condensed. For example, pretend the '_' is a space, and look at "Hello____world". HTML, and at least some XML parsers, will interpret this as "Hello_world". They condense white space. Some XML parsers do not, and will leave it as "Hello____world". (Remember to keep pretending the _ is a space.) It's an issue that hasn't been resolved to my satisfaction. TinyXml supports both motifs. Call TiXmlBase::SetCondenseWhiteSpace( bool ) to set the desired behavior. The default is to condense white space. If you change the default, you should call TiXmlBase::SetCondenseWhiteSpace( bool ) before making any calls to Parse XML data, and I don't recommend changing it after it has been set. <h2> Using and Installing </h2> To Compile and Run xmltest: 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. The Linux makefile is very generic and will probably run on other systems, but is only tested on Linux. You no longer need to run 'make depend'. The dependecies have been hard coded. To Use in an Application: 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. <h2> Where it may go. </h2> At this point, I'm focusing on tightening up remaining issues. Bug fixes (though comfortably rare) and minor interface corrections. There are some "it would be nice if..." items. I'll keep those posted as tasks on SourceForge. (www.sourceforge.net/projects/tinyxml) <h2> How TinyXml works. </h2> An example is probably the best way to go. Take: @verbatim <?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> @endverbatim It’s 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: @verbatim TiXmlDocument doc( "demo.xml" ); doc.LoadFile(); @endverbatim And it’s ready to go. Now let’s look at some lines and how they relate to the DOM. <?xml version="1.0" standalone=‘no’> The first line is a declaration, and gets turned into the TiXmlDeclaration class. It will be the first child of the document node. This is the only directive/special tag parsed by by TinyXml. Generally directive targs are stored in TiXmlUnknown so the commands won’t be lost when it is saved back to disk. <?-- Our to do list data --> A comment. Will become a TiXmlComment object. <ToDo> The ToDo tag defines a TiXmlElement object. This one does not have any attributes, but will contain 2 other elements, both of which are items. <Item priority="1"> Creates another TiXmlElement which is a child of the "ToDo" element. This element has 1 attribute, with the name ‘priority’ and the value ‘1’. Go to the A TiXmlText. This is a leaf node and cannot contain other nodes. It is a child of the ‘Item" Element. <bold> Another TiXmlElement, this one a child of the "Item" element. Etc. Look