Represents an XML element in an XML configuration file. More...
#include <cxmlelement.h>
Classes | |
| class | ParamResolver |
| Base class for classes that resolve parameters ($PARAM) that occur in in XPath expressions to their values. More... | |
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 () const |
| virtual std::string | detailedInfo () const |
Represents an XML element in an XML configuration file.
XML-typed NED parameters are accessible as cXMLElement via the cPar::xmlValue() method.
cXMLElement provides readonly access to XML documents via a DOM-like API. (A full-featured DOM implementation would have been too bloated for the purpose of accessing readonly configuration files).
Features: readonly access (getter methods) only; represents only elements, attributes and text content (i.e. 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 is 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 is provided via limited support of the XInclude 1.0 spec, if the underlying XML parser supports it (e.g. Expat does not). An element <xi:include href="doc.xml"/> will be replaced with the content of the corresponding document. The "href" and "parse" attributes from the XInclude spec are supported.
| virtual std::string cXMLElement::detailedInfo | ( | ) | const [virtual] |
Returns tree contents in an 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.
| 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 nodefoo -- 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 (remove the 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" (remove the spaces!).// * [@color='yellow']/foo/bar -- first "bar" child of first "foo" child of a "yellow-colored" node (remove the spaces!)The method throws an exception if the path expression is invalid, and returns NULL if the element is not found.
| 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::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::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.
1.6.3