XML Handling functions
[Implementations]

---

Detailed Description

Functions useful for working with or producing XML.

Functions
void	DigitalSpaces::ProcessXMLNodeForStrings (DIXMLNode1 *rootNode, const std::map< std::string, std::string > &sourceToReplacementMap)
	Function to process through a tree of XML Nodes, look for the specified strings in text elements and attribute strings.
Variant	DigitalSpaces::GetVariantFromXML (DIXMLElement1 *)
	A function that can take a DIXMLElement1 and convert it into a Variant.
SettingMap	DigitalSpaces::GetSettingMapFromXML (DIXMLNode1 *)
	A function that can take an XML element, look for <setting name=""> nodes, then get Variant values for their children (using GetVariantFromXML).
void	DigitalSpaces::FillInSettingNode (DIXMLNode1 *iNode, const SettingMap &settings)
	Using the value of the settings parameter, add child nodes to iNode.
Wml::Vector3f	DigitalSpaces::_readVector (DigitalSpaces::DIXMLNode1 *xmlNode)
	Convenince override of _readVector( DIXMLElement1* ).
Wml::Vector3f	DigitalSpaces::_readVector (DigitalSpaces::DIXMLElement1 *xmlElem)
	Extract Vector data from a xml element.
Wml::Quaternionf	DigitalSpaces::_readQuaternion (DigitalSpaces::DIXMLNode1 *xmlNode)
	Convenince override of _readQuaternion( DIXMLElement1* ).
Wml::Quaternionf	DigitalSpaces::_readQuaternion (DigitalSpaces::DIXMLElement1 *xmlElem)
	Extract Quaternion data from a xml element.
Wml::Vector4f	DigitalSpaces::_readColour (DigitalSpaces::DIXMLNode1 *xmlNode)
	Convenince override of _readColour( DIXMLElement1* ).
Wml::Vector4f	DigitalSpaces::_readColour (DigitalSpaces::DIXMLElement1 *xmlElem)
	Extract colour data from a xml element.
std::string	DigitalSpaces::_readName (DigitalSpaces::DIXMLNode1 *xmlNode)
	Convenince override of _readName( DIXMLElement1* ).
std::string	DigitalSpaces::_readName (DigitalSpaces::DIXMLElement1 *xmlElem)
	Reads or generates a name for an element from "name" attribute.
std::string	DigitalSpaces::_autoName ()
	Create an automatically generated name.
bool	DigitalSpaces::_readBool (const char *string)
	Checks if a string contains a representation of true, otherwise returns false.

---

Function Documentation

std::string DigitalSpaces::_autoName

(

)

Create an automatically generated name.

This should be unique. Uses an incrementing base 36 number.

Note:

Should this be changed to use some sort of randomly generated string, with a good range? This would help prevent collisions. Especially when generated names are saved!

bool DigitalSpaces::_readBool

(

const char *

string

)

Checks if a string contains a representation of true, otherwise returns false.

Values that will return true are:

• true (case insensitive)
• yes (case insensitive)
• 1

Wml::Vector4f DigitalSpaces::_readColour

(

DigitalSpaces::DIXMLElement1 *

xmlElem

)

Extract colour data from a xml element.

The implementation does not check that xmlElem is in fact a <colour> element. The attributes extracted are case sensitive. The acceptable attributes are:

		<colour r="1.0" g="1.0" b="1.0" />
		<colour r="1.0" g="1.0" b="1.0" a="1.0" />
		

Use of other cases (e.g. R,G,B) will not be read. If neither of the forms are found (any of the attributes are missing), an uninitialized value will be returned.

Todo:

Should there be an error return value? Since this is a implementation function, not an interface function, throwing an exception would be acceptable.

The attributes are red,green,blue,alpha. If alpha is not specified, it is provided as 1.0.

The acceptable values range from 0.0 to 1.0.

Wml::Vector4f DigitalSpaces::_readColour

(

DigitalSpaces::DIXMLNode1 *

xmlNode

)

Convenince override of _readColour( DIXMLElement1* ).

std::string DigitalSpaces::_readName

(

DigitalSpaces::DIXMLElement1 *

xmlElem

)

Reads or generates a name for an element from "name" attribute.

If the provided element does not have a name attribute, a response from _autoName is returned.

Returns:

Returns std::string instead of const char* because autogenerated name would either leak, or re-use static memory.

std::string DigitalSpaces::_readName

(

DigitalSpaces::DIXMLNode1 *

xmlNode

)

Convenince override of _readName( DIXMLElement1* ).

Wml::Quaternionf DigitalSpaces::_readQuaternion

(

DigitalSpaces::DIXMLElement1 *

xmlElem

)

Extract Quaternion data from a xml element.

The implementation does not check that xmlElem is in fact a <quaternion> element. The attributes extracted are case sensitive. The acceptable attributes are:

		<quaternion w="1.0" x="0.0" y="0.0" z="0.0" />
		<quaternion qw="1.0" qx="0.0" qy="0.0" qz="0.0" />
		<quaternion axisx="0.0" axisy="3.141592" axisz="0.0" />
		<quaternion anglex="0" angley="1.0" anglez="0.0" angle="3.141592" />
		

Use of other cases (e.g. W,X,Y,Z) will not be read. If none of the forms are found (any of the attributes are missing), an uninitialized value will be returned.

Todo:

Should there be an error return value? Since this is a implementation function, not an interface function, throwing an exception would be acceptable.

Of the above examples, the first two forms (w,x,y,z and qw,qx,qy,qz) are equivalent. These are the w,x,y,z values used in standard quaternion representation.

The third form provides rotation around the Euler axis (X, Y, Z). The rotation is measured in radians. See http://www.gamasutra.com/features/19980703/quaternions_01.htm (Listing 3) for an explanation of how this is converted to a quaternion.

The forth form specifies a vector and a rotation around that vector. The rotation is measured in radians.

Wml::Quaternionf DigitalSpaces::_readQuaternion

(

DigitalSpaces::DIXMLNode1 *

xmlNode

)

Convenince override of _readQuaternion( DIXMLElement1* ).

Wml::Vector3f DigitalSpaces::_readVector

(

DigitalSpaces::DIXMLElement1 *

xmlElem

)

Extract Vector data from a xml element.

The implementation does not check that xmlElem is in fact a <vector> element. The attributes extracted are case sensitive. The acceptable attributes are:

		<vector x="0.0" y="0.0" z="0.0" />
		

Use of other cases (e.g. X,Y,Z) will not be read. If any of the attributes are missing, an uninitialized value will be returned.

Todo:

Should there be an error return value? Since this is a implementation function, not an interface function, throwing an exception would be acceptable.

Wml::Vector3f DigitalSpaces::_readVector

(

DigitalSpaces::DIXMLNode1 *

xmlNode

)

Convenince override of _readVector( DIXMLElement1* ).

void DigitalSpaces::FillInSettingNode	(	DIXMLNode1 *	iNode,
		const SettingMap &	settings
	)

Using the value of the settings parameter, add child nodes to iNode.

This is the inverse of GetSettingMapFromXML.

SettingMap DigitalSpaces::GetSettingMapFromXML

(

DIXMLNode1 *

)

A function that can take an XML element, look for <setting name=""> nodes, then get Variant values for their children (using GetVariantFromXML).

This is stored in a map, with the value of name as the key.

		<settings>
			<setting name="Key1">
				<float val="0.0"/>
			</setting>
			<setting name="Key2">
				<string val="Key2Value" />
			</setting>
		</settings>
		

Variant DigitalSpaces::GetVariantFromXML

(

DIXMLElement1 *

)

A function that can take a DIXMLElement1 and convert it into a Variant.

This accepts:

• <float val="0.0">
• <double val="0.0">
• <bool val="true">
• <int val="0">
• <unint val="0">
• <string val="string">
• <vector x="0.0" y="0.0" z="0.0">
• <quaternion w="0.0" x="0.0" y="0.0" z="0.0">
• <colour r="0.0" g="0.0" b="0.0" a="0.0"> (and color)

It's type checks are case insensitive, however the value reading isnt. This means that <Vector>, <vector> and <VeCtOr> will be treated identically, however X and x will not (only x will be read).

Todo:

Improve attribute reading process to be case insensitive.

Todo:

Add support for <settings> (or <settingmap>) using GetSettingMapFromXML.

void DigitalSpaces::ProcessXMLNodeForStrings	(	DIXMLNode1 *	rootNode,
		const std::map< std::string, std::string > &	sourceToReplacementMap
	)

Function to process through a tree of XML Nodes, look for the specified strings in text elements and attribute strings.

Parameters:

	rootNode	The XML Node to start the recusrive search from.
	sourceToReplacementMap	A map where the keys are the text values to be replaced, and the keys are the values to replace them with.

Note:

Due to the recursive nature of this function, passing it an extremely deep XML structure may cause a crash.