cXMLElement Class Reference
[Utility classes]

#include <cxmlelement.h>

List of all members.


Detailed Description

Represents an XML element in an XML configuration file.

XML-typed NED parameters are accessible as cXMLElement via the cPar::xmlValue() method.

cXMLElement provides read only access to the XML, with functionality that resembles DOM. (A full-featured DOM implementation would have been too bloated for the purpose of accessing readonly configuration files).

Features: only readonly (getter) methods; represents only elements and text (entities, processing instructions, comments are ignored); attributes are presented as part of an element node (not as separate attribute nodes as in DOM); mixed content model not supported (element body cannot mix text with further elements); text is represented as a property of its enclosing element (and not as separate node as in DOM); CDATA sections are also represented as text (with the above restrictions); strings are presented in UTF-8 format (which is normal ASCII string if only characters 0x01-0x7F are used; encoding of the XML file itself may use arbitrary encoding provided it's supported by the underlying XML parser); no namespace support.

Supports XPath-like addressing via the getElementByPath() member function.

File inclusion via limited support of the XInclude 1.0 spec. An element <xi:include href="doc.xml"/> gets replaced with the content of the corresponding document. The "href" and "parse" attributes from the XInclude spec are supported.


Public Member Functions

Common properties
virtual const char * getTagName () const
virtual const char * getSourceLocation () const
virtual const char * getNodeValue () const
virtual const char * getAttribute (const char *attr) const
virtual bool hasAttributes () const
virtual const cXMLAttributeMap & getAttributes () const
Generic access to children and siblings
virtual cXMLElementgetParentNode () const
virtual bool hasChildren () const
virtual cXMLElementgetFirstChild () const
virtual cXMLElementgetLastChild () const
virtual cXMLElementgetNextSibling () const
virtual cXMLElementgetPreviousSibling () const
virtual cXMLElementgetFirstChildWithTag (const char *tagname) const
virtual cXMLElementgetNextSiblingWithTag (const char *tagname) const
virtual cXMLElementList getChildren () const
virtual cXMLElementList getChildrenByTagName (const char *tagname) const
virtual cXMLElementList getElementsByTagName (const char *tagname) const
Utility functions
cXMLElementgetFirstChildWithAttribute (const char *tagname, const char *attr, const char *attrvalue=NULL) const
cXMLElementgetElementById (const char *idattrvalue) const
cXMLElementgetElementByPath (const char *pathexpression, cXMLElement *root=NULL, ParamResolver *resolver=NULL) const
void debugDump (int depth=0) const

Classes

class  ParamResolver
 Base class for classes that resolve parameters ($PARAM) that occur in in XPath expressions to their values. More...


Member Function Documentation

void cXMLElement::debugDump int  depth = 0  )  const
 

Dumps tree content to ev in a XML-like format.

This method is only useful for debugging, because it does not perform necessary escaping in text nodes and attribute values, so the output is not necessarily well-formed XML.

virtual const char* cXMLElement::getAttribute const char *  attr  )  const [virtual]
 

Returns the value of the attribute with the given name.

It returns NULL if the given attribute is not found.

virtual const cXMLAttributeMap& cXMLElement::getAttributes  )  const [virtual]
 

Returns attributes as a const (immutable) std::map.

virtual cXMLElementList cXMLElement::getChildren  )  const [virtual]
 

Returns list of child elements.

virtual cXMLElementList cXMLElement::getChildrenByTagName const char *  tagname  )  const [virtual]
 

Returns list of child elements with the given tag name.

cXMLElement* cXMLElement::getElementById const char *  idattrvalue  )  const
 

Returns the first element which has an "id" attribute with the given value.

("id" attributes are supposed to be unique in an XML document.) Returns NULL if not found.

cXMLElement* cXMLElement::getElementByPath const char *  pathexpression,
cXMLElement root = NULL,
ParamResolver resolver = NULL
const
 

Returns the first element designated by the given path expression.

("First" in the sense of preorder depth-first traversal.) Path expressions must be given in an XPath-like notation: they consist of path components (or "steps") separated by "/" or "//". A path component can be an element tag name, "*", "." or ".."; tag name and "*" can have an optional predicate in the form "[position]" or "[@attribute='value']". "/" means child element; "//" means a element any levels under the current one; ".", ".." and "*" mean what you expect them to: current element, parent element, element with any tag name.

Examples:

  • . -- this element
  • ./foo -- first "foo" child of this node
  • foo -- same as ./foo (initial ./ can be omitted)
  • ./foo -- first "foo" child of this node
  • ./foo/bar -- first "bar" child of first "foo" child of this node
  • .//bar -- first "bar" anywhere under this node (depth-first search!)
  • ./ * /bar -- first "bar" child two levels below this node (omit spaces)
  • ./foo[0] -- first "foo" child of this node
  • ./foo[1] -- second "foo" child of this node
  • ./foo[@color='green'] -- first "foo" child which has attribute "color" with value "green"
  • .//bar[1] -- a "bar" anywhere under this node which is the second "bar" among its siblings
  • .// * [@color='yellow'] -- an element anywhere under this node with attribute color="yellow" (omit spaces)
  • .// * [@color='yellow']/foo/bar -- first "bar" child of first "foo" child of a "yellow-colored" node (omit spaces)

The method throws an exception if the path expression is invalid, and returns NULL if the element is not found.

virtual cXMLElementList cXMLElement::getElementsByTagName const char *  tagname  )  const [virtual]
 

Returns list of contained elements with the given tag name, in preorder traversal order.

virtual cXMLElement* cXMLElement::getFirstChild  )  const [virtual]
 

Returns pointer to the first child element, or NULL if this element has no children.

cXMLElement* cXMLElement::getFirstChildWithAttribute const char *  tagname,
const char *  attr,
const char *  attrvalue = NULL
const
 

Returns find first child element with the given tagname and the given attribute present, and (optionally) having the given value.

tagname might be NULL -- then any element with the given attribute will be accepted. Returns NULL if not found.

virtual cXMLElement* cXMLElement::getFirstChildWithTag const char *  tagname  )  const [virtual]
 

Returns pointer to the first child element with the given tag name, or NULL if this element has no such children.

virtual cXMLElement* cXMLElement::getLastChild  )  const [virtual]
 

Returns pointer to the last child element, or NULL if this element has no children.

virtual cXMLElement* cXMLElement::getNextSibling  )  const [virtual]
 

Returns pointer to the next sibling of this element (i.e.

the next child in the parent element). Returns NULL if there're no subsequent elements.

getFirstChild() and getNextSibling() can be used to loop through the child list:

 for (cXMLElement *child=node->getFirstChild(); child; child = child->getNextSibling())
 {
    ...
 }
 

virtual cXMLElement* cXMLElement::getNextSiblingWithTag const char *  tagname  )  const [virtual]
 

Returns pointer to the next sibling of this element with the given tag name.

Return NULL if there're no such subsequent elements.

getFirstChildWithTag() and getNextSiblingWithTag() are a convient way to loop through elements with a certain tag name in the child list:

 for (cXMLElement *child=node->getFirstChildWithTag("foo"); child; child = child->getNextSiblingWithTag("foo"))
 {
     ...
 }
 

virtual const char* cXMLElement::getNodeValue  )  const [virtual]
 

Returns text node in the element, or NULL otherwise.

(Mixing text and child elements is not supported.)

virtual cXMLElement* cXMLElement::getParentNode  )  const [virtual]
 

Returns the parent element, or NULL if this element has no parent.

virtual cXMLElement* cXMLElement::getPreviousSibling  )  const [virtual]
 

Returns pointer to the previous sibling of this element (i.e.

the previous child in the parent element). Returns NULL if there're no elements before this one.

virtual const char* cXMLElement::getSourceLocation  )  const [virtual]
 

Returns a string containing a file/line position showing where this element originally came from.

virtual const char* cXMLElement::getTagName  )  const [virtual]
 

Returns the element name.

virtual bool cXMLElement::hasAttributes  )  const [virtual]
 

Returns true if the node has attributes.

virtual bool cXMLElement::hasChildren  )  const [virtual]
 

Returns true if the node has children.


The documentation for this class was generated from the following file:
Generated on Sat Oct 21 17:47:57 2006 for OMNeT++/OMNEST Simulation Library by  doxygen 1.4.6