An entity initialisation parameter node. More...

#include <ParamNode.h>

Public Types
typedef std::map< std::string, CParamNode >	ChildrenMap

Public Member Functions
	CParamNode (bool isOk=true)
	Constructs a new, empty node. More...

void	CopyFilteredChildrenOfChild (const CParamNode &src, const char *name, const std::set< std::string > &permitted)
	Finds the childs named name from src and from this, and copies the source child's children which are in the permitted set into this node's child. More...

const CParamNode &	GetChild (const char *name) const
	Returns the (unique) child node with the given name, or a node with IsOk() == false if there is none. More...

bool	IsOk () const
	Returns true if this is a valid CParamNode, false if it represents a non-existent node. More...

const std::wstring &	ToString () const
	Returns the content of this node as a string. More...

const std::string	ToUTF8 () const
	Returns the content of this node as an 8-bit string. More...

const CStrIntern	ToUTF8Intern () const
	Returns the content of this node as an internalized 8-bit string. More...

int	ToInt () const
	Parses the content of this node as an integer. More...

fixed	ToFixed () const
	Parses the content of this node as a fixed-point number. More...

float	ToFloat () const
	Parses the content of this node as a floating-point number. More...

bool	ToBool () const
	Parses the content of this node as a boolean ("true" == true, anything else == false) More...

std::wstring	ToXML () const
	Returns the content of this node and its children as an XML string. More...

void	ToXML (std::wostream &strm) const
	Write the content of this node and its children as an XML string, to the stream. More...

jsval	ToJSVal (JSContext *cx, bool cacheValue) const
	Returns a jsval representation of this node and its children. More...

const ChildrenMap &	GetChildren () const
	Returns the names/nodes of the children of this node, ordered by name. More...

Static Public Member Functions
static void	LoadXML (CParamNode &ret, const XMBFile &file, const wchar_t *sourceIdentifier=NULL)
	Loads the XML data specified by file into the node ret. More...

static void	LoadXML (CParamNode &ret, const VfsPath &path)
	Loads the XML data specified by path into the node ret. More...

static PSRETURN	LoadXMLString (CParamNode &ret, const char xml, const wchar_t sourceIdentifier=NULL)
	See LoadXML, but parses the XML string xml. More...

static std::wstring	EscapeXMLString (const std::wstring &str)
	Escapes a string so that it is well-formed XML content/attribute text. More...

Private Member Functions
void	ApplyLayer (const XMBFile &xmb, const XMBElement &element, const wchar_t *sourceIdentifier=NULL)
	Overlays the specified data onto this node. More...

void	ResetScriptVal ()

jsval	ConstructJSVal (JSContext *cx) const

Private Attributes
std::wstring	m_Value

ChildrenMap	m_Childs

bool	m_IsOk

CScriptValRooted	m_ScriptVal
	Caches the ToJSVal script representation of this node. More...

Detailed Description

An entity initialisation parameter node.

Each node has a text value, plus a number of named child nodes (in a tree structure). Child nodes are unordered, and there cannot be more than one with the same name. Nodes are immutable.

Nodes can be initialised from XML files. Child elements are mapped onto child nodes. Attributes are mapped onto child nodes with names prefixed by "@" (e.g. the XML <a b="c"><d/></a> is loaded as a node with two child nodes, one called "@b" and one called "d").

They can also be initialised from multiple XML files, which is used by ICmpTemplateManager for entity template inheritance. Loading one XML file like:

* <Entity>
*   <Example1>
*     <A attr="value">text</A>
*   </Example1>
*   <Example2>
*     <B/>
*   </Example2>
*   <Example3>
*     <C/>
*   </Example3>
*   <Example4 datatype="tokens">
*     one two three
*   </Example4>
* </Entity>
* 

then a second like:

* <Entity>
*   <Example1>
*     <A>example</A>   <!-- replace the content of the old A element -->
*     <D>new</D>       <!-- add a new child to the old Example1 element -->
*   </Example1>
*   <Example2 disable=""/>   <!-- delete the old Example2 element -->
*   <Example3 replace="">   <!-- replace all the old children of the Example3 element -->
*     <D>new</D>
*   </Example3>
*   <Example4 datatype="tokens">  <!-- treat as space-separated lists of tokens to merge -->
*     four             <!-- add a token to the parent's set -->
*     -two             <!-- remove a token from the parent's set -->
*   </Example4>
* </Entity>
* 

is equivalent to loading a single file like:

* <Entity>
*   <Example1>
*     <A attr="value">example</A>
*     <D>new</D>
*   </Example1>
*   <Example3>
*     <D>new</D>
*   </Example3>
*   <Example4>
*     one three four
*   </Example4>
* </Entity>
* 

Parameter nodes can be translated to JavaScript objects. The previous example will become the object:

* { "Entity": {
*     "Example1": {
*       "A": { "@attr": "value", "_string": "example" },
*       "D": "new"
*     },
*     "Example3": {
*       "D": "new"
*     },
*     "Example4": { "@datatype": "tokens", "_string": "one three four" }
*   }
* }
* 

(Note the special _string for the hopefully-rare cases where a node contains both child nodes and text.)

Definition at line 112 of file ParamNode.h.

Member Typedef Documentation

typedef std::map<std::string, CParamNode> CParamNode::ChildrenMap

Definition at line 115 of file ParamNode.h.

Constructor & Destructor Documentation

CParamNode::CParamNode ( bool isOk = true )

Constructs a new, empty node.

Definition at line 42 of file ParamNode.cpp.

Member Function Documentation

void CParamNode::ApplyLayer	(	const XMBFile &	xmb,
		const XMBElement &	element,
		const wchar_t *	sourceIdentifier = `NULL`
	)

private

Overlays the specified data onto this node.

See class documentation for the concept and examples.

Parameters

xmb	Representation of the XMB file containing an element with the data to apply.
element	Element inside the specified `xmb` file containing the data to apply.
sourceIdentifier	Optional; string you can pass along to indicate the source of the data getting applied. Used for output to log messages if an error occurs.

Definition at line 74 of file ParamNode.cpp.

jsval CParamNode::ConstructJSVal ( JSContext * cx ) const

private

Definition at line 329 of file ParamNode.cpp.

void CParamNode::CopyFilteredChildrenOfChild	(	const CParamNode &	src,
		const char *	name,
		const std::set< std::string > &	permitted
	)

Finds the childs named name from src and from this, and copies the source child's children which are in the permitted set into this node's child.

Intended for use as a filtered clone of XML files. this and src must have childs named name.

Definition at line 170 of file ParamNode.cpp.

std::wstring CParamNode::EscapeXMLString ( const std::wstring & str )

static

Escapes a string so that it is well-formed XML content/attribute text.

(Replaces "&" with "&" etc, and replaces invalid characters with U+FFFD.)

Definition at line 249 of file ParamNode.cpp.

const CParamNode & CParamNode::GetChild ( const char * name ) const

Returns the (unique) child node with the given name, or a node with IsOk() == false if there is none.

Definition at line 185 of file ParamNode.cpp.

const CParamNode::ChildrenMap & CParamNode::GetChildren ( ) const

Returns the names/nodes of the children of this node, ordered by name.

Definition at line 244 of file ParamNode.cpp.

bool CParamNode::IsOk ( ) const

Returns true if this is a valid CParamNode, false if it represents a non-existent node.

Definition at line 193 of file ParamNode.cpp.

void CParamNode::LoadXML	(	CParamNode &	ret,
		const XMBFile &	file,
		const wchar_t *	sourceIdentifier = `NULL`
	)

static

Loads the XML data specified by file into the node ret.

Any existing data in ret will be overwritten or else kept, so this can be called multiple times to build up a node from multiple inputs.

Parameters

sourceIdentifier Optional; string you can pass along to indicate the source of the data getting loaded. Used for output to log messages if an error occurs.

Definition at line 47 of file ParamNode.cpp.

void CParamNode::LoadXML	(	CParamNode &	ret,
		const VfsPath &	path
	)

static

Loads the XML data specified by path into the node ret.

Any existing data in ret will be overwritten or else kept, so this can be called multiple times to build up a node from multiple inputs.

Definition at line 52 of file ParamNode.cpp.

PSRETURN CParamNode::LoadXMLString	(	CParamNode &	ret,
		const char *	xml,
		const wchar_t *	sourceIdentifier = `NULL`
	)

static

See LoadXML, but parses the XML string xml.

Returns: error code if parsing failed, else PSRETURN_OK

Parameters

sourceIdentifier Optional; string you can pass along to indicate the source of the data getting loaded. Used for output to log messages if an error occurs.

Definition at line 62 of file ParamNode.cpp.

void CParamNode::ResetScriptVal ( )

private

Definition at line 374 of file ParamNode.cpp.

bool CParamNode::ToBool ( ) const

Parses the content of this node as a boolean ("true" == true, anything else == false)

Definition at line 236 of file ParamNode.cpp.

fixed CParamNode::ToFixed ( ) const

Parses the content of this node as a fixed-point number.

Definition at line 222 of file ParamNode.cpp.

float CParamNode::ToFloat ( ) const

Parses the content of this node as a floating-point number.

Definition at line 227 of file ParamNode.cpp.

int CParamNode::ToInt ( ) const

Parses the content of this node as an integer.

Definition at line 213 of file ParamNode.cpp.

jsval CParamNode::ToJSVal	(	JSContext *	cx,
		bool	cacheValue
	)		const

Returns a jsval representation of this node and its children.

If cacheValue is true, then the same jsval will be returned each time this is called (regardless of whether you passed the same cx - be careful to only use the cache in one context). When caching, the lifetime of cx must be longer than the lifetime of this node. The cache will be reset if this node is modified (e.g. by LoadXML), but not if any child nodes are modified (so don't do that).

Definition at line 316 of file ParamNode.cpp.

const std::wstring & CParamNode::ToString ( ) const

Returns the content of this node as a string.

Definition at line 198 of file ParamNode.cpp.

const std::string CParamNode::ToUTF8 ( ) const

Returns the content of this node as an 8-bit string.

Definition at line 203 of file ParamNode.cpp.

const CStrIntern CParamNode::ToUTF8Intern ( ) const

Returns the content of this node as an internalized 8-bit string.

Should only be used for predictably small and frequently-used strings.

Definition at line 208 of file ParamNode.cpp.

std::wstring CParamNode::ToXML ( ) const

Returns the content of this node and its children as an XML string.

Definition at line 275 of file ParamNode.cpp.

void CParamNode::ToXML ( std::wostream & strm ) const

Write the content of this node and its children as an XML string, to the stream.

Definition at line 282 of file ParamNode.cpp.

Member Data Documentation

ChildrenMap CParamNode::m_Childs

private

Definition at line 253 of file ParamNode.h.

bool CParamNode::m_IsOk

private

Definition at line 254 of file ParamNode.h.

CScriptValRooted CParamNode::m_ScriptVal

mutableprivate

Caches the ToJSVal script representation of this node.

Definition at line 259 of file ParamNode.h.

std::wstring CParamNode::m_Value

private

Definition at line 252 of file ParamNode.h.

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

/home/sathyam/0ad.svn/source/simulation2/system/ParamNode.h
/home/sathyam/0ad.svn/source/simulation2/system/ParamNode.cpp

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation