Pyrogenesis HEAD
Pyrogenesis, a RTS Engine
CParamNode Class Reference

An entity initialisation parameter node. More...

#include <ParamNode.h>

Public Types

typedef std::map< std::string, CParamNodeChildrenMap
 

Public Member Functions

 CParamNode (bool isOk=true)
 Constructs a new, empty node. More...
 
const CParamNodeGetChild (const char *name) const
 Returns the (unique) child node with the given name, or a node with IsOk() == false if there is none. More...
 
const CParamNodeGetOnlyChild () const
 Returns the only child node, 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 ToWString () const
 Returns the content of this node as a wstring. More...
 
const std::string & ToString () const
 Returns the content of this node as an UTF8 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::string ToXMLString () const
 Returns the content of this node and its children as an XML string. More...
 
void ToXMLString (std::ostream &strm) const
 Write the content of this node and its children as an XML string, to the stream. More...
 
void ToJSVal (const ScriptRequest &rq, bool cacheValue, JS::MutableHandleValue ret) const
 Returns a JS::Value representation of this node and its children. More...
 
const ChildrenMapGetChildren () 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 XMBData &xmb, 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, const std::string &validatorName)
 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::string EscapeXMLString (const std::string &str)
 Escapes a string so that it is well-formed XML content/attribute text. More...
 

Public Attributes

std::string m_Name
 
u32 m_Index
 

Private Member Functions

void ApplyLayer (const XMBData &xmb, const XMBElement &element, const wchar_t *sourceIdentifier=NULL)
 Overlays the specified data onto this node. More...
 
void ResetScriptVal ()
 
void ConstructJSVal (const ScriptRequest &rq, JS::MutableHandleValue ret) const
 

Private Attributes

std::string m_Value
 
ChildrenMap m_Childs
 
bool m_IsOk
 
std::shared_ptr< JS::PersistentRootedValue > 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:

<Example1>
<A attr="value">text</A>
</Example1>
<Example2>
<B/>
</Example2>
<Example3>
<C/>
</Example3>
<Example4 datatype="tokens">
one two three
</Example4>
<Example5>
<E/>
<F>
<I>test</I>
</F>
<H>
<J>example</J>
</H>
</Example5>
#define E(e)
Definition: Entity.h:25

then a second like:

<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>
<Example5 filtered=""> <!-- drop all children of this node that are not in this file -->
<F merge=""> <!-- only add this element if it is also present in the parent -->
<K>example</K> <!-- if F is present merge its children normally -->
</F>
<G merge=""/> <!-- keep the G element of the parent if it exists -->
<H>
<J>text</J>
</H>
</Example5>

is equivalent to loading a single file like:

<Example1>
<A attr="value">example</A>
<D>new</D>
</Example1>
<Example3>
<D>new</D>
</Example3>
<Example4>
one three four
</Example4>
<Example5>
<F>
<I>test</I>
<K>example</K>
</F>
<H>
<J>text</J>
</H>
</Example5>

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" },
"Example5": {
"F": {
"I": "test",
"K": "example"
},
"H": {
"J": "text"
}
}
}
}

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

Member Typedef Documentation

◆ ChildrenMap

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

Constructor & Destructor Documentation

◆ CParamNode()

CParamNode::CParamNode ( bool  isOk = true)

Constructs a new, empty node.

Member Function Documentation

◆ ApplyLayer()

void CParamNode::ApplyLayer ( const XMBData 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
xmbRepresentation of the XMB file containing an element with the data to apply.
elementElement inside the specified xmb file containing the data to apply.
sourceIdentifierOptional; string you can pass along to indicate the source of the data getting applied. Used for output to log messages if an error occurs.

◆ ConstructJSVal()

void CParamNode::ConstructJSVal ( const ScriptRequest rq,
JS::MutableHandleValue  ret 
) const
private

◆ EscapeXMLString()

std::string CParamNode::EscapeXMLString ( const std::string &  str)
static

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

(Replaces "&" with "&amp;" etc)

◆ GetChild()

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.

◆ GetChildren()

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

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

◆ GetOnlyChild()

const CParamNode & CParamNode::GetOnlyChild ( ) const

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

This is mainly useful for the root node.

◆ IsOk()

bool CParamNode::IsOk ( ) const

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

◆ LoadXML() [1/2]

void CParamNode::LoadXML ( CParamNode ret,
const VfsPath path,
const std::string &  validatorName 
)
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.

◆ LoadXML() [2/2]

void CParamNode::LoadXML ( CParamNode ret,
const XMBData xmb,
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
sourceIdentifierOptional; string you can pass along to indicate the source of the data getting loaded. Used for output to log messages if an error occurs.

◆ LoadXMLString()

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
sourceIdentifierOptional; string you can pass along to indicate the source of the data getting loaded. Used for output to log messages if an error occurs.

◆ ResetScriptVal()

void CParamNode::ResetScriptVal ( )
private

◆ ToBool()

bool CParamNode::ToBool ( ) const

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

◆ ToFixed()

fixed CParamNode::ToFixed ( ) const

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

◆ ToFloat()

float CParamNode::ToFloat ( ) const

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

◆ ToInt()

int CParamNode::ToInt ( ) const

Parses the content of this node as an integer.

◆ ToJSVal()

void CParamNode::ToJSVal ( const ScriptRequest rq,
bool  cacheValue,
JS::MutableHandleValue  ret 
) const

Returns a JS::Value representation of this node and its children.

If cacheValue is true, then the same JS::Value 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).

◆ ToString()

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

Returns the content of this node as an UTF8 string.

◆ ToUTF8Intern()

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.

◆ ToWString()

const std::wstring CParamNode::ToWString ( ) const

Returns the content of this node as a wstring.

◆ ToXMLString() [1/2]

std::string CParamNode::ToXMLString ( ) const

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

◆ ToXMLString() [2/2]

void CParamNode::ToXMLString ( std::ostream &  strm) const

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

Member Data Documentation

◆ m_Childs

ChildrenMap CParamNode::m_Childs
private

◆ m_Index

u32 CParamNode::m_Index

◆ m_IsOk

bool CParamNode::m_IsOk
private

◆ m_Name

std::string CParamNode::m_Name

◆ m_ScriptVal

std::shared_ptr<JS::PersistentRootedValue> CParamNode::m_ScriptVal
mutableprivate

Caches the ToJSVal script representation of this node.

◆ m_Value

std::string CParamNode::m_Value
private

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