1
// Copyright (C) 2002-2011 Nikolaus Gebhardt
2
// This file is part of the "Irrlicht Engine" and the "irrXML" project.
3
// For conditions of distribution and use, see copyright notice in irrlicht.h and/or irrXML.h
5
#ifndef __IRR_XML_H_INCLUDED__
6
#define __IRR_XML_H_INCLUDED__
9
#include "IrrCompileConfig.h"
11
/** \mainpage irrXML 1.2 API documentation
12
<div align="center"><img src="logobig.png" ></div>
14
\section intro Introduction
16
Welcome to the irrXML API documentation.
17
Here you'll find any information you'll need to develop applications with
18
irrXML. If you look for a tutorial on how to start, take a look at the \ref irrxmlexample,
19
at the homepage of irrXML at <A HREF="http://www.ambiera.com/irrxml/">www.ambiera.com/irrxml/</A>
20
or into the SDK in the directory example.
22
irrXML is intended to be a high speed and easy-to-use XML Parser for C++, and
23
this documentation is an important part of it. If you have any questions or
24
suggestions, just send a email to the author of the engine, Nikolaus Gebhardt
25
(niko (at) irrlicht3d.org). For more informations about this parser, see \ref history.
27
\section features Features
29
irrXML provides forward-only, read-only
30
access to a stream of non validated XML data. It was fully implemented by
31
Nikolaus Gebhardt. Its current features are:
33
- It it fast as lighting and has very low memory usage. It was
34
developed with the intention of being used in 3D games, as it already has been.
35
- irrXML is very small: It only consists of 60 KB of code and can be added easily
36
to your existing project.
37
- Of course, it is platform independent and works with lots of compilers.
38
- It is able to parse ASCII, UTF-8, UTF-16 and UTF-32 text files, both in
39
little and big endian format.
40
- Independent of the input file format, the parser can return all strings in ASCII, UTF-8,
41
UTF-16 and UTF-32 format.
42
- With its optional file access abstraction it has the advantage that it can read not
43
only from files but from any type of data (memory, network, ...). For example when
44
used with the Irrlicht Engine, it directly reads from compressed .zip files.
45
- Just like the Irrlicht Engine for which it was originally created, it is extremely easy
47
- It has no external dependencies, it does not even need the STL.
49
Although irrXML has some strenghts, it currently also has the following limitations:
51
- The input xml file is not validated and assumed to be correct.
53
\section irrxmlexample Example
55
The following code demonstrates the basic usage of irrXML. A simple xml
56
file like this is parsed:
60
<!-- This is a config file for the mesh viewer -->
61
<model file="dwarf.dea" />
62
<messageText caption="Irrlicht Engine Mesh Viewer">
63
Welcome to the Mesh Viewer of the "Irrlicht Engine".
68
The code for parsing this file would look like this:
71
using namespace irr; // irrXML is located in the namespace irr::io
74
#include <string> // we use STL strings to store data in this example
78
// create the reader using one of the factory functions
80
IrrXMLReader* xml = createIrrXMLReader("config.xml");
82
// strings for storing the data we want to get out of the file
83
std::string modelFile;
84
std::string messageText;
87
// parse the file until end reached
89
while(xml && xml->read())
91
switch(xml->getNodeType())
94
// in this xml file, the only text which occurs is the messageText
95
messageText = xml->getNodeData();
99
if (!strcmp("model", xml->getNodeName()))
100
modelFile = xml->getAttributeValue("file");
102
if (!strcmp("messageText", xml->getNodeName()))
103
caption = xml->getAttributeValue("caption");
109
// delete the xml parser after usage
114
\section howto How to use
116
Simply add the source files in the /src directory of irrXML to your project. Done.
118
\section license License
120
The irrXML license is based on the zlib license. Basicly, this means you can do with
121
irrXML whatever you want:
123
Copyright (C) 2002-2011 Nikolaus Gebhardt
125
This software is provided 'as-is', without any express or implied
126
warranty. In no event will the authors be held liable for any damages
127
arising from the use of this software.
129
Permission is granted to anyone to use this software for any purpose,
130
including commercial applications, and to alter it and redistribute it
131
freely, subject to the following restrictions:
133
1. The origin of this software must not be misrepresented; you must not
134
claim that you wrote the original software. If you use this software
135
in a product, an acknowledgment in the product documentation would be
136
appreciated but is not required.
138
2. Altered source versions must be plainly marked as such, and must not be
139
misrepresented as being the original software.
141
3. This notice may not be removed or altered from any source distribution.
143
\section history History
145
As lots of references in this documentation and the source show, this xml
146
parser has originally been a part of the
147
<A HREF="http://irrlicht.sourceforge.net" >Irrlicht Engine</A>. But because
148
the parser has become very useful with the latest release, people asked for a
149
separate version of it, to be able to use it in non Irrlicht projects. With
150
irrXML 1.0, this has now been done.
157
//! Enumeration of all supported source text file formats
160
//! ASCII, file without byte order mark, or not a text file
166
//! UTF-16 format, big endian
169
//! UTF-16 format, little endian
172
//! UTF-32 format, big endian
175
//! UTF-32 format, little endian
180
//! Enumeration for all xml nodes which are parsed by IrrXMLReader
183
//! No xml node. This is usually the node if you did not read anything yet.
186
//! An xml element such as <foo>
189
//! End of an xml element such as </foo>
192
//! Text within an xml element: <foo> this is the text. <foo>
195
//! An xml comment like <!-- I am a comment --> or a DTD definition.
198
//! An xml cdata section like <![CDATA[ this is some CDATA ]]>
205
//! Callback class for file read abstraction.
206
/** With this, it is possible to make the xml parser read in other
207
things than just files. The Irrlicht engine is using this for example to
208
read xml from compressed .zip files. To make the parser read in
209
any other data, derive a class from this interface, implement the
210
two methods to read your data and give a pointer to an instance of
211
your implementation when calling createIrrXMLReader(),
212
createIrrXMLReaderUTF16() or createIrrXMLReaderUTF32() */
213
class IFileReadCallBack
218
virtual ~IFileReadCallBack() {}
220
//! Reads an amount of bytes from the file.
221
/** \param buffer: Pointer to buffer where to read bytes will be written to.
222
\param sizeToRead: Amount of bytes to read from the file.
223
\return Returns how much bytes were read. */
224
virtual int read(void* buffer, int sizeToRead) = 0;
226
//! Returns size of file in bytes
227
virtual long getSize() const = 0;
230
//! Empty class to be used as parent class for IrrXMLReader.
231
/** If you need another class as base class for the xml reader, you can do this by creating
232
the reader using for example new CXMLReaderImpl<char, YourBaseClass>(yourcallback);
233
The Irrlicht Engine for example needs IReferenceCounted as base class for every object to
234
let it automaticly reference countend, hence it replaces IXMLBase with IReferenceCounted.
235
See irrXML.cpp on how this can be done in detail. */
240
//! Interface providing easy read access to a XML file.
241
/** You can create an instance of this reader using one of the factory functions
242
createIrrXMLReader(), createIrrXMLReaderUTF16() and createIrrXMLReaderUTF32().
243
If using the parser from the Irrlicht Engine, please use IFileSystem::createXMLReader()
245
For a detailed intro how to use the parser, see \ref irrxmlexample and \ref features.
247
The typical usage of this parser looks like this:
250
using namespace irr; // irrXML is located in the namespace irr::io
255
// create the reader using one of the factory functions
256
IrrXMLReader* xml = createIrrXMLReader("config.xml");
259
return; // file could not be opened
261
// parse the file until end reached
264
// based on xml->getNodeType(), do something.
267
// delete the xml parser after usage
271
See \ref irrxmlexample for a more detailed example.
273
template<class char_type, class super_class>
274
class IIrrXMLReader : public super_class
279
virtual ~IIrrXMLReader() {}
281
//! Reads forward to the next xml node.
282
/** \return Returns false, if there was no further node. */
283
virtual bool read() = 0;
285
//! Returns the type of the current XML node.
286
virtual EXML_NODE getNodeType() const = 0;
288
//! Returns attribute count of the current XML node.
290
non null if the current node is EXN_ELEMENT, and the element has attributes.
291
\return Returns amount of attributes of this xml node. */
292
virtual unsigned int getAttributeCount() const = 0;
294
//! Returns name of an attribute.
295
/** \param idx: Zero based index, should be something between 0 and getAttributeCount()-1.
296
\return Name of the attribute, 0 if an attribute with this index does not exist. */
297
virtual const char_type* getAttributeName(int idx) const = 0;
299
//! Returns the value of an attribute.
300
/** \param idx: Zero based index, should be something between 0 and getAttributeCount()-1.
301
\return Value of the attribute, 0 if an attribute with this index does not exist. */
302
virtual const char_type* getAttributeValue(int idx) const = 0;
304
//! Returns the value of an attribute.
305
/** \param name: Name of the attribute.
306
\return Value of the attribute, 0 if an attribute with this name does not exist. */
307
virtual const char_type* getAttributeValue(const char_type* name) const = 0;
309
//! Returns the value of an attribute in a safe way.
310
/** Like getAttributeValue(), but does not
311
return 0 if the attribute does not exist. An empty string ("") is returned then.
312
\param name: Name of the attribute.
313
\return Value of the attribute, and "" if an attribute with this name does not exist */
314
virtual const char_type* getAttributeValueSafe(const char_type* name) const = 0;
316
//! Returns the value of an attribute as integer.
317
/** \param name Name of the attribute.
318
\return Value of the attribute as integer, and 0 if an attribute with this name does not exist or
319
the value could not be interpreted as integer. */
320
virtual int getAttributeValueAsInt(const char_type* name) const = 0;
322
//! Returns the value of an attribute as integer.
323
/** \param idx: Zero based index, should be something between 0 and getAttributeCount()-1.
324
\return Value of the attribute as integer, and 0 if an attribute with this index does not exist or
325
the value could not be interpreted as integer. */
326
virtual int getAttributeValueAsInt(int idx) const = 0;
328
//! Returns the value of an attribute as float.
329
/** \param name: Name of the attribute.
330
\return Value of the attribute as float, and 0 if an attribute with this name does not exist or
331
the value could not be interpreted as float. */
332
virtual float getAttributeValueAsFloat(const char_type* name) const = 0;
334
//! Returns the value of an attribute as float.
335
/** \param idx: Zero based index, should be something between 0 and getAttributeCount()-1.
336
\return Value of the attribute as float, and 0 if an attribute with this index does not exist or
337
the value could not be interpreted as float. */
338
virtual float getAttributeValueAsFloat(int idx) const = 0;
340
//! Returns the name of the current node.
341
/** Only non null, if the node type is EXN_ELEMENT.
342
\return Name of the current node or 0 if the node has no name. */
343
virtual const char_type* getNodeName() const = 0;
345
//! Returns data of the current node.
346
/** Only non null if the node has some
347
data and it is of type EXN_TEXT or EXN_UNKNOWN. */
348
virtual const char_type* getNodeData() const = 0;
350
//! Returns if an element is an empty element, like <foo />
351
virtual bool isEmptyElement() const = 0;
353
//! Returns format of the source xml file.
354
/** It is not necessary to use
355
this method because the parser will convert the input file format
356
to the format wanted by the user when creating the parser. This
357
method is useful to get/display additional informations. */
358
virtual ETEXT_FORMAT getSourceFormat() const = 0;
360
//! Returns format of the strings returned by the parser.
361
/** This will be UTF8 for example when you created a parser with
362
IrrXMLReaderUTF8() and UTF32 when it has been created using
363
IrrXMLReaderUTF32. It should not be necessary to call this
364
method and only exists for informational purposes. */
365
virtual ETEXT_FORMAT getParserFormat() const = 0;
369
template <typename T>
374
xmlChar<T>(char in) : c(static_cast<T>(in)) {}
375
xmlChar<T>(wchar_t in) : c(static_cast<T>(in)) {}
376
explicit xmlChar<T>(unsigned char in) : c(static_cast<T>(in)) {}
377
explicit xmlChar<T>(unsigned short in) : c(static_cast<T>(in)) {}
378
explicit xmlChar<T>(unsigned int in) : c(static_cast<T>(in)) {}
379
explicit xmlChar<T>(unsigned long in) : c(static_cast<T>(in)) {}
380
operator T() const { return c; }
381
void operator=(int t) { c=static_cast<T>(t); }
384
//! defines the utf-16 type.
385
/** Not using wchar_t for this because
386
wchar_t has 16 bit on windows and 32 bit on other operating systems. */
387
typedef xmlChar<unsigned short> char16;
389
//! defines the utf-32 type.
390
/** Not using wchar_t for this because
391
wchar_t has 16 bit on windows and 32 bit on other operating systems. */
392
typedef xmlChar<unsigned int> char32;
394
//! A UTF-8 or ASCII character xml parser.
395
/** This means that all character data will be returned in 8 bit ASCII or UTF-8 by this parser.
396
The file to read can be in any format, it will be converted to UTF-8 if it is not
398
Create an instance of this with createIrrXMLReader();
399
See IIrrXMLReader for description on how to use it. */
400
typedef IIrrXMLReader<char, IXMLBase> IrrXMLReader;
402
//! A UTF-16 xml parser.
403
/** This means that all character data will be returned in UTF-16 by this parser.
404
The file to read can be in any format, it will be converted to UTF-16 if it is not
406
Create an instance of this with createIrrXMLReaderUTF16();
407
See IIrrXMLReader for description on how to use it. */
408
typedef IIrrXMLReader<char16, IXMLBase> IrrXMLReaderUTF16;
410
//! A UTF-32 xml parser.
411
/** This means that all character data will be returned in UTF-32 by this parser.
412
The file to read can be in any format, it will be converted to UTF-32 if it is not
414
Create an instance of this with createIrrXMLReaderUTF32();
415
See IIrrXMLReader for description on how to use it. */
416
typedef IIrrXMLReader<char32, IXMLBase> IrrXMLReaderUTF32;
419
//! Creates an instance of an UFT-8 or ASCII character xml parser.
420
/** This means that all character data will be returned in 8 bit ASCII or UTF-8.
421
The file to read can be in any format, it will be converted to UTF-8 if it is not in this format.
422
If you are using the Irrlicht Engine, it is better not to use this function but
423
IFileSystem::createXMLReaderUTF8() instead.
424
\param filename: Name of file to be opened.
425
\return Returns a pointer to the created xml parser. This pointer should be
426
deleted using 'delete' after no longer needed. Returns 0 if an error occured
427
and the file could not be opened. */
428
IRRLICHT_API IrrXMLReader* IRRCALLCONV createIrrXMLReader(const char* filename);
430
//! Creates an instance of an UFT-8 or ASCII character xml parser.
431
/** This means that all character data will be returned in 8 bit ASCII or UTF-8. The file to read can
432
be in any format, it will be converted to UTF-8 if it is not in this format.
433
If you are using the Irrlicht Engine, it is better not to use this function but
434
IFileSystem::createXMLReaderUTF8() instead.
435
\param file: Pointer to opened file, must have been opened in binary mode, e.g.
436
using fopen("foo.bar", "wb"); The file will not be closed after it has been read.
437
\return Returns a pointer to the created xml parser. This pointer should be
438
deleted using 'delete' after no longer needed. Returns 0 if an error occured
439
and the file could not be opened. */
440
IRRLICHT_API IrrXMLReader* IRRCALLCONV createIrrXMLReader(FILE* file);
442
//! Creates an instance of an UFT-8 or ASCII character xml parser.
443
/** This means that all character data will be returned in 8 bit ASCII or UTF-8. The file to read can
444
be in any format, it will be converted to UTF-8 if it is not in this format.
445
If you are using the Irrlicht Engine, it is better not to use this function but
446
IFileSystem::createXMLReaderUTF8() instead.
447
\param callback: Callback for file read abstraction. Implement your own
448
callback to make the xml parser read in other things than just files. See
449
IFileReadCallBack for more information about this.
450
\param deleteCallback: if true, the callback will be deleted after the file
451
has been read. Otherwise the caller si responsible for cleaning it up.
452
\return Returns a pointer to the created xml parser. This pointer should be
453
deleted using 'delete' after no longer needed. Returns 0 if an error occured
454
and the file could not be opened. */
455
IRRLICHT_API IrrXMLReader* IRRCALLCONV createIrrXMLReader(IFileReadCallBack* callback,
456
bool deleteCallback = false);
458
//! Creates an instance of an UFT-16 xml parser.
460
all character data will be returned in UTF-16. The file to read can
461
be in any format, it will be converted to UTF-16 if it is not in this format.
462
If you are using the Irrlicht Engine, it is better not to use this function but
463
IFileSystem::createXMLReader() instead.
464
\param filename: Name of file to be opened.
465
\return Returns a pointer to the created xml parser. This pointer should be
466
deleted using 'delete' after no longer needed. Returns 0 if an error occured
467
and the file could not be opened. */
468
IRRLICHT_API IrrXMLReaderUTF16* IRRCALLCONV createIrrXMLReaderUTF16(const char* filename);
470
//! Creates an instance of an UFT-16 xml parser.
471
/** This means that all character data will be returned in UTF-16. The file to read can
472
be in any format, it will be converted to UTF-16 if it is not in this format.
473
If you are using the Irrlicht Engine, it is better not to use this function but
474
IFileSystem::createXMLReader() instead.
475
\param file: Pointer to opened file, must have been opened in binary mode, e.g.
476
using fopen("foo.bar", "wb"); The file will not be closed after it has been read.
477
\return Returns a pointer to the created xml parser. This pointer should be
478
deleted using 'delete' after no longer needed. Returns 0 if an error occured
479
and the file could not be opened. */
480
IRRLICHT_API IrrXMLReaderUTF16* IRRCALLCONV createIrrXMLReaderUTF16(FILE* file);
482
//! Creates an instance of an UFT-16 xml parser.
483
/** This means that all character data will be returned in UTF-16. The file to read can
484
be in any format, it will be converted to UTF-16 if it is not in this format.
485
If you are using the Irrlicht Engine, it is better not to use this function but
486
IFileSystem::createXMLReader() instead.
487
\param callback: Callback for file read abstraction. Implement your own
488
callback to make the xml parser read in other things than just files. See
489
IFileReadCallBack for more information about this.
490
\param deleteCallback: if true, the callback will be deleted after the file
491
has been read. Otherwise the caller si responsible for cleaning it up.
492
\return Returns a pointer to the created xml parser. This pointer should be
493
deleted using 'delete' after no longer needed. Returns 0 if an error occured
494
and the file could not be opened. */
495
IRRLICHT_API IrrXMLReaderUTF16* IRRCALLCONV createIrrXMLReaderUTF16(IFileReadCallBack* callback,
496
bool deleteCallback = false);
499
//! Creates an instance of an UFT-32 xml parser.
500
/** This means that all character data will be returned in UTF-32. The file to read can
501
be in any format, it will be converted to UTF-32 if it is not in this format.
502
If you are using the Irrlicht Engine, it is better not to use this function but
503
IFileSystem::createXMLReader() instead.
504
\param filename: Name of file to be opened.
505
\return Returns a pointer to the created xml parser. This pointer should be
506
deleted using 'delete' after no longer needed. Returns 0 if an error occured
507
and the file could not be opened. */
508
IRRLICHT_API IrrXMLReaderUTF32* IRRCALLCONV createIrrXMLReaderUTF32(const char* filename);
510
//! Creates an instance of an UFT-32 xml parser.
511
/** This means that all character data will be returned in UTF-32. The file to read can
512
be in any format, it will be converted to UTF-32 if it is not in this format.
513
if you are using the Irrlicht Engine, it is better not to use this function but
514
IFileSystem::createXMLReader() instead.
515
\param file: Pointer to opened file, must have been opened in binary mode, e.g.
516
using fopen("foo.bar", "wb"); The file will not be closed after it has been read.
517
\return Returns a pointer to the created xml parser. This pointer should be
518
deleted using 'delete' after no longer needed. Returns 0 if an error occured
519
and the file could not be opened. */
520
IRRLICHT_API IrrXMLReaderUTF32* IRRCALLCONV createIrrXMLReaderUTF32(FILE* file);
522
//! Creates an instance of an UFT-32 xml parser.
524
all character data will be returned in UTF-32. The file to read can
525
be in any format, it will be converted to UTF-32 if it is not in this format.
526
If you are using the Irrlicht Engine, it is better not to use this function but
527
IFileSystem::createXMLReader() instead.
528
\param callback: Callback for file read abstraction. Implement your own
529
callback to make the xml parser read in other things than just files. See
530
IFileReadCallBack for more information about this.
531
\param deleteCallback: if true, the callback will be deleted after the file
532
has been read. Otherwise the caller si responsible for cleaning it up.
533
\return Returns a pointer to the created xml parser. This pointer should be
534
deleted using 'delete' after no longer needed. Returns 0 if an error occured
535
and the file could not be opened. */
536
IRRLICHT_API IrrXMLReaderUTF32* IRRCALLCONV createIrrXMLReaderUTF32(IFileReadCallBack* callback,
537
bool deleteCallback = false);
541
\brief Header file of the irrXML, the Irrlicht XML parser.
543
This file includes everything needed for using irrXML,
544
the XML parser of the Irrlicht Engine. To use irrXML,
545
you only need to include this file in your project:
551
It is also common to use the two namespaces in which irrXML is included,
552
directly after including irrXML.h:
561
} // end namespace io
562
} // end namespace irr
564
#endif // __IRR_XML_H_INCLUDED__
added
removed
include/irrXML.h
