tag.h

Jabber code library, developed with c

/*
  Copyright (c) 2005-2008 by Jakob Schroeter <[e-mail]>
  This file is part of the gloox library. http://camaya.net/gloox

  This software is distributed under a license. The full license
  agreement can be found in the file LICENSE in this distribution.
  This software may not be copied, modified, sold or distributed
  other than expressed in the named license agreement.

  This software is distributed without any warranty.
*/


#ifndef TAG_H__
#define TAG_H__

#include "gloox.h"

#include <string>
#include <list>
#include <utility>

namespace gloox
{

  /**
   * @brief This is an abstraction of an XML element.
   *
   * @author Jakob Schroeter <[e-mail]>
   * @since 0.4
   */
  class GLOOX_API Tag
  {
    public:
      /**
       * An XML element's attribute.
       */
      typedef std::pair<std::string, std::string> Attribute;

      /**
       * A list of XML element attributes.
       */
      typedef std::list<Attribute> AttributeList;

      /**
       * A list of Tags.
       */
      typedef std::list<Tag*> TagList;

      /**
       * Creates an empty tag.
       * @deprecated Will be removed in 1.0
       */
      GLOOX_DEPRECATED_CTOR Tag();

      /**
       * Creates a new tag with a given name (and XML character data, if given).
       * @param name The name of the element.
       * @param cdata The XML character data of the element.
       * @param incoming Indicates whether tag names, attributes, attribute values, and cdata shall
       * be escaped (false, default) or not (true).
       */
      explicit Tag( const std::string& name, const std::string& cdata = "", bool incoming = false );

      /**
       * Creates a new tag as a child tag of the given parent, with a given name (and
       * XML character data, if given).
       * @param parent The parent tag.
       * @param name The name of the element.
       * @param cdata The XML character data of the element.
       * @param incoming Indicates whether tag names, attributes, attribute values, and cdata shall
       * be escaped (false, default) or not (true).
       */
      explicit Tag( Tag *parent, const std::string& name, const std::string& cdata = "",
                    bool incoming = false );

      /**
       * Creates a new tag with a given name and an attribute.
       * @param name The name of the element.
       * @param attrib The attribute name.
       * @param value The attribute value.
       * @param incoming Indicates whether tag names, attributes, attribute values, and cdata shall
       * be escaped (false, default) or not (true).
       * @since 0.9
       */
      explicit Tag( const std::string& name, const std::string& attrib, const std::string& value,
                    bool incoming = false );

      /**
       * Creates a new tag as a child tag of the given parent, with a given name and
       * an attribute.
       * @param parent The parent tag.
       * @param name The name of the element.
       * @param attrib The attribute name.
       * @param value The attribute value.
       * @param incoming Indicates whether tag names, attributes, attribute values, and cdata shall
       * be escaped (false, default) or not (true).
       * @since 0.9
       */
      explicit Tag( Tag *parent, const std::string& name, const std::string& attrib, const std::string& value,
                    bool incoming = false );

      /**
       * Virtual destructor.
       */
      virtual ~Tag();

      /**
       * 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.
       * @return The complete XML.
       */
      virtual const std::string xml() const;

      /**
       * Use this function to add a new attribute to the tag.
       * @param name The name of the attribute.
       * @param value The value of the attribute.
       */
      virtual void addAttribute( const std::string& name, const std::string& value );

      /**
       * Use this function to add a new attribute to the tag. The value is an @c int here.
       * @param name The name of the attribute.
       * @param value The value of the attribute.
       * @since 0.8
       */
      virtual void addAttribute( const std::string& name, int value );

      /**
       * Use this function to add a new attribute to the tag. The value is a @c long here.
       * @param name The name of the attribute.
       * @param value The value of the attribute.
       * @since 0.9
       */
      virtual void addAttribute( const std::string& name, long value );

      /**
       * Sets the given attributes. Any existing attributes are lost.
       * @param attributes The attributes to set.
       * @since 0.9
       */
      virtual void setAttributes( const AttributeList& attributes ) { m_attribs = attributes; }

      /**
       * Use this function to add a child node to the tag. The Tag will be owned by Tag.
       * @param child The node to be inserted.
       */
      virtual void addChild( Tag *child );

      /**
       * Use this function to add a copy of the given element to the tag.
       * @param child The node to be inserted.
       * @since 0.9
       */
      virtual void addChildCopy( const Tag *child );

      /**
       * Sets the XML character data for this Tag.
       * @param cdata The new cdata.
       */
      virtual void setCData( const std::string& cdata )
        { m_cdata = m_incoming ? relax( cdata ) : cdata; }

      /**
       * Adds the string to the existing XML character data for this Tag.
       * @param cdata The additional cdata.
       */
      virtual void addCData( const std::string& cdata )
        { m_cdata += m_incoming ? relax( cdata ) : cdata; }

      /**
       * Use this function to retrieve the name of an element.
       * @return The name of the tag.
       */
      virtual const std::string& name() const { return m_name; }

      /**
       * Use this function to retrieve the XML character data of an element.
       * @return The cdata the element contains.
       */
      virtual const std::string& cdata() const { return m_cdata; }

      /**
       * Use this function to manipulate the list of attributes.
       * @return A reference to the list of attributes.
       */
      virtual AttributeList& attributes() { return m_attribs; }

      /**
       * Use this function to fetch a const list of attributes.
       * @return A constant reference to the list of attributes.
       */
      virtual const AttributeList& attributes() const { return m_attribs; }

      /**
       * Use this function to manipulate the list of child elements.
       * @return A reference to the list of child elements.
       */
      virtual TagList& children() { return m_children; }

      /**
       * Use this function to fetch a const list of child elements.
       * @return A constant reference to the list of child elements.
       */
      virtual const TagList& children() const { return m_children; }

      /**
       * This function can be used to retrieve the value of a Tag's attribute.
       * @param name The name of the attribute to look for.
       * @return The value of the attribute if found, an empty string otherwise.
       */
      virtual const std::string findAttribute( const std::string& name ) const;

      /**
       * Checks whether the tag has a attribute with given name and optional value.
       * @param name The name of the attribute to check for.
       * @param value The value of the attribute to check for.
       * @return Whether the attribute exists (optionally with the given value).
       */
      virtual bool hasAttribute( const std::string& name, const std::string& value = "" ) const;

      /**
       * This function finds and returns the @b first element within the child elements of the current tag
       * that has a matching tag name.
       * @param name The name of the element to search for.
       * @return The found Tag, or NULL.
       */
      virtual Tag* findChild( const std::string& name ) const;

      /**
       * This function finds and returns the @b first element within the child elements of the current tag,
       * that has a certain name, and a certain attribute with a certain value.
       * @param name The name of the element to search for.