/** @mainpage

TinyXML

TinyXML هو محلّل XML بسيط وصغير مكتوب بلغة C++ ويمكن دمجه بسهولة في البرامج الأخرى.

ما الذي يفعله؟

باختصار، يقوم TinyXML بتحليل مستند XML ويبني منه نموذج كائن المستند (DOM) الذي يمكن قراءته وتعديله وحفظه.

XML تعني "لغة الترميز القابلة للامتداد". تتيح لك إنشاء ترميزات المستندات الخاصة بك. فبينما يؤدي HTML عملاً جيداً جداً في ترميز المستندات للمتصفحات، يتيح لك XML تعريف أي نوع من ترميز المستندات، على سبيل المثال مستند يصف قائمة "مهام" لتطبيق منظّم. XML تنسيق منظم ومريح للغاية. كل تلك الصيغ العشوائية للملفات التي أُنشئت لتخزين بيانات التطبيقات يمكن استبدالها جميعاً بـ XML. محلّل واحد لكل شيء.

أفضل مكان للمواصفة الكاملة والصحيحة، والتي يصعب قراءتها بصراحة، هو http://www.w3.org/TR/2004/REC-xml-20040204/. ويمكن العثور على مقدمة إلى XML (تعجبني كثيراً) على http://skew.org/xml/tutorial.

توجد طرق مختلفة للوصول إلى بيانات XML والتفاعل معها. يستخدم TinyXML نموذج كائن المستند (DOM)، أي أن بيانات XML تُحلل إلى كائنات C++ يمكن تصفحها ومعالجتها، ثم كتابتها إلى القرص أو إلى تيار إخراج آخر. يمكنك أيضاً إنشاء مستند XML من الصفر باستخدام كائنات C++ وكتابته إلى القرص أو إلى تيار إخراج آخر.

صُمم TinyXML ليكون سهل التعلم وسريعاً فيه. يتكون من ملفي رؤوس (headers) وأربعة ملفات cpp. فقط أضف هذه إلى مشروعك وانطلق. يوجد ملف مثال - xmltest.cpp - ليبدأ معك.

يُطرح TinyXML بموجب رخصة ZLib، لذا يمكنك استخدامه في البرمجيات مفتوحة المصدر أو التجارية. تفاصيل الترخيص موجودة في أعلى كل ملف مصدري.

يسعى TinyXML ليكون محللاً مرناً، مع مخرجات XML صحيحة ومتوافقة حقاً. يفترض أن يُصرَّح TinyXML على أي نظام متوافق بشكل معقول مع C++. لا يعتمد على الاستثناءات أو RTTI. يمكن ترجمته مع دعم STL أو بدونه. يدعم TinyXML بالكامل ترميز UTF-8، وأول 64 ألف كيان حرفي.

ما الذي لا يفعله؟

لا يحلل TinyXML تعريفات أنواع المستندات (DTDs) أو لغات الأنماط القابلة للامتداد (XSLs) ولا يستخدمها. توجد محللات أخرى (تفقد www.sourceforge.org وابحث عن XML) أكثر اكتمالاً بكثير من حيث الميزات. لكنها أيضاً أكبر حجماً بكثير، وتستغرق وقتاً أطول للإعداد في مشروعك، ولها منحنى تعلم أعلى، وغالباً ما تحمل رخصة أكثر تقييداً. إذا كنت تعمل مع المتصفحات أو لديك احتياجات XML أكثر اكتمالاً، فإن TinyXML ليس المحلل المناسب لك.

بناء جملة DTD التالي لن يُحلل في TinyXML في الوقت الحالي:

@verbatim ]> @endverbatim

لأن TinyXML يرى هذا كعقدة !DOCTYPE تحتوي عقدة !ELEMENT مدمجة بشكل غير قانوني. قد يُعالج هذا الأمر في المستقبل.

الدروس التعليمية.

لغير الصبورين، إليك درساً تعليمياً لتبدأ به. طريقة رائعة للانطلاق، لكن من الجدير أن تقرأ هذا الدليل (القصير جداً) بالكامل.

• @subpage tutorial0

حالة الكود.

TinyXML كود ناضج ومُختبَر. إنه مستقر جداً. إذا وجدت أخطاء، فيرجى تقديم تقرير خطأ على موقع sourceforge (www.sourceforge.net/projects/tinyxml). سنقوم بإصلاحها في أقرب وقت ممكن.

توجد بعض المجالات القابلة للتحسين؛ يرجى مراجعة sourceforge إذا كنت مهتماً بالعمل على TinyXML.

مشاريع ذات صلة

مشاريع 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 إطلاقاً. جميع أصناف النصوص مُنفَّذة بواسطة TinyXML نفسه. تستخدم جميع طرق API صيغة 'const char*' للإدخال.

استخدم #define في زمن الترجمة:

TIXML_USE_STL

لترجمة إحدى النسختين أو الأخرى. يمكن تمرير هذا بواسطة المترجم، أو تعيينه كسطر أول في "tinyxml.h".

ملاحظة: إذا كنت تترجم كود الاختبار في Linux، فإن تعيين متغير البيئة TINYXML_USE_STL=YES/NO سيتحكم في ترجمة STL. في ملف مشروع Windows، تُوفَّر أهداف STL وغير STL. في مشروعك، ربما يكون من الأسهل إضافة السطر "#define TIXML_USE_STL" كسطر أول من tinyxml.h.

UTF-8

يدعم TinyXML ترميز UTF-8 مما يتيح التعامل مع ملفات XML بأي لغة. كما يدعم TinyXML "الوضع القديم" (legacy mode) - الترميز المستخدم قبل دعم UTF-8 ويمكن وصفه على الأرجح بأنه "ascii موسّع".

في الوضع الطبيعي، سيحاول TinyXML اكتشاف الترميز الصحيح واستخدامه. ومع ذلك، بتعيين قيمة TIXML_DEFAULT_ENCODING في ملف الرأس، يمكن إجبار TinyXML على استخدام ترميز واحد دائماً.

سيفترض TinyXML الوضع القديم (Legacy Mode) حتى يحدث أحد الأمور التالية:

1. إذا بدأت الملف أو تيار البيانات "بايتات UTF-8 الافتتاحية" غير القياسية ولكن الشائعة (0xef 0xbb 0xbf)، فسيقرأها TinyXML كـ UTF-8.
2. إذا قُرئ وسم التصريح (declaration) وكان يحتوي encoding="UTF-8"، فسيقرأه TinyXML كـ UTF-8.
3. إذا قُرئ وسم التصريح ولم يكن فيه ترميز محدد، فسيقرأه TinyXML كـ UTF-8.
4. إذا قُرئ وسم التصريح وكان يحتوي encoding="something else"، فسيقرأه TinyXML في الوضع القديم (Legacy Mode). في الوضع القديم، سيعمل TinyXML كما كان يعمل من قبل. ليس من الواضح ماذا يفعل هذا الوضع بالضبط، لكن المحتوى القديم يجب أن يستمر في العمل.
5. وإلى أن يتحقق أحد المعايير المذكورة أعلاه، يعمل TinyXML في الوضع القديم (Legacy Mode).

ماذا يحدث إذا كان الترميز مضبوطاً أو مكتشفاً بشكل غير صحيح؟ سيحاول TinyXML قراءة النص الذي يُرى أنه غير مشفَّر بشكل سليم وتمريره. قد تحصل على بعض النتائج الغريبة أو أحرف مشوهة. قد ترغب في إجبار TinyXML على الوضع الصحيح.

يمكنك إجبار TinyXML على الوضع القديم باستخدام LoadFile( TIXML_ENCODING_LEGACY ) أو LoadFile( filename, TIXML_ENCODING_LEGACY ). يمكنك إجباره على استخدام الوضع القديم طوال الوقت بتعيين TIXML_DEFAULT_ENCODING = TIXML_ENCODING_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. وهذا مصدر للالتباس.

بالنسبة للغات "عالية ascii" - كل ما ليس إنجليزياً، إلى حد كبير - يمكن لـ TinyXML التعامل مع جميع اللغات، في الوقت نفسه، طالما أن XML مشفَّر بـ UTF-8. قد يكون ذلك صعباً بعض الشيء، فالبرامج وأنظمة التشغيل الأقدم تميل إلى استخدام صفحة الرموز "الافتراضية" أو "التقليدية". العديد من التطبيقات (وتقريباً كل الحديثة منها) يمكنها إخراج UTF-8، لكن التطبيقات الأقدم أو العنيدة (أو المعطوبة فقط) ما تزال تخرج النص بصفحة الرموز الافتراضية.

على سبيل المثال، تستخدم الأنظمة اليابانية تقليدياً ترميز SHIFT-JIS. النص المشفَّر بـ SHIFT-JIS لا يمكن قراءته بواسطة TinyXML. يمكن لمحرر نصوص جيد استيراد SHIFT-JIS ثم الحفظ بصيغة UTF-8.

رابط Skew.org يقوم بعمل رائع في تغطية قضية الترميز.

ملف الاختبار "utf8test.xml" هو XML يحتوي على الإنجليزية والإسبانية والروسية والصينية المبسطة. (نأمل أن تكون مترجمة بشكل صحيح). الملف "utf8test.gif" هو لقطة شاشة لملف XML معروض في IE. لاحظ أنه إذا لم تكن لديك الخطوط الصحيحة (الصينية المبسطة أو الروسية) على نظامك، فلن ترى مخرجات تطابق ملف GIF حتى لو تمكنت من تحليله بشكل صحيح. لاحظ أيضاً (على الأقل على جهاز Windows الخاص بي) أن مخرجات وحدة التحكم بصفحة رموز غربية، لذا فإن Print() أو printf() لا يمكنها عرض الملف بشكل صحيح. هذا ليس خطأً في TinyXML - بل مجرد مشكلة في نظام التشغيل. لا تُفقد أي بيانات أو تُتلف بواسطة TinyXML. وحدة التحكم فقط لا تعرض UTF-8.

الكيانات

@verbatim & & < < > > " " ' ' @endverbatim

يتم التعرف عليها عند قراءة مستند XML، وتُترجم إلى ما يعادلها في UTF-8. على سبيل المثال، النص الذي يحتوي XML بالشكل:

@verbatim Far & Away @endverbatim

سيكون له Value() بقيمة "Far & Away" عند الاستعلام من كائن TiXmlText، وسيُكتب مرة أخرى إلى تيار/ملف XML كعلامة ampersand (&). الإصدارات الأقدم من TinyXML "حافظت" على كيانات الأحرف، لكن الإصدارات الأحدث تترجمها إلى أحرف.

بالإضافة إلى ذلك، يمكن تحديد أي حرف بنقطة رمز Unicode الخاصة به: الصياغتان " " أو " " كلتاهما تشيران إلى حرف المسافة غير المنفصلة (non-breaking space).

الطباعة

• Print( FILE* ). الإخراج إلى تيار std-C، والذي يشمل جميع ملفات C بالإضافة إلى stdout.

  • "طباعة منسقة"، لكن ليس لديك تحكم في خيارات الطباعة.
  • يُخرج مباشرة إلى كائن FILE، لذلك لا يوجد حمل على الذاكرة في كود TinyXML.
  • تُستخدم بواسطة Print() وSaveFile()

• operator<<. الإخراج إلى تيار C++.

  • يتكامل مع iostreams القياسية في C++.
  • يُخرج في وضع "الطباعة الشبكية" بدون فواصل أسطر. جيد للنقل عبر الشبكة ونقل XML بين كائنات C++، لكنه صعب القراءة للبشر.

• TiXmlPrinter. الإخراج إلى std::string أو مخزن ذاكرة.

  • واجهة API أقل إيجازاً
  • خيارات الطباعة المستقبلية ستوضع هنا.
  • قد تتغير الطباعة قليلاً في الإصدارات المستقبلية مع تحسينها وتوسيعها.

التيارات

الإخراج بنمط C: - يعتمد على FILE* - طريقتا Print() وSaveFile()

يولّد مخرجات منسقة، مع الكثير من المسافات البيضاء، تهدف إلى أن تكون قابلة للقراءة قدر الإمكان. إنها سريعة جداً، ومتسامحة مع مستندات XML غير سليمة البنية. على سبيل المثال، مستند XML يحتوي على عنصري جذر وتصريحين، سيظل يُطبع.

الإدخال بنمط C: - يعتمد على FILE* - طريقتا Parse() وLoadFile()

قراءة سريعة ومتسامحة. استخدمها كلما لم تكن بحاجة إلى تيارات C++.

الإخراج بنمط C++: - يعتمد على std::ostream - operator<<

يولّد مخرجات مكثفة، مخصصة للنقل عبر الشبكة بدلاً من readability. اعتماداً على تنفيذ نظامك لصنف ostream، قد تكون هذه أبطأ إلى حد ما. (أو لا تكون). غير متسامح مع XML غير سليم البنية: يجب أن يحتوي المستند على عنصر جذر واحد صحيح. العناصر الإضافية على مستوى الجذر لن تُخرج عبر التيار.

الإدخال بنمط C++: - يعتمد على std::istream - operator>>

يقرأ XML من تيار، مما يجعله مفيداً للنقل عبر الشبكة. الجزء الصعب هو معرفة متى يكتمل مستند XML، لأنه سيكون هناك حتماً تقريباً بيانات أخرى في التيار. سيفترض TinyXML أن بيانات XML مكتملة بعد قراءة عنصر الجذر. بعبارة أخرى، المستندات غير سليمة البناء التي تحتوي على أكثر من عنصر جذر لن تُقرأ بشكل صحيح. لاحظ أيضاً أن operator>> أبطأ إلى حد ما من Parse، بسبب تنفيذ STL وقيود TinyXML معاً.

المسافات البيضاء

إنها قضية لم تُحل بما يرضيني. يدعم TinyXML النهجين الأولين. استدعِ TiXmlBase::SetCondenseWhiteSpace( bool ) لتعيين السلوك المطلوب. الافتراضي هو ضغط المسافات البيضاء.

إذا غيّرت الافتراضي، فيجب عليك استدعاء TiXmlBase::SetCondenseWhiteSpace( bool ) قبل القيام بأي استدعاءات لتحليل بيانات XML، ولا أنصح بتغييره بعد تعيينه.

المقابض

عند تصفح مستند XML بطريقة قوية، من المهم التحقق من القيم الراجعة null من استدعاءات الطرق. يمكن أن يولد تنفيذ آمن من الأخطاء الكثير من الكود مثل:

@verbatim 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. @endverbatim

أُدخلت المقابض (Handles) لتنظيف هذا الأمر. باستخدام صنف TiXmlHandle، يُختصر الكود السابق إلى:

@verbatim TiXmlHandle docHandle( &document ); TiXmlElement* child2 = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", 1 ).ToElement(); if ( child2 ) { // do something useful @endverbatim

وهو أمر أسهل بكثير في التعامل معه. راجع TiXmlHandle لمزيد من المعلومات.

تتبع الصف والعمود

يمكن لـ TinyXML تتبع أصل الصف والعمود لجميع العقد والسمات في ملف نصي. تعيد طريقتا TiXmlBase::Row() وTiXmlBase::Column() أصل العقدة في النص المصدر. يمكن ضبط حجم التبويبات الصحيح في TiXmlDocument::SetTabSize().

الاستخدام والتثبيت

لتجميع وتشغيل xmltest:

يتم توفير ملف Makefile لنظام Linux وملف .dsw لـ Visual C++ في Windows. فقط قم بالتجميع والتشغيل. سيكتب الملف demotest.xml إلى قرصك ويولّد مخرجات على الشاشة. كما يختبر التجول في DOM بطباعة عدد العقد التي تم العثور عليها باستخدام تقنيات مختلفة.

إن makefile الخاص بـ Linux عام جداً ويعمل على أنظمة عديدة - وهو مُختبَر حالياً على mingw وMacOSX. لا تحتاج إلى تشغيل 'make depend'. فقد تم ترميز التبعيات بشكل ثابت.

ملف مشروع Windows لـ VC6

• tinyxml: مكتبة tinyxml، بدون STL
• tinyxmlSTL: مكتبة tinyxml، مع STL
• tinyXmlTest: تطبيق اختبار، بدون STL
• tinyXmlTestSTL: تطبيق اختبار، مع STL

Makefile

PROFILE وDEBUG وTINYXML_USE_STL. التفاصيل (على ما هي عليه) موجودة في ملف makefile.

في دليل tinyxml، اكتب "make clean" ثم "make". سيتم إنشاء الملف التنفيذي 'xmltest'.

لاستخدامه في تطبيق:

أضف tinyxml.cpp وtinyxml.h وtinyxmlerror.cpp وtinyxmlparser.cpp وtinystr.cpp وtinystr.h إلى مشروعك أو ملف make. هذا كل شيء! يجب أن يُصرَّح على أي نظام متوافق بشكل معقول مع C++. لست بحاجة إلى تفعيل الاستثناءات أو RTTI لـ TinyXML.

كيف يعمل TinyXML.

المثال هو على الأرجح أفضل طريقة للمضي قدماً. خذ:

@verbatim <?xml version="1.0" standalone=no> Go to the Toy store! Do bills @endverbatim

إنها ليست قائمة مهام كبيرة، لكنها ستفي بالغرض. لقراءة هذا الملف (قل "demo.xml") يمكنك إنشاء مستند وتحليله:

@verbatim TiXmlDocument doc( "demo.xml" ); doc.LoadFile(); @endverbatim

وهو جاهز للاستخدام. الآن لننظر إلى بعض الأسطر وكيف ترتبط بـ DOM.

@verbatim

التوثيق

الترخيص

المراجع

المساهمون، وجهات الاتصال، ونبذة تاريخية