[xml/c/c++] TinyXML中文文檔

[xml/c/c++]TinyXML中文文檔
TinyXML

譯註：本文是TinyXML 2.5.2版本Document的中文文檔，經原作者Lee Thomason同意由hansen翻譯，如有誤譯或者錯漏，歡迎指正。
著作權：著作權歸原作者所有，翻譯文檔著作權歸本人hansen所有，轉載請註明出處。
原文：http://www.grinninglizard.com/tinyxmldocs/index.html

TinyXml 文檔

TinyXML是一個簡單小巧，可以很容易整合到其它程式中的C++ XML解析器。

它能做些什麼

簡單地說，TinyXML解析一個XML文檔並由此產生一個可讀可修改可儲存的文件物件模型（DOM）。

XML的意思是“可延伸標記語言 (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個字元實體（<i>譯註：如果你不明白這句譯文，可能你需要瞭解一下Unicode編碼</i>）。

它無法做些什麼

TinyXML不解析不使用DTDs（文件類型定義）或者XSLs（可延伸樣式表語言 (XSL)）。有其它解析器（到www.sourceforge.org搜尋一下XML）具有更加全面的特性，但它們也就更大，需要花更長的時間來建立你的項目，有更陡的學習曲線，而且經常有一個更嚴格的許可協議。如果你是用於瀏覽器或者有更複雜的XML需要，那麼TinyXML不適合你。

下面的DTD文法在TinyXML裡是不做解析的：

<!DOCTYPE Archiv [
<!ELEMENT Comment (#PCDATA)>
]>

因為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<<和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模式：
如果檔案或者資料流以非標準但普遍的"UTF-8引導位元組" (0xef 0xbb 0xbf)開始，TinyXML會以UTF-8的方式來讀取它。
如果包含有encoding="UTF-8"的聲明被讀取，那麼TinyXML會以UTF-8的方式來讀取它。
如果讀取到沒有指定編碼方式的聲明，那麼TinyXML會以UTF-8的方式來讀取它。
如果包含有encoding=“其它編碼”的聲明被讀取，那麼TinyXML會以Legacy模式來讀取它。在Legacy模式下，TinyXML會像以前那樣工作，雖然已經不是很清楚這種模式是如何工作的了，但舊的內容還得保持能夠運行。
除了上面提到的情況，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檔案和標準輸出。
"相當漂亮的列印", 但你沒法控制列印選項。
輸出資料直接寫到FILE對象中，所以TinyXML代碼沒有記憶體負擔。
被Print()和SaveFile()調用。

operator<<：輸出到一個c++流中。
與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<<

產生壓縮過的輸出，目的是為了便於網路傳輸而不是為了可讀性。它可能有些慢（可能不會），這主要跟你系統上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>
<!– Our to do list data –>
<ToDo>
<Item priority="1"> Go to the <bold>Toy store!</bold></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 類，同時也是文檔結點的第一個子結點。

這是TinyXML唯一能夠解析的指令/特殊標籤。一般來說指令標籤會儲存在TiXmlUnknown 以保證在它儲存回磁碟時不會丟失這些命令。

<!– Our to do list data –>

這是一個注釋，會成為一個TiXmlComment對象。

<ToDo>

"ToDo"標籤定義了一個TiXmlElement 對象。它沒有任何屬性，但包含另外的兩個元素。

<Item priority="1">

產生另一個TiXmlElement對象，它是“ToDo”元素的子結點。此元素有一個名為“priority”和值為“1”的屬性。

Go to the

TiXmlText ，這是一個葉子結點，它不能再包含其它結點，是"Item" TiXmlElement的子結點。

<bold>

另一個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 Ellerton