CzXmlParser Class Reference

The Xml parser. More...

#include <CzXml.h>

List of all members.

Public Member Functions
	CzXmlParser ()
virtual	~CzXmlParser ()
void	setEncoding (const char *enocding)
const CzString &	getEncoding () const
void	setVersion (const char *version)
const CzString &	getVersion () const
const CzString &	getFilename () const
CzXmlNode *	AllocNode ()
CzXmlTagMarker *	AllocTag ()
CzXmlAttribute *	AllocAttribute ()
eCzXmlParseError	Parse (const char *pFilename)
	Parses the supplied file.
eCzXmlParseError	Parse (CzFile *file)
	Parses the supplied file.
eCzXmlParseError	Parse (CzDataInput *pData)
	Parses the supplied memory buffer.
int	Save (const char *filename)
	Saves entire node tree to a file with the specified filename.
const char *	getErrorString (eCzXmlParseError error) const
	Returns the string repesentation of the supplied error.
CzXmlNode *	getRoot ()
CzXmlNode *	getFirstNamedNode (CzXmlNode *parent, const char *node_name)
CzXmlNodeList *	getNamedNodes (CzXmlNode *parent, const char *node_name)

---

Detailed Description

The Xml parser.

Introduction

AppEasy comes with a basic XML parser that has the following features:

• Load and save XML files
• Very small code footprint
• Very quick parser
• Uses memory pooling for tags, attributes and values, reducing memory fragmentation
• Error output, including line numbers

CzXmlParser does however have limitations such as no support for XML schemas and will allow you to do some things that normal XML parsers will not allow you to do.

The XML engine is split into the following classes:

• CzXmlAttribute - A nodes named attributes and values
• CzXmlNode - A named node containing a collection of attributes
• CzXmlParser - The main parser object that loads and parsers the XML file

Loading an XML file

To load an XML file, create an instance of CzXmlParser and call Parse() to parse the data, like shown below:

// Load the xml file
CzXmlParser*    xml = new CzXmlParser();
if (xml->Parse("./Scene1.xml") == eXMLParserError_None)
{
    // Save the xml file back out
    xml->getRoot()->Save("test1.xml");
}

In this example we create an instance of the XML parser object then call Parse() passing in the name of the XML file. If there was no parsing errors then we save the file back out to check that it worked.

Three versions of Parse() are available:

• Parse(const char* filename);
• Parse(CzFile <em>file);
• Parse(CzDataInput data);

These allowing parsing of a named file, an AppEasy file and a data input stream.

Working with Nodes

The parser provides a number of useful methods that you can use to get nodes from the parsed data:

• getRoot() - Returns the root node of the loaded XML data
• getFirstNamedNode() - Searches the complete XML node structure from the specified parent node and returns the first node who's name matches the supplied node name
• gettNamedNodes() - Searches the complete XML node structure from the specified node and returns all nodes who's names match the supplied node name

Once you have a node you can begin querying the nodes value and attributes. To get the nodes value you can use the following methods:

• getValue() - Returns the nodes value as a string
• getValueAsInt() - Returns the nodes value as an integer
• getValueAsFloat() - Returns the nodes value as a floating point number
• getValueAsBool() - Returns the nodes value as a boolean

For debug purposes you can also print the nodes attributes and complete hierarchy using the following methods:

• PrintAttributes() - Prints the nodes attributes to a string
• PrintTree() - Prints the entier XML node structure to a string

You can search a nodes child nodes using the following methods:

• getFirstNode() - Returns the first node
• getFirstNamedNode(unsigned int name_hash) - Returns the first named mode
• getNamedNodes(unsigned int name_hash, CzXmlNodeList *nodes) - Returns all nodes that match the supplied name

Note that these methods take a hashed string value as node names instead of a string for faster searching.

CzXmlNode also provides methods for saving its structure to a file:

• SaveAttributes(CzFile* file) - Saves a group of mode attributes to a file
• SaveTree(CzFile* file) - Saves a complete mode tree to a file
• Save(const char* filename) - Saves a complete mode tree to a file with specified filename

Querying attributes can be done using the following methods:

• GetAttributeCount() - Returns number of attributes that the node contains
• GetAttribute(const char* name) - Gets the named attribute
• GetAttribute(int index) - Gets the attribute at the specified index

And finally methods have been provided for building nodes:

• SetName(const char* name, int len) - Sets the nodes name
• SetValue(const char* value, int len) - Sets the nodes value
• AddChild(CzXmlNode* node) - Adds a new node as a child
• AddAttribute(CzXmlAttribute <em>attribute) - Adds a new attribute to the node
• AddAttribute(CzString& name, CzString& value) - Adds a new attribute to the node
• AddAttribute(CzString& name, const char value) - Adds a new attribute to the node
• UpdateAttribute(const CzString& name, const char* value, CzXmlParser* parser) - Updates an existing named attribute in the node

Node and Attribute Iteration

CzXmlNode provides iterator based access to both child nodes and attributes:

typedef CIwList<CzXmlNode*>::iterator       _Iterator;
typedef CIwList<CzXmlAttribute*>::iterator      _AttribIterator;
_Iterator               begin()
_Iterator               end()
_AttribIterator         attribs_begin()
_AttribIterator         attribs_end()   

These types and methods allow you to easily walk the nodes child nodes and attributes. Below is an example showing how to walk a nodes child nodes and each nodes attributes:

// Walk the child nodes
for (CzXmlNode::_Iterator nodes = node->begin(); nodes != node->end(); ++nodes)
{
    // Walk the nodes attrobutes
    for (CzXmlNode::_AttribIterator attribs = (*nodes)->attribs_begin(); attribs != (*nodes)->attribs_end(); ++attribs)
    {
    }
}

Attribute Query

CzXmlAttribute provides an extensive set of methods for querying attribute values and converting the data to different formats. Below is a list of all methods:

CzString&       getValue() { return Value; }
int             getValueAsInt() const;
float           getValueAsFloat() const;
bool            getValueAsBool() const;
bool            getValueAsPoint(CIwFVec2 &point);
bool            getValueAsPoint3(CIwFVec3 &point);
bool            getValueAsPoint4(CIwFVec4 &point);
bool            getValueAsColour(CIwColour &colour);
bool            getValueAsRect(CIwRect &rect);

CzXmlStringList*    getValueAsList();
int             getValueAsListOfInt();
int             getValueAsListOfFloat();
int             getValueAsListOfBool();

The list value retrieval methods uses a pooled memory system to reduce constant allocation and deallocation of memory, so please ensure that you store off the values retrieved from the pool buffers before calling the list methods again or data will be written over. To see how the list pool buffers are used lets take a quick look at at GetValueAsRect():

bool CzXmlAttribute::getValueAsRect(CzIRect& rect)
{
    if (Value.getAsListOfInt(CzXmlTools::IntListPool) != 4)
    {
        return false;
    }
    rect.x = CzXmlTools::IntListPool[0];
    rect.y = CzXmlTools::IntListPool[1];
    rect.w = CzXmlTools::IntListPool[2];
    rect.h = CzXmlTools::IntListPool[3];

    return true;
}

As you can see, when we call GetAsListOfInt() a global buffer called CzXmlTools::IntListPool is filled with the values that are returned.

Creating an XML file

XML is very useful when it comes to representing data in a platform independent manner. It's also very useful when it comes to serialising game state and other data to storage as it can be saved in a good structured format.

To create an XML file you need to create a root XML node then add further named child nodes that contain values and attributes that contain your data. Below shows a quick example:

// Create root XML node
CzXmlNode* root = new CzXmlNode();
root->SetName("xml");

// Create and add a settings child node to the root
CzXmlNode* settings_node = new CzXmlNode();
settings_node->SetName("Settings");
root->AddChild(settings_node);

// Create and add a FullVersion node to the settings node
CzXmlNode*  value_node = new CzXmlNode();
value_node->SetName("FullVersion");
value_node->SetValue("true");
settings_node->AddChild(value_node);

// Save the XML file
settings_node->Save("./Settings.xml");

// Cleanup xml data
delete root;

The above code will generate the following XML file:

<?xml version="1.0"?>
<Settings>
    <FullVersion>true</FullVersion>
</Settings>

---

Constructor & Destructor Documentation

CzXmlParser::CzXmlParser

(

)

[inline]

virtual CzXmlParser::~CzXmlParser

(

)

[inline, virtual]

---

Member Function Documentation

CzXmlAttribute* CzXmlParser::AllocAttribute

(

)

[inline]

CzXmlNode* CzXmlParser::AllocNode

(

)

[inline]

CzXmlTagMarker* CzXmlParser::AllocTag

(

)

[inline]

const CzString& CzXmlParser::getEncoding

(

)

const [inline]

const char * CzXmlParser::getErrorString

(

eCzXmlParseError

error

)

const

Returns the string repesentation of the supplied error.

const CzString& CzXmlParser::getFilename

(

)

const [inline]

CzXmlNode* CzXmlParser::getFirstNamedNode	(	CzXmlNode *	parent,
		const char *	node_name
	)		[inline]

Parameters:

node_name

Get first occurrence of a node in this node and all children

CzXmlNodeList* CzXmlParser::getNamedNodes	(	CzXmlNode *	parent,
		const char *	node_name
	)		[inline]

Parameters:

node_name

/ Get all occurrences of a node in this node and all children (caller is responsible for cleaning up list). Pass NULL as bode_name to return all nodes

CzXmlNode* CzXmlParser::getRoot

(

)

[inline]

const CzString& CzXmlParser::getVersion

(

)

const [inline]

eCzXmlParseError CzXmlParser::Parse

(

const char *

pFilename

)

Parses the supplied file.

eCzXmlParseError CzXmlParser::Parse

(

CzFile *

file

)

Parses the supplied file.

eCzXmlParseError CzXmlParser::Parse

(

CzDataInput *

pData

)

Parses the supplied memory buffer.

int CzXmlParser::Save

(

const char *

filename

)

Saves entire node tree to a file with the specified filename.

void CzXmlParser::setEncoding

(

const char *

enocding

)

[inline]

void CzXmlParser::setVersion

(

const char *

version

)

[inline]

---

The documentation for this class was generated from the following files:

• CzXml.h
• CzXml.cpp