#include <cxmlelement.h>

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 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.

Inheritance diagram for cXMLElement:

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

Public Member Functions
Redefined cObject methods.
virtual const char *	getName () const override

virtual std::string	str () const override

virtual cObject *	getOwner () const override

virtual void	forEachChild (cVisitor *v) override

Common properties
virtual const char *	getTagName () const

virtual const char *	getSourceFileName () const

virtual int	getSourceLineNumber () const

virtual const char *	getSourceLocation () const

virtual const char *	getNodeValue () const

virtual const char *	getAttribute (const char *attr) const

virtual bool	hasAttributes () const

virtual cXMLAttributeMap	getAttributes () const

virtual std::string	getXML () 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
virtual cXMLElement *	getFirstChildWithAttribute (const char tagname, const char attr, const char *attrvalue=nullptr) const

virtual cXMLElement *	getElementById (const char *idattrvalue) const

virtual cXMLElement *	getElementByPath (const char pathexpression, cXMLElement root=nullptr, ParamResolver *resolver=nullptr) const

Public Member Functions inherited from cObject
	cObject ()

	cObject (const cObject &other)=default

virtual	~cObject ()

virtual const char *	getClassName () const

bool	isName (const char *s) const

virtual const char *	getFullName () const

virtual std::string	getFullPath () const

virtual std::string	getClassAndFullName () const

virtual std::string	getClassAndFullPath () const

const cObject *	getThisPtr () const

virtual std::ostream &	printOn (std::ostream &os) const

virtual cObject *	dup () const

virtual void	parsimPack (cCommBuffer *buffer) const

virtual void	parsimUnpack (cCommBuffer *buffer)

virtual bool	isOwnedObject () const

virtual bool	isSoftOwner () const

cObject *	findObject (const char *name, bool deep=true)

virtual cClassDescriptor *	getDescriptor () const

void	copyNotSupported () const

Additional Inherited Members
Protected Member Functions inherited from cObject
virtual void	take (cOwnedObject *obj)

virtual void	drop (cOwnedObject *obj)

void	dropAndDelete (cOwnedObject *obj)

Member Function Documentation

◆ getName()

virtual const char* getName ( ) const

inlineoverridevirtual

Returns the tag name as object name.

Reimplemented from cObject.

◆ str()

virtual std::string str ( ) const

overridevirtual

Returns a one-line description of the element.

Reimplemented from cObject.

◆ getOwner()

virtual cObject* getOwner ( ) const

inlineoverridevirtual

Returns the parent element.

Reimplemented from cObject.

◆ forEachChild()

virtual void forEachChild ( cVisitor * v )

overridevirtual

Enables traversing the object tree, performing some operation on each object. The operation is encapsulated in the particular subclass of cVisitor.

This method should be redefined in every subclass to call v->visit(obj) for every obj object contained.

Reimplemented from cObject.

◆ getTagName()

virtual const char* getTagName ( ) const

virtual

Returns the element name.

◆ getSourceFileName()

virtual const char* getSourceFileName ( ) const

inlinevirtual

Returns the file name this element originally came from.

◆ getSourceLineNumber()

virtual int getSourceLineNumber ( ) const

inlinevirtual

Returns the line number in the file this element originally came from.

◆ getSourceLocation()

virtual const char* getSourceLocation ( ) const

virtual

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

◆ getNodeValue()

virtual const char* getNodeValue ( ) const

virtual

Returns text node in the element, or nullptr otherwise. (Mixing text and child elements is not supported.)

◆ getAttribute()

virtual const char* getAttribute ( const char * attr ) const

virtual

Returns the value of the attribute with the given name. It returns nullptr if the given attribute is not found.

◆ hasAttributes()

virtual bool hasAttributes ( ) const

virtual

Returns true if the element has attributes

◆ getAttributes()

virtual cXMLAttributeMap getAttributes ( ) const

virtual

Returns attributes in an a std::map.

◆ getXML()

virtual std::string getXML ( ) const

virtual

Returns the subtree as an XML fragment.

◆ getParentNode()

virtual cXMLElement* getParentNode ( ) const

virtual

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

◆ hasChildren()

virtual bool hasChildren ( ) const

virtual

Returns true if the element has child elements.

◆ getFirstChild()

virtual cXMLElement* getFirstChild ( ) const

virtual

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

◆ getLastChild()

virtual cXMLElement* getLastChild ( ) const

virtual

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

◆ getNextSibling()

virtual cXMLElement* getNextSibling ( ) const

virtual

Returns pointer to the next sibling of this element (i.e. the next child in the parent element). Returns nullptr if there're no subsequent elements.

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

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

◆ getPreviousSibling()

virtual cXMLElement* getPreviousSibling ( ) const

virtual

Returns pointer to the previous sibling of this element (i.e. the previous child in the parent element). Returns nullptr if there're no elements before this one.

◆ getFirstChildWithTag()

virtual cXMLElement* getFirstChildWithTag ( const char * tagname ) const

virtual

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

◆ getNextSiblingWithTag()

virtual cXMLElement* getNextSiblingWithTag ( const char * tagname ) const

virtual

Returns pointer to the next sibling of this element with the given tag name. Return nullptr 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=element->getFirstChildWithTag("foo"); child; child = child->getNextSiblingWithTag("foo"))
{
    ...
}

◆ getChildren()

virtual cXMLElementList getChildren ( ) const

virtual

Returns list of child elements.

◆ getChildrenByTagName()

virtual cXMLElementList getChildrenByTagName ( const char * tagname ) const

virtual

Returns list of child elements with the given tag name.

◆ getElementsByTagName()

virtual cXMLElementList getElementsByTagName ( const char * tagname ) const

virtual

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

◆ getFirstChildWithAttribute()

virtual cXMLElement* getFirstChildWithAttribute	(	const char *	tagname,
		const char *	attr,
		const char *	attrvalue = `nullptr`
	)		const

virtual

Returns find first child element with the given tagname and the given attribute present, and (optionally) having the given value. tagname might be nullptr – then any element with the given attribute will be accepted. Returns nullptr if not found.

◆ getElementById()

virtual cXMLElement* getElementById ( const char * idattrvalue ) const

virtual

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 nullptr if not found.

◆ getElementByPath()

virtual cXMLElement* getElementByPath	(	const char *	pathexpression,
		cXMLElement *	root = `nullptr`,
		ParamResolver *	resolver = `nullptr`
	)		const

virtual

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

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

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

cxmlelement.h

Description

Classes

Public Member Functions

Additional Inherited Members

Member Function Documentation

◆ getName()

◆ str()

◆ getOwner()

◆ forEachChild()

◆ getTagName()

◆ getSourceFileName()

◆ getSourceLineNumber()

◆ getSourceLocation()

◆ getNodeValue()

◆ getAttribute()

◆ hasAttributes()

◆ getAttributes()

◆ getXML()

◆ getParentNode()

◆ hasChildren()

◆ getFirstChild()

◆ getLastChild()

◆ getNextSibling()

◆ getPreviousSibling()

◆ getFirstChildWithTag()

◆ getNextSiblingWithTag()

◆ getChildren()

◆ getChildrenByTagName()

◆ getElementsByTagName()

◆ getFirstChildWithAttribute()

◆ getElementById()

◆ getElementByPath()