Hendrik Lipka
A port of the irrlicht XML parser library.
irrXML.h@0:41a49a73580c, 2010-11-17 (annotated)
- Committer:
- hlipka
- Date:
- Wed Nov 17 20:19:41 2010 +0000
- Revision:
- 0:41a49a73580c
initial version
Who changed what in which revision?
| User | Revision | Line number | New contents of line |
|---|---|---|---|
| hlipka | 0:41a49a73580c | 1 | // Copyright (C) 2002-2005 Nikolaus Gebhardt |
| hlipka | 0:41a49a73580c | 2 | // This file is part of the "Irrlicht Engine" and the "irrXML" project. |
| hlipka | 0:41a49a73580c | 3 | // For conditions of distribution and use, see copyright notice in irrlicht.h and/or irrXML.h |
| hlipka | 0:41a49a73580c | 4 | |
| hlipka | 0:41a49a73580c | 5 | #ifndef __IRR_XML_H_INCLUDED__ |
| hlipka | 0:41a49a73580c | 6 | #define __IRR_XML_H_INCLUDED__ |
| hlipka | 0:41a49a73580c | 7 | |
| hlipka | 0:41a49a73580c | 8 | #include <stdio.h> |
| hlipka | 0:41a49a73580c | 9 | |
| hlipka | 0:41a49a73580c | 10 | /** \mainpage irrXML 1.2 API documentation |
| hlipka | 0:41a49a73580c | 11 | <div align="center"><img src="logobig.png" ></div> |
| hlipka | 0:41a49a73580c | 12 | |
| hlipka | 0:41a49a73580c | 13 | \section intro Introduction |
| hlipka | 0:41a49a73580c | 14 | |
| hlipka | 0:41a49a73580c | 15 | Welcome to the irrXML API documentation. |
| hlipka | 0:41a49a73580c | 16 | Here you'll find any information you'll need to develop applications with |
| hlipka | 0:41a49a73580c | 17 | irrXML. If you look for a tutorial on how to start, take a look at the \ref irrxmlexample, |
| hlipka | 0:41a49a73580c | 18 | at the homepage of irrXML at <A HREF="http://xml.irrlicht3d.org" >xml.irrlicht3d.org</A> |
| hlipka | 0:41a49a73580c | 19 | or into the SDK in the directory \example. |
| hlipka | 0:41a49a73580c | 20 | |
| hlipka | 0:41a49a73580c | 21 | irrXML is intended to be a high speed and easy-to-use XML Parser for C++, and |
| hlipka | 0:41a49a73580c | 22 | this documentation is an important part of it. If you have any questions or |
| hlipka | 0:41a49a73580c | 23 | suggestions, just send a email to the author of the engine, Nikolaus Gebhardt |
| hlipka | 0:41a49a73580c | 24 | (niko (at) irrlicht3d.org). For more informations about this parser, see \ref history. |
| hlipka | 0:41a49a73580c | 25 | |
| hlipka | 0:41a49a73580c | 26 | \section features Features |
| hlipka | 0:41a49a73580c | 27 | |
| hlipka | 0:41a49a73580c | 28 | irrXML provides forward-only, read-only |
| hlipka | 0:41a49a73580c | 29 | access to a stream of non validated XML data. It was fully implemented by |
| hlipka | 0:41a49a73580c | 30 | Nikolaus Gebhardt. Its current features are: |
| hlipka | 0:41a49a73580c | 31 | |
| hlipka | 0:41a49a73580c | 32 | - It it fast as lighting and has very low memory usage. It was |
| hlipka | 0:41a49a73580c | 33 | developed with the intention of being used in 3D games, as it already has been. |
| hlipka | 0:41a49a73580c | 34 | - irrXML is very small: It only consists of 60 KB of code and can be added easily |
| hlipka | 0:41a49a73580c | 35 | to your existing project. |
| hlipka | 0:41a49a73580c | 36 | - Of course, it is platform independent and works with lots of compilers. |
| hlipka | 0:41a49a73580c | 37 | - It is able to parse ASCII, UTF-8, UTF-16 and UTF-32 text files, both in |
| hlipka | 0:41a49a73580c | 38 | little and big endian format. |
| hlipka | 0:41a49a73580c | 39 | - Independent of the input file format, the parser can return all strings in ASCII, UTF-8, |
| hlipka | 0:41a49a73580c | 40 | UTF-16 and UTF-32 format. |
| hlipka | 0:41a49a73580c | 41 | - With its optional file access abstraction it has the advantage that it can read not |
| hlipka | 0:41a49a73580c | 42 | only from files but from any type of data (memory, network, ...). For example when |
| hlipka | 0:41a49a73580c | 43 | used with the Irrlicht Engine, it directly reads from compressed .zip files. |
| hlipka | 0:41a49a73580c | 44 | - Just like the Irrlicht Engine for which it was originally created, it is extremely easy |
| hlipka | 0:41a49a73580c | 45 | to use. |
| hlipka | 0:41a49a73580c | 46 | - It has no external dependencies, it does not even need the STL. |
| hlipka | 0:41a49a73580c | 47 | |
| hlipka | 0:41a49a73580c | 48 | Although irrXML has some strenghts, it currently also has the following limitations: |
| hlipka | 0:41a49a73580c | 49 | |
| hlipka | 0:41a49a73580c | 50 | - The input xml file is not validated and assumed to be correct. |
| hlipka | 0:41a49a73580c | 51 | |
| hlipka | 0:41a49a73580c | 52 | \section irrxmlexample Example |
| hlipka | 0:41a49a73580c | 53 | |
| hlipka | 0:41a49a73580c | 54 | The following code demonstrates the basic usage of irrXML. A simple xml |
| hlipka | 0:41a49a73580c | 55 | file like this is parsed: |
| hlipka | 0:41a49a73580c | 56 | \code |
| hlipka | 0:41a49a73580c | 57 | <?xml version="1.0"?> |
| hlipka | 0:41a49a73580c | 58 | <config> |
| hlipka | 0:41a49a73580c | 59 | <!-- This is a config file for the mesh viewer --> |
| hlipka | 0:41a49a73580c | 60 | <model file="dwarf.dea" /> |
| hlipka | 0:41a49a73580c | 61 | <messageText caption="Irrlicht Engine Mesh Viewer"> |
| hlipka | 0:41a49a73580c | 62 | Welcome to the Mesh Viewer of the "Irrlicht Engine". |
| hlipka | 0:41a49a73580c | 63 | </messageText> |
| hlipka | 0:41a49a73580c | 64 | </config> |
| hlipka | 0:41a49a73580c | 65 | \endcode |
| hlipka | 0:41a49a73580c | 66 | |
| hlipka | 0:41a49a73580c | 67 | The code for parsing this file would look like this: |
| hlipka | 0:41a49a73580c | 68 | \code |
| hlipka | 0:41a49a73580c | 69 | #include <irrXML.h> |
| hlipka | 0:41a49a73580c | 70 | using namespace irr; // irrXML is located in the namespace irr::io |
| hlipka | 0:41a49a73580c | 71 | using namespace io; |
| hlipka | 0:41a49a73580c | 72 | |
| hlipka | 0:41a49a73580c | 73 | #include <string> // we use STL strings to store data in this example |
| hlipka | 0:41a49a73580c | 74 | |
| hlipka | 0:41a49a73580c | 75 | void main() |
| hlipka | 0:41a49a73580c | 76 | { |
| hlipka | 0:41a49a73580c | 77 | // create the reader using one of the factory functions |
| hlipka | 0:41a49a73580c | 78 | |
| hlipka | 0:41a49a73580c | 79 | IrrXMLReader* xml = createIrrXMLReader("config.xml"); |
| hlipka | 0:41a49a73580c | 80 | |
| hlipka | 0:41a49a73580c | 81 | // strings for storing the data we want to get out of the file |
| hlipka | 0:41a49a73580c | 82 | std::string modelFile; |
| hlipka | 0:41a49a73580c | 83 | std::string messageText; |
| hlipka | 0:41a49a73580c | 84 | std::string caption; |
| hlipka | 0:41a49a73580c | 85 | |
| hlipka | 0:41a49a73580c | 86 | // parse the file until end reached |
| hlipka | 0:41a49a73580c | 87 | |
| hlipka | 0:41a49a73580c | 88 | while(xml && xml->read()) |
| hlipka | 0:41a49a73580c | 89 | { |
| hlipka | 0:41a49a73580c | 90 | switch(xml->getNodeType()) |
| hlipka | 0:41a49a73580c | 91 | { |
| hlipka | 0:41a49a73580c | 92 | case EXN_TEXT: |
| hlipka | 0:41a49a73580c | 93 | // in this xml file, the only text which occurs is the messageText |
| hlipka | 0:41a49a73580c | 94 | messageText = xml->getNodeData(); |
| hlipka | 0:41a49a73580c | 95 | break; |
| hlipka | 0:41a49a73580c | 96 | case EXN_ELEMENT: |
| hlipka | 0:41a49a73580c | 97 | { |
| hlipka | 0:41a49a73580c | 98 | if (!strcmp("model", xml->getNodeName())) |
| hlipka | 0:41a49a73580c | 99 | modelFile = xml->getAttributeValue("file"); |
| hlipka | 0:41a49a73580c | 100 | else |
| hlipka | 0:41a49a73580c | 101 | if (!strcmp("messageText", xml->getNodeName())) |
| hlipka | 0:41a49a73580c | 102 | caption = xml->getAttributeValue("caption"); |
| hlipka | 0:41a49a73580c | 103 | } |
| hlipka | 0:41a49a73580c | 104 | break; |
| hlipka | 0:41a49a73580c | 105 | } |
| hlipka | 0:41a49a73580c | 106 | } |
| hlipka | 0:41a49a73580c | 107 | |
| hlipka | 0:41a49a73580c | 108 | // delete the xml parser after usage |
| hlipka | 0:41a49a73580c | 109 | delete xml; |
| hlipka | 0:41a49a73580c | 110 | } |
| hlipka | 0:41a49a73580c | 111 | \endcode |
| hlipka | 0:41a49a73580c | 112 | |
| hlipka | 0:41a49a73580c | 113 | \section howto How to use |
| hlipka | 0:41a49a73580c | 114 | |
| hlipka | 0:41a49a73580c | 115 | Simply add the source files in the /src directory of irrXML to your project. Done. |
| hlipka | 0:41a49a73580c | 116 | |
| hlipka | 0:41a49a73580c | 117 | \section license License |
| hlipka | 0:41a49a73580c | 118 | |
| hlipka | 0:41a49a73580c | 119 | The irrXML license is based on the zlib license. Basicly, this means you can do with |
| hlipka | 0:41a49a73580c | 120 | irrXML whatever you want: |
| hlipka | 0:41a49a73580c | 121 | |
| hlipka | 0:41a49a73580c | 122 | Copyright (C) 2002-2005 Nikolaus Gebhardt |
| hlipka | 0:41a49a73580c | 123 | |
| hlipka | 0:41a49a73580c | 124 | This software is provided 'as-is', without any express or implied |
| hlipka | 0:41a49a73580c | 125 | warranty. In no event will the authors be held liable for any damages |
| hlipka | 0:41a49a73580c | 126 | arising from the use of this software. |
| hlipka | 0:41a49a73580c | 127 | |
| hlipka | 0:41a49a73580c | 128 | Permission is granted to anyone to use this software for any purpose, |
| hlipka | 0:41a49a73580c | 129 | including commercial applications, and to alter it and redistribute it |
| hlipka | 0:41a49a73580c | 130 | freely, subject to the following restrictions: |
| hlipka | 0:41a49a73580c | 131 | |
| hlipka | 0:41a49a73580c | 132 | 1. The origin of this software must not be misrepresented; you must not |
| hlipka | 0:41a49a73580c | 133 | claim that you wrote the original software. If you use this software |
| hlipka | 0:41a49a73580c | 134 | in a product, an acknowledgment in the product documentation would be |
| hlipka | 0:41a49a73580c | 135 | appreciated but is not required. |
| hlipka | 0:41a49a73580c | 136 | |
| hlipka | 0:41a49a73580c | 137 | 2. Altered source versions must be plainly marked as such, and must not be |
| hlipka | 0:41a49a73580c | 138 | misrepresented as being the original software. |
| hlipka | 0:41a49a73580c | 139 | |
| hlipka | 0:41a49a73580c | 140 | 3. This notice may not be removed or altered from any source distribution. |
| hlipka | 0:41a49a73580c | 141 | |
| hlipka | 0:41a49a73580c | 142 | \section history History |
| hlipka | 0:41a49a73580c | 143 | |
| hlipka | 0:41a49a73580c | 144 | As lots of references in this documentation and the source show, this xml |
| hlipka | 0:41a49a73580c | 145 | parser has originally been a part of the |
| hlipka | 0:41a49a73580c | 146 | <A HREF="http://irrlicht.sourceforge.net" >Irrlicht Engine</A>. But because |
| hlipka | 0:41a49a73580c | 147 | the parser has become very useful with the latest release, people asked for a |
| hlipka | 0:41a49a73580c | 148 | separate version of it, to be able to use it in non Irrlicht projects. With |
| hlipka | 0:41a49a73580c | 149 | irrXML 1.0, this has now been done. |
| hlipka | 0:41a49a73580c | 150 | */ |
| hlipka | 0:41a49a73580c | 151 | |
| hlipka | 0:41a49a73580c | 152 | namespace irr |
| hlipka | 0:41a49a73580c | 153 | { |
| hlipka | 0:41a49a73580c | 154 | namespace io |
| hlipka | 0:41a49a73580c | 155 | { |
| hlipka | 0:41a49a73580c | 156 | //! Enumeration of all supported source text file formats |
| hlipka | 0:41a49a73580c | 157 | enum ETEXT_FORMAT |
| hlipka | 0:41a49a73580c | 158 | { |
| hlipka | 0:41a49a73580c | 159 | //! ASCII, file without byte order mark, or not a text file |
| hlipka | 0:41a49a73580c | 160 | ETF_ASCII, |
| hlipka | 0:41a49a73580c | 161 | |
| hlipka | 0:41a49a73580c | 162 | //! UTF-8 format |
| hlipka | 0:41a49a73580c | 163 | ETF_UTF8, |
| hlipka | 0:41a49a73580c | 164 | |
| hlipka | 0:41a49a73580c | 165 | //! UTF-16 format, big endian |
| hlipka | 0:41a49a73580c | 166 | ETF_UTF16_BE, |
| hlipka | 0:41a49a73580c | 167 | |
| hlipka | 0:41a49a73580c | 168 | //! UTF-16 format, little endian |
| hlipka | 0:41a49a73580c | 169 | ETF_UTF16_LE, |
| hlipka | 0:41a49a73580c | 170 | |
| hlipka | 0:41a49a73580c | 171 | //! UTF-32 format, big endian |
| hlipka | 0:41a49a73580c | 172 | ETF_UTF32_BE, |
| hlipka | 0:41a49a73580c | 173 | |
| hlipka | 0:41a49a73580c | 174 | //! UTF-32 format, little endian |
| hlipka | 0:41a49a73580c | 175 | ETF_UTF32_LE, |
| hlipka | 0:41a49a73580c | 176 | }; |
| hlipka | 0:41a49a73580c | 177 | |
| hlipka | 0:41a49a73580c | 178 | |
| hlipka | 0:41a49a73580c | 179 | //! Enumeration for all xml nodes which are parsed by IrrXMLReader |
| hlipka | 0:41a49a73580c | 180 | enum EXML_NODE |
| hlipka | 0:41a49a73580c | 181 | { |
| hlipka | 0:41a49a73580c | 182 | //! No xml node. This is usually the node if you did not read anything yet. |
| hlipka | 0:41a49a73580c | 183 | EXN_NONE, |
| hlipka | 0:41a49a73580c | 184 | |
| hlipka | 0:41a49a73580c | 185 | //! A xml element, like <foo> |
| hlipka | 0:41a49a73580c | 186 | EXN_ELEMENT, |
| hlipka | 0:41a49a73580c | 187 | |
| hlipka | 0:41a49a73580c | 188 | //! End of an xml element, like </foo> |
| hlipka | 0:41a49a73580c | 189 | EXN_ELEMENT_END, |
| hlipka | 0:41a49a73580c | 190 | |
| hlipka | 0:41a49a73580c | 191 | //! Text within a xml element: <foo> this is the text. </foo> |
| hlipka | 0:41a49a73580c | 192 | EXN_TEXT, |
| hlipka | 0:41a49a73580c | 193 | |
| hlipka | 0:41a49a73580c | 194 | //! An xml comment like <!-- I am a comment --> or a DTD definition. |
| hlipka | 0:41a49a73580c | 195 | EXN_COMMENT, |
| hlipka | 0:41a49a73580c | 196 | |
| hlipka | 0:41a49a73580c | 197 | //! An xml cdata section like <![CDATA[ this is some CDATA ]]> |
| hlipka | 0:41a49a73580c | 198 | EXN_CDATA, |
| hlipka | 0:41a49a73580c | 199 | |
| hlipka | 0:41a49a73580c | 200 | //! Unknown element. |
| hlipka | 0:41a49a73580c | 201 | EXN_UNKNOWN |
| hlipka | 0:41a49a73580c | 202 | }; |
| hlipka | 0:41a49a73580c | 203 | |
| hlipka | 0:41a49a73580c | 204 | //! Callback class for file read abstraction. |
| hlipka | 0:41a49a73580c | 205 | /** With this, it is possible to make the xml parser read in other things |
| hlipka | 0:41a49a73580c | 206 | than just files. The Irrlicht engine is using this for example to |
| hlipka | 0:41a49a73580c | 207 | read xml from compressed .zip files. To make the parser read in |
| hlipka | 0:41a49a73580c | 208 | any other data, derive a class from this interface, implement the |
| hlipka | 0:41a49a73580c | 209 | two methods to read your data and give a pointer to an instance of |
| hlipka | 0:41a49a73580c | 210 | your implementation when calling createIrrXMLReader(), |
| hlipka | 0:41a49a73580c | 211 | createIrrXMLReaderUTF16() or createIrrXMLReaderUTF32() */ |
| hlipka | 0:41a49a73580c | 212 | class IFileReadCallBack |
| hlipka | 0:41a49a73580c | 213 | { |
| hlipka | 0:41a49a73580c | 214 | public: |
| hlipka | 0:41a49a73580c | 215 | |
| hlipka | 0:41a49a73580c | 216 | //! virtual destructor |
| hlipka | 0:41a49a73580c | 217 | virtual ~IFileReadCallBack() {}; |
| hlipka | 0:41a49a73580c | 218 | |
| hlipka | 0:41a49a73580c | 219 | //! Reads an amount of bytes from the file. |
| hlipka | 0:41a49a73580c | 220 | /** \param buffer: Pointer to buffer where to read bytes will be written to. |
| hlipka | 0:41a49a73580c | 221 | \param sizeToRead: Amount of bytes to read from the file. |
| hlipka | 0:41a49a73580c | 222 | \return Returns how much bytes were read. */ |
| hlipka | 0:41a49a73580c | 223 | virtual int read(void* buffer, int sizeToRead) = 0; |
| hlipka | 0:41a49a73580c | 224 | |
| hlipka | 0:41a49a73580c | 225 | //! Returns size of file in bytes |
| hlipka | 0:41a49a73580c | 226 | virtual int getSize() = 0; |
| hlipka | 0:41a49a73580c | 227 | }; |
| hlipka | 0:41a49a73580c | 228 | |
| hlipka | 0:41a49a73580c | 229 | //! Empty class to be used as parent class for IrrXMLReader. |
| hlipka | 0:41a49a73580c | 230 | /** If you need another class as base class for the xml reader, you can do this by creating |
| hlipka | 0:41a49a73580c | 231 | the reader using for example new CXMLReaderImpl<char, YourBaseClass>(yourcallback); |
| hlipka | 0:41a49a73580c | 232 | The Irrlicht Engine for example needs IUnknown as base class for every object to |
| hlipka | 0:41a49a73580c | 233 | let it automaticly reference countend, hence it replaces IXMLBase with IUnknown. |
| hlipka | 0:41a49a73580c | 234 | See irrXML.cpp on how this can be done in detail. */ |
| hlipka | 0:41a49a73580c | 235 | class IXMLBase |
| hlipka | 0:41a49a73580c | 236 | { |
| hlipka | 0:41a49a73580c | 237 | }; |
| hlipka | 0:41a49a73580c | 238 | |
| hlipka | 0:41a49a73580c | 239 | //! Interface providing easy read access to a XML file. |
| hlipka | 0:41a49a73580c | 240 | /** You can create an instance of this reader using one of the factory functions |
| hlipka | 0:41a49a73580c | 241 | createIrrXMLReader(), createIrrXMLReaderUTF16() and createIrrXMLReaderUTF32(). |
| hlipka | 0:41a49a73580c | 242 | If using the parser from the Irrlicht Engine, please use IFileSystem::createXMLReader() |
| hlipka | 0:41a49a73580c | 243 | instead. |
| hlipka | 0:41a49a73580c | 244 | For a detailed intro how to use the parser, see \ref irrxmlexample and \ref features. |
| hlipka | 0:41a49a73580c | 245 | |
| hlipka | 0:41a49a73580c | 246 | The typical usage of this parser looks like this: |
| hlipka | 0:41a49a73580c | 247 | \code |
| hlipka | 0:41a49a73580c | 248 | #include <irrXML.h> |
| hlipka | 0:41a49a73580c | 249 | using namespace irr; // irrXML is located in the namespace irr::io |
| hlipka | 0:41a49a73580c | 250 | using namespace io; |
| hlipka | 0:41a49a73580c | 251 | |
| hlipka | 0:41a49a73580c | 252 | void main() |
| hlipka | 0:41a49a73580c | 253 | { |
| hlipka | 0:41a49a73580c | 254 | // create the reader using one of the factory functions |
| hlipka | 0:41a49a73580c | 255 | IrrXMLReader* xml = createIrrXMLReader("config.xml"); |
| hlipka | 0:41a49a73580c | 256 | |
| hlipka | 0:41a49a73580c | 257 | if (xml == 0) |
| hlipka | 0:41a49a73580c | 258 | return; // file could not be opened |
| hlipka | 0:41a49a73580c | 259 | |
| hlipka | 0:41a49a73580c | 260 | // parse the file until end reached |
| hlipka | 0:41a49a73580c | 261 | while(xml->read()) |
| hlipka | 0:41a49a73580c | 262 | { |
| hlipka | 0:41a49a73580c | 263 | // based on xml->getNodeType(), do something. |
| hlipka | 0:41a49a73580c | 264 | } |
| hlipka | 0:41a49a73580c | 265 | |
| hlipka | 0:41a49a73580c | 266 | // delete the xml parser after usage |
| hlipka | 0:41a49a73580c | 267 | delete xml; |
| hlipka | 0:41a49a73580c | 268 | } |
| hlipka | 0:41a49a73580c | 269 | \endcode |
| hlipka | 0:41a49a73580c | 270 | See \ref irrxmlexample for a more detailed example. |
| hlipka | 0:41a49a73580c | 271 | */ |
| hlipka | 0:41a49a73580c | 272 | template<class char_type, class super_class> |
| hlipka | 0:41a49a73580c | 273 | class IIrrXMLReader : public super_class |
| hlipka | 0:41a49a73580c | 274 | { |
| hlipka | 0:41a49a73580c | 275 | public: |
| hlipka | 0:41a49a73580c | 276 | |
| hlipka | 0:41a49a73580c | 277 | //! Destructor |
| hlipka | 0:41a49a73580c | 278 | virtual ~IIrrXMLReader() {}; |
| hlipka | 0:41a49a73580c | 279 | |
| hlipka | 0:41a49a73580c | 280 | //! Reads forward to the next xml node. |
| hlipka | 0:41a49a73580c | 281 | /** \return Returns false, if there was no further node. */ |
| hlipka | 0:41a49a73580c | 282 | virtual bool read() = 0; |
| hlipka | 0:41a49a73580c | 283 | |
| hlipka | 0:41a49a73580c | 284 | //! Returns the type of the current XML node. |
| hlipka | 0:41a49a73580c | 285 | virtual EXML_NODE getNodeType() const = 0; |
| hlipka | 0:41a49a73580c | 286 | |
| hlipka | 0:41a49a73580c | 287 | //! Returns attribute count of the current XML node. |
| hlipka | 0:41a49a73580c | 288 | /** This is usually |
| hlipka | 0:41a49a73580c | 289 | non null if the current node is EXN_ELEMENT, and the element has attributes. |
| hlipka | 0:41a49a73580c | 290 | \return Returns amount of attributes of this xml node. */ |
| hlipka | 0:41a49a73580c | 291 | virtual int getAttributeCount() const = 0; |
| hlipka | 0:41a49a73580c | 292 | |
| hlipka | 0:41a49a73580c | 293 | //! Returns name of an attribute. |
| hlipka | 0:41a49a73580c | 294 | /** \param idx: Zero based index, should be something between 0 and getAttributeCount()-1. |
| hlipka | 0:41a49a73580c | 295 | \return Name of the attribute, 0 if an attribute with this index does not exist. */ |
| hlipka | 0:41a49a73580c | 296 | virtual const char_type* getAttributeName(int idx) const = 0; |
| hlipka | 0:41a49a73580c | 297 | |
| hlipka | 0:41a49a73580c | 298 | //! Returns the value of an attribute. |
| hlipka | 0:41a49a73580c | 299 | /** \param idx: Zero based index, should be something between 0 and getAttributeCount()-1. |
| hlipka | 0:41a49a73580c | 300 | \return Value of the attribute, 0 if an attribute with this index does not exist. */ |
| hlipka | 0:41a49a73580c | 301 | virtual const char_type* getAttributeValue(int idx) const = 0; |
| hlipka | 0:41a49a73580c | 302 | |
| hlipka | 0:41a49a73580c | 303 | //! Returns the value of an attribute. |
| hlipka | 0:41a49a73580c | 304 | /** \param name: Name of the attribute. |
| hlipka | 0:41a49a73580c | 305 | \return Value of the attribute, 0 if an attribute with this name does not exist. */ |
| hlipka | 0:41a49a73580c | 306 | virtual const char_type* getAttributeValue(const char_type* name) const = 0; |
| hlipka | 0:41a49a73580c | 307 | |
| hlipka | 0:41a49a73580c | 308 | //! Returns the value of an attribute in a safe way. |
| hlipka | 0:41a49a73580c | 309 | /** Like getAttributeValue(), but does not |
| hlipka | 0:41a49a73580c | 310 | return 0 if the attribute does not exist. An empty string ("") is returned then. |
| hlipka | 0:41a49a73580c | 311 | \param name: Name of the attribute. |
| hlipka | 0:41a49a73580c | 312 | \return Value of the attribute, and "" if an attribute with this name does not exist */ |
| hlipka | 0:41a49a73580c | 313 | virtual const char_type* getAttributeValueSafe(const char_type* name) const = 0; |
| hlipka | 0:41a49a73580c | 314 | |
| hlipka | 0:41a49a73580c | 315 | //! Returns the value of an attribute as integer. |
| hlipka | 0:41a49a73580c | 316 | /** \param name Name of the attribute. |
| hlipka | 0:41a49a73580c | 317 | \return Value of the attribute as integer, and 0 if an attribute with this name does not exist or |
| hlipka | 0:41a49a73580c | 318 | the value could not be interpreted as integer. */ |
| hlipka | 0:41a49a73580c | 319 | virtual int getAttributeValueAsInt(const char_type* name) const = 0; |
| hlipka | 0:41a49a73580c | 320 | |
| hlipka | 0:41a49a73580c | 321 | //! Returns the value of an attribute as integer. |
| hlipka | 0:41a49a73580c | 322 | /** \param idx: Zero based index, should be something between 0 and getAttributeCount()-1. |
| hlipka | 0:41a49a73580c | 323 | \return Value of the attribute as integer, and 0 if an attribute with this index does not exist or |
| hlipka | 0:41a49a73580c | 324 | the value could not be interpreted as integer. */ |
| hlipka | 0:41a49a73580c | 325 | virtual int getAttributeValueAsInt(int idx) const = 0; |
| hlipka | 0:41a49a73580c | 326 | |
| hlipka | 0:41a49a73580c | 327 | //! Returns the value of an attribute as float. |
| hlipka | 0:41a49a73580c | 328 | /** \param name: Name of the attribute. |
| hlipka | 0:41a49a73580c | 329 | \return Value of the attribute as float, and 0 if an attribute with this name does not exist or |
| hlipka | 0:41a49a73580c | 330 | the value could not be interpreted as float. */ |
| hlipka | 0:41a49a73580c | 331 | virtual float getAttributeValueAsFloat(const char_type* name) const = 0; |
| hlipka | 0:41a49a73580c | 332 | |
| hlipka | 0:41a49a73580c | 333 | //! Returns the value of an attribute as float. |
| hlipka | 0:41a49a73580c | 334 | /** \param idx: Zero based index, should be something between 0 and getAttributeCount()-1. |
| hlipka | 0:41a49a73580c | 335 | \return Value of the attribute as float, and 0 if an attribute with this index does not exist or |
| hlipka | 0:41a49a73580c | 336 | the value could not be interpreted as float. */ |
| hlipka | 0:41a49a73580c | 337 | virtual float getAttributeValueAsFloat(int idx) const = 0; |
| hlipka | 0:41a49a73580c | 338 | |
| hlipka | 0:41a49a73580c | 339 | //! Returns the name of the current node. |
| hlipka | 0:41a49a73580c | 340 | /** Only non null, if the node type is EXN_ELEMENT. |
| hlipka | 0:41a49a73580c | 341 | \return Name of the current node or 0 if the node has no name. */ |
| hlipka | 0:41a49a73580c | 342 | virtual const char_type* getNodeName() const = 0; |
| hlipka | 0:41a49a73580c | 343 | |
| hlipka | 0:41a49a73580c | 344 | //! Returns data of the current node. |
| hlipka | 0:41a49a73580c | 345 | /** Only non null if the node has some |
| hlipka | 0:41a49a73580c | 346 | data and it is of type EXN_TEXT or EXN_UNKNOWN. */ |
| hlipka | 0:41a49a73580c | 347 | virtual const char_type* getNodeData() const = 0; |
| hlipka | 0:41a49a73580c | 348 | |
| hlipka | 0:41a49a73580c | 349 | //! Returns if an element is an empty element, like <foo /> |
| hlipka | 0:41a49a73580c | 350 | virtual bool isEmptyElement() const = 0; |
| hlipka | 0:41a49a73580c | 351 | |
| hlipka | 0:41a49a73580c | 352 | //! Returns format of the source xml file. |
| hlipka | 0:41a49a73580c | 353 | /** It is not necessary to use |
| hlipka | 0:41a49a73580c | 354 | this method because the parser will convert the input file format |
| hlipka | 0:41a49a73580c | 355 | to the format wanted by the user when creating the parser. This |
| hlipka | 0:41a49a73580c | 356 | method is useful to get/display additional informations. */ |
| hlipka | 0:41a49a73580c | 357 | virtual ETEXT_FORMAT getSourceFormat() const = 0; |
| hlipka | 0:41a49a73580c | 358 | |
| hlipka | 0:41a49a73580c | 359 | //! Returns format of the strings returned by the parser. |
| hlipka | 0:41a49a73580c | 360 | /** This will be UTF8 for example when you created a parser with |
| hlipka | 0:41a49a73580c | 361 | IrrXMLReaderUTF8() and UTF32 when it has been created using |
| hlipka | 0:41a49a73580c | 362 | IrrXMLReaderUTF32. It should not be necessary to call this |
| hlipka | 0:41a49a73580c | 363 | method and only exists for informational purposes. */ |
| hlipka | 0:41a49a73580c | 364 | virtual ETEXT_FORMAT getParserFormat() const = 0; |
| hlipka | 0:41a49a73580c | 365 | }; |
| hlipka | 0:41a49a73580c | 366 | |
| hlipka | 0:41a49a73580c | 367 | |
| hlipka | 0:41a49a73580c | 368 | //! defines the utf-16 type. |
| hlipka | 0:41a49a73580c | 369 | /** Not using wchar_t for this because |
| hlipka | 0:41a49a73580c | 370 | wchar_t has 16 bit on windows and 32 bit on other operating systems. */ |
| hlipka | 0:41a49a73580c | 371 | typedef unsigned short char16; |
| hlipka | 0:41a49a73580c | 372 | |
| hlipka | 0:41a49a73580c | 373 | //! defines the utf-32 type. |
| hlipka | 0:41a49a73580c | 374 | /** Not using wchar_t for this because |
| hlipka | 0:41a49a73580c | 375 | wchar_t has 16 bit on windows and 32 bit on other operating systems. */ |
| hlipka | 0:41a49a73580c | 376 | typedef unsigned long char32; |
| hlipka | 0:41a49a73580c | 377 | |
| hlipka | 0:41a49a73580c | 378 | //! A UTF-8 or ASCII character xml parser. |
| hlipka | 0:41a49a73580c | 379 | /** This means that all character data will be returned in 8 bit ASCII or UTF-8 by this parser. |
| hlipka | 0:41a49a73580c | 380 | The file to read can be in any format, it will be converted to UTF-8 if it is not |
| hlipka | 0:41a49a73580c | 381 | in this format. |
| hlipka | 0:41a49a73580c | 382 | Create an instance of this with createIrrXMLReader(); |
| hlipka | 0:41a49a73580c | 383 | See IIrrXMLReader for description on how to use it. */ |
| hlipka | 0:41a49a73580c | 384 | typedef IIrrXMLReader<char, IXMLBase> IrrXMLReader; |
| hlipka | 0:41a49a73580c | 385 | |
| hlipka | 0:41a49a73580c | 386 | //! A UTF-16 xml parser. |
| hlipka | 0:41a49a73580c | 387 | /** This means that all character data will be returned in UTF-16 by this parser. |
| hlipka | 0:41a49a73580c | 388 | The file to read can be in any format, it will be converted to UTF-16 if it is not |
| hlipka | 0:41a49a73580c | 389 | in this format. |
| hlipka | 0:41a49a73580c | 390 | Create an instance of this with createIrrXMLReaderUTF16(); |
| hlipka | 0:41a49a73580c | 391 | See IIrrXMLReader for description on how to use it. */ |
| hlipka | 0:41a49a73580c | 392 | typedef IIrrXMLReader<char16, IXMLBase> IrrXMLReaderUTF16; |
| hlipka | 0:41a49a73580c | 393 | |
| hlipka | 0:41a49a73580c | 394 | //! A UTF-32 xml parser. |
| hlipka | 0:41a49a73580c | 395 | /** This means that all character data will be returned in UTF-32 by this parser. |
| hlipka | 0:41a49a73580c | 396 | The file to read can be in any format, it will be converted to UTF-32 if it is not |
| hlipka | 0:41a49a73580c | 397 | in this format. |
| hlipka | 0:41a49a73580c | 398 | Create an instance of this with createIrrXMLReaderUTF32(); |
| hlipka | 0:41a49a73580c | 399 | See IIrrXMLReader for description on how to use it. */ |
| hlipka | 0:41a49a73580c | 400 | typedef IIrrXMLReader<char32, IXMLBase> IrrXMLReaderUTF32; |
| hlipka | 0:41a49a73580c | 401 | |
| hlipka | 0:41a49a73580c | 402 | |
| hlipka | 0:41a49a73580c | 403 | //! Creates an instance of an UFT-8 or ASCII character xml parser. |
| hlipka | 0:41a49a73580c | 404 | /** This means that all character data will be returned in 8 bit ASCII or UTF-8. |
| hlipka | 0:41a49a73580c | 405 | The file to read can be in any format, it will be converted to UTF-8 if it is not in this format. |
| hlipka | 0:41a49a73580c | 406 | If you are using the Irrlicht Engine, it is better not to use this function but |
| hlipka | 0:41a49a73580c | 407 | IFileSystem::createXMLReaderUTF8() instead. |
| hlipka | 0:41a49a73580c | 408 | \param filename: Name of file to be opened. |
| hlipka | 0:41a49a73580c | 409 | \return Returns a pointer to the created xml parser. This pointer should be |
| hlipka | 0:41a49a73580c | 410 | deleted using 'delete' after no longer needed. Returns 0 if an error occured |
| hlipka | 0:41a49a73580c | 411 | and the file could not be opened. */ |
| hlipka | 0:41a49a73580c | 412 | IrrXMLReader* createIrrXMLReader(const char* filename); |
| hlipka | 0:41a49a73580c | 413 | |
| hlipka | 0:41a49a73580c | 414 | //! Creates an instance of an UFT-8 or ASCII character xml parser. |
| hlipka | 0:41a49a73580c | 415 | /** This means that all character data will be returned in 8 bit ASCII or UTF-8. The file to read can |
| hlipka | 0:41a49a73580c | 416 | be in any format, it will be converted to UTF-8 if it is not in this format. |
| hlipka | 0:41a49a73580c | 417 | If you are using the Irrlicht Engine, it is better not to use this function but |
| hlipka | 0:41a49a73580c | 418 | IFileSystem::createXMLReaderUTF8() instead. |
| hlipka | 0:41a49a73580c | 419 | \param file: Pointer to opened file, must have been opened in binary mode, e.g. |
| hlipka | 0:41a49a73580c | 420 | using fopen("foo.bar", "wb"); The file will not be closed after it has been read. |
| hlipka | 0:41a49a73580c | 421 | \return Returns a pointer to the created xml parser. This pointer should be |
| hlipka | 0:41a49a73580c | 422 | deleted using 'delete' after no longer needed. Returns 0 if an error occured |
| hlipka | 0:41a49a73580c | 423 | and the file could not be opened. */ |
| hlipka | 0:41a49a73580c | 424 | IrrXMLReader* createIrrXMLReader(FILE* file); |
| hlipka | 0:41a49a73580c | 425 | |
| hlipka | 0:41a49a73580c | 426 | //! Creates an instance of an UFT-8 or ASCII character xml parser. |
| hlipka | 0:41a49a73580c | 427 | /** This means that all character data will be returned in 8 bit ASCII or UTF-8. The file to read can |
| hlipka | 0:41a49a73580c | 428 | be in any format, it will be converted to UTF-8 if it is not in this format. |
| hlipka | 0:41a49a73580c | 429 | If you are using the Irrlicht Engine, it is better not to use this function but |
| hlipka | 0:41a49a73580c | 430 | IFileSystem::createXMLReaderUTF8() instead. |
| hlipka | 0:41a49a73580c | 431 | \param callback: Callback for file read abstraction. Implement your own |
| hlipka | 0:41a49a73580c | 432 | callback to make the xml parser read in other things than just files. See |
| hlipka | 0:41a49a73580c | 433 | IFileReadCallBack for more information about this. |
| hlipka | 0:41a49a73580c | 434 | \return Returns a pointer to the created xml parser. This pointer should be |
| hlipka | 0:41a49a73580c | 435 | deleted using 'delete' after no longer needed. Returns 0 if an error occured |
| hlipka | 0:41a49a73580c | 436 | and the file could not be opened. */ |
| hlipka | 0:41a49a73580c | 437 | IrrXMLReader* createIrrXMLReader(IFileReadCallBack* callback); |
| hlipka | 0:41a49a73580c | 438 | |
| hlipka | 0:41a49a73580c | 439 | //! Creates an instance of an UFT-16 xml parser. |
| hlipka | 0:41a49a73580c | 440 | /** This means that |
| hlipka | 0:41a49a73580c | 441 | all character data will be returned in UTF-16. The file to read can |
| hlipka | 0:41a49a73580c | 442 | be in any format, it will be converted to UTF-16 if it is not in this format. |
| hlipka | 0:41a49a73580c | 443 | If you are using the Irrlicht Engine, it is better not to use this function but |
| hlipka | 0:41a49a73580c | 444 | IFileSystem::createXMLReader() instead. |
| hlipka | 0:41a49a73580c | 445 | \param filename: Name of file to be opened. |
| hlipka | 0:41a49a73580c | 446 | \return Returns a pointer to the created xml parser. This pointer should be |
| hlipka | 0:41a49a73580c | 447 | deleted using 'delete' after no longer needed. Returns 0 if an error occured |
| hlipka | 0:41a49a73580c | 448 | and the file could not be opened. */ |
| hlipka | 0:41a49a73580c | 449 | IrrXMLReaderUTF16* createIrrXMLReaderUTF16(const char* filename); |
| hlipka | 0:41a49a73580c | 450 | |
| hlipka | 0:41a49a73580c | 451 | //! Creates an instance of an UFT-16 xml parser. |
| hlipka | 0:41a49a73580c | 452 | /** This means that all character data will be returned in UTF-16. The file to read can |
| hlipka | 0:41a49a73580c | 453 | be in any format, it will be converted to UTF-16 if it is not in this format. |
| hlipka | 0:41a49a73580c | 454 | If you are using the Irrlicht Engine, it is better not to use this function but |
| hlipka | 0:41a49a73580c | 455 | IFileSystem::createXMLReader() instead. |
| hlipka | 0:41a49a73580c | 456 | \param file: Pointer to opened file, must have been opened in binary mode, e.g. |
| hlipka | 0:41a49a73580c | 457 | using fopen("foo.bar", "wb"); The file will not be closed after it has been read. |
| hlipka | 0:41a49a73580c | 458 | \return Returns a pointer to the created xml parser. This pointer should be |
| hlipka | 0:41a49a73580c | 459 | deleted using 'delete' after no longer needed. Returns 0 if an error occured |
| hlipka | 0:41a49a73580c | 460 | and the file could not be opened. */ |
| hlipka | 0:41a49a73580c | 461 | IrrXMLReaderUTF16* createIrrXMLReaderUTF16(FILE* file); |
| hlipka | 0:41a49a73580c | 462 | |
| hlipka | 0:41a49a73580c | 463 | //! Creates an instance of an UFT-16 xml parser. |
| hlipka | 0:41a49a73580c | 464 | /** This means that all character data will be returned in UTF-16. The file to read can |
| hlipka | 0:41a49a73580c | 465 | be in any format, it will be converted to UTF-16 if it is not in this format. |
| hlipka | 0:41a49a73580c | 466 | If you are using the Irrlicht Engine, it is better not to use this function but |
| hlipka | 0:41a49a73580c | 467 | IFileSystem::createXMLReader() instead. |
| hlipka | 0:41a49a73580c | 468 | \param callback: Callback for file read abstraction. Implement your own |
| hlipka | 0:41a49a73580c | 469 | callback to make the xml parser read in other things than just files. See |
| hlipka | 0:41a49a73580c | 470 | IFileReadCallBack for more information about this. |
| hlipka | 0:41a49a73580c | 471 | \return Returns a pointer to the created xml parser. This pointer should be |
| hlipka | 0:41a49a73580c | 472 | deleted using 'delete' after no longer needed. Returns 0 if an error occured |
| hlipka | 0:41a49a73580c | 473 | and the file could not be opened. */ |
| hlipka | 0:41a49a73580c | 474 | IrrXMLReaderUTF16* createIrrXMLReaderUTF16(IFileReadCallBack* callback); |
| hlipka | 0:41a49a73580c | 475 | |
| hlipka | 0:41a49a73580c | 476 | |
| hlipka | 0:41a49a73580c | 477 | //! Creates an instance of an UFT-32 xml parser. |
| hlipka | 0:41a49a73580c | 478 | /** This means that all character data will be returned in UTF-32. The file to read can |
| hlipka | 0:41a49a73580c | 479 | be in any format, it will be converted to UTF-32 if it is not in this format. |
| hlipka | 0:41a49a73580c | 480 | If you are using the Irrlicht Engine, it is better not to use this function but |
| hlipka | 0:41a49a73580c | 481 | IFileSystem::createXMLReader() instead. |
| hlipka | 0:41a49a73580c | 482 | \param filename: Name of file to be opened. |
| hlipka | 0:41a49a73580c | 483 | \return Returns a pointer to the created xml parser. This pointer should be |
| hlipka | 0:41a49a73580c | 484 | deleted using 'delete' after no longer needed. Returns 0 if an error occured |
| hlipka | 0:41a49a73580c | 485 | and the file could not be opened. */ |
| hlipka | 0:41a49a73580c | 486 | IrrXMLReaderUTF32* createIrrXMLReaderUTF32(const char* filename); |
| hlipka | 0:41a49a73580c | 487 | |
| hlipka | 0:41a49a73580c | 488 | //! Creates an instance of an UFT-32 xml parser. |
| hlipka | 0:41a49a73580c | 489 | /** This means that all character data will be returned in UTF-32. The file to read can |
| hlipka | 0:41a49a73580c | 490 | be in any format, it will be converted to UTF-32 if it is not in this format. |
| hlipka | 0:41a49a73580c | 491 | if you are using the Irrlicht Engine, it is better not to use this function but |
| hlipka | 0:41a49a73580c | 492 | IFileSystem::createXMLReader() instead. |
| hlipka | 0:41a49a73580c | 493 | \param file: Pointer to opened file, must have been opened in binary mode, e.g. |
| hlipka | 0:41a49a73580c | 494 | using fopen("foo.bar", "wb"); The file will not be closed after it has been read. |
| hlipka | 0:41a49a73580c | 495 | \return Returns a pointer to the created xml parser. This pointer should be |
| hlipka | 0:41a49a73580c | 496 | deleted using 'delete' after no longer needed. Returns 0 if an error occured |
| hlipka | 0:41a49a73580c | 497 | and the file could not be opened. */ |
| hlipka | 0:41a49a73580c | 498 | IrrXMLReaderUTF32* createIrrXMLReaderUTF32(FILE* file); |
| hlipka | 0:41a49a73580c | 499 | |
| hlipka | 0:41a49a73580c | 500 | //! Creates an instance of an UFT-32 xml parser. |
| hlipka | 0:41a49a73580c | 501 | /** This means that |
| hlipka | 0:41a49a73580c | 502 | all character data will be returned in UTF-32. The file to read can |
| hlipka | 0:41a49a73580c | 503 | be in any format, it will be converted to UTF-32 if it is not in this format. |
| hlipka | 0:41a49a73580c | 504 | If you are using the Irrlicht Engine, it is better not to use this function but |
| hlipka | 0:41a49a73580c | 505 | IFileSystem::createXMLReader() instead. |
| hlipka | 0:41a49a73580c | 506 | \param callback: Callback for file read abstraction. Implement your own |
| hlipka | 0:41a49a73580c | 507 | callback to make the xml parser read in other things than just files. See |
| hlipka | 0:41a49a73580c | 508 | IFileReadCallBack for more information about this. |
| hlipka | 0:41a49a73580c | 509 | \return Returns a pointer to the created xml parser. This pointer should be |
| hlipka | 0:41a49a73580c | 510 | deleted using 'delete' after no longer needed. Returns 0 if an error occured |
| hlipka | 0:41a49a73580c | 511 | and the file could not be opened. */ |
| hlipka | 0:41a49a73580c | 512 | IrrXMLReaderUTF32* createIrrXMLReaderUTF32(IFileReadCallBack* callback); |
| hlipka | 0:41a49a73580c | 513 | |
| hlipka | 0:41a49a73580c | 514 | |
| hlipka | 0:41a49a73580c | 515 | /*! \file irrxml.h |
| hlipka | 0:41a49a73580c | 516 | \brief Header file of the irrXML, the Irrlicht XML parser. |
| hlipka | 0:41a49a73580c | 517 | |
| hlipka | 0:41a49a73580c | 518 | This file includes everything needed for using irrXML, |
| hlipka | 0:41a49a73580c | 519 | the XML parser of the Irrlicht Engine. To use irrXML, |
| hlipka | 0:41a49a73580c | 520 | you only need to include this file in your project: |
| hlipka | 0:41a49a73580c | 521 | |
| hlipka | 0:41a49a73580c | 522 | \code |
| hlipka | 0:41a49a73580c | 523 | #include <irrXML.h> |
| hlipka | 0:41a49a73580c | 524 | \endcode |
| hlipka | 0:41a49a73580c | 525 | |
| hlipka | 0:41a49a73580c | 526 | It is also common to use the two namespaces in which irrXML is included, |
| hlipka | 0:41a49a73580c | 527 | directly after #including irrXML.h: |
| hlipka | 0:41a49a73580c | 528 | |
| hlipka | 0:41a49a73580c | 529 | \code |
| hlipka | 0:41a49a73580c | 530 | #include <irrXML.h> |
| hlipka | 0:41a49a73580c | 531 | using namespace irr; |
| hlipka | 0:41a49a73580c | 532 | using namespace io; |
| hlipka | 0:41a49a73580c | 533 | \endcode |
| hlipka | 0:41a49a73580c | 534 | */ |
| hlipka | 0:41a49a73580c | 535 | |
| hlipka | 0:41a49a73580c | 536 | } // end namespace io |
| hlipka | 0:41a49a73580c | 537 | } // end namespace irr |
| hlipka | 0:41a49a73580c | 538 | |
| hlipka | 0:41a49a73580c | 539 | #endif // __IRR_XML_H_INCLUDED__ |