541 lines
22 KiB
C++
541 lines
22 KiB
C++
// Copyright (C) 2002-2005 Nikolaus Gebhardt
|
|
// This file is part of the "Irrlicht Engine" and the "irrXML" project.
|
|
// For conditions of distribution and use, see copyright notice in irrlicht.h and/or irrXML.h
|
|
|
|
#ifndef __IRR_XML_H_INCLUDED__
|
|
#define __IRR_XML_H_INCLUDED__
|
|
|
|
#include <stdio.h>
|
|
|
|
/** \mainpage irrXML 1.2 API documentation
|
|
<div align="center"><img src="logobig.png" ></div>
|
|
|
|
\section intro Introduction
|
|
|
|
Welcome to the irrXML API documentation.
|
|
Here you'll find any information you'll need to develop applications with
|
|
irrXML. If you look for a tutorial on how to start, take a look at the \ref irrxmlexample,
|
|
at the homepage of irrXML at <A HREF="http://xml.irrlicht3d.org" >xml.irrlicht3d.org</A>
|
|
or into the SDK in the directory \example.
|
|
|
|
irrXML is intended to be a high speed and easy-to-use XML Parser for C++, and
|
|
this documentation is an important part of it. If you have any questions or
|
|
suggestions, just send a email to the author of the engine, Nikolaus Gebhardt
|
|
(niko (at) irrlicht3d.org). For more informations about this parser, see \ref history.
|
|
|
|
\section features Features
|
|
|
|
irrXML provides forward-only, read-only
|
|
access to a stream of non validated XML data. It was fully implemented by
|
|
Nikolaus Gebhardt. Its current features are:
|
|
|
|
- It it fast as lighting and has very low memory usage. It was
|
|
developed with the intention of being used in 3D games, as it already has been.
|
|
- irrXML is very small: It only consists of 60 KB of code and can be added easily
|
|
to your existing project.
|
|
- Of course, it is platform independent and works with lots of compilers.
|
|
- It is able to parse ASCII, UTF-8, UTF-16 and UTF-32 text files, both in
|
|
little and big endian format.
|
|
- Independent of the input file format, the parser can return all strings in ASCII, UTF-8,
|
|
UTF-16 and UTF-32 format.
|
|
- With its optional file access abstraction it has the advantage that it can read not
|
|
only from files but from any type of data (memory, network, ...). For example when
|
|
used with the Irrlicht Engine, it directly reads from compressed .zip files.
|
|
- Just like the Irrlicht Engine for which it was originally created, it is extremely easy
|
|
to use.
|
|
- It has no external dependencies, it does not even need the STL.
|
|
|
|
Although irrXML has some strenghts, it currently also has the following limitations:
|
|
|
|
- The input xml file is not validated and assumed to be correct.
|
|
|
|
\section irrxmlexample Example
|
|
|
|
The following code demonstrates the basic usage of irrXML. A simple xml
|
|
file like this is parsed:
|
|
\code
|
|
<?xml version="1.0"?>
|
|
<config>
|
|
<!-- This is a config file for the mesh viewer -->
|
|
<model file="dwarf.dea" />
|
|
<messageText caption="Irrlicht Engine Mesh Viewer">
|
|
Welcome to the Mesh Viewer of the "Irrlicht Engine".
|
|
</messageText>
|
|
</config>
|
|
\endcode
|
|
|
|
The code for parsing this file would look like this:
|
|
\code
|
|
#include <irrXML.h>
|
|
using namespace irr; // irrXML is located in the namespace irr::io
|
|
using namespace io;
|
|
|
|
#include <string> // we use STL strings to store data in this example
|
|
|
|
void main()
|
|
{
|
|
// create the reader using one of the factory functions
|
|
|
|
IrrXMLReader* xml = createIrrXMLReader("config.xml");
|
|
|
|
// strings for storing the data we want to get out of the file
|
|
std::string modelFile;
|
|
std::string messageText;
|
|
std::string caption;
|
|
|
|
// parse the file until end reached
|
|
|
|
while(xml && xml->read())
|
|
{
|
|
switch(xml->getNodeType())
|
|
{
|
|
case EXN_TEXT:
|
|
// in this xml file, the only text which occurs is the messageText
|
|
messageText = xml->getNodeData();
|
|
break;
|
|
case EXN_ELEMENT:
|
|
{
|
|
if (!strcmp("model", xml->getNodeName()))
|
|
modelFile = xml->getAttributeValue("file");
|
|
else
|
|
if (!strcmp("messageText", xml->getNodeName()))
|
|
caption = xml->getAttributeValue("caption");
|
|
}
|
|
break;
|
|
}
|
|
}
|
|
|
|
// delete the xml parser after usage
|
|
delete xml;
|
|
}
|
|
\endcode
|
|
|
|
\section howto How to use
|
|
|
|
Simply add the source files in the /src directory of irrXML to your project. Done.
|
|
|
|
\section license License
|
|
|
|
The irrXML license is based on the zlib license. Basicly, this means you can do with
|
|
irrXML whatever you want:
|
|
|
|
Copyright (C) 2002-2005 Nikolaus Gebhardt
|
|
|
|
This software is provided 'as-is', without any express or implied
|
|
warranty. In no event will the authors be held liable for any damages
|
|
arising from the use of this software.
|
|
|
|
Permission is granted to anyone to use this software for any purpose,
|
|
including commercial applications, and to alter it and redistribute it
|
|
freely, subject to the following restrictions:
|
|
|
|
1. The origin of this software must not be misrepresented; you must not
|
|
claim that you wrote the original software. If you use this software
|
|
in a product, an acknowledgment in the product documentation would be
|
|
appreciated but is not required.
|
|
|
|
2. Altered source versions must be plainly marked as such, and must not be
|
|
misrepresented as being the original software.
|
|
|
|
3. This notice may not be removed or altered from any source distribution.
|
|
|
|
\section history History
|
|
|
|
As lots of references in this documentation and the source show, this xml
|
|
parser has originally been a part of the
|
|
<A HREF="http://irrlicht.sourceforge.net" >Irrlicht Engine</A>. But because
|
|
the parser has become very useful with the latest release, people asked for a
|
|
separate version of it, to be able to use it in non Irrlicht projects. With
|
|
irrXML 1.0, this has now been done.
|
|
*/
|
|
|
|
namespace irr
|
|
{
|
|
namespace io
|
|
{
|
|
//! Enumeration of all supported source text file formats
|
|
enum ETEXT_FORMAT
|
|
{
|
|
//! ASCII, file without byte order mark, or not a text file
|
|
ETF_ASCII,
|
|
|
|
//! UTF-8 format
|
|
ETF_UTF8,
|
|
|
|
//! UTF-16 format, big endian
|
|
ETF_UTF16_BE,
|
|
|
|
//! UTF-16 format, little endian
|
|
ETF_UTF16_LE,
|
|
|
|
//! UTF-32 format, big endian
|
|
ETF_UTF32_BE,
|
|
|
|
//! UTF-32 format, little endian
|
|
ETF_UTF32_LE
|
|
};
|
|
|
|
|
|
//! Enumeration for all xml nodes which are parsed by IrrXMLReader
|
|
enum EXML_NODE
|
|
{
|
|
//! No xml node. This is usually the node if you did not read anything yet.
|
|
EXN_NONE,
|
|
|
|
//! A xml element, like <foo>
|
|
EXN_ELEMENT,
|
|
|
|
//! End of an xml element, like </foo>
|
|
EXN_ELEMENT_END,
|
|
|
|
//! Text within a xml element: <foo> this is the text. </foo>
|
|
EXN_TEXT,
|
|
|
|
//! An xml comment like <!-- I am a comment --> or a DTD definition.
|
|
EXN_COMMENT,
|
|
|
|
//! An xml cdata section like <![CDATA[ this is some CDATA ]]>
|
|
EXN_CDATA,
|
|
|
|
//! Unknown element.
|
|
EXN_UNKNOWN
|
|
};
|
|
|
|
//! Callback class for file read abstraction.
|
|
/** With this, it is possible to make the xml parser read in other things
|
|
than just files. The Irrlicht engine is using this for example to
|
|
read xml from compressed .zip files. To make the parser read in
|
|
any other data, derive a class from this interface, implement the
|
|
two methods to read your data and give a pointer to an instance of
|
|
your implementation when calling createIrrXMLReader(),
|
|
createIrrXMLReaderUTF16() or createIrrXMLReaderUTF32() */
|
|
class IFileReadCallBack
|
|
{
|
|
public:
|
|
|
|
//! virtual destructor
|
|
virtual ~IFileReadCallBack() {};
|
|
|
|
//! Reads an amount of bytes from the file.
|
|
/** \param buffer: Pointer to buffer where to read bytes will be written to.
|
|
\param sizeToRead: Amount of bytes to read from the file.
|
|
\return Returns how much bytes were read. */
|
|
virtual int read(void* buffer, int sizeToRead) = 0;
|
|
|
|
//! Returns size of file in bytes
|
|
virtual int getSize() = 0;
|
|
};
|
|
|
|
//! Empty class to be used as parent class for IrrXMLReader.
|
|
/** If you need another class as base class for the xml reader, you can do this by creating
|
|
the reader using for example new CXMLReaderImpl<char, YourBaseClass>(yourcallback);
|
|
The Irrlicht Engine for example needs IUnknown as base class for every object to
|
|
let it automaticly reference countend, hence it replaces IXMLBase with IUnknown.
|
|
See irrXML.cpp on how this can be done in detail. */
|
|
class IXMLBase
|
|
{
|
|
};
|
|
|
|
//! Interface providing easy read access to a XML file.
|
|
/** You can create an instance of this reader using one of the factory functions
|
|
createIrrXMLReader(), createIrrXMLReaderUTF16() and createIrrXMLReaderUTF32().
|
|
If using the parser from the Irrlicht Engine, please use IFileSystem::createXMLReader()
|
|
instead.
|
|
For a detailed intro how to use the parser, see \ref irrxmlexample and \ref features.
|
|
|
|
The typical usage of this parser looks like this:
|
|
\code
|
|
#include <irrXML.h>
|
|
using namespace irr; // irrXML is located in the namespace irr::io
|
|
using namespace io;
|
|
|
|
void main()
|
|
{
|
|
// create the reader using one of the factory functions
|
|
IrrXMLReader* xml = createIrrXMLReader("config.xml");
|
|
|
|
if (xml == 0)
|
|
return; // file could not be opened
|
|
|
|
// parse the file until end reached
|
|
while(xml->read())
|
|
{
|
|
// based on xml->getNodeType(), do something.
|
|
}
|
|
|
|
// delete the xml parser after usage
|
|
delete xml;
|
|
}
|
|
\endcode
|
|
See \ref irrxmlexample for a more detailed example.
|
|
*/
|
|
template<class char_type, class super_class>
|
|
class IIrrXMLReader : public super_class
|
|
{
|
|
public:
|
|
|
|
//! Destructor
|
|
virtual ~IIrrXMLReader() {};
|
|
|
|
//! Reads forward to the next xml node.
|
|
/** \return Returns false, if there was no further node. */
|
|
virtual bool read() = 0;
|
|
|
|
//! Returns the type of the current XML node.
|
|
virtual EXML_NODE getNodeType() const = 0;
|
|
|
|
//! Returns attribute count of the current XML node.
|
|
/** This is usually
|
|
non null if the current node is EXN_ELEMENT, and the element has attributes.
|
|
\return Returns amount of attributes of this xml node. */
|
|
virtual int getAttributeCount() const = 0;
|
|
|
|
//! Returns name of an attribute.
|
|
/** \param idx: Zero based index, should be something between 0 and getAttributeCount()-1.
|
|
\return Name of the attribute, 0 if an attribute with this index does not exist. */
|
|
virtual const char_type* getAttributeName(int idx) const = 0;
|
|
|
|
//! Returns the value of an attribute.
|
|
/** \param idx: Zero based index, should be something between 0 and getAttributeCount()-1.
|
|
\return Value of the attribute, 0 if an attribute with this index does not exist. */
|
|
virtual const char_type* getAttributeValue(int idx) const = 0;
|
|
|
|
//! Returns the value of an attribute.
|
|
/** \param name: Name of the attribute.
|
|
\return Value of the attribute, 0 if an attribute with this name does not exist. */
|
|
virtual const char_type* getAttributeValue(const char_type* name) const = 0;
|
|
|
|
//! Returns the value of an attribute in a safe way.
|
|
/** Like getAttributeValue(), but does not
|
|
return 0 if the attribute does not exist. An empty string ("") is returned then.
|
|
\param name: Name of the attribute.
|
|
\return Value of the attribute, and "" if an attribute with this name does not exist */
|
|
virtual const char_type* getAttributeValueSafe(const char_type* name) const = 0;
|
|
|
|
//! Returns the value of an attribute as integer.
|
|
/** \param name Name of the attribute.
|
|
\return Value of the attribute as integer, and 0 if an attribute with this name does not exist or
|
|
the value could not be interpreted as integer. */
|
|
virtual int getAttributeValueAsInt(const char_type* name) const = 0;
|
|
|
|
//! Returns the value of an attribute as integer.
|
|
/** \param idx: Zero based index, should be something between 0 and getAttributeCount()-1.
|
|
\return Value of the attribute as integer, and 0 if an attribute with this index does not exist or
|
|
the value could not be interpreted as integer. */
|
|
virtual int getAttributeValueAsInt(int idx) const = 0;
|
|
|
|
//! Returns the value of an attribute as float.
|
|
/** \param name: Name of the attribute.
|
|
\return Value of the attribute as float, and 0 if an attribute with this name does not exist or
|
|
the value could not be interpreted as float. */
|
|
virtual float getAttributeValueAsFloat(const char_type* name) const = 0;
|
|
|
|
//! Returns the value of an attribute as float.
|
|
/** \param idx: Zero based index, should be something between 0 and getAttributeCount()-1.
|
|
\return Value of the attribute as float, and 0 if an attribute with this index does not exist or
|
|
the value could not be interpreted as float. */
|
|
virtual float getAttributeValueAsFloat(int idx) const = 0;
|
|
|
|
//! Returns the name of the current node.
|
|
/** Only non null, if the node type is EXN_ELEMENT.
|
|
\return Name of the current node or 0 if the node has no name. */
|
|
virtual const char_type* getNodeName() const = 0;
|
|
|
|
//! Returns data of the current node.
|
|
/** Only non null if the node has some
|
|
data and it is of type EXN_TEXT or EXN_UNKNOWN. */
|
|
virtual const char_type* getNodeData() const = 0;
|
|
|
|
//! Returns if an element is an empty element, like <foo />
|
|
virtual bool isEmptyElement() const = 0;
|
|
|
|
//! Returns format of the source xml file.
|
|
/** It is not necessary to use
|
|
this method because the parser will convert the input file format
|
|
to the format wanted by the user when creating the parser. This
|
|
method is useful to get/display additional informations. */
|
|
virtual ETEXT_FORMAT getSourceFormat() const = 0;
|
|
|
|
//! Returns format of the strings returned by the parser.
|
|
/** This will be UTF8 for example when you created a parser with
|
|
IrrXMLReaderUTF8() and UTF32 when it has been created using
|
|
IrrXMLReaderUTF32. It should not be necessary to call this
|
|
method and only exists for informational purposes. */
|
|
virtual ETEXT_FORMAT getParserFormat() const = 0;
|
|
};
|
|
|
|
|
|
//! defines the utf-16 type.
|
|
/** Not using wchar_t for this because
|
|
wchar_t has 16 bit on windows and 32 bit on other operating systems. */
|
|
typedef unsigned short char16;
|
|
|
|
//! defines the utf-32 type.
|
|
/** Not using wchar_t for this because
|
|
wchar_t has 16 bit on windows and 32 bit on other operating systems. */
|
|
typedef unsigned long char32;
|
|
|
|
//! A UTF-8 or ASCII character xml parser.
|
|
/** This means that all character data will be returned in 8 bit ASCII or UTF-8 by this parser.
|
|
The file to read can be in any format, it will be converted to UTF-8 if it is not
|
|
in this format.
|
|
Create an instance of this with createIrrXMLReader();
|
|
See IIrrXMLReader for description on how to use it. */
|
|
typedef IIrrXMLReader<char, IXMLBase> IrrXMLReader;
|
|
|
|
//! A UTF-16 xml parser.
|
|
/** This means that all character data will be returned in UTF-16 by this parser.
|
|
The file to read can be in any format, it will be converted to UTF-16 if it is not
|
|
in this format.
|
|
Create an instance of this with createIrrXMLReaderUTF16();
|
|
See IIrrXMLReader for description on how to use it. */
|
|
typedef IIrrXMLReader<char16, IXMLBase> IrrXMLReaderUTF16;
|
|
|
|
//! A UTF-32 xml parser.
|
|
/** This means that all character data will be returned in UTF-32 by this parser.
|
|
The file to read can be in any format, it will be converted to UTF-32 if it is not
|
|
in this format.
|
|
Create an instance of this with createIrrXMLReaderUTF32();
|
|
See IIrrXMLReader for description on how to use it. */
|
|
typedef IIrrXMLReader<char32, IXMLBase> IrrXMLReaderUTF32;
|
|
|
|
|
|
//! Creates an instance of an UFT-8 or ASCII character xml parser.
|
|
/** This means that all character data will be returned in 8 bit ASCII or UTF-8.
|
|
The file to read can be in any format, it will be converted to UTF-8 if it is not in this format.
|
|
If you are using the Irrlicht Engine, it is better not to use this function but
|
|
IFileSystem::createXMLReaderUTF8() instead.
|
|
\param filename: Name of file to be opened.
|
|
\return Returns a pointer to the created xml parser. This pointer should be
|
|
deleted using 'delete' after no longer needed. Returns 0 if an error occured
|
|
and the file could not be opened. */
|
|
IrrXMLReader* createIrrXMLReader(const char* filename);
|
|
|
|
//! Creates an instance of an UFT-8 or ASCII character xml parser.
|
|
/** This means that all character data will be returned in 8 bit ASCII or UTF-8. The file to read can
|
|
be in any format, it will be converted to UTF-8 if it is not in this format.
|
|
If you are using the Irrlicht Engine, it is better not to use this function but
|
|
IFileSystem::createXMLReaderUTF8() instead.
|
|
\param file: Pointer to opened file, must have been opened in binary mode, e.g.
|
|
using fopen("foo.bar", "wb"); The file will not be closed after it has been read.
|
|
\return Returns a pointer to the created xml parser. This pointer should be
|
|
deleted using 'delete' after no longer needed. Returns 0 if an error occured
|
|
and the file could not be opened. */
|
|
IrrXMLReader* createIrrXMLReader(FILE* file);
|
|
|
|
//! Creates an instance of an UFT-8 or ASCII character xml parser.
|
|
/** This means that all character data will be returned in 8 bit ASCII or UTF-8. The file to read can
|
|
be in any format, it will be converted to UTF-8 if it is not in this format.
|
|
If you are using the Irrlicht Engine, it is better not to use this function but
|
|
IFileSystem::createXMLReaderUTF8() instead.
|
|
\param callback: Callback for file read abstraction. Implement your own
|
|
callback to make the xml parser read in other things than just files. See
|
|
IFileReadCallBack for more information about this.
|
|
\return Returns a pointer to the created xml parser. This pointer should be
|
|
deleted using 'delete' after no longer needed. Returns 0 if an error occured
|
|
and the file could not be opened. */
|
|
IrrXMLReader* createIrrXMLReader(IFileReadCallBack* callback);
|
|
|
|
//! Creates an instance of an UFT-16 xml parser.
|
|
/** This means that
|
|
all character data will be returned in UTF-16. The file to read can
|
|
be in any format, it will be converted to UTF-16 if it is not in this format.
|
|
If you are using the Irrlicht Engine, it is better not to use this function but
|
|
IFileSystem::createXMLReader() instead.
|
|
\param filename: Name of file to be opened.
|
|
\return Returns a pointer to the created xml parser. This pointer should be
|
|
deleted using 'delete' after no longer needed. Returns 0 if an error occured
|
|
and the file could not be opened. */
|
|
IrrXMLReaderUTF16* createIrrXMLReaderUTF16(const char* filename);
|
|
|
|
//! Creates an instance of an UFT-16 xml parser.
|
|
/** This means that all character data will be returned in UTF-16. The file to read can
|
|
be in any format, it will be converted to UTF-16 if it is not in this format.
|
|
If you are using the Irrlicht Engine, it is better not to use this function but
|
|
IFileSystem::createXMLReader() instead.
|
|
\param file: Pointer to opened file, must have been opened in binary mode, e.g.
|
|
using fopen("foo.bar", "wb"); The file will not be closed after it has been read.
|
|
\return Returns a pointer to the created xml parser. This pointer should be
|
|
deleted using 'delete' after no longer needed. Returns 0 if an error occured
|
|
and the file could not be opened. */
|
|
IrrXMLReaderUTF16* createIrrXMLReaderUTF16(FILE* file);
|
|
|
|
//! Creates an instance of an UFT-16 xml parser.
|
|
/** This means that all character data will be returned in UTF-16. The file to read can
|
|
be in any format, it will be converted to UTF-16 if it is not in this format.
|
|
If you are using the Irrlicht Engine, it is better not to use this function but
|
|
IFileSystem::createXMLReader() instead.
|
|
\param callback: Callback for file read abstraction. Implement your own
|
|
callback to make the xml parser read in other things than just files. See
|
|
IFileReadCallBack for more information about this.
|
|
\return Returns a pointer to the created xml parser. This pointer should be
|
|
deleted using 'delete' after no longer needed. Returns 0 if an error occured
|
|
and the file could not be opened. */
|
|
IrrXMLReaderUTF16* createIrrXMLReaderUTF16(IFileReadCallBack* callback);
|
|
|
|
|
|
//! Creates an instance of an UFT-32 xml parser.
|
|
/** This means that all character data will be returned in UTF-32. The file to read can
|
|
be in any format, it will be converted to UTF-32 if it is not in this format.
|
|
If you are using the Irrlicht Engine, it is better not to use this function but
|
|
IFileSystem::createXMLReader() instead.
|
|
\param filename: Name of file to be opened.
|
|
\return Returns a pointer to the created xml parser. This pointer should be
|
|
deleted using 'delete' after no longer needed. Returns 0 if an error occured
|
|
and the file could not be opened. */
|
|
IrrXMLReaderUTF32* createIrrXMLReaderUTF32(const char* filename);
|
|
|
|
//! Creates an instance of an UFT-32 xml parser.
|
|
/** This means that all character data will be returned in UTF-32. The file to read can
|
|
be in any format, it will be converted to UTF-32 if it is not in this format.
|
|
if you are using the Irrlicht Engine, it is better not to use this function but
|
|
IFileSystem::createXMLReader() instead.
|
|
\param file: Pointer to opened file, must have been opened in binary mode, e.g.
|
|
using fopen("foo.bar", "wb"); The file will not be closed after it has been read.
|
|
\return Returns a pointer to the created xml parser. This pointer should be
|
|
deleted using 'delete' after no longer needed. Returns 0 if an error occured
|
|
and the file could not be opened. */
|
|
IrrXMLReaderUTF32* createIrrXMLReaderUTF32(FILE* file);
|
|
|
|
//! Creates an instance of an UFT-32 xml parser.
|
|
/** This means that
|
|
all character data will be returned in UTF-32. The file to read can
|
|
be in any format, it will be converted to UTF-32 if it is not in this format.
|
|
If you are using the Irrlicht Engine, it is better not to use this function but
|
|
IFileSystem::createXMLReader() instead.
|
|
\param callback: Callback for file read abstraction. Implement your own
|
|
callback to make the xml parser read in other things than just files. See
|
|
IFileReadCallBack for more information about this.
|
|
\return Returns a pointer to the created xml parser. This pointer should be
|
|
deleted using 'delete' after no longer needed. Returns 0 if an error occured
|
|
and the file could not be opened. */
|
|
IrrXMLReaderUTF32* createIrrXMLReaderUTF32(IFileReadCallBack* callback);
|
|
|
|
|
|
/*! \file irrxml.h
|
|
\brief Header file of the irrXML, the Irrlicht XML parser.
|
|
|
|
This file includes everything needed for using irrXML,
|
|
the XML parser of the Irrlicht Engine. To use irrXML,
|
|
you only need to include this file in your project:
|
|
|
|
\code
|
|
#include <irrXML.h>
|
|
\endcode
|
|
|
|
It is also common to use the two namespaces in which irrXML is included,
|
|
directly after #including irrXML.h:
|
|
|
|
\code
|
|
#include <irrXML.h>
|
|
using namespace irr;
|
|
using namespace io;
|
|
\endcode
|
|
*/
|
|
|
|
} // end namespace io
|
|
} // end namespace irr
|
|
|
|
#endif // __IRR_XML_H_INCLUDED__
|
|
|