tinyxml

/** @mainpage

<h1> TinyXML </h1>

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

<h2> Ce qu'il fait. </h2>
	
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 <a href="http://www.w3.org/TR/2004/REC-xml-20040204/">
http://www.w3.org/TR/2004/REC-xml-20040204/</a>. Une introduction à XML (que j'aime vraiment) se trouve à 
<a href="http://skew.org/xml/tutorial/">http://skew.org/xml/tutorial</a>.

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.

<h2> Ce qu'il ne fait pas. </h2>

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
	<!DOCTYPE Archiv [
	 <!ELEMENT Comment (#PCDATA)>
	]>
@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.

<h2> Tutoriels. </h2>

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

<h2> État du code.  </h2>

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.

<h2> Projets apparentés </h2>

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

<ul>
<li> <b>TinyXPath</b> (http://tinyxpath.sourceforge.net). TinyXPath est un décodeur de syntaxe XPath à faible empreinte, écrit en C++.</li>
<li> <b>TinyXML++</b> (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.</li>
</ul>

<h2> Fonctionnalités </h2>

<h3> Utilisation de STL </h3>

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.

<h3> UTF-8 </h3>

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 :
<ol>
	<li> 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. </li>
	<li> Si la balise de déclaration est lue et qu'elle a un encoding="UTF-8", alors TinyXML le lira comme UTF-8. </li>
	<li> 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. </li>
	<li> 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.</li>
	<li> Jusqu'à ce que l'un des critères ci-dessus soit rempli, TinyXML fonctionne en mode Legacy.</li>
</ol>

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.

L'UTF-8 n'est pas un format double octet - mais c'est un encodage standard d'Unicode ! TinyXML n'utilise ni ne supporte directement wchar, TCHAR ou _UNICODE de Microsoft pour le moment. Il est courant de voir le terme « Unicode » utilisé incorrectement pour désigner l'UTF-16, un encodage large des caractères unicode. C'est une source de confusion.

Pour les langues à « caractères élevés » - pratiquement tout ce qui n'est pas anglais - TinyXML peut gérer toutes les langues, en même temps, tant que le XML est encodé en UTF-8. Cela peut être un peu délicat, les anciens programmes et systèmes d'exploitation ont tendance à utiliser la page de code « par défaut » ou « traditionnelle ». De nombreuses applications (et presque toutes les modernes) peuvent produire de l'UTF-8, mais les plus anciennes ou têtues (ou simplement défaillantes) produisent encore du texte dans la page de code par défaut.

Par exemple, les systèmes japonais utilisent traditionnellement l'encodage SHIFT-JIS. Le texte encodé en SHIFT-JIS ne peut pas être lu par TinyXML. Un bon éditeur de texte peut importer du SHIFT-JIS puis le sauvegarder en UTF-8.

Le <a href="http://skew.org/xml/tutorial/">lien Skew.org</a> fait un excellent travail en couvrant le problème d'encodage.

Le fichier test "utf8test.xml" est un XML contenant de l'anglais, de l'espagnol, du russe et du chinois simplifié. (Espérons qu'ils sont correctement traduits). Le fichier "utf8test.gif" est une capture d'écran du fichier XML, rendu dans IE. Notez que si vous n'avez pas les bonnes polices (chinois simplifié ou russe) sur votre système, vous ne verrez pas une sortie correspondant au fichier GIF même si vous pouvez l'analyser correctement. Notez également que (du moins sur ma machine Windows) la sortie console est dans une page de code occidentale, donc Print() ou printf() ne peuvent pas afficher correctement le fichier. Ce n'est pas un bogue de TinyXML - juste un problème de système d'exploitation. Aucune donnée n'est perdue ou détruite par TinyXML. La console ne rend tout simplement pas l'UTF-8.

<h3> Entités </h3>
TinyXML reconnaît les « entités de caractères » prédéfinies, c'est-à-dire les caractères spéciaux. À savoir :

@verbatim
	&amp;	&
	&lt;	<
	&gt;	>
	&quot;	"
	&apos;	'
@endverbatim

Ces entités sont reconnues lors de la lecture du document XML et traduites en leurs équivalents UTF-8. Par exemple, un texte avec le XML de :

@verbatim
	Far &amp; Away
@endverbatim

aura la valeur Value() de "Far & Away" lorsqu'il sera interrogé à partir de l'objet TiXmlText, et sera réécrit dans le flux/fichier XML sous forme d'esperluette. Les anciennes versions de TinyXML « préservaient » les entités de caractères, mais les nouvelles versions les traduiront en caractères.

De plus, tout caractère peut être spécifié par son point de code Unicode : la syntaxe "&#xA0;" ou "&#160;" correspondent toutes deux au caractère d'espace insécable.

<h3> Impression </h3>
TinyXML peut imprimer la sortie de plusieurs manières différentes, chacune avec ses forces et ses limites.

- Print( FILE* ). Sortie vers un flux std-C, qui inclut tous les fichiers C ainsi que stdout.
	- « Belle impression », mais vous n'avez pas le contrôle sur les options d'impression.
	- La sortie est directement diffusée vers l'objet FILE, donc il n'y a pas de surcharge mémoire dans le code TinyXML.
	- Utilisé par Print() et SaveFile()

- operator<<. Sortie vers un flux c++.
	- S'intègre avec les iostreams C++ standard.
	- Produit une sortie en « mode réseau » sans sauts de ligne. Bon pour la transmission réseau et le déplacement de XML entre objets C++, mais difficile à lire pour un humain.

- TiXmlPrinter. Sortie vers un std::string ou un tampon mémoire.
	- L'API est moins concise
	- Les futures options d'impression seront placées ici.
	- L'impression pourrait légèrement changer dans les versions futures à mesure qu'elle est affinée et étendue.

<h3> Flux </h3>
Avec TIXML_USE_STL activé, TinyXML supporte les flux C++ (operator <<,>>) ainsi que les flux C (FILE*). Il y a quelques différences dont vous devez être conscient.

Entrée/sortie de style C :
	- basé sur FILE*
	- les méthodes Print() et SaveFile()

	Génère une sortie formatée, avec beaucoup d'espaces blancs, destinée à être aussi lisible que possible par un humain. Ils sont très rapides et tolérants aux documents XML mal formés. Par exemple, un document XML contenant 2 éléments racines et 2 déclarations sera quand même imprimé.

Entrée de style C :
	- basé sur FILE*
	- les méthodes Parse() et LoadFile()

	Une lecture rapide et tolérante. Utilisez-la lorsque vous n'avez pas besoin des flux C++.

Sortie de style C++ :
	- basé sur std::ostream
	- operator<<

	Génère une sortie condensée, destinée à la transmission réseau plutôt qu'à la lisibilité. Selon l'implémentation de la classe ostream de votre système, celles-ci peuvent être un peu plus lentes. (Ou pas.) Pas tolérante au XML mal formé : un document doit contenir le bon élément racine unique. Les éléments racine supplémentaires ne seront pas diffusés.

Entrée de style C++ :
	- basé sur std::istream
	- operator>>

	Lit le XML depuis un flux, ce qui le rend utile pour la transmission réseau. La partie délicate est de savoir quand le document XML est complet, car il y aura presque certainement d'autres données dans le flux. TinyXML considérera les données XML comme complètes après avoir lu l'élément racine. Autrement dit, les documents mal construits avec plus d'un élément racine ne seront pas lus correctement. Notez également que operator>> est un peu plus lent que Parse, en raison à la fois de l'implémentation de la STL et des limitations de TinyXML.

<h3> Espaces blancs </h3>
Le monde entier n'est tout simplement pas d'accord sur la question de savoir si les espaces blancs doivent être conservés ou condensés. Par exemple, imaginez que le '_' est un espace, et regardez "Hello____world". HTML, et au moins certains analyseurs XML, interpréteront cela comme "Hello_world". Ils condensent les espaces blancs. Certains analyseurs XML ne le font pas, et le laisseront comme "Hello____world". (N'oubliez pas de continuer à imaginer que le _ est un espace.) D'autres suggèrent que __Hello___world__ devrait devenir Hello___world.

C'est un problème qui n'a pas été résolu à ma satisfaction. TinyXML supporte les 2 premières approches. Appelez TiXmlBase::SetCondenseWhiteSpace( bool ) pour définir le comportement souhaité. La valeur par défaut est de condenser les espaces blancs.

Si vous modifiez la valeur par défaut, vous devez appeler TiXmlBase::SetCondenseWhiteSpace( bool ) avant de faire des appels pour analyser des données XML, et je ne recommande pas de le modifier après qu'il a été défini.

<h3> Handles </h3>

Lors de la navigation robuste dans un document XML, il est important de vérifier les retours nuls des appels de méthode. Une implémentation sécurisée contre les erreurs peut générer beaucoup de code comme :

@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 )
			{
				// Enfin faire quelque chose d'utile.
@endverbatim

Les handles ont été introduits pour nettoyer cela. En utilisant la classe TiXmlHandle, le code précédent se réduit à :

@verbatim
TiXmlHandle docHandle( &document );
TiXmlElement* child2 = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", 1 ).ToElement();
if ( child2 )
{
	// faire quelque chose d'utile
@endverbatim

Ce qui est beaucoup plus facile à gérer. Voir TiXmlHandle pour plus d'informations.

<h3> Suivi des lignes et des colonnes </h3>
Pouvoir suivre les nœuds et les attributs jusqu'à leur emplacement d'origine dans les fichiers source peut être très important pour certaines applications. De plus, savoir où les erreurs d'analyse se sont produites dans la source originale peut faire gagner beaucoup de temps.

TinyXML peut suivre l'origine de la ligne et de la colonne de tous les nœuds et attributs dans un fichier texte. Les méthodes TiXmlBase::Row() et TiXmlBase::Column() renvoient l'origine du nœud dans le texte source. Les tabulations correctes peuvent être configurées dans TiXmlDocument::SetTabSize().

<h2> Utilisation et installation </h2>

Pour compiler et exécuter xmltest :

Un Makefile Linux et un fichier .dsw Visual C++ Windows sont fournis. Compilez et exécutez simplement. Il écrira le fichier demotest.xml sur votre disque et générera une sortie à l'écran. Il teste également le parcours du DOM en affichant le nombre de nœuds trouvés en utilisant différentes techniques.

Le makefile Linux est très générique et fonctionne sur de nombreux systèmes - il est actuellement testé sur mingw et MacOSX. Vous n'avez pas besoin d'exécuter 'make depend'. Les dépendances ont été codées en dur.

<h3>Fichier projet Windows pour VC6</h3>
<ul>
<li>tinyxml:		bibliothèque tinyxml, non-STL </li>
<li>tinyxmlSTL:		bibliothèque tinyxml, STL </li>
<li>tinyXmlTest:	application de test, non-STL </li>
<li>tinyXmlTestSTL: application de test, STL </li>
</ul>

<h3>Makefile</h3>
En haut du makefile, vous pouvez définir :

PROFILE, DEBUG, et TINYXML_USE_STL. Les détails (tels quels) sont dans le makefile.

Dans le répertoire tinyxml, tapez "make clean" puis "make". Le fichier exécutable 'xmltest' sera créé.

<h3>Pour utiliser dans une application :</h3>

Ajoutez tinyxml.cpp, tinyxml.h, tinyxmlerror.cpp, tinyxmlparser.cpp, tinystr.cpp et tinystr.h à votre projet ou fichier make. C'est tout ! Cela devrait compiler sur tout système raisonnablement conforme au C++. Vous n'avez pas besoin d'activer les exceptions ou le RTTI pour TinyXML.

<h2> Comment TinyXML fonctionne.  </h2>

Un exemple est probablement la meilleure façon de procéder. Prenez :
@verbatim
	<?xml version="1.0" standalone=no>
	<!-- Notre liste de tâches à faire -->
	<ToDo>
		<Item priority="1"> Aller au <bold>magasin de jouets !</bold></Item>
		<Item priority="2"> Faire les factures</Item>
	</ToDo>
@endverbatim

Ce n'est pas une grande liste de tâches, mais cela fera l'affaire. Pour lire ce fichier (disons "demo.xml"), vous créeriez un document et l'analyseriez :
@verbatim
	TiXmlDocument doc( "demo.xml" );
	doc.LoadFile();
@endverbatim

Et c'est prêt. Regardons maintenant quelques lignes et leur relation avec le DOM.

@verbatim
<?xml version="1.0" standalone=no>
@endverbatim

	La première ligne est une déclaration, et devient la classe TiXmlDeclaration. Ce sera le premier enfant du nœud document.
	
	C'est la seule directive/balise spéciale analysée par TinyXML. Généralement, les balises de directive sont stockées dans TiXmlUnknown afin que les commandes ne soient pas perdues lors de la sauvegarde sur le disque.

@verbatim
<!-- Notre liste de tâches à faire -->
@endverbatim

	Un commentaire. Deviendra un objet TiXmlComment.

@verbatim
<ToDo>
@endverbatim

	La balise "ToDo" définit un objet TiXmlElement. Celui-ci n'a pas d'attributs, mais contient 2 autres éléments.

@verbatim
<Item priority="1"> 
@endverbatim

	Crée un autre TiXmlElement qui est un enfant de l'élément "ToDo". Cet élément a 1 attribut, avec le nom "priority" et la valeur "1".

@verbatim
Go to the
@endverbatim 

	Un TiXmlText. C'est un nœud feuille et ne peut pas contenir d'autres nœuds. C'est un enfant du TiXmlElement "Item".

@verbatim
<bold>
@endverbatim

	
	Un autre TiXmlElement, celui-ci enfant de l'élément "Item".

Etc.

En regardant l'arbre d'objets complet, vous obtenez :
@verbatim
TiXmlDocument					"demo.xml"
	TiXmlDeclaration			"version='1.0'" "standalone=no"
	TiXmlComment				" Notre liste de tâches à faire"
	TiXmlElement				"ToDo"
		TiXmlElement			"Item" Attributs : priority = 1
			TiXmlText			"Go to the "
			TiXmlElement		"bold"
				TiXmlText		"magasin de jouets !"
		TiXmlElement			"Item" Attributs : priority=2
			TiXmlText			"Faire les factures"
@endverbatim

<h2> Documentation </h2>

La documentation est construite avec Doxygen, en utilisant le fichier de configuration 'dox'.

<h2> Licence </h2>

TinyXML est distribué sous la licence zlib :

Ce logiciel est fourni « en l'état », sans aucune garantie expresse ou implicite. En aucun cas les auteurs ne pourront être tenus responsables des dommages résultant de l'utilisation de ce logiciel.

Permission est accordée à quiconque d'utiliser ce logiciel à des fins quelconques, y compris les applications commerciales, et de le modifier et de le redistribuer librement, sous réserve des restrictions suivantes :

1. L'origine de ce logiciel ne doit pas être présentée de manière trompeuse ; vous ne devez pas prétendre avoir écrit le logiciel original. Si vous utilisez ce logiciel dans un produit, une mention dans la documentation du produit serait appréciée mais n'est pas requise.

2. Les versions sources modifiées doivent être clairement marquées comme telles et ne doivent pas être présentées comme étant le logiciel original.

3. Cette notice ne peut être supprimée ou modifiée à partir de toute distribution source.

<h2> Références  </h2>

Le World Wide Web Consortium est l'organisme de normalisation de référence pour XML, et ses pages web contiennent d'énormes quantités d'informations.

La spécification de référence : <a href="http://www.w3.org/TR/2004/REC-xml-20040204/">
http://www.w3.org/TR/2004/REC-xml-20040204/</a>

Je recommande également « XML Pocket Reference » de Robert Eckstein et publié par O'Reilly... le livre qui a lancé toute l'affaire.

<h2> Contributeurs, contacts et une brève histoire </h2>

Un grand merci à tous ceux qui envoient des suggestions, des bogues, des idées et des encouragements. Tout cela aide et rend ce projet amusant. Un merci spécial aux contributeurs sur les pages web qui le maintiennent vivant.

Tant de gens ont envoyé des bogues et des idées, que plutôt que de les lister ici, nous essayons de donner crédit dans le fichier "changes.txt".

TinyXML a été initialement écrit par Lee Thomason. (Souvent le « Je » est encore dans la documentation.) Lee révise les modifications et publie de nouvelles versions, avec l'aide de Yves Berquin, Andrew Ellerton et de la communauté tinyXml.

Nous apprécions vos suggestions et aimerions savoir si vous utilisez TinyXML. Nous espérons que vous l'apprécierez et le trouverez utile. Veuillez poser des questions, commenter, signaler des bogues ou nous contacter à :

www.sourceforge.net/projects/tinyxml

Lee Thomason, Yves Berquin, Andrew Ellerton
*/