/** @mainpage

TinyXML

TinyXML एक सरल, छोटा, C++ XML पार्सर है जिसे अन्य प्रोग्रामों में आसानी से एकीकृत किया जा सकता है।

यह क्या करता है।

संक्षेप में, TinyXML एक XML दस्तावेज़ को पार्स करता है, और उससे एक Document Object Model (DOM) बनाता है जिसे पढ़ा, संशोधित और सहेजा जा सकता है।

XML का अर्थ है "eXtensible Markup Language"। यह आपको अपना स्वयं का दस्तावेज़ मार्कअप बनाने की अनुमति देता है। जहाँ HTML ब्राउज़रों के लिए दस्तावेज़ों को चिह्नित करने का बहुत अच्छा काम करता है, वहीं XML आपको किसी भी प्रकार का दस्तावेज़ मार्कअप परिभाषित करने की अनुमति देता है, उदाहरण के लिए एक दस्तावेज़ जो किसी आयोजक अनुप्रयोग के लिए "to do" सूची का वर्णन करता है। XML एक अत्यंत संरचित और सुविधाजनक प्रारूप है। अनुप्रयोग डेटा संग्रहीत करने के लिए बनाए गए वे सभी यादृच्छिक फ़ाइल प्रारूप सभी XML द्वारा प्रतिस्थापित किए जा सकते हैं। सब कुछ के लिए एक पार्सर।

पूर्ण, सही, और स्पष्ट रूप से कहें तो पढ़ने में कठिन स्पेक के लिए सबसे अच्छी जगह है http://www.w3.org/TR/2004/REC-xml-20040204/। XML का एक परिचय (जो मुझे वास्तव में पसंद है) http://skew.org/xml/tutorial पर पाया जा सकता है।

XML डेटा तक पहुँचने और उसके साथ बातचीत करने के विभिन्न तरीके हैं। TinyXML एक Document Object Model (DOM) का उपयोग करता है, जिसका अर्थ है कि XML डेटा को C++ ऑब्जेक्ट्स में पार्स किया जाता है जिन्हें ब्राउज़ और हेरफेर किया जा सकता है, और फिर डिस्क या किसी अन्य आउटपुट स्ट्रीम पर लिखा जा सकता है। आप C++ ऑब्जेक्ट्स के साथ शुरू से एक XML दस्तावेज़ भी बना सकते हैं और इसे डिस्क या किसी अन्य आउटपुट स्ट्रीम पर लिख सकते हैं।

TinyXML को आसान और तेज़ी से सीखने योग्य बनाने के लिए डिज़ाइन किया गया है। यह दो हेडर और चार cpp फ़ाइलें हैं। बस इन्हें अपने प्रोजेक्ट में जोड़ें और आप शुरू कर सकते हैं। आरंभ करने के लिए एक उदाहरण फ़ाइल - xmltest.cpp - है।

TinyXML ZLib लाइसेंस के अंतर्गत जारी किया गया है, इसलिए आप इसे ओपन सोर्स या व्यावसायिक कोड में उपयोग कर सकते हैं। लाइसेंस का विवरण हर स्रोत फ़ाइल के शीर्ष पर है।

TinyXML एक लचीला पार्सर बनने का प्रयास करता है, लेकिन वास्तव में सही और अनुरूप XML आउटपुट के साथ। TinyXML को किसी भी उचित रूप से C++ संगत प्रणाली पर संकलित होना चाहिए। यह एक्सेप्शन या RTTI पर निर्भर नहीं करता है। इसे STL समर्थन के साथ या बिना संकलित किया जा सकता है। TinyXML पूरी तरह से UTF-8 एन्कोडिंग और पहले 64k वर्ण संस्थाओं का समर्थन करता है।

यह क्या नहीं करता।

TinyXML DTDs (Document Type Definitions) या XSLs (eXtensible Stylesheet Language) को पार्स या उपयोग नहीं करता है। वहाँ अन्य पार्सर मौजूद हैं (www.sourceforge.org देखें, XML खोजें) जो बहुत अधिक पूर्ण रूप से सुविधा संपन्न हैं। लेकिन वे बहुत बड़े भी हैं, आपके प्रोजेक्ट में सेट अप करने में अधिक समय लेते हैं, उनकी सीखने की अवस्था (learning curve) अधिक कठिन होती है, और अक्सर अधिक प्रतिबंधात्मक लाइसेंस होता है। यदि आप ब्राउज़रों के साथ काम कर रहे हैं या आपकी अधिक पूर्ण XML आवश्यकताएँ हैं, तो TinyXML आपके लिए पार्सर नहीं है।

निम्नलिखित DTD सिंटैक्स इस समय TinyXML में पार्स नहीं होगा:

@verbatim ]> @endverbatim

क्योंकि TinyXML इसे एक !DOCTYPE नोड के रूप में देखता है जिसमें अवैध रूप से एम्बेडेड !ELEMENT नोड है। इस पर भविष्य में ध्यान दिया जा सकता है।

ट्यूटोरियल।

अधीर लोगों के लिए, यहाँ एक ट्यूटोरियल है जो आपको आरंभ कराएगा। शुरू करने का एक शानदार तरीका, लेकिन इस (अत्यंत छोटे) मैनुअल को पूरी तरह पढ़ना आपके समय के लायक है।

• @subpage tutorial0

कोड स्थिति।

TinyXML परिपक्व, परीक्षित कोड है। यह अत्यंत स्थिर है। यदि आपको बग मिलते हैं, तो कृपया sourceforge वेब साइट (www.sourceforge.net/projects/tinyxml) पर बग रिपोर्ट दर्ज करें। हम उन्हें जल्द से जल्द ठीक कर देंगे।

सुधार के कुछ क्षेत्र हैं; यदि आप TinyXML पर काम करने में रुचि रखते हैं तो कृपया sourceforge देखें।

संबंधित परियोजनाएँ

TinyXML परियोजनाएँ जो आपको उपयोगी लग सकती हैं! (विवरण परियोजनाओं द्वारा प्रदान किए गए हैं।)

• TinyXPath (http://tinyxpath.sourceforge.net). TinyXPath एक छोटा पदचिह्न (footprint) 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 फ़ाइल शामिल नहीं की जाती है। सभी स्ट्रिंग क्लासें TinyXML द्वारा स्वयं कार्यान्वित की जाती हैं। API विधियाँ इनपुट के लिए सभी 'const char*' रूप का उपयोग करती हैं।

कंपाइल-टाइम #define का उपयोग करें:

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 "लेगेसी मोड" का भी समर्थन करता है - UTF-8 समर्थन से पहले उपयोग की जाने वाली एन्कोडिंग और संभवतः "विस्तारित ascii" के रूप में सबसे अच्छा वर्णित है।

सामान्यतः, TinyXML सही एन्कोडिंग का पता लगाने और उसका उपयोग करने का प्रयास करेगा। हालाँकि, हेडर फ़ाइल में TIXML_DEFAULT_ENCODING का मान सेट करके, TinyXML को हमेशा एक एन्कोडिंग का उपयोग करने के लिए बाध्य किया जा सकता है।

TinyXML निम्नलिखित में से एक होने तक लेगेसी मोड मान लेगा:

1. यदि गैर-मानक लेकिन सामान्य "UTF-8 लीड बाइट्स" (0xef 0xbb 0xbf) फ़ाइल या डेटा स्ट्रीम शुरू करते हैं, तो TinyXML इसे UTF-8 के रूप में पढ़ेगा।
2. यदि घोषणा टैग पढ़ा जाता है, और उसमें encoding="UTF-8" है, तो TinyXML इसे UTF-8 के रूप में पढ़ेगा।
3. यदि घोषणा टैग पढ़ा जाता है, और उसमें कोई एन्कोडिंग निर्दिष्ट नहीं है, तो TinyXML इसे UTF-8 के रूप में पढ़ेगा।
4. यदि घोषणा टैग पढ़ा जाता है, और उसमें encoding="कुछ और" है, तो TinyXML इसे लेगेसी मोड के रूप में पढ़ेगा। लेगेसी मोड में, TinyXML पहले की तरह काम करेगा। यह स्पष्ट नहीं है कि यह मोड वास्तव में क्या करता है, लेकिन पुरानी सामग्री काम करती रहनी चाहिए।
5. जब तक उपरोक्त मानदंडों में से एक पूरा नहीं होता, TinyXML लेगेसी मोड में चलता है।

क्या होता है यदि एन्कोडिंग गलत तरीके से सेट या पहचानी जाती है? TinyXML अनुचित रूप से एन्कोडेड के रूप में देखे गए पाठ को पढ़ने और पास करने का प्रयास करेगा। आपको कुछ अजीब परिणाम या विकृत वर्ण मिल सकते हैं। आप TinyXML को सही मोड में जाने के लिए बाध्य करना चाह सकते हैं।

आप LoadFile( TIXML_ENCODING_LEGACY ) या LoadFile( filename, TIXML_ENCODING_LEGACY ) का उपयोग करके TinyXML को लेगेसी मोड में बाध्य कर सकते हैं। आप TIXML_DEFAULT_ENCODING = TIXML_ENCODING_LEGACY सेट करके इसे हमेशा लेगेसी मोड का उपयोग करने के लिए बाध्य कर सकते हैं। इसी तरह, आप उसी तकनीक के साथ इसे TIXML_ENCODING_UTF8 पर बाध्य कर सकते हैं।

अंग्रेज़ी उपयोगकर्ताओं के लिए, अंग्रेज़ी XML का उपयोग करते हुए, UTF-8 लो-ASCII के समान है। आपको UTF-8 के बारे में जागरूक होने या अपना कोड किसी भी तरह से बदलने की आवश्यकता नहीं है। आप UTF-8 को ASCII के "सुपरसेट" के रूप में सोच सकते हैं।

UTF-8 एक डबल बाइट प्रारूप नहीं है - लेकिन यह यूनिकोड की एक मानक एन्कोडिंग है! TinyXML इस समय wchar, TCHAR, या Microsoft के _UNICODE का उपयोग या सीधे समर्थन नहीं करता है। "Unicode" शब्द को अक्सर अनुचित रूप से UTF-16, यूनिकोड की एक चौड़ी बाइट एन्कोडिंग, के संदर्भ में देखना आम है। यह भ्रम का एक स्रोत है।