readme.txt

xml 简单解析器

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.) Others suggest that __Hello___world__ should become
Hello___world.

It's an issue that hasn't been resolved to my satisfaction. TinyXml supports the
first 2 approaches. 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.


<h3> Handles </h3>

Where browsing an XML document in a robust way, it is important to check
for null returns from method calls. An error safe implementation can
generate a lot of code like:

@verbatim
TiXmlElement* root = document.FirstChildElement( "Document" );
if ( root )
{
	TiXmlElement* element = root->FirstChildElement( "Element" );
	if ( element )
	{
		TiXmlElement* child = element->FirstChildElement( "Child" );
		if ( child )
		{
			TiXmlElement* child2 = child->NextSiblingElement( "Child" );
			if ( child2 )
			{
				// Finally do something useful.
@endverbatim

Handles have been introduced to clean this up. Using the TiXmlHandle class,
the previous code reduces to:

@verbatim
TiXmlHandle docHandle( &document );
TiXmlElement* child2 = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", 1 ).Element();
if ( child2 )
{
	// do something useful
@endverbatim

Which is much easier to deal with. See TiXmlHandle for more information.


<h3> Row and Column tracking </h3>
Being able to track nodes and attributes back to their origin location
in source files can be very important for some applications. Additionally,
knowing where parsing errors occured in the original source can be very
time saving.

TinyXml can tracks the row and column origin of all nodes and attributes
in a text file. The TiXmlBase::Row() and TiXmlBase::Column() methods return
the origin of the node in the source text. The correct tabs can be 
configured in TiXmlDocument::SetTabSize().


<h2> Using and Installing </h2>

To Compile and Run xmltest:

A Linux Makefile and a Windows Visual C++ .dsw 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.

<h3>Windows project file for VC6</h3>
<ul>
<li>tinyxml:		tinyxml library, non-STL </li>
<li>tinyxmlSTL:		tinyxml library, STL </li>
<li>tinyXmlTest:	test app, non-STL </li>
<li>tinyXmlTestSTL: test app, STL </li>
</ul>

<h3>Linux Make file</h3>
At the top of the makefile you can set:

PROFILE, DEBUG, and TINYXML_USE_STL. Details (such that they are) are in
the makefile.

In the tinyxml directory, type "make clean" then "make". The executable
file 'xmltest' will be created.



<h3>To Use in an Application:</h3>

Add tinyxml.cpp, tinyxml.h, tinyxmlerror.cpp, tinyxmlparser.cpp, tinystr.cpp, and tinystr.h 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> 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

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:
@verbatim
	TiXmlDocument doc( "demo.xml" );
	doc.LoadFile();
@endverbatim

And its ready to go. Now lets look at some lines and how they 
relate to the DOM.

@verbatim
<?xml version="1.0" standalone=no>
@endverbatim

	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 wont be lost when it is saved back to disk.

@verbatim
<!-- Our to do list data -->
@endverbatim

	A comment. Will become a TiXmlComment object.

@verbatim
<ToDo>
@endverbatim

	The "ToDo" tag defines a TiXmlElement object. This one does not have 
	any attributes, but does contain 2 other elements.

@verbatim
<Item priority="1"> 
@endverbatim

	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" TiXmlElement.

@verbatim
<bold>
@endverbatim

	
	Another TiXmlElement, this one a child of the "Item" element.

Etc.

Looking at the entire object tree, you end up with:
@verbatim
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			"Do bills"
@endverbatim

<h2> Documentation </h2>

The documentation is build with Doxygen, using the 'dox' 
configuration file.

<h2> License </h2>

TinyXml is released under the zlib license:

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.

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:

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.

2. Altered source versions must be plainly marked as such, and 
must not be misrepresented as being the original software.

3. This notice may not be removed or altered from any source 
distribution.

<h2> References  </h2>

The World Wide Web Consortium is the definitive standard body for 
XML, and there web pages contain huge amounts of information. 

The definitive spec: <a href="http://www.w3.org/TR/2004/REC-xml-20040204/">
http://www.w3.org/TR/2004/REC-xml-20040204/</a>

I also recommend "XML Pocket Reference" by Robert Eckstein and published by 
OReilly...the book that got the whole thing started.

<h2> Contributors, Contacts, and a Brief History </h2>

Thanks very much to everyone who sends suggestions, bugs, ideas, and 
encouragement. It all helps, and makes this project fun. A special thanks
to the contributors on the web pages that keep it lively.

So many people have sent in bugs and ideas, that rather than list here 
we try to give credit due in the "changes.txt" file.

TinyXml was originally written be Lee Thomason. (Often the "I" still
in the documenation.) Lee reviews changes and releases new versions,
with the help of Yves Berquin and the tinyXml community.

We appreciate your suggestions, and would love to know if you 
use TinyXml. Hopefully you will enjoy it and find it useful. 
Please post questions, comments, file bugs, or contact us at:

www.sourceforge.net/projects/tinyxml

Lee Thomason,
Yves Berquin
*/