# 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 cXMLElement * | getParentNode () const
virtual bool | hasChildren () const
virtual cXMLElement * | getFirstChild () const
virtual cXMLElement * | getLastChild () const
virtual cXMLElement * | getNextSibling () const
virtual cXMLElement * | getPreviousSibling () const
virtual cXMLElement * | getFirstChildWithTag (const char *tagname) const
virtual cXMLElement * | getNextSiblingWithTag (const char *tagname) const
virtual cXMLElementList | getChildren () const
virtual cXMLElementList | getChildrenByTagName (const char *tagname) const
virtual cXMLElementList | getElementsByTagName (const char *tagname) const
Utility functions
cXMLElement * | getFirstChildWithAttribute (const char *tagname, const char *attr, const char *attrvalue=NULL) const
cXMLElement * | getElementById (const char *idattrvalue) const
cXMLElement * | getElementByPath (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:

- cxmlelement.h