【VC++开源代码栏目提醒】:文章导读:在新的一年中,各位网友都进入紧张的学习或是工作阶段。
网学会员整理了VC++开源代码-TinyXML2.5.2中文文档 - 编程语言的相关内容供大家参考,祝大家在新的一年里工作和学习顺利!
TinyXML2.5.2 中文文档译注:本文是 TinyXML 2.5.2 版本 Document 的中文文档,经原作者 Lee Thomason 同意由 hansen 翻译,如有误译或者错漏,欢迎指正。
版权:
版权归原作者所有,翻译文档版权归本人 hansen 所有,转载请注明出处。
原文:http://www.grinninglizard.com/tinyxmldocs/index.html TinyXml 文档 2.5.2 TinyXMLTinyXML 是一个简单小巧,可以很容易集成到其它程序中的 C XML 解析器。
它能做些什么简单地说,TinyXML 解析一个 XML 文档并由此生成一个可读可修改可保存的文档对象模型(DOM)。
XML 的意思是“可扩展标记语言“(eXtensible Markup Language)。
它允许你创建你自己的文档标记。
在为浏览器标记文档方面 HTML 做得很好,然而 XML 允许你定义任何文档标记,比如可以为一个组织者应用程序定义一个描述“to do”列表的文档。
XML 拥有一个结构化并且方便的格式,所有为存储应用程序数据而创建的随机文件格式都可以用 XML 代替,而这一切只需要一个解析器。
最全面正确的说明可以在 http://www.w3.org/TR/2004/REC-xml-20040204/找到,但坦白地说,它很晦涩难懂。
事实上我喜欢 http://skew.org/xml/tutorial 上关于 XML 的介绍。
有不同的方法可以访问和与 XML 数据进行交互。
TinyXML 使用
文档对象模型(DOM),这意味着 XML数据被解析成一个可被浏览和操作的 C对象,然后它可以被写到磁盘或者另一个输出流中。
你也可以把C对象构造成一个 XML
文档然后把它写到磁盘或者另一个输出流中。
TinyXML 被
设计得容易快速上手。
它只有两个头文件和四个 cpp 文件。
只需要把它们简单地加到你的项目中就行了。
有一个例子文件——xmltest.cpp 来引导你该怎么做。
TinyXML 以 Zlib 许可来发布,所以你可以在
开源或者商业软件中使用它。
许可证更具体的描述在每个源代 码文件的顶部可以找到。
TinyXML 在保证正确和恰当的 XML 输出的基础上尝试成为一个灵活的解析器。
TinyXML 可以在任何合理 的 C适用系统上编译。
它不依赖于异常或者运行时类型信息,有没有 STL 支持都可以编译。
TinyXML 完全支持 UTF-8 编码和前 64k 个字符实体(译注: 可能你需要了解一下 Unicode 如果你不明白这句译文, 编码)。
它无法做些什么 TinyXML 不解析不使用 DTDs(文档类型定义)或者 XSLs(可扩展样式表语言)。
有其它解析器(到 www.sourceforge.org 搜索一下 XML)具有更加全面的特性,但它们也就更大,需要花更长的时间来建立 你的项目,有更陡的
学习曲线,而且经常有一个更严格的许可协议。
如果你是用于浏览器或者有更复杂的 XML 需要,那么 TinyXML 不适合你。
下面的 DTD 语法在 TinyXML 里是不做解析的: 因为 TinyXML 把它看成是一个带着非法嵌入ELEMENT 结点的DOCTYPE 结点。
或许这在将来会得到支 持。
指南 有耐性些,这是一份能很好地指导你怎么开始的指南,它(非常短小精悍)值得你花时间完整地读上一遍。
TinyXML 指南
代码状况 TinyXML 是成熟且经过测试的
代码,非常健壮。
如果你发现了漏洞,请提交漏洞报告到 sourcefore 网站上 (www.sourceforge.net/projects/tinyxml)。
我们会尽快修正。
有些地方可以让你得到提高,如果你对 TinyXML 的工作感兴趣的话可以上 sourceforge 查找一下。
相关项目 你也许会觉得 TinyXML 很有用!(简介由项目提供) TinyXPath http://tinyxpath.sourceforge.net. TinyXPath 是一个小巧的 XPath 语法译码器脚本, 用 C写成。
TinyXML http://code.google.com/p/ticpp/. TinyXML是一个全新的 TinyXML 接口,使用了 许多诸如模板,异常处理和更好的错误处理这些 C强项技术。
特性 使用 STL TinyXML 可以被编译成使用或不使用 STL。
如果使用 STL,TinyXML 会使用 std::string 类,而且完全支持 std::istream,std::ostream,operator。
许多 API 方法都有 ‘const char’和’const std::string’ 两个版本。
如果被编译成不使用 STL,则任何 STL 都不会被包含。
所有 string 类都由 TinyXML 它自己实现。
所有 API 方法都只提供’const char’传入参数。
使用运行时定义: TIXML_USE_STL 来编译成不同的版本。
这可以作为参数传给编译器或者在“tinyxml.h”文件的第一行进行设置。
注意:如果在 Linux 上编译测试
代码,设置环境变量 TINYXML_USE_STLYES/NO 可以控制 STL 的编译。
而在 Windows 上,项目文件提供了 STL 和非 STL 两种目标文件。
在你的项目中,在 tinyxml.h 的第一行 添加define TIXML_USE_STL应该是最简单的。
UTF-8 TinyXML 支持 UTF-8,所以可以处理任何语言的 XML 文件,而且 TinyXML 也支持“legacy 模式”——一种 在支持 UTF-8 之前使用的编码方式,可能最好的解释是“扩展的 ascii”。
正常情况下,TinyXML 会检测出正确的编码并使用它,然而,通过设置头文件中的 TIXML_DEFAULT_ENCODING 值,TinyXML 可以被强制成总是使用某一种编码。
除非以下情况发生,否则 TinyXML 会默认使用 Legacy 模式:1. 如果文件或者数据流以非标准但普遍的UTF-8 引导字节 0xef 0xbb 0xbf开始,TinyXML 会以 UTF-8 的方式来读取它。
2. 如果包含有 encodingUTF-8的声明被读取,那么 TinyXML 会以 UTF-8 的方式来读取它。
3. 如果读取到没有指定编码方式的声明,那么 TinyXML 会以 UTF-8 的方式来读取它。
4. 如果包含有 encoding“其它编码”的声明被读取,那么 TinyXML 会以 Legacy 模式来读取它。
在 Legacy 模式下,TinyXML 会像以前那样
工作,虽然已经不是很清楚这种模式是如何工作的了,但旧的内 容还得保持能够运行。
5. 除了上面提到的情况,TinyXML 会默认运行在 Legacy 模式下。
如果编码设置错误或者检测到错误会发生什么事呢?TinyXML 会尝试跳过这些看似不正确的编码,你可能 会得到一些奇怪的结果或者乱码,你可以强制 TinyXML 使用正确的编码模式。
通过使用 LoadFile TIXML_ENCODING_LEGACY 或者 LoadFile filename TIXML_ENCODING_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,TCHAR,或者微软的_UNICODE。
Unicode这个术语被普遍地认为指的是 UTF-16(一种 unicode 的宽字节编码)是不适当的,这是混淆的来源。
对于“high-ascii”语言来说——几乎所有非英语语言,只要 XML 被编码成 UTF-8, TinyXML 就能够处理。
说起来可能有点微妙,比较旧的程序和操作系统趋向于使用“默认”或者“传统”的编码方式。
许多应用程序(和几乎所有现在的应用
程序)都能够输出 UTF-8,但是那些比较旧或者难处理的(或者干脆不能使用的)系统还是只能以默认编码来输出文本。
比如说,日本的系统传统上使用 SHIFT-JIS 编码,这种情况下 TinyXML 就无法读取了。
但是一个好的文本编辑器可以导入 SHIFT-JIS 的文本然后保存成 UTF-8 编码格式的。
Skew.org link 上关于转换编码的话题做得很好。
测试文件“utf8test.xml”包含了英文、西班牙文、俄文和简体中文(希望它们都能够被正确地转化)。
“utf8test.gif”文件是从 IE 上截取的 XML 文件快照。
请注意如果你的
系统上没有正确的字体(简体中文或者俄文),那么即使你正确地解析了也看不到与 GIF 文件上一样的输出。
同时要注意在一个西方编码的控制台上(至少我的 Windows 机器是这样),Print或者 printf也无法正确地显示这个文件,这不关 TinyXML的事——这只是操作系统的问题。
TinyXML 没有丢掉或者损坏数据,只是控制台无法显示 UTF-8 而已。
实体TinyXML 认得预定义的特殊“字符实体”,即:amp lt gt quot apos ‘这些在 XML 文档读取时都会被辨认出来,并会被转化成等价的 UTF-8 字符。
比如下面的 XML 文本:Far amp Away从 TiXmlText 对象
查询出来时会变成Far Away这样的值,而写回 XML 流/文件时会以“amp”的方式写回。
老版本的 TinyXML“保留”了字符实体,而在新版本中它们会被转化成字符串。
另外,所有字符都可以用它的 Unicode 编码数字来指定, xA0和160都表示不可分的空格字符。
打印 TinyXML 有几种不同的方式来打印输出,当然它们各有各的优缺点。
Print FILE :输出到一个标准 C 流中,包括所有的 C 文件和标准输出。
o 相当漂亮的打印 但你没法控制打印选项。
o 输出数据直接写到 FILE 对象中,所以 TinyXML
代码没有内存负担。
o 被 Print和 SaveFile调用。
operator会比 Parse 慢一些。
空格 对是保留还是压缩空格这一问题人们还没达成共识。
举个例子,假设‘_’代表一个空格,对于 Hello____world,
HTML 和某些 XML 解析器会解释成Hello_world,它们
压缩掉了一些空格。
而有些 XML 解析器却不会这样,它们会保留空格,于是就是“Hello____world”(记住_表示一个空格)。
其它的还建议 __Hello___world__应该变成 Hello___world 。
这是一个解决得不能让我满意的
问题。
TinyXML 一开始就两种方式都支持。
调用 TiXmlBase::SetCondenseWhiteSpace bool 来设置你想要的结果,默认是压缩掉多余的空格。
如果想要改变默认行为,你应该在解析任何 XML 数据之前调用 TiXmlBase::SetCondenseWhiteSpace bool ,而且我不建议设置之后再去改动它。
句柄想要健壮地读取一个 XML 文档,检查方法调用后的返回值是否为 null 是很重要的。
一种安全的检错实现可能会产生像这样的
代码: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.用句柄的话就不会这么冗长了,使用 TiXmlHandle 类,前面的
代码就会变成这样:TiXmlHandle docHandle document TiXmlElement child2 docHandle.FirstChild Document .FirstChild Element .Child Child 1 .ToElementif child2 // do something useful这处理起来容易多了。
查阅 TiXmlHandle 可以得到更多的信息。
行列追踪 对于某些应用程序来说,能够追踪节点和属性在它们源文件中的原始位置是很重要的。
另外,知道解析错 误在源文件中的发生位置可以节省大量时间。
TinyXML 能够追踪所有结点和属性在文本文件中的行列原始位置。
TiXmlBase::Row 和 TiXmlBase::Column 方法返回结点在源文件中的原始位置。
正确的制表符号可以经由 TiXmlDocument::SetTabSize 来配置。
使用与安装 编译与运行 xmltest: 提供了一个 Linux Makefile 和一个 Windows Visual C .dsw 文件。
只需要简单地编译和运行,它就会在 你的磁盘上生成 demotest.xml 文件并在屏幕上输出。
它还尝试用不同的方法遍历 DOM 并打印出结点数。
那个 Linux makefile 很通用,可以运行在很多系统上——它目前已经在 mingw 和 MacOSX 上测试过。
你 不需要运行 ‘make depend’,因为那些依赖关系已经硬编码在文件里了。
用于
VC6 的 Windows 项目文件 tinyxml: tinyxml 库,非 STL tiny
xmlSTL: tinyxml 库,STL tinyXmlTest: 用于测试的应用程序,非 STL tinyXmlTestSTL: 用于测试的应用程序,STL Makefile 在 makefile 的顶部你可以设置: PROFILE,DEBUG,和 TINYXML_USE_STL。
makefile 里有具体描述。
在 tinyxml 目录输入“make clean”然后“make”,就可以生成可执行的“xmltest”文件。
在某一应用程序中使用:把 tinyxml.cpp,tinyxml.h, tinyxmlerror.cpp, tinyxmlparser.cpp, tinystr.cpp, 和 tinystr.h 添加到你的项目和 makefile 中。
就这么简单,它可以在任何合理的 C适用系统上编译。
不需要为 TinyXML 打开异常或者运行时类型信息支持。
TinyXML 怎么工作举个例子可能是最好的办法,理解一下: Go to the Toy store Do bills它称不上是一个 To Do
列表,但它已经足够了。
像下面这样读取并解析这个文件(叫“demo.xml”)你就能创建一个文档:TiXmlDocument doc demo.xml doc.LoadFile现在它准备好了,让我们看看其中的某些行和它们怎么与 DOM 联系起来。
第一行是一个声明,它会转化成 TiXmlDeclaration 类,同时也是文档结点的第一个子结点。
这是 TinyXML 唯一能够解析的指令/特殊标签。
一般来说指令标签会保存在 TiXmlUnknown 以保证在它保存回磁盘时不会丢失这些命令。
这是一个注释,会成为一个 TiXmlComment 对象。
ToDo标签定义了一个 TiXmlElement 对象。
它没有任何属性,但包含另外的两个元素。
生成另一个 TiXmlElement 对象,它是“ToDo”元素的子结点。
此元素有一个名为“priority”和值为“1”的属性。
Go to theTiXmlText ,这是一个叶子结点,它不能再包含其它结点,是Item TiXmlElement 的子结点。
另一个 TiXmlElement 这也是“Item”元素的子结点。
等等最后,看看整个对象树:TiXmlDocument demo.xmlTiXmlDeclaration version’1.0′ standalonenoTiXmlComment Our to do list dataTiXmlElement ToDoTiXmlElement Item Attribtutes: priority 1TiXmlText Go to the TiXmlElement boldTiXmlText Toy storeTiXmlElement Item Attributes: priority2TiXmlText Do bills文档本文档由 Doxygen 使用‘dox’配置文件生成。
许可证TinyXML 基于 zlib 许可证来发布:本软件按“现状”提供(即现在你看到的样子),不做任何明确或隐晦的保证。
由使用此软件所引起的任何损失都决不可能由作者承担。
只要遵循下面的限制,就允许任何人把这软件用于任何目的,包括商业
软件,也允许修改它并自由地重新发布:1. 决不能虚报软件的来源;你决不能声称是你是软件的第一作者。
如果你在某个产品中使用了这个软件,那么在产品文档中加入一个致谢辞我们会很感激,但这并非必要。
2. 修改了源版本就应该清楚地标记出来,决不能虚报说这是原始软件。
3. 本通告不能从源发布版本中移除或做修改。
参考书目万维网联盟是定制 XML 的权威标准机构,它的网页上有大量的信息。
权威指南:http://www.w3.org/TR/2004/REC-xml-20040204/我还要推荐由 OReilly 出版由 Robert Eckstein 撰写的XML Pocket Reference……这本书囊括了入门所需要的一切。
捐助者,联系人,还有简史非常感谢给我们建议,漏洞报告,意见和鼓励的所有人。
它们很有用,并且使得这个项目变得有趣。
特别感谢那些捐助者,是他们让这个网站页面生机勃勃。
有很多人发来漏洞
报告和意见,与其在这里一一列出来不如我们试着把它们写到“changes.txt”文件中加以赞扬。
TinyXML 的原作者是 Lee Thomason文档中还经常出现“我”这个词 。
Yves Berquin, 在 Andrew Ellerton,和 tinyXml 社区的帮助下,Lee 查阅修改和发布新版本。
我们会很感激你的建议,还有我们想知道你是否在使用 TinyXML。
希望你喜欢它并觉得它很有用。
请邮寄问题,评论,漏洞报告给我们,或者你也可登录网站与我们取得联系:www.sourceforge.net/projects/tinyxmlLee Thomason, Yves Berquin, Andrew Ellerton关于 TinyXML 文档的翻译翻译这份文档是因为前段时间做项目时需要用到 XML 解析,在网上找了不少这方面的东西,Xerces C无疑是最强大的,但对我来说 Xerces 实在太庞大了,我只需要最基本的 XML 解析就够了。
最后发现了TinyXML,这家伙正是我需要的,够简单够小巧,而且跨平台,要知道跨平台对于 C/C简直是一场恶梦,别说 Unix 与 Windows 之间的跨平台,就连 Linux,HP,AIX 和 Solaris 之间的跨平台就足够让我头大了,这也是为什么我程序写到 90时换用 JAVA 写的原因之一。
但 TinyXML 这个小巧的 C XML 解析器还是给我留下了深刻的印象,学习曲线相当平缓,我记得当时花了一个下午就看完它的 Documentation 和 Tutorial 并完成了那个 XML 应用模块的开发。
所以如果你在 C中要用到不需太复杂的 XML 解析,那 TinyXML 非常值得考虑。
就由于其 Documentation 和 Tutorial 的短小,所以我才产生了翻译它们并放到 blog 上的念头,希望有一天能对在找这方面资料的国内朋友有所帮助。
这样做是有根据的,我用 google 的网站管理员工具看过,发现我的 blog 在 google 上的收录情况还不错,排名也在渐渐上升中,总有一天网友能在
搜索引擎中找到这些文章。
另一方面,我很想尝试一下翻译技术文章的滋味并培养一下这方面的能力,也许有一天我可以学学候捷靠翻译些国外的技术专著过活。
Documentation 的翻译刚好花费了我整整一个星期晚上的休息时间,很多字句我自己是能理解的,但是到真的用中文的语言习惯翻译出来时还是费了我不少脑细胞。
我大体上是逐字逐句翻译的,但有些实在不合中文语言习惯的我就意译了。
Tutorial 的翻译大概也需要一星期,下星期再放上来。