---

skMSXMLElementObject Class Reference

This object is a container for a Microsoft MSXML XML element, and exposes an interface to it to Simkin The class implements methods from the Executable interface. More...

#include <skMSXMLElementObject.h>

Inheritance diagram for skMSXMLElementObject:

List of all members.

Public Member Functions
	skMSXMLElementObject ()
	Default Constructor.
	skMSXMLElementObject (const skString &location, XMLElement &elem)
	Constructor which takes an Element.
	~skMSXMLElementObject ()
	Destructor.
int	executableType () const
	Returns XMLELEMENT_TYPE indicating the element is an XMLElementObject.
int	intValue () const
float	floatValue () const
bool	boolValue () const
Char	charValue () const
skString	strValue () const
bool	setValue (const skString &name, const skString &attribute, const skRValue &return_value)
	sets the value of an item in the element.
bool	setValueAt (const skRValue &array_index, const skString &attribute, const skRValue &value)
	Sets a value within the nth element of the XML element.
bool	getValue (const skString &name, const skString &attribute, skRValue &return_value)
	Retrieves a field from the XML.
bool	getValueAt (const skRValue &array_index, const skString &attribute, skRValue &value)
	Retrieves the nth value from within the element.
bool	method (const skString &name, skRValueArray &args, skRValue &ret, skExecutableContext &ctxt)
	this method attempts to execute a method stored in the XML.
void	copyItemsInto (XMLElement &other)
	Clears the other element and does a deep copy of the children of this node into that one.
virtual void	setAddIfNotPresent (bool enable)
	sets the flag controlling whether new elements are created as they are accessed
virtual bool	getAddIfNotPresent ()
	this returns the value of the flag controlling whether new elements are created as they are accessed
XMLElement	getElement ()
	This method returns the XML Element being held by the object.
void	setAttribute (skString name, const skString &value)
	Sets an attribute on this node.
skString	getAttribute (const skString &name)
	This method returns the value of an attribute attached to this element.
skString	getLocation () const
	This function returns the location associated with this object (typically a file name).
void	save (ostream &out)
	Call this method to save the state of the object back to a stream.
virtual skString	getSource (const skString &location)
	Returns the source code for the given method.
virtual void	getInstanceVariables (skRValueTable &table)
	This method returns the instance variables for this object.
virtual void	getAttributes (skRValueTable &table)
	This method returns the attributes for this object.
Static Public Member Functions
skString	getData (const XMLElement &element)
	retrieves the text data from an element
void	setData (XMLElement &element, const skString &data)
	sets the text data for a node by looking for the first CDATA and TEXT child node
XMLElement	findChild (XMLElement &parent, const skString &tagname)
	returns a child element
XMLElement	findChild (XMLElement &parent, int index)
	returns the nth child element
XMLElement	findChild (XMLElement &parent, const skString &tagname, const skString &attribute, const skString &value)
	returns a child element with the given attribute set to the given value
skString	getAttribute (XMLElement &elem, const skString &name)
	safely retrieves an attribute from the given element
skString	toString (_bstr_t &str)
	Converts an MS string to a Simkin skString.
_bstr_t	fromString (const skString &str)
	Converts a Simkin skString to an MS string.
int	countChildren (XMLElement &parent)
	this method returns the number of element children of the given element
Protected Member Functions
virtual void	setElement (XMLElement &element)
	This method updates the associated element and clears the parse tree cache.
virtual skMSXMLElementObject *	createXMLElementObject (const skString &location, XMLElement &element)
	This method creates a new XML Element object to wrap an element.
skExecutableIterator *	createIterator (const skString &qualifier)
	This function returns an skExecutableIterator object which is used in the for each statement.
skExecutableIterator *	createIterator ()
	This function returns an skExecutableIterator object which is used in the for each statement.
Protected Attributes
skString	m_ScriptLocation
	the location that the XML document came from

---

Detailed Description

This object is a container for a Microsoft MSXML XML element, and exposes an interface to it to Simkin The class implements methods from the Executable interface.

The methods getValue, setValue and method all search for matching element tags within the XML document. Only the first matching tag is used. The class uses the Xerces library to access XML documents

The class supports the following fields:

• "nodename" - returns the tag name of this element
• "numChildren" - returns the number of children of this element

The class supports the following methods:

• dump - writes the whole XML Object out to the tracer (useful for debugging)
• enumerate([name]) - returns an skMSXMLElementObjectEnumerator which enumerates over the child elements of this element. If no tag name is passed the enumerator lists all the children. A tag name can be passed to show only children with the matching tag name.
• addElement([tag name]) - adds a new empty element with the given tag name to this element
• containsElement([tag name]) - returns true if the XML element contains an element with the given tag
• tagName - returns the tag name of this element

---

Constructor & Destructor Documentation

skMSXMLElementObject::skMSXMLElementObject (  const skString &  location, XMLElement &  elem )

Constructor which takes an Element. Parameters: location  - used to identify the source of the document in error messages elem  - the element to be stored

---

Member Function Documentation

bool skMSXMLElementObject::boolValue (   )  const [virtual]

Returns: the value of the element text data as a boolean Reimplemented from skExecutable.

Char skMSXMLElementObject::charValue (   )  const [virtual]

Returns: the first character of the element text data Reimplemented from skExecutable.

void skMSXMLElementObject::copyItemsInto (  XMLElement &  other  )

Clears the other element and does a deep copy of the children of this node into that one. Parameters: other  - the element into which our children will be copied

skExecutableIterator * skMSXMLElementObject::createIterator (   )  [protected, virtual]

This function returns an skExecutableIterator object which is used in the for each statement. It will iterate over *all* children of this element Reimplemented from skExecutable.

skExecutableIterator * skMSXMLElementObject::createIterator (  const skString &  qualifier  )  [protected, virtual]

This function returns an skExecutableIterator object which is used in the for each statement. It will iterate over elements with the given tag. Parameters: qualifier  tag - only elements with this tag will appear in the iteration Reimplemented from skExecutable.

skMSXMLElementObject * skMSXMLElementObject::createXMLElementObject (  const skString &  location, XMLElement &  element )  [protected, virtual]

This method creates a new XML Element object to wrap an element. Override this for special behaviour in derived classes. In this method, the newly created object inherits this object's m_AddIfNotPresent flag Parameters: location  the location of this element element  the DOM element to associate with the object

int skMSXMLElementObject::executableType (   )  const [virtual]

Returns XMLELEMENT_TYPE indicating the element is an XMLElementObject. Returns: the type as XML element Reimplemented from skExecutable.

XMLElement skMSXMLElementObject::findChild (  XMLElement &  parent, const skString &  tagname, const skString &  attribute, const skString &  value )  [static]

returns a child element with the given attribute set to the given value Parameters: parent  the parent element tagname  the tag name of the element attribute  name of the attribute value  value of the named attribute Returns: the first element child of the parent with the matching tag name and attribute value, or null if not found

XMLElement skMSXMLElementObject::findChild (  XMLElement &  parent, int  index )  [static]

returns the nth child element Parameters: parent  the parent element index  the index of the element Returns: the matching element or null if outside the current list ot items

XMLElement skMSXMLElementObject::findChild (  XMLElement &  parent, const skString &  tagname )  [static]

returns a child element Parameters: parent  the parent element tagname  the tag name of the element Returns: the first element child of the parent with the matching tag name, or null if not found

float skMSXMLElementObject::floatValue (   )  const [virtual]

Returns: the value of the element text data as a float Reimplemented from skExecutable.

bool skMSXMLElementObject::getAddIfNotPresent (   )  [virtual]

this returns the value of the flag controlling whether new elements are created as they are accessed Returns: true if the feature is enabled, otherwise false (the default)

skString skMSXMLElementObject::getAttribute (  const skString &  name  )

This method returns the value of an attribute attached to this element. Returns: the value of the given attribute

void skMSXMLElementObject::getAttributes (  skRValueTable &  table  )  [virtual]

This method returns the attributes for this object. Parameters: table  a table to filled with the values of the attributes Reimplemented from skExecutable.

skString skMSXMLElementObject::getData (  const XMLElement &  element  )  [static]

retrieves the text data from an element Parameters: element  Returns: the text from a child node of type CDATA or TEXT

XMLElement skMSXMLElementObject::getElement (   )

This method returns the XML Element being held by the object. Returns: the underlying Element

void skMSXMLElementObject::getInstanceVariables (  skRValueTable &  table  )  [virtual]

This method returns the instance variables for this object. Parameters: table  a table to filled with references to the instance variables Reimplemented from skExecutable.

bool skMSXMLElementObject::getValue (  const skString &  name, const skString &  attribute, skRValue &  return_value )  [virtual]

Retrieves a field from the XML. The first sub-element matching the tag is found. The value returned is an XMLElementObject, unless the attrib value is specified. It also supports the following built-in field: "nodename" - returns the tag name of this element If the m_AddIfNotPresent flag is true, a new item will be added if one is not already present. Parameters: name  - the tag name containing the data attribute  - the attribute name to retrieve return_value  - the RValue to containing the value to be set Returns: true if the method was found, false otherwise Reimplemented from skExecutable.

bool skMSXMLElementObject::getValueAt (  const skRValue &  array_index, const skString &  attribute, skRValue &  value )  [virtual]

Retrieves the nth value from within the element. If the array index falls within the range of the number of children of this element, a new XMLElementObject encapsulating the child is returned. If the m_AddIfNotPresent flag is true, a new item with the tag name "array_item" will be added if one is not already present Reimplemented from skExecutable.

int skMSXMLElementObject::intValue (   )  const [virtual]

Returns: the value of the element text data as an integer Reimplemented from skExecutable.

bool skMSXMLElementObject::method (  const skString &  name, skRValueArray &  args, skRValue &  ret, skExecutableContext &  ctxt )  [virtual]

this method attempts to execute a method stored in the XML. It searches for an element whose tag matches the method name and if found passes the text for the tag through to the interpeter. The method also supports the following methods to Simkin scripts: dump - writes the whole XML Object out to the tracer (useful for debugging) enumerate([name]) - returns an skMSXMLElementObjectEnumerator which enumerates over the child elements of this element. If no tag name is passed the enumerator lists all the children. A tag name can be passed to show only children with the matching tag name. Parameters: name  the name of the method args  an array of arguments to the method ret  the object to receive the result of the method call ctxt  context object to receive errors Returns: true if the method was found, false otherwise Exceptions: skParseException  - if a syntax error is encountered while the script is running skRuntimeException  - if an error occurs while the script is running Reimplemented from skExecutable.

void skMSXMLElementObject::save (  ostream &  out  )

Call this method to save the state of the object back to a stream. Exceptions: IOException  if there was an error writing to the stream

void skMSXMLElementObject::setAddIfNotPresent (  bool  enable  )  [virtual]

sets the flag controlling whether new elements are created as they are accessed Parameters: enable  enables this feature (which by default is disabled)

void skMSXMLElementObject::setData (  XMLElement &  element, const skString &  data )  [static]

sets the text data for a node by looking for the first CDATA and TEXT child node Parameters: element  the element to be changed data  the data to be set

void skMSXMLElementObject::setElement (  XMLElement &  element  )  [protected, virtual]

This method updates the associated element and clears the parse tree cache. Parameters: element  - the new Element

bool skMSXMLElementObject::setValue (  const skString &  name, const skString &  attribute, const skRValue &  return_value )  [virtual]

sets the value of an item in the element. The first sub-element matching the tag is found. If the value passed is an element, it is first copied. If the m_AddIfNotPresent flag is true, a new item will be added if one is not already present Parameters: name  - the name of the element tag to set (null if it's the overall element) attribute  - the name of the attribute to set (null to set text for the element) return_value  - the RValue to receive the value Returns: true if the field was found, false otherwise Reimplemented from skExecutable.

bool skMSXMLElementObject::setValueAt (  const skRValue &  array_index, const skString &  attribute, const skRValue &  value )  [virtual]

Sets a value within the nth element of the XML element. If the m_AddIfNotPresent flag is true, a new item with the tag name "array_item" will be added if one is not already present. Parameters: array_index  - the identifier of the item - this might be a string, integer or any other legal value attribute  - the attribute name to set (may be blank) value  - the value to be set Returns: true if the field was changed, false if the field could not be set or found Reimplemented from skExecutable.

skString skMSXMLElementObject::strValue (   )  const [virtual]

Returns: the value of the element text data as a string Reimplemented from skExecutable.

---

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

• skMSXMLElementObject.h
• skMSXMLElementObject.cpp

---