ClickHouse/base/poco/XML/include/Poco/DOM/Element.h

//
// Element.h
//
// Library: XML
// Package: DOM
// Module:  DOM
//
// Definition of the DOM Element class.
//
// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
// and Contributors.
//
// SPDX-License-Identifier:	BSL-1.0
//


#ifndef DOM_Element_INCLUDED
#define DOM_Element_INCLUDED


#include "Poco/DOM/AbstractContainerNode.h"
#include "Poco/XML/Name.h"
#include "Poco/XML/XML.h"


namespace Poco
{
namespace XML
{


    class Attr;
    class NodeList;
    class Document;


    class XML_API Element : public AbstractContainerNode
    /// The Element interface represents an element in an XML document.
    /// Elements may have attributes associated with them; since the Element interface
    /// inherits from Node, the generic Node interface attribute attributes may
    /// be used to retrieve the set of all attributes for an element. There are
    /// methods on the Element interface to retrieve either an Attr object by name
    /// or an attribute value by name. In XML, where an attribute value may contain
    /// entity references, an Attr object should be retrieved to examine the possibly
    /// fairly complex sub-tree representing the attribute value.
    {
    public:
        const XMLString & tagName() const;
        /// Returns the name of the element.
        ///
        /// For example, in
        ///
        ///     <elementExample id="demo">
        ///         ...
        ///     </elementExample>
        ///
        /// tagName has the value "elementExample". Note that this is case-preserving in XML,
        /// as are all of the operations of the DOM.

        const XMLString & getAttribute(const XMLString & name) const;
        /// Retrieves an attribute value by name.
        ///
        /// Returns the attribute's value, if the attribute
        /// exists, or an empty string otherwise.

        void setAttribute(const XMLString & name, const XMLString & value);
        /// Adds a new attribute. If an attribute with that name is already present
        /// in the element, its value is changed to be that of the value parameter.
        /// This value is a simple string; it is not parsed as it is being set. So any
        /// markup (such as syntax to be recognized as an entity reference) is treated
        /// as literal text, and needs to be appropriately escaped by the implementation
        /// when it is written out.

        void removeAttribute(const XMLString & name);
        /// Removes an attribute by name.

        Attr * getAttributeNode(const XMLString & name) const;
        /// Retrieves an Attr node by name.

        Attr * setAttributeNode(Attr * newAttr);
        /// Adds a new attribute. If an attribute with that name is already
        /// present in the element, it is replaced by the new one.

        Attr * addAttributeNodeNP(Attr * oldAttr, Attr * newAttr);
        /// For internal use only.
        /// Adds a new attribute after oldAttr.
        /// If oldAttr is 0, newAttr is set as first attribute.
        /// Returns newAttr.
        /// Does not fire any events.

        Attr * removeAttributeNode(Attr * oldAttr);
        /// Removes the specified attribute.

        NodeList * getElementsByTagName(const XMLString & name) const;
        /// Returns a NodeList of all descendant elements with a given tag
        /// name, in the order in which they would be encountered in a
        /// preorder traversal of the Element tree.
        ///
        /// The special name "*" matches all tags.
        ///
        /// The returned NodeList must be released with a call
        /// to release() when no longer needed.

        void normalize();
        /// Puts all Text nodes in the full depth of the sub-tree underneath this Element,
        /// including attribute nodes, into a "normal" form where only markup (e.g.,
        /// tags, comments, processing instructions, CDATA sections, and entity references)
        /// separates Text nodes, i.e., there are no adjacent Text nodes. This can be
        /// used to ensure that the DOM view of a document is the same as if it were
        /// saved and re-loaded, and is useful when operations (such as XPointer
        /// lookups) that depend on a particular document tree structure are to be used.
        ///
        /// Note: In cases where the document contains CDATASections, the normalize
        /// operation alone may not be sufficient, since XPointers do not differentiate
        /// between Text nodes and CDATASection nodes.

        // DOM Level 2
        const XMLString & getAttributeNS(const XMLString & namespaceURI, const XMLString & localName) const;
        /// Retrieves an attribute value by name.
        ///
        /// Returns the attribute's value, if the attribute
        /// exists, or an empty string otherwise.

        void setAttributeNS(const XMLString & namespaceURI, const XMLString & qualifiedName, const XMLString & value);
        /// Adds a new attribute. If an attribute with that name
        /// is already present in the element, its value is changed
        /// to be that of the value parameter.

        void removeAttributeNS(const XMLString & namespaceURI, const XMLString & localName);
        /// Removes an attribute by name.

        Attr * getAttributeNodeNS(const XMLString & namespaceURI, const XMLString & localName) const;
        /// Retrieves an Attr node by name.

        Attr * setAttributeNodeNS(Attr * newAttr);
        /// Adds a new attribute. If an attribute with that name is already
        /// present in the element, it is replaced by the new one.

        bool hasAttribute(const XMLString & name) const;
        /// Returns true if and only if the element has the specified attribute.

        bool hasAttributeNS(const XMLString & namespaceURI, const XMLString & localName) const;
        /// Returns true if and only if the element has the specified attribute.

        NodeList * getElementsByTagNameNS(const XMLString & namespaceURI, const XMLString & localName) const;
        /// Returns a NodeList of all the descendant Elements with a given local name and namespace URI
        /// in the order in which they are encountered in a preorder traversal of this Element tree.
        ///
        /// The special value "*" matches all namespaces, or local names respectively.
        ///
        /// The returned NodeList must be released with a call
        /// to release() when no longer needed.

        const XMLString & namespaceURI() const;
        XMLString prefix() const;
        const XMLString & localName() const;
        bool hasAttributes() const;
        XMLString innerText() const;

        Element * getChildElement(const XMLString & name) const;
        /// Returns the first child element with the given name, or null
        /// if such an element does not exist.
        ///
        /// This method is an extension to the W3C Document Object Model.

        Element * getChildElementNS(const XMLString & namespaceURI, const XMLString & localName) const;
        /// Returns the first child element with the given namespaceURI and localName,
        /// or null if such an element does not exist.
        ///
        /// This method is an extension to the W3C Document Object Model.

        Element * getElementById(const XMLString & elementId, const XMLString & idAttribute) const;
        /// Returns the first Element whose ID attribute (given in idAttribute)
        /// has the given elementId. If no such element exists, returns null.
        ///
        /// This method is an extension to the W3C Document Object Model.

        Element *
        getElementByIdNS(const XMLString & elementId, const XMLString & idAttributeURI, const XMLString & idAttributeLocalName) const;
        /// Returns the first Element whose ID attribute (given in idAttributeURI and idAttributeLocalName)
        /// has the given elementId. If no such element exists, returns null.
        ///
        /// This method is an extension to the W3C Document Object Model.

        // Node
        const XMLString & nodeName() const;
        NamedNodeMap * attributes() const;
        unsigned short nodeType() const;

    protected:
        Element(Document * pOwnerDocument, const XMLString & namespaceURI, const XMLString & localName, const XMLString & qname);
        Element(Document * pOwnerDocument, const Element & elem);
        ~Element();

        Node * copyNode(bool deep, Document * pOwnerDocument) const;

        void dispatchNodeRemovedFromDocument();
        void dispatchNodeInsertedIntoDocument();

    private:
        const Name & _name;
        Attr * _pFirstAttr;

        friend class Attr;
        friend class Document;
        friend class AttrMap;
    };


    //
    // inlines
    //
    inline const XMLString & Element::tagName() const
    {
        return _name.qname();
    }


}
} // namespace Poco::XML


#endif // DOM_Element_INCLUDED