/** @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.

الكيانات

يتعرف TinyXML على "كيانات الأحرف" المعرفة مسبقاً، أي الأحرف الخاصة. وهي:

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

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

@verbatim Far & Away @endverbatim