Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | Related Pages
gloox::Tag

Tag Class Reference

This is an abstraction of an XML element. More...

#include <tag.h>

Inherited by Stanza.

Inheritance diagram for Tag:

Inheritance graph
[legend]
Collaboration diagram for Tag:

Collaboration graph
[legend]
List of all members.

Public Types

typedef std::pair< std::string,
std::string > 		Attribute
typedef std::list< Attribute > AttributeList
typedef std::list< Tag * > TagList

Public Member Functions

GLOOX_DEPRECATED_CTOR Tag ()
 Tag (const std::string &name, const std::string &cdata="", bool incoming=false)
 Tag (Tag *parent, const std::string &name, const std::string &cdata="", bool incoming=false)
 Tag (const std::string &name, const std::string &attrib, const std::string &value, bool incoming=false)
 Tag (Tag *parent, const std::string &name, const std::string &attrib, const std::string &value, bool incoming=false)
virtual ~Tag ()
virtual const std::string xml () const
virtual void addAttribute (const std::string &name, const std::string &value)
virtual void addAttribute (const std::string &name, int value)
virtual void addAttribute (const std::string &name, long value)
virtual void setAttributes (const AttributeList &attributes)
virtual void addChild (Tag *child)
virtual void addChildCopy (const Tag *child)
virtual void setCData (const std::string &cdata)
virtual void addCData (const std::string &cdata)
virtual const std::string & name () const
virtual const std::string & cdata () const
virtual AttributeList & attributes ()
virtual const AttributeList & attributes () const
virtual TagList & children ()
virtual const TagList & children () const
virtual const std::string findAttribute (const std::string &name) const
virtual bool hasAttribute (const std::string &name, const std::string &value="") const
virtual Tag * findChild (const std::string &name) const
virtual Tag * findChild (const std::string &name, const std::string &attr, const std::string &value="") const
virtual bool hasChild (const std::string &name, const std::string &attr="", const std::string &value="") const
virtual Tag * findChildWithAttrib (const std::string &attr, const std::string &value="") const
virtual bool hasChildWithAttrib (const std::string &attr, const std::string &value="") const
TagList findChildren (const std::string &name) const
void removeChild (Tag *tag)
virtual GLOOX_DEPRECATED bool empty () const
bool hasChildWithCData (const std::string &name, const std::string &cdata) const
Tag * parent () const
virtual StanzaType type () const
virtual Tag * clone () const
Tag * findTag (const std::string &expression)
Tag::TagList findTagList (const std::string &expression)
bool operator== (const Tag &right) const
bool operator!= (const Tag &right) const
 operator bool () const

Static Public Member Functions

static const std::string escape (std::string what)
static const std::string relax (std::string what)

Protected Types

enum  XPathError { XPNoError, XPExpectedLeftOperand }

Detailed Description

This is an abstraction of an XML element.

Author:
Jakob Schroeter <js@camaya.net>
Since:
0.4

Definition at line 32 of file tag.h.

Member Typedef Documentation

typedef std::pair<std::string, std::string> Attribute
 

An XML element's attribute.

Definition at line 38 of file tag.h.

typedef std::list<Attribute> AttributeList
 

A list of XML element attributes.

Definition at line 43 of file tag.h.

typedef std::list<Tag*> TagList
 

A list of Tags.

Definition at line 48 of file tag.h.

Member Enumeration Documentation

enum XPathError [protected]
 

XPath error conditions.

Enumeration values:
XPNoError  No error occured.
XPExpectedLeftOperand  Operator expected a left-hand operand.

Definition at line 385 of file tag.h.

Constructor & Destructor Documentation

Tag (   ) 
 

Creates an empty tag.

Deprecated:
Will be removed in 1.0

Definition at line 29 of file tag.cpp.

Tag (  const std::string &  name,
const std::string &  cdata = "",
bool  incoming = false
)  [explicit]
 

Creates a new tag with a given name (and XML character data, if given).

Parameters:
name The name of the element.
cdata The XML character data of the element.
incoming Indicates whether tag names, attributes, attribute values, and cdata shall be escaped (false, default) or not (true).

Definition at line 34 of file tag.cpp.

Tag (  Tag *  parent,
const std::string &  name,
const std::string &  cdata = "",
bool  incoming = false
)  [explicit]
 

Creates a new tag as a child tag of the given parent, with a given name (and XML character data, if given).

Parameters:
parent The parent tag.
name The name of the element.
cdata The XML character data of the element.
incoming Indicates whether tag names, attributes, attribute values, and cdata shall be escaped (false, default) or not (true).

Definition at line 42 of file tag.cpp.

Tag (  const std::string &  name,
const std::string &  attrib,
const std::string &  value,
bool  incoming = false
)  [explicit]
 

Creates a new tag with a given name and an attribute.

Parameters:
name The name of the element.
attrib The attribute name.
value The attribute value.
incoming Indicates whether tag names, attributes, attribute values, and cdata shall be escaped (false, default) or not (true).
Since:
0.9

Definition at line 52 of file tag.cpp.

Tag (  Tag *  parent,
const std::string &  name,
const std::string &  attrib,
const std::string &  value,
bool  incoming = false
)  [explicit]
 

Creates a new tag as a child tag of the given parent, with a given name and an attribute.

Parameters:
parent The parent tag.
name The name of the element.
attrib The attribute name.
value The attribute value.
incoming Indicates whether tag names, attributes, attribute values, and cdata shall be escaped (false, default) or not (true).
Since:
0.9

Definition at line 60 of file tag.cpp.

~Tag (   )  [virtual]
 

Virtual destructor.

Definition at line 71 of file tag.cpp.

Member Function Documentation

void addAttribute (  const std::string &  name,
long  value
)  [virtual]
 

Use this function to add a new attribute to the tag. The value is a long here.

Parameters:
name The name of the attribute.
value The value of the attribute.
Since:
0.9

Definition at line 255 of file tag.cpp.

void addAttribute (  const std::string &  name,
int  value
)  [virtual]
 

Use this function to add a new attribute to the tag. The value is an int here.

Parameters:
name The name of the attribute.
value The value of the attribute.
Since:
0.8

Definition at line 236 of file tag.cpp.

void addAttribute (  const std::string &  name,
const std::string &  value
)  [virtual]
 

Use this function to add a new attribute to the tag.

Parameters:
name The name of the attribute.
value The value of the attribute.

Definition at line 217 of file tag.cpp.

virtual void addCData (  const std::string &  cdata  )  [inline, virtual]
 

Adds the string to the existing XML character data for this Tag.

Parameters:
cdata The additional cdata.

Definition at line 169 of file tag.h.

void addChild (  Tag *  child  )  [virtual]
 

Use this function to add a child node to the tag. The Tag will be owned by Tag.

Parameters:
child The node to be inserted.

Definition at line 274 of file tag.cpp.

void addChildCopy (  const Tag *  child  )  [virtual]
 

Use this function to add a copy of the given element to the tag.

Parameters:
child The node to be inserted.
Since:
0.9

Definition at line 283 of file tag.cpp.

virtual const AttributeList& attributes (   )  const [inline, virtual]
 

Use this function to fetch a const list of attributes.

Returns:
A constant reference to the list of attributes.

Definition at line 194 of file tag.h.

virtual AttributeList& attributes (   )  [inline, virtual]
 

Use this function to manipulate the list of attributes.

Returns:
A reference to the list of attributes.

Definition at line 188 of file tag.h.

virtual const std::string& cdata (   )  const [inline, virtual]
 

Use this function to retrieve the XML character data of an element.

Returns:
The cdata the element contains.

Definition at line 182 of file tag.h.

virtual const TagList& children (   )  const [inline, virtual]
 

Use this function to fetch a const list of child elements.

Returns:
A constant reference to the list of child elements.

Definition at line 206 of file tag.h.

virtual TagList& children (   )  [inline, virtual]
 

Use this function to manipulate the list of child elements.

Returns:
A reference to the list of child elements.

Definition at line 200 of file tag.h.

Tag * clone (   )  const [virtual]
 

This function creates a deep copy of this Tag.

Returns:
An independent copy of the Tag.
Since:
0.7

Definition at line 356 of file tag.cpp.

virtual GLOOX_DEPRECATED bool empty (   )  const [inline, virtual]
 

Returns whether the Tag is considered empty, i.e. invalid.

Returns:
True if the Tag is valid, false if not.
Deprecated:
Use operator bool() instead.

Definition at line 295 of file tag.h.

const std::string escape (  std::string  what  )  [static]
 

Does some fancy escaping. (& --> &, etc).

Parameters:
what A string to escape.
Deprecated:
Will be removed in 1.0.

Definition at line 151 of file tag.cpp.

const std::string findAttribute (  const std::string &  name  )  const [virtual]
 

This function can be used to retrieve the value of a Tag's attribute.

Parameters:
name The name of the attribute to look for.
Returns:
The value of the attribute if found, an empty string otherwise.

Definition at line 293 of file tag.cpp.

Tag * findChild (  const std::string &  name,
const std::string &  attr,
const std::string &  value = ""
)  const [virtual]
 

This function finds and returns the first element within the child elements of the current tag, that has a certain name, and a certain attribute with a certain value.

Parameters:
name The name of the element to search for.
attr The name of the attribute of the child element.
value The value of the attribute of the child element.
Returns:
The found Tag, or NULL.

Definition at line 325 of file tag.cpp.

Tag * findChild (  const std::string &  name  )  const [virtual]
 

This function finds and returns the first element within the child elements of the current tag that has a matching tag name.

Parameters:
name The name of the element to search for.
Returns:
The found Tag, or NULL.

Definition at line 317 of file tag.cpp.

Tag::TagList findChildren (  const std::string &  name  )  const
 

Returns a list of child tags of the current tag with the given name.

Parameters:
name The name of the tags to look for.
Returns:
A list of tags with the given name.
Note:
The tags are still linked to the current Tag and should not be deleted from the TagList.
Since:
0.9

Definition at line 371 of file tag.cpp.

Tag * findChildWithAttrib (  const std::string &  attr,
const std::string &  value = ""
)  const [virtual]
 

This function checks whether the Tag has a child element which posesses a given attribute with an optional value. The name of the child element does not matter.

Parameters:
attr The name of the attribute of the child element.
value The value of the attribute of the child element.
Returns:
The child if found, NULL otherwise.

Definition at line 348 of file tag.cpp.

Tag * findTag (  const std::string &  expression  ) 
 

Evaluates the given XPath expression and returns the result Tag. If more than one Tag match, only the first one is returned.

Note:
Currently, XPath support is somewhat limited. However, it should be useable for basic expressions. For now, see src/tests/xpath/xpath_test.cpp for supported expressions.
Parameters:
expression An XPath expression to evaluate.
Returns:
A matched Tag, or 0.
Since:
0.9

Definition at line 388 of file tag.cpp.

Tag::TagList findTagList (  const std::string &  expression  ) 
 

Evaluates the given XPath expression and returns the matched Tags.

Note:
Currently, XPath support is somewhat limited. However, it should be useable for basic expressions. For now, see src/tests/xpath/xpath_test.cpp for supported expressions.
Parameters:
expression An XPath expression to evaluate.
Returns:
A list of matched Tags, or an empty TagList.
Since:
0.9

Definition at line 394 of file tag.cpp.

bool hasAttribute (  const std::string &  name,
const std::string &  value = ""
)  const [virtual]
 

Checks whether the tag has a attribute with given name and optional value.

Parameters:
name The name of the attribute to check for.
value The value of the attribute to check for.
Returns:
Whether the attribute exists (optionally with the given value).

Definition at line 303 of file tag.cpp.

virtual bool hasChild (  const std::string &  name,
const std::string &  attr = "",
const std::string &  value = ""
)  const [inline, virtual]
 

This function checks whether the Tag has a child element with a given name, and optionally this child element is checked for having a given attribute with an optional value.

Parameters:
name The name of the child element.
attr The name of the attribute of the child element.
value The value of the attribute of the child element.
Returns:
True if the given child element exists, false otherwise.

Definition at line 250 of file tag.h.

virtual bool hasChildWithAttrib (  const std::string &  attr,
const std::string &  value = ""
)  const [inline, virtual]
 

This function checks whether the Tag has a child element which posesses a given attribute with an optional value. The name of the child element does not matter.

Parameters:
attr The name of the attribute of the child element.
value The value of the attribute of the child element.
Returns:
True if any such child element exists, false otherwise.

Definition at line 270 of file tag.h.

bool hasChildWithCData (  const std::string &  name,
const std::string &  cdata
)  const
 

This function checks whether a child element with given name exists and has XML character data that equals the given cdata string.

Parameters:
name The name of the child element.
cdata The character data that has to exist in the child element.
Returns:
True if a child element with given cdata exists, false otherwise.

Definition at line 339 of file tag.cpp.

virtual const std::string& name (   )  const [inline, virtual]
 

Use this function to retrieve the name of an element.

Returns:
The name of the tag.

Definition at line 176 of file tag.h.

operator bool (   )  const [inline]
 

Returns true if the Tag is valid, false otherwise.

Definition at line 365 of file tag.h.

bool operator!= (  const Tag &  right  )  const [inline]
 

Checks two Tags for inequality. Order of attributes and child tags does matter.

Parameters:
right The Tag to check against the current Tag.
Since:
0.9

Definition at line 360 of file tag.h.

bool operator== (  const Tag &  right  )  const
 

Checks two Tags for equality. Order of attributes and child tags does matter.

Parameters:
right The Tag to check against the current Tag.
Since:
0.9

Definition at line 81 of file tag.cpp.

Tag* parent (   )  const [inline]
 

Returns the tag's parent Tag.

Returns:
The Tag above the current Tag. May be 0.

Definition at line 310 of file tag.h.

const std::string relax (  std::string  what  )  [static]
 

Reverses operation of escape(). (& --> &).

Parameters:
what A string to de-escape.
Deprecated:
Will be removed in 1.0.

Definition at line 173 of file tag.cpp.

void removeChild (  Tag *  tag  )  [inline]
 

Removes the given Tag from the list of child Tags.

Parameters:
tag The Tag to delete from the list of child Tags.
Note:
The Tag tag is not deleted.

Definition at line 288 of file tag.h.

virtual void setAttributes (  const AttributeList &  attributes  )  [inline, virtual]
 

Sets the given attributes. Any existing attributes are lost.

Parameters:
attributes The attributes to set.
Since:
0.9

Definition at line 143 of file tag.h.

virtual void setCData (  const std::string &  cdata  )  [inline, virtual]
 

Sets the XML character data for this Tag.

Parameters:
cdata The new cdata.

Definition at line 162 of file tag.h.

virtual StanzaType type (   )  const [inline, virtual]
 

Returns the stanza type.

Returns:
The type of the stanza.

Definition at line 316 of file tag.h.

const std::string xml (   )  const [virtual]
 

This function can be used to retrieve the complete XML of a tag as a string. It includes all the attributes, child nodes and character data.

Returns:
The complete XML.

Definition at line 97 of file tag.cpp.

The documentation for this class was generated from the following files:
Generated on Sat Mar 22 09:32:34 2008 for gloox by  doxygen 1.4.1