TinyXML中文文档.docx

1、TinyXML中文文档TinyXML中文文档 六月 08TinyXML中文文档TinyXML No Comments »完整显示 1 2 3 4 5 6 7  译注：本文是TinyXML 2.5.2版本Document的中文文档，经原作者Lee Thomason同意由hansen翻译，如有误译或者错漏，欢迎指正。版权：版权归原作者所有，翻译文档版权归本人hansen所有，转载请注明出处。原文：TinyXml 文档2.5.2TinyXML TinyXML是一个简单小巧，可以很容易集成到其它程序中的C+ XML解析器。 它能做些什么简单地说，TinyXML解析一个XML文档并由

2、此生成一个可读可修改可保存的文档对象模型（DOM）。 XML的意思是“可扩展标记语言“（eXtensible Markup Language）。它允许你创建你自己的文档标记。在为浏览器标记文档方面HTML做得很好，然而XML允许你定义任何文档标记，比如可以为一个组织者应用程序定义一个描述“to do”列表的文档。 XML拥有一个结构化并且方便的格式，所有为存储应用程序数据而创建的随机文件格式都可以用XML代替，而这一切只需要一个解析器。 最全面正确的说明可以在http:/www.w3.org/TR/2004/REC-xml-20040204/找到

3、，但坦白地说，它很晦涩难懂。事实上我喜欢http:/skew.org/xml/tutorial上关于XML的介绍。 有不同的方法可以访问和与XML数据进行交互。TinyXML使用文档对象模型（DOM），这意味着XML数据被解析成一个可被浏览和操作的C+对象，然后它可以被写到磁盘或者另一个输出流中。你也可以把C+对象构造成一个XML文档然后把它写到磁盘或者另一个输出流中。 TinyXML被设计得容易快速上手。它只有两个头文件和四个cpp文件。只需要把它们简单地加到你的项目中就行了。有一个例子文件xmltest.cpp来引导你该怎么做。 TinyXML以Zlib许可来发布，所以你可以在开源或者商业

4、软件中使用它。许可证更具体的描述在每个源代码文件的顶部可以找到。 TinyXML在保证正确和恰当的XML输出的基础上尝试成为一个灵活的解析器。TinyXML可以在任何合理的C+适用系统上编译。它不依赖于异常或者运行时类型信息，有没有STL支持都可以编译。TinyXML完全支持UTF-8编码和前64k个字符实体（<i>译注：如果你不明白这句译文，可能你需要了解一下Unicode编码</i>）。 它无法做些什么TinyXML不解析不使用DTDs（文档类型定义）或者XSLs（可扩展样式表语言）。有其它解析器（到www.sourceforge.org搜索一下XML）具有更加全面

5、的特性，但它们也就更大，需要花更长的时间来建立你的项目，有更陡的学习曲线，而且经常有一个更严格的许可协议。如果你是用于浏览器或者有更复杂的XML需要，那么TinyXML不适合你。 下面的DTD语法在TinyXML里是不做解析的：  <!DOCTYPE Archiv <!ELEMENT Comment (#PCDATA)>>因为TinyXML把它看成是一个带着非法嵌入!ELEMENT结点的!DOCTYPE结点。或许这在将来会得到支持。 指南有耐性些，这是一份能很好地指导你怎么开始的指南，它（非常短小精悍）值得你花时间完整地读上一遍。 TinyXML指南 代码状况

6、TinyXML是成熟且经过测试的代码，非常健壮。如果你发现了漏洞，请提交漏洞报告到sourcefore网站上 （ 我们会尽快修正。 有些地方可以让你得到提高，如果你对TinyXML的工作感兴趣的话可以上sourceforge查找一下。 相关项目你也许会觉得TinyXML很有用！（简介由项目提供） TinyXPath (). TinyXPath是一个小巧的XPath语法译码器脚本，用C+写成。TinyXML+ ( TinyXML+是一个全新的TinyXML接口，使用了许多诸如模板，异常处理和更好的错误处理这些C+强项技术。 特性使用STL TinyXML可以被编译成使用或不使用STL。如果使用S

7、TL，TinyXML会使用std:string类，而且完全支持std:istream，std:ostream，operator<<和operator>>。许多API方法都有 ‘const char*’和’const std:string&’两个版本。 如果被编译成不使用STL，则任何STL都不会被包含。所有string类都由TinyXML它自己实现。所有API方法都只提供’const char*’传入参数。 使用运行时定义： TIXML_USE_STL 来编译成不同的版本。这可以作为参数传给

8、编译器或者在“tinyxml.h”文件的第一行进行设置。 注意：如果在Linux上编译测试代码，设置环境变量TINYXML_USE_STL=YES/NO可以控制STL的编译。而在Windows上，项目文件提供了STL和非STL两种目标文件。在你的项目中，在tinyxml.h的第一行添加#define TIXML_USE_STL应该是最简单的。 UTF-8 TinyXML支持UTF-8，所以可以处理任何语言的XML文件，而且TinyXML也支持“legacy模式”一种在支持UTF-8之前使用的编码方式，可能最好的解释是“扩展的ascii

9、”。 正常情况下，TinyXML会检测出正确的编码并使用它，然而，通过设置头文件中的TIXML_DEFAULT_ENCODING值，TinyXML可以被强制成总是使用某一种编码。 除非以下情况发生，否则TinyXML会默认使用Legacy模式： 如果文件或者数据流以非标准但普遍的UTF-8引导字节 (0xef 0xbb 0xbf)开始，TinyXML会以UTF-8的方式来读取它。如果包含有encoding=UTF-8的声明被读取，那么TinyXML会以UTF-8的方式来读取它。如果读取到没有指定编码方式的声明，那么TinyXML会以UTF-8的方式来读取它。如果包含有encodin

10、g=“其它编码”的声明被读取，那么TinyXML会以Legacy模式来读取它。在Legacy模式下，TinyXML会像以前那样工作，虽然已经不是很清楚这种模式是如何工作的了，但旧的内容还得保持能够运行。除了上面提到的情况，TinyXML会默认运行在Legacy模式下。 如果编码设置错误或者检测到错误会发生什么事呢？TinyXML会尝试跳过这些看似不正确的编码，你可能会得到一些奇怪的结果或者乱码，你可以强制TinyXML使用正确的编码模式。 通过使用LoadFile( TIXML_ENCODING_LEGACY )或者LoadFile( filename, TIXML_E

11、NCODING_LEGACY )， 你可以强制TinyXML使用Legacy模式。你也可以通过设置TIXML_DEFAULT_ENCODING = TIXML_ENCODING_LEGACY来强制一直使用Legacy模式。同样的，你也可以通过相同的方法来强制设置成TIXML_ENCODING_UTF8。 对于使用英文XML的英语用户来说，UTF-8跟low-ASCII是一样的。你不需要知道UTF-8或者一点也不需要修改你的代码。你可以把UTF-8当作是ASCII的超集。 UTF-8并不是一种双字节格式，但它是一种标准的Unicode编码！TinyXML当前不使用或者直接支持wchar，TCHA

12、R，或者微软的_UNICODE。Unicode这个术语被普遍地认为指的是UTF-16（一种unicode的宽字节编码）是不适当的，这是混淆的来源。 对于“high-ascii”语言来说几乎所有非英语语言，只要XML被编码成UTF-8， TinyXML就能够处理。说起来可能有点微妙，比较旧的程序和操作系统趋向于使用“默认”或者“传统”的编码方式。许多应用程序（和几乎所有现在的应用程序）都能够输出UTF-8，但是那些比较旧或者难处理的（或者干脆不能使用的）系统还是只能以默认编码来输出文本。 比如说，日本的系统传统上使用SHIF

13、T-JIS编码，这种情况下TinyXML就无法读取了。但是一个好的文本编辑器可以导入SHIFT-JIS的文本然后保存成UTF-8编码格式的。 Skew.org link上关于转换编码的话题做得很好。 测试文件“utf8test.xml”包含了英文、西班牙文、俄文和简体中文（希望它们都能够被正确地转化）。“utf8test.gif”文件是从IE上截取的XML文件快照。请注意如果你的系统上没有正确的字体（简体中文或者俄文），那么即使你正确地解析了也看不到与GIF文件上一样的输出。同时要注意在一个西方编码的控制台上（至少我的Windows机器是这样），

14、Print()或者printf()也无法正确地显示这个文件，这不关TinyXML的事这只是操作系统的问题。TinyXML没有丢掉或者损坏数据，只是控制台无法显示UTF-8而已。 实体TinyXML认得预定义的特殊“字符实体”，即：  &amp; &&lt; <&gt; >&quot; &apos; ‘ 这些在XML文档读取时都会被辨认出来，并会被转化成等价的UTF-8字符。比如下面的XML文本：  Far &amp; Away 从TiXmlText 对象查询出来时会变成F

15、ar & Away这样的值，而写回XML流/文件时会以“&amp;”的方式写回。老版本的TinyXML“保留”了字符实体，而在新版本中它们会被转化成字符串。 另外，所有字符都可以用它的Unicode编码数字来指定，  和 都表示不可分的空格字符。 打印TinyXML有几种不同的方式来打印输出，当然它们各有各的优缺点。 Print( FILE* )：输出到一个标准C流中，包括所有的C文件和标准输出。相当漂亮的打印, 但你没法控制打印选项。输出数据直接写到FILE对象中，所以TinyXML代码没有内存负担。被Pri

16、nt()和SaveFile()调用。  operator<<：输出到一个c+流中。与C+ iostreams集成在一起。在network printing模式下输出没有换行符，这对于网络传输和C+对象之间的XML交换有好处，但人很难阅读。 TiXmlPrinter：输出到一个std:string或者内存缓冲区中。API还不是很简练。将来会增加打印选项。在将来的版本中可能有些细微的变化，因为它会被改进和扩展。 流设置了TIXML_USE_STL，TinyXML就能支持C+流（operator <<，>>）和C（FILE*）流。但它们之间有些差异你需要

17、知道： C风格输出： 基于FILE*用Print()和SaveFile()方法 生成具有很多空格的格式化过的输出，这是为了尽可能让人看得明白。它们非常快，而且能够容忍XML文档中的格式错误。例如一个XML文档包含两个根元素和两个声明仍然能被打印出来。 C风格输入：基于FILE*用Parse()和LoadFile()方法 速度快，容错性好。当你不需要C+流时就可以使用它。 C+风格输出： 基于std:ostreamoperator<< 生成压缩过的输出，目的是为了便于网络传输而不是为了可读性。它可能有些慢（可能不会），这主要跟你系统上ostream类的实现有关。无法容忍格式错误的XM

18、L：此文档只能包含一个根元素。另外根级别的元素无法以流形式输出。 C+风格输入： 基于std:istreamoperator>> 从流中读取XML使其可用于网络传输。通过些小技巧，它知道当XML文档读取完毕时，流后面的就一定是其它数据了。TinyXML总假定当它读取到根结点后XML数据就结束了。换句话说，那些具有不止一个根元素的文档是无法被正确读取的。另外还要注意由于STL的实现和TinyXML的限制，operator>>会比Parse慢一些。 空格对是保留还是压缩空格这一问题人们还没达成共识。举个例子，假设‘_’代表一个空格，对于Hello_w

19、orld，HTML和某些XML解析器会解释成Hello_world，它们压缩掉了一些空格。而有些XML解析器却不会这样，它们会保留空格，于是就是“Hello_world”（记住_表示一个空格）。其它的还建议_Hello_world_应该变成Hello_world 。 这是一个解决得不能让我满意的问题。TinyXML一开始就两种方式都支持。调用TiXmlBase:SetCondenseWhiteSpace( bool )来设置你想要的结果，默认是压缩掉多余的空格。 如果想要改变默认行为，你应该在解析任何XML数据之前调用TiXmlBase:SetCondenseWhite

20、Space( bool ) ，而且我不建议设置之后再去改动它。 句柄想要健壮地读取一个XML文档，检查方法调用后的返回值是否为null是很重要的。一种安全的检错实现可能会产生像这样的代码：  TiXmlElement* root = document.FirstChildElement( Document );if ( root ) TiXmlElement* element = root->FirstChildElement( Element ); if ( element ) TiXmlElement* child = element->FirstChildEleme

21、nt( Child ); if ( child ) TiXmlElement* child2 = child->NextSiblingElement( Child ); if ( child2 ) / Finally do something useful. 用句柄的话就不会这么冗长了，使用TiXmlHandle类，前面的代码就会变成这样：  TiXmlHandle docHandle( &document );TiXmlElement* child2 = docHandle.FirstChild( Document ).FirstChild( Element ).Ch

22、ild( Child, 1 ).ToElement();if ( child2 ) / do something useful 这处理起来容易多了。 查阅TiXmlHandle可以得到更多的信息。 行列追踪对于某些应用程序来说，能够追踪节点和属性在它们源文件中的原始位置是很重要的。另外，知道解析错误在源文件中的发生位置可以节省大量时间。 TinyXML能够追踪所有结点和属性在文本文件中的行列原始位置。TiXmlBase:Row() 和 TiXmlBase:Column() 方法返回结点在源文件中的原始位置。正确的制表符号可以经由TiXmlDocument:SetTabSize() 来配置。 使

23、用与安装编译与运行xmltest： 提供了一个Linux Makefile和一个Windows Visual C+ .dsw 文件。只需要简单地编译和运行，它就会在你的磁盘上生成demotest.xml文件并在屏幕上输出。它还尝试用不同的方法遍历DOM并打印出结点数。 那个Linux makefile很通用，可以运行在很多系统上它目前已经在mingw和MacOSX上测试过。你不需要运行 ‘make depend’，因为那些依赖关系已经硬编码在文件里了。 用于VC6的Windows项目文件tinyxml： tinyxml 库，非STLtinyxmlSTL： tinyxml

24、 库，STLtinyXmlTest： 用于测试的应用程序，非STLtinyXmlTestSTL： 用于测试的应用程序，STL Makefile在makefile的顶部你可以设置： PROFILE，DEBUG，和TINYXML_USE_STL。makefile里有具体描述。 在tinyxml目录输入“make clean”然后“make”，就可以生成可执行的“xmltest”文件。 在某一应用程序中使用：把tinyxml.cpp，tinyxml.h， tinyxmlerror.cpp， tinyxmlparser.cpp，

25、tinystr.cpp， 和 tinystr.h 添加到你的项目和makefile中。就这么简单，它可以在任何合理的C+适用系统上编译。不需要为TinyXML打开异常或者运行时类型信息支持。 TinyXML怎么工作举个例子可能是最好的办法，理解一下：  <?xml version=1.0 standalone=no><!– Our to do list data –><ToDo><Item priority=1> Go to the <bold>Toy store!</bold></

26、Item><Item priority=2> Do bills</Item></ToDo> 它称不上是一个To Do列表，但它已经足够了。像下面这样读取并解析这个文件（叫“demo.xml”）你就能创建一个文档： TiXmlDocument doc( demo.xml );doc.LoadFile();现在它准备好了，让我们看看其中的某些行和它们怎么与DOM联系起来。  <?xml version=1.0 standalone=no> 第一行是一个声明，它会转化成TiXmlDeclaration 类，同时也

27、是文档结点的第一个子结点。 这是TinyXML唯一能够解析的指令/特殊标签。一般来说指令标签会保存在TiXmlUnknown 以保证在它保存回磁盘时不会丢失这些命令。  <!– Our to do list data –> 这是一个注释，会成为一个TiXmlComment对象。  <ToDo> ToDo标签定义了一个TiXmlElement 对象。它没有任何属性，但包含另外的两个元素。  <Item priority=1> 生成另一个TiXmlElement对象，它是“ToDo”元

28、素的子结点。此元素有一个名为“priority”和值为“1”的属性。  Go to the TiXmlText ，这是一个叶子结点，它不能再包含其它结点，是Item TiXmlElement的子结点。  <bold> 另一个TiXmlElement, 这也是“Item”元素的子结点。 等等 最后，看看整个对象树：  TiXmlDocument demo.xmlTiXmlDeclaration version=’1.0′ standalone=noTiXmlC

29、omment Our to do list dataTiXmlElement ToDoTiXmlElement Item Attribtutes: priority = 1TiXmlText Go to the TiXmlElement boldTiXmlText Toy store!TiXmlElement Item Attributes: priority=2TiXmlText Do bills  文档本文档由Doxygen使用‘dox’配置文件生成。 许可证TinyXML基于zlib许可证来发布： 本软件按“现状”提供（即现在你看

30、到的样子），不做任何明确或隐晦的保证。由使用此软件所引起的任何损失都决不可能由作者承担。 只要遵循下面的限制，就允许任何人把这软件用于任何目的，包括商业软件，也允许修改它并自由地重新发布： 1. 决不能虚报软件的来源；你决不能声称是你是软件的第一作者。如果你在某个产品中使用了这个软件，那么在产品文档中加入一个致谢辞我们会很感激，但这并非必要。 2. 修改了源版本就应该清楚地标记出来，决不能虚报说这是原始软件。 3. 本通告不能从源发布版本中移除或做修改。 参考书目万维网联盟是定制XML的权威标准机构，它的网页上有大量的信息。 权威指南：http:/www.w3.org/TR/2004/REC-xml-20040204/ 我还要推荐由OReilly出版由Robert Eckstein撰写的XML Pocket Reference……这本书囊括了入门所需要的一切。 捐助者，联系人，还有简史非常感谢给我们建议，漏洞报告，意见和鼓励的所有人。它们很有用，并且使得这个项目变得有趣。特别感谢那些捐助者，是他们让这个网站页面生机勃勃。 有很多人发来漏洞报告和意见，与其在这里一一列出来不如我们试着把它们写到“changes.txt”文件中加以赞扬。 TinyXML的原作者是Le