TinyXml 文档

TinyXml 文档

TinyXML是一个简单小巧，可以很轻易集成到其它法度中的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不合适你。

指南

有耐性些，这是一份能很好地领导你怎么开端的指南，它（很是短小精干）值得你花时候完全地读上一遍。

• 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< operator><。很多API办法都有 ‘const char*’和’const std::string&’两个版本。

若是被编译成不应用STL，则任何STL都不会被包含。所有string类都由TinyXML它本身实现。所有API办法都只供给’const char*’传入参数。

应用运行时定义：

TIXML_USE_STL

来编译成不合的版本。这可以作为参数传给编译器或者在“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”。

正常景象下，TinyXML会检测出正确的编码并应用它，然而，经由过程设置头文件中的TIXML_DEFAULT_ENCODING值，TinyXML可以被强迫成老是应用某一种编码。

除非以下景象产生，不然TinyXML会默认应用Legacy模式：

1. 若是文件或者数据流以非标准但广泛的"UTF-8勾引字节" （0 xef 0 xbb 0 xbf）开端，TinyXML会以UTF-8的体式格式来读取它。
2. 若是包含有encoding="UTF-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认得预定义的特别“字符实体”，即：

& &
< < br style='font-size:12px;font-style:normal;font-weight:400;color:rgb(51, 51, 51);' />> <
" "
' ‘

这些在XML文档读取时都邑被辨认出来，并会被转化成等价的UTF-8字符。比如下面的XML文本：

Far & Away

从TiXmlText 对象查询出来时会变成"Far & Away"如许的值，而写回XML流/文件时会以“&”的体式格式写回。老版本的TinyXML“保存”了字符实体，而在新版本中它们会被转化成字符串。

别的，所有字符都可以用它的Unicode编码数字来指定， " "和" "都默示不成分的空格字符。

打印

TinyXML有几种不合的体式格式来打印输出，当然它们各有各的优毛病。

• • Print（ FILE* ）：输出到一个标准C流中，包含所有的C文件和标准输出。
    • "相当摩登的打印"， 但你没法把握打印选项。
    • 输出数据直接写到FILE对象中，所以TinyXML代码没有内存肩负。
    • 被Print（）和SaveFile（）调用。

• operator< cli>
  • 与C++ iostreams集成在一路。
  • 在"network printing"模式下输出没有换行符，这对于收集传输和C++对象之间的XML互换有益处，但人很难浏览。
• TiXmlPrinter：输出到一个std::string或者内存缓冲区中。
  • API还不是很简洁。
  • 将来会增长打印选项。
  • 在将来的版本中可能有些细微的变更，因为它会被改进和扩大。

流

设置了TIXML_USE_STL，TinyXML就能支撑C++流（operator < ><）和C（FILE*）流。但它们之间有些差别你须要知道：

C风格输出：

• 基于FILE*
• 用Print（）和SaveFile（）办法

生成具有很多空格的格局化过的输出，这是为了尽可能让人看得熟悉打听。它们很是快，并且可以或许容忍XML文档中的格局错误。例如一个XML文档包含两个根元素和两个声明仍然能被打印出来。

C风格输入：

• 基于FILE*
• 用Parse（）和LoadFile（）办法

速度快，容错性好。当你不须要C++流时就可以应用它。

C++风格输出：

• 基于std::ostream
• operator< li>

生成紧缩过的输出，目标是为了便于收集传输而不是为了可读性。它可能有些慢（可能不会），这首要跟你体系上ostream类的实现有关。无法容忍格局错误的XML：此文档只能包含一个根元素。别的根级此外元素无法以流情势输出。

C++风格输入：

• 基于std::istream
• operator<<

从流中读取XML使其可用于收集传输。经由过程些小技能，它知道当XML文档读取完毕时，流后面的就必然是其它数据了。TinyXML总假定当它读取到 根结点后XML数据就停止了。换句话说，那些具有不止一个根元素的文档是无法被正确读取的。别的还要重视因为STL的实现和TinyXML的限 制，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 ）.ToElement（）;
if （ 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
• tinyxmlSTL： 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怎么工作

举个例子可能是最好的办法，懂得一下：

< xml version="1.0" standalone="no" >


Go to the Toy store!
Do bills

它称不上是一个To Do列表，但它已经足够了。像下面如许读取并解析这个文件（叫“demo.xml”）你就能创建一个文档：

TiXmlDocument doc（"demo.xml" ）;
doc.LoadFile（）;

如今它筹办好了，让我们看看此中的某些行和它们怎么与DOM接洽起来。

< xml version="1.0" standalone="no" >

第一行是一个声明，它会转化成TiXmlDeclaration 类，同时也是文档结点的第一个子结点。

这是TinyXML独一可以或许解析的指令/特别标签。一般来说指令标签会保存在TiXmlUnknown 以包管在它保存回磁盘时不会丧失这些号令。

这是一个注释，会成为一个TiXmlComment对象。

"ToDo"标签定义了一个TiXmlElement 对象。它没有任何属性，但包含别的的两个元素。

生成另一个TiXmlElement对象，它是“ToDo”元素的子结点。此元素有一个名为“priority”和值为“1”的属性。

Go to the

TiXmlText ，这是一个叶子结点，它不克不及再包含其它结点，是"Item" TiXmlElement的子结点。

另一个TiXmlElement， 这也是“Item”元素的子结点。

等等

最后，看看全部对象树：

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"

文档

本文档由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/tinyxml

Lee Thomason， Yves Berquin， Andrew EllertonMRMY