/** @mainpage

TinyXML

TinyXML est un analyseur XML simple, petit et en C++ qui peut être facilement intégré dans d'autres programmes.

Ce qu'il fait.

En bref, TinyXML analyse un document XML et construit à partir de celui-ci un modèle objet de document (DOM) qui peut être lu, modifié et sauvegardé.

XML signifie « eXtensible Markup Language ». Il permet de créer vos propres balises de document. Là où HTML fait un très bon travail de balisage des documents pour les navigateurs, XML vous permet de définir n'importe quel type de balisage de document, par exemple un document décrivant une liste de « tâches à faire » pour une application d'organisation. XML est un format très structuré et pratique. Tous ces formats de fichiers aléatoires créés pour stocker des données d'application peuvent être remplacés par XML. Un seul analyseur pour tout.

Le meilleur endroit pour la spécification complète, correcte et, franchement, difficile à lire se trouve à l'adresse http://www.w3.org/TR/2004/REC-xml-20040204/. Une introduction à XML (que j'aime vraiment) se trouve à http://skew.org/xml/tutorial.

Il existe différentes manières d'accéder et d'interagir avec les données XML. TinyXML utilise un modèle objet de document (DOM), ce qui signifie que les données XML sont analysées en objets C++ qui peuvent être parcourus et manipulés, puis écrits sur le disque ou un autre flux de sortie. Vous pouvez également construire un document XML à partir de zéro avec des objets C++ et l'écrire sur le disque ou un autre flux de sortie.

TinyXML est conçu pour être facile et rapide à apprendre. Il se compose de deux en-têtes et de quatre fichiers cpp. Ajoutez simplement ceux-ci à votre projet et c'est parti. Il y a un fichier d'exemple - xmltest.cpp - pour vous aider à démarrer.

TinyXML est distribué sous la licence ZLib, vous pouvez donc l'utiliser dans du code open source ou commercial. Les détails de la licence se trouvent en haut de chaque fichier source.

TinyXML tente d'être un analyseur flexible, mais avec une sortie XML véritablement correcte et conforme. TinyXML devrait compiler sur tout système raisonnablement conforme au C++. Il ne repose pas sur les exceptions ou le RTTI. Il peut être compilé avec ou sans support STL. TinyXML prend entièrement en charge l'encodage UTF-8 et les 64 000 premières entités de caractères.

Ce qu'il ne fait pas.

TinyXML n'analyse ni n'utilise les DTD (Document Type Definitions) ou les XSL (eXtensible Stylesheet Language). Il existe d'autres analyseurs (consultez www.sourceforge.org, cherchez XML) qui sont beaucoup plus complets. Mais ils sont aussi beaucoup plus gros, prennent plus de temps à configurer dans votre projet, ont une courbe d'apprentissage plus élevée et ont souvent une licence plus restrictive. Si vous travaillez avec des navigateurs ou avez des besoins XML plus complets, TinyXML n'est pas l'analyseur qu'il vous faut.

La syntaxe DTD suivante ne sera pas analysée pour le moment dans TinyXML :

@verbatim ]> @endverbatim

car TinyXML voit cela comme un nœud !DOCTYPE avec un nœud !Element intégré illégalement. Cela pourrait être résolu à l'avenir.

Tutoriels.

Pour les impatients, voici un tutoriel pour vous lancer. Un excellent moyen de commencer, mais il vaut la peine de lire ce manuel (très court) en entier.

• @subpage tutorial0

État du code.

TinyXML est un code mature et testé. Il est très stable. Si vous trouvez des bogues, veuillez soumettre un rapport de bogue sur le site web sourceforge (www.sourceforge.net/projects/tinyxml). Nous les résoudrons dès que possible.

Il y a quelques domaines d'amélioration ; veuillez consulter sourceforge si vous êtes intéressé à travailler sur TinyXML.

Projets apparentés

Des projets TinyXML qui pourraient vous être utiles ! (Descriptions fournies par les projets.)

• TinyXPath (http://tinyxpath.sourceforge.net). TinyXPath est un décodeur de syntaxe XPath à faible empreinte, écrit en C++.
• TinyXML++ (http://code.google.com/p/ticpp/). TinyXML++ est une toute nouvelle interface pour TinyXML qui utilise BEAUCOUP des forces du C++. Templates, exceptions et bien meilleure gestion des erreurs.

Fonctionnalités

Utilisation de STL

TinyXML peut être compilé pour utiliser ou non STL. En utilisant STL, TinyXML utilise la classe std::string et prend entièrement en charge std::istream, std::ostream, operator<< et operator>>. De nombreuses méthodes API ont à la fois des formes 'const char*' et 'const std::string&'.

Lorsque le support STL est désactivé à la compilation, aucun fichier STL n'est inclus du tout. Toutes les classes de chaînes sont implémentées par TinyXML lui-même. Les méthodes API utilisent toutes la forme 'const char*' pour l'entrée.

Utilisez le #define de temps de compilation :

TIXML_USE_STL

pour compiler une version ou l'autre. Cela peut être passé par le compilateur, ou défini comme première ligne de "tinyxml.h".

Remarque : Si vous compilez le code de test sous Linux, définir la variable d'environnement TINYXML_USE_STL=YES/NO controlera la compilation STL. Dans le fichier projet Windows, des cibles STL et non STL sont fournies. Dans votre projet, il est probablement plus simple d'ajouter la ligne "#define TIXML_USE_STL" comme première ligne de tinyxml.h.

UTF-8

TinyXML supporte l'UTF-8, permettant de manipuler des fichiers XML dans n'importe quelle langue. TinyXML supporte également le "mode legacy" - l'encodage utilisé avant le support UTF-8 et probablement mieux décrit comme "ASCII étendu".

Normalement, TinyXML essaiera de détecter le bon encodage et de l'utiliser. Cependant, en définissant la valeur de TIXML_DEFAULT_ENCODING dans le fichier d'en-tête, TinyXML peut être forcé à toujours utiliser un seul encodage.

TinyXML supposera le mode Legacy jusqu'à ce que l'un des événements suivants se produise :

1. Si les « octets de tête UTF-8 » non standard mais courants (0xef 0xbb 0xbf) débutent le fichier ou le flux de données, TinyXML le lira comme UTF-8.
2. Si la balise de déclaration est lue et qu'elle a un encoding="UTF-8", alors TinyXML le lira comme UTF-8.
3. Si la balise de déclaration est lue et qu'elle n'a pas d'encodage spécifié, alors TinyXML le lira comme UTF-8.
4. Si la balise de déclaration est lue et qu'elle a un encoding="quelque chose d'autre", alors TinyXML le lira en mode Legacy. En mode legacy, TinyXML fonctionnera comme avant. On ne sait pas exactement ce que fait ce mode, mais l'ancien contenu devrait continuer à fonctionner.
5. Jusqu'à ce que l'un des critères ci-dessus soit rempli, TinyXML fonctionne en mode Legacy.

Que se passe-t-il si l'encodage est mal défini ou détecté ? TinyXML essaiera de lire et de transmettre le texte considéré comme mal encodé. Vous pourriez obtenir des résultats étranges ou des caractères tronqués. Vous voudrez peut-être forcer TinyXML dans le bon mode.

Vous pouvez forcer TinyXML en mode Legacy en utilisant LoadFile( TIXML_ENCODING_LEGACY ) ou LoadFile( filename, TIXML_ENCODING_LEGACY ). Vous pouvez le forcer à utiliser le mode legacy tout le temps en définissant TIXML_DEFAULT_ENCODING = TIXML_ENCODING_LEGACY. De même, vous pouvez le forcer à TIXML_ENCODING_UTF8 avec la même technique.

Pour les utilisateurs anglophones, utilisant du XML en anglais, l'UTF-8 est identique à l'ASCII faible. Vous n'avez pas besoin d'être conscient de l'UTF-8 ou de modifier votre code d'aucune façon. Vous pouvez considérer l'UTF-8 comme un « sur-ensemble » de l'ASCII.