Phx::XmlDescriptionNode Class Reference

A value-type that converts an XmlNode into a form more easily manipulated by the Description class. More...

#include <PhxXmlDescription.h>

List of all members.

Public Types
typedef std::set< AttribSpec, AttribSpecComp >	AttribSpecSet
	A typedef for a set of AttribSpec's.
Public Member Functions
	XmlDescriptionNode (XmlNode *node)
	Constructs a description node from an existing XmlNode.
	XmlDescriptionNode (const String &descType)
	Constructs a description node that is empty.
	XmlDescriptionNode (const XmlDescriptionNode &node)
	Copy constructor to copy a node.
const XmlDescriptionNode &	operator= (const XmlDescriptionNode &rhs)
	Assignment operator allowing nodes to be copied.
const String &	type (void) const
	Gets the node type (i.e., the tag).
void	type (const String &type)
	Sets the node type (tag).
void	file (const String &file)
	Sets the file attribute value.
const String &	file (void) const
	Gets the file attribute value.
uint32_t	attributeCount (void) const
	Gets the number of attributes attached to this node.
AttribSpecSet	attributes (const String &name="") const
	Returns a std::vector containing all of the AttribSpec structures which have associated attribute values.
XmlDescriptionNode *	childAttribute (const AttribSpec &attrib)
	Retrieves the child node that is keyed by the "name" and "index" fields specified in the given AttribSpec.
const XmlDescriptionNode *	childAttribute (const AttribSpec &attrib) const
XmlDescriptionNode	childAttributeSubstitute (const AttribSpec &attrib) const
	Recursively loads description nodes until the child node referenced by the file() attribute is found.
void	childAttribute (const AttribSpec &attrib, const XmlDescriptionNode *node)
	Sets the child node for the given attribute name and index (specified by an AttribSpec).
void	childAttribute (const AttribSpec &attrib, const XmlDescriptionNode &node)
	Same as childAttribute(const AttribSpec&, const XmlDescriptionNode*) but takes const-reference as the attribute value.
String	stringAttributeDefault (const AttribSpec &attrib, const String &defaultValue="") const
	Retrieves the value of the attribute with name given, parsed as a string.
String	stringAttribute (const AttribSpec &attrib) const
	Retrieves the value of the attribute with name given.
void	stringAttribute (const AttribSpec &attrib, const String &value)
	Sets the attribute 'name' as a string.
float	floatAttribute (const AttribSpec &attrib) const
double	doubleAttribute (const AttribSpec &attrib) const
uint64_t	uint64Attribute (const AttribSpec &attrib) const
uint32_t	uint32Attribute (const AttribSpec &attrib) const
uint16_t	uint16Attribute (const AttribSpec &attrib) const
uint8_t	uint8Attribute (const AttribSpec &attrib) const
int64_t	int64Attribute (const AttribSpec &attrib) const
int32_t	int32Attribute (const AttribSpec &attrib) const
int16_t	int16Attribute (const AttribSpec &attrib) const
int8_t	int8Attribute (const AttribSpec &attrib) const
bool	boolAttribute (const AttribSpec &attrib) const
float	floatAttributeDefault (const AttribSpec &attrib, float defaultValue) const
double	doubleAttributeDefault (const AttribSpec &attrib, double defaultValue) const
uint64_t	uint64AttributeDefault (const AttribSpec &attrib, uint64_t defaultValue) const
uint32_t	uint32AttributeDefault (const AttribSpec &attrib, uint32_t defaultValue) const
uint16_t	uint16AttributeDefault (const AttribSpec &attrib, uint16_t defaultValue) const
uint8_t	uint8AttributeDefault (const AttribSpec &attrib, uint8_t defaultValue) const
int64_t	int64AttributeDefault (const AttribSpec &attrib, int64_t defaultValue) const
int32_t	int32AttributeDefault (const AttribSpec &attrib, int32_t defaultValue) const
int16_t	int16AttributeDefault (const AttribSpec &attrib, int16_t defaultValue) const
int8_t	int8AttributeDefault (const AttribSpec &attrib, int8_t defaultValue) const
bool	boolAttributeDefault (const AttribSpec &attrib, bool defaultValue) const
void	floatAttribute (const AttribSpec &attrib, float value)
void	doubleAttribute (const AttribSpec &attrib, double value)
void	uint64Attribute (const AttribSpec &attrib, uint64_t value)
void	uint32Attribute (const AttribSpec &attrib, uint32_t value)
void	uint16Attribute (const AttribSpec &attrib, uint16_t value)
void	uint8Attribute (const AttribSpec &attrib, uint8_t value)
void	int64Attribute (const AttribSpec &attrib, int64_t value)
void	int32Attribute (const AttribSpec &attrib, int32_t value)
void	int16Attribute (const AttribSpec &attrib, int16_t value)
void	int8Attribute (const AttribSpec &attrib, int8_t value)
void	boolAttribute (const AttribSpec &attrib, bool value)
Friends
std::ostream &	operator<< (std::ostream &os, const XmlDescriptionNode &node)
	Operator to print XmlDescriptionNode to ostream.
Classes
class	AttribSpec
	Attributes in a description can either be a singleton or a collection. This AttribSpec structure allows one to specify an attribute by name, or name and selector (for collections) to XmlDescriptionNode APIs. More...
struct	AttribSpecComp

---

Detailed Description

A value-type that converts an XmlNode into a form more easily manipulated by the Description class.

The XmlDocument and XmlNode class provide a level of detail not necessary for Description values. Descriptions also need to be able to pass XmlNode's by value and often make copies without the presence of an owning document (and hence no definition of encoding, a DTD, etc.) This is not possible using the XmlNode class directly, and thus we trade away the XmlDocument/XmlNode classes' power and generality for flexibility and specificity by using this class instead of XmlNode.

Note:

Attributes with a value of "" are considered "empty" are may be ignored. Your code should never depend on an attribute being able to hold the value "", as this value will not be read or written to files.

---

Constructor & Destructor Documentation

Phx::XmlDescriptionNode::XmlDescriptionNode (  XmlNode *  node  )

Constructs a description node from an existing XmlNode. This clones the entire node and all of its children. Parameters: node  The XmlNode to be copied.

Phx::XmlDescriptionNode::XmlDescriptionNode (  const String &  descType  )

Constructs a description node that is empty. Parameters: descType  The type of description this node represents. In an xml file, this is the tag of the node.

Phx::XmlDescriptionNode::XmlDescriptionNode (  const XmlDescriptionNode &  node  )

Copy constructor to copy a node. Parameters: node  The node to be copied.

---

Member Function Documentation

uint32_t Phx::XmlDescriptionNode::attributeCount (  void   )  const [inline]

Gets the number of attributes attached to this node. This is the total number of child elements, including ATTRIB elements and child XML nodes.

AttribSpecSet Phx::XmlDescriptionNode::attributes (  const String &  name = ""  )  const

Returns a std::vector containing all of the AttribSpec structures which have associated attribute values. Since clients will often not know the value of the selector for many of their collection attributes (or for that matter, how many attributes are in the collection), they may use this method to get a list of the existing attributes and then iterate through the list, checking for known attributes with valid selectors before querying the attribute value. Parameters: name  An attribute name that can be passed to filter the returned values. If name is "", all valid AttribSpec's will be returned. Otherwise, only those with AttribSpec::name() == name will be returned (that is, all those attributes from the same collection). Warning: The order of the returned attribute specifications is implementation dependent and should not be relied upon.

void Phx::XmlDescriptionNode::childAttribute (  const AttribSpec &  attrib, const XmlDescriptionNode &  node )

Same as childAttribute(const AttribSpec&, const XmlDescriptionNode*) but takes const-reference as the attribute value. This syntax is somewhat more convenient/efficient for certain situations, as it allows the client to pass a temporary. Parameters: attrib  An AttribSpec designating the attribute described by node. node  A const-reference to the XmlDescriptionNode to be copied as the attribute

void Phx::XmlDescriptionNode::childAttribute (  const AttribSpec &  attrib, const XmlDescriptionNode *  node )

Sets the child node for the given attribute name and index (specified by an AttribSpec). The node given here is copied. The pointer parameter remains the responsbility of the client. Parameters: attrib  An AttribSpec designating the attribute described by node. node  A pointer to the XmlDescriptionNode to be copied as the attribute. If node is 0, the child will be removed.

XmlDescriptionNode* Phx::XmlDescriptionNode::childAttribute (  const AttribSpec &  attrib  )

Retrieves the child node that is keyed by the "name" and "index" fields specified in the given AttribSpec. This returns the child node precisely as it appears in the XML file, including its file() attribute (which specifies the file whose content should be used in lieu of this node's content). In the case that file() != "", the client should honor the file author's request and attempt to use the referenced file instead. Use childAttributeSubstitute() to retrieve the ultimately referenced node automatically (this is the typical call used by simulator components). However, some editors may wish to view/modify the exact XML data, in which case this method may be more appropriate. Parameters: attrib  The child attribute node to be returned. Returns: The requested child node, or 0 if no such child exists.

XmlDescriptionNode Phx::XmlDescriptionNode::childAttributeSubstitute (  const AttribSpec &  attrib  )  const

Recursively loads description nodes until the child node referenced by the file() attribute is found. If the requested node has a file() parameter value, then the contents of the specified file will be loaded and parsed. If the parsed node also specifies a file() attribute, then the substitution is performed and continues recursively. When the final content is located (i.e., a node is parsed with file() == "") the substitution stops and that node is returned as the child of this node. Of course, if the child node has file() == "" already, a copy of the child is returned. If the substitution is not desired (i.e., you want the verbatim content of the node, including its file() attribute), then request the child node via childAttribute(). Note: The referenced file is read in each time this method is called. Reading the file in when this XmlDescriptionNode was constructed would make many nodes unnecessarily large. Thus, the substitution is performed on request only, and the once the copy is returned, it will not be cached internally. Parameters: attrib  The child attribute node to be returned. Returns: The requested child node, or an empty node if the child does not exist. You can easily query the existance of a child using childAttribute() (which returns 0 when the child does not exist). Exceptions: NotFoundException,IOException  if there is a problem opening a referenced file.

const String& Phx::XmlDescriptionNode::file (  void   )  const [inline]

Gets the file attribute value. See also: file(const String&).

void Phx::XmlDescriptionNode::file (  const String &  file  )  [inline]

Sets the file attribute value. The file attribute is an optional value that specifies an external file whose content should be used in lieu of other content in this node. That is, all content in the node should be ignored if file() != "". By default, childAttribute() will automatically perform this substitution (returning instead the content from the other file). Parameters: file  The new file value.

const XmlDescriptionNode& Phx::XmlDescriptionNode::operator= (  const XmlDescriptionNode &  rhs  )

Assignment operator allowing nodes to be copied. Parameters: rhs  The node to be copied to 'this'. Returns: *this

void Phx::XmlDescriptionNode::stringAttribute (  const AttribSpec &  attrib, const String &  value )

Sets the attribute 'name' as a string. Parameters: attrib  The attribute to be written. value  The value to be set for the attribute attrib. If value is "", the attribute will be removed.

String Phx::XmlDescriptionNode::stringAttribute (  const AttribSpec &  attrib  )  const [inline]

Retrieves the value of the attribute with name given. Parameters: attrib  The attribute to be returned. Returns: The attribute value, as a string, or "" if a value was not found.

String Phx::XmlDescriptionNode::stringAttributeDefault (  const AttribSpec &  attrib, const String &  defaultValue = "" )  const

Retrieves the value of the attribute with name given, parsed as a string. Parameters: attrib  The attribute to be returned. defaultValue  The value to be returned if attribute attrib does not exist (or it is "", which is considered to be equivalent), or if it could not be parsed correctly. Returns: The value of the attribute, as a string.

void Phx::XmlDescriptionNode::type (  const String &  type  )  [inline]

Sets the node type (tag). Parameters: type  The new type for the element.

---

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

• PhxXmlDescription.h

---