Common::XMLParser Class Reference

#include <xmlparser.h>

Inheritance diagram for Common::XMLParser:

Classes
struct	ParserNode
struct	XMLKeyLayout

Public Types
enum	ParserState {   kParserNeedHeader, kParserNeedKey, kParserNeedKeyName, kParserNeedPropertyName,   kParserNeedPropertyOperator, kParserNeedPropertyValue, kParserError }
typedef HashMap< String, XMLParser::XMLKeyLayout *, IgnoreCase_Hash, IgnoreCase_EqualTo >	ChildMap

Public Member Functions
	XMLParser ()
ParserNode *	allocNode ()
void	freeNode (ParserNode *node)
bool	loadFile (const Path &filename)
bool	loadFile (const FSNode &node)
bool	loadBuffer (const byte *buffer, uint32 size, DisposeAfterUse::Flag disposable=DisposeAfterUse::NO)
bool	loadStream (SeekableReadStream *stream)
void	close ()
bool	parse ()
ParserNode *	getActiveNode ()
ParserNode *	getParentNode (ParserNode *child)
void	setAllowText ()

Public Attributes
XMLKeyLayout *	_XMLkeys
ObjectPool< ParserNode, 8 >	_nodePool

Protected Member Functions
virtual void	buildLayout ()=0
virtual bool	keyCallback (ParserNode *node)=0
virtual bool	closedKeyCallback (ParserNode *node)
virtual bool	textCallback (const String &val)
bool	closeKey ()
bool	parseKeyValue (String keyName)
bool	parseActiveKey (bool closed)
bool	parserError (const String &errStr)
bool	skipSpaces ()
bool	skipComments ()
virtual bool	isValidNameChar (char c)
bool	parseToken ()
bool	parseIntegerKey (const char *key, int count,...)
bool	parseIntegerKey (const String &keyStr, int count,...)
bool	vparseIntegerKey (const char *key, int count, va_list args)
bool	parseXMLHeader (ParserNode *node)
virtual void	cleanup ()
virtual bool	handleUnknownKey (ParserNode *node)

Protected Attributes
List< XMLKeyLayout * >	_layoutList

Detailed Description

The base XMLParser class implements generic functionality for parsing XML-like files.

In order to use it, it must be inherited with a child class that implements the XMLParser::keyCallback() function.

See also

XMLParser::keyCallback()

Member Enumeration Documentation

ParserState

enum Common::XMLParser::ParserState

Active state for the parser

Constructor & Destructor Documentation

XMLParser()

Common::XMLParser::XMLParser ( )

inline

Parser constructor.

Member Function Documentation

loadFile()

bool Common::XMLParser::loadFile

(

const Path &

filename

)

Loads a file into the parser. Used for the loading of Theme Description files straight from the filesystem.

Parameters

filename

Name of the file to load.

loadBuffer()

bool Common::XMLParser::loadBuffer	(	const byte *	buffer,
		uint32	size,
		DisposeAfterUse::Flag	disposable = DisposeAfterUse::NO
	)

Loads a memory buffer into the parser. Used for loading the default theme fallback directly from memory if no themes can be found.

Parameters

buffer	Pointer to the buffer.
size	Size of the buffer
disposable	Sets if the XMLParser owns the buffer, i.e. if it can be freed safely after it's no longer needed by the parser.

parse()

bool Common::XMLParser::parse

(

)

The actual parsing function. Parses the loaded data stream, returns true if successful.

getActiveNode()

ParserNode* Common::XMLParser::getActiveNode ( )

inline

Returns the active node being parsed (the one on top of the node stack).

getParentNode()

ParserNode* Common::XMLParser::getParentNode ( ParserNode *  child )

inline

Returns the parent of a given node in the stack.

setAllowText()

void Common::XMLParser::setAllowText ( )

inline

Allow text nodes (eg <tag>this is a text node</tag>) to appear in the document.

By default this parser does not allow text nodes and expects all data to appear in attributes.

buildLayout()

virtual void Common::XMLParser::buildLayout ( )

protectedpure virtual

The buildLayout function builds the layout for the parser to use based on a series of helper macros. This function is automatically generated by the CUSTOM_XML_PARSER() macro on custom parsers.

See the documentation regarding XML layouts.

keyCallback()

virtual bool Common::XMLParser::keyCallback ( ParserNode *  node )

protectedpure virtual

The keycallback function is automatically overloaded on custom parsers when using the CUSTOM_XML_PARSER() macro.

Its job is to call the corresponding Callback function for the given node. A function for each key type must be declared separately. See the custom parser creation instructions.

When parsing a key in such function, one may chose to skip it, e.g. because it's not needed on the current configuration. In order to ignore a key, you must set the "ignore" field of its KeyNode struct to "true": The key and all its children will then be automatically ignored by the parser.

The callback function must return true if the key was properly handled (this includes the case when the key is being ignored). False otherwise. The return of keyCallback() is the same as the callback function's. See the sample implementation in GUI::ThemeParser.

closedKeyCallback()

virtual bool Common::XMLParser::closedKeyCallback ( ParserNode *  node )

inlineprotectedvirtual

The closed key callback function MAY be overloaded by inheriting classes to implement parser-specific functions.

The closedKeyCallback is issued once a key has been finished parsing, to let the parser verify that all the required subkeys, etc, were included.

Unlike the keyCallbacks(), there's just a closedKeyCallback() for all keys. Use "node->name" to distinguish between each key type.

Returns true if the key was properly closed, false otherwise. By default, all keys are properly closed.

Reimplemented in GUI::ThemeParser, Tetraedge::InGameSceneXmlParser, GUI::MetadataParser, and Tetraedge::TeNameValXmlParser.

textCallback()

virtual bool Common::XMLParser::textCallback ( const String &  val )

inlineprotectedvirtual

Called when a text node is found. This will only be called if setAllowText() has been called, otherwise text nodes are considered parse errors.

Reimplemented in Tetraedge::InGameSceneXmlParser, Tetraedge::CharacterSettingsXmlParser, Tetraedge::TeTextLayoutXmlParser, and Tetraedge::ObjectSettingsXmlParser.

closeKey()

bool Common::XMLParser::closeKey ( )

protected

Called when a node is closed. Manages its cleanup and calls the closing callback function if needed.

parseKeyValue()

bool Common::XMLParser::parseKeyValue ( String  keyName )

protected

Parses the value of a given key. There's no reason to overload this.

parseActiveKey()

bool Common::XMLParser::parseActiveKey ( bool  closed )

protected

Called once a key has been parsed. It handles the closing/cleanup of the node stack and calls the keyCallback.

parserError()

bool Common::XMLParser::parserError ( const String &  errStr )

protected

Prints an error message when parsing fails and stops the parser. Parser error always returns "false" so we can pass the return value directly and break down the parsing.

skipSpaces()

bool Common::XMLParser::skipSpaces ( )

protected

Skips spaces/whitelines etc.

Returns

true if any spaces were skipped.

skipComments()

bool Common::XMLParser::skipComments ( )

protected

Skips comment blocks and comment lines.

Returns

true if any comments were skipped.

isValidNameChar()

virtual bool Common::XMLParser::isValidNameChar ( char  c )

inlineprotectedvirtual

Check if a given character can be part of a KEY or VALUE name. Overload this if you want to support keys with strange characters in their name.

parseToken()

bool Common::XMLParser::parseToken ( )

protected

Parses a the first textual token found.

parseIntegerKey()

bool Common::XMLParser::parseIntegerKey ( const char *  key, int  count,   ...  )

protected

Parses the values inside an integer key. The count parameter specifies the number of values inside the key, which are expected to be separated with commas.

Sample usage: parseIntegerKey("255, 255, 255", 3, &red, &green, &blue); [will parse each field into its own integer]

parseIntegerKey("1234", 1, &number); [will parse the single number into the variable]

Parameters

key	String containing the integers to be parsed.
count	Number of comma-separated ints in the string.
...	Integer variables to store the parsed ints, passed by reference.

Returns

True if the parsing succeeded.

cleanup()

virtual void Common::XMLParser::cleanup ( )

inlineprotectedvirtual

Overload if your parser needs to support parsing the same file several times, so you can clean up the internal state of the parser before each parse.

Reimplemented in GUI::ThemeParser, and GUI::MetadataParser.

handleUnknownKey()

virtual bool Common::XMLParser::handleUnknownKey ( ParserNode *  node )

inlineprotectedvirtual

Overload if your parser wants to be notified of keys which haven't been explicitly declared.

The functions should return true if the key was handled and parsing should continue, or false (default) to raise a parsing error.

Reimplemented in Tetraedge::CharacterSettingsXmlParser, and Tetraedge::InventoryObjectsXmlParser.

---

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

• common/formats/xmlparser.h