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

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


#ifndef DOM_TreeWalker_INCLUDED
#define DOM_TreeWalker_INCLUDED


#include "Poco/XML/XML.h"
#include "Poco/XML/XMLString.h"


namespace Poco
{
namespace XML
{


    class Node;
    class NodeFilter;


    class XML_API TreeWalker
    /// TreeWalker objects are used to navigate a document tree or subtree using
    /// the view of the document defined by their whatToShow flags and filter (if
    /// any). Any function which performs navigation using a TreeWalker will automatically
    /// support any view defined by a TreeWalker.
    ///
    /// Omitting nodes from the logical view of a subtree can result in a structure
    /// that is substantially different from the same subtree in the complete, unfiltered
    /// document. Nodes that are siblings in the TreeWalker view may be children
    /// of different, widely separated nodes in the original view. For instance,
    /// consider a NodeFilter that skips all nodes except for Text nodes and the
    /// root node of a document. In the logical view that results, all text nodes
    /// will be siblings and appear as direct children of the root node, no matter
    /// how deeply nested the structure of the original document.
    ///
    /// A TreeWalker can be directly instantiated using one of its constructors -
    /// the DocumentTraversal interface is not needed and therefore not implemented.
    /// Unlike most other DOM classes, TreeWalker supports value semantics.
    ///
    /// If the TreeWalker's current node is removed from the document, the
    /// result of calling any of the movement methods is undefined. This behavior
    /// does not conform to the DOM Level 2 Traversal specification.
    {
    public:
        TreeWalker(Node * root, unsigned long whatToShow, NodeFilter * pFilter = 0);
        /// Creates a TreeWalker over the subtree rooted at the specified node.

        TreeWalker(const TreeWalker & walker);
        /// Creates a TreeWalker by copying another TreeWalker.

        TreeWalker & operator=(const TreeWalker & walker);
        /// Assignment operator.

        ~TreeWalker();
        /// Destroys the TreeWalker.

        Node * root() const;
        /// The root node of the TreeWalker, as specified when it was created.

        unsigned long whatToShow() const;
        /// This attribute determines which node types are presented via the TreeWalker.
        /// The available set of constants is defined in the NodeFilter interface. Nodes
        /// not accepted by whatToShow will be skipped, but their children may still
        /// be considered. Note that this skip takes precedence over the filter, if
        /// any.

        NodeFilter * filter() const;
        /// The NodeFilter used to screen nodes.

        bool expandEntityReferences() const;
        /// The value of this flag determines whether the children of entity reference
        /// nodes are visible to the iterator. If false, they and their descendants
        /// will be rejected. Note that this rejection takes precedence over whatToShow
        /// and the filter. Also note that this is currently the only situation where
        /// NodeIterators may reject a complete subtree rather than skipping individual
        /// nodes.
        ///
        /// To produce a view of the document that has entity references expanded and
        /// does not expose the entity reference node itself, use the whatToShow flags
        /// to hide the entity reference node and set expandEntityReferences to true
        /// when creating the iterator. To produce a view of the document that has entity
        /// reference nodes but no entity expansion, use the whatToShow flags to show
        /// the entity reference node and set expandEntityReferences to false.
        ///
        /// This implementation does not support entity reference expansion and
        /// thus always returns false.

        Node * currentNode() const;
        /// The node at which the TreeWalker is currently positioned.
        /// Alterations to the DOM tree may cause the current node to no longer be accepted
        /// by the TreeWalker's associated filter. currentNode may also be explicitly
        /// set to any node, whether or not it is within the subtree specified by the
        /// root node or would be accepted by the filter and whatToShow flags. Further
        /// traversal occurs relative to currentNode even if it is not part of the current
        /// view, by applying the filters in the requested direction; if no traversal
        /// is possible, currentNode is not changed.

        Node * getCurrentNode() const;
        /// See currentNode().

        void setCurrentNode(Node * pNode);
        /// Sets the current node.

        Node * parentNode();
        /// Moves to and returns the closest visible ancestor node of the current node.
        /// If the search for parentNode attempts to step upward from the TreeWalker's
        /// root node, or if it fails to find a visible ancestor node, this method retains
        /// the current position and returns null.

        Node * firstChild();
        /// Moves the TreeWalker to the first visible child of the current node, and
        /// returns the new node. If the current node has no visible children, returns
        /// null, and retains the current node.

        Node * lastChild();
        /// Moves the TreeWalker to the last visible child of the current node, and
        /// returns the new node. If the current node has no visible children, returns
        /// null, and retains the current node.

        Node * previousSibling();
        /// Moves the TreeWalker to the previous sibling of the current node, and returns
        /// the new node. If the current node has no visible previous sibling, returns
        /// null, and retains the current node.

        Node * nextSibling();
        /// Moves the TreeWalker to the next sibling of the current node, and returns
        /// the new node. If the current node has no visible next sibling, returns null,
        /// and retains the current node.

        Node * previousNode();
        /// Moves the TreeWalker to the previous visible node in document order relative
        /// to the current node, and returns the new node. If the current node has no
        /// previous node, or if the search for previousNode attempts to step upward
        /// from the TreeWalker's root node, returns null, and retains the current node.

        Node * nextNode();
        /// Moves the TreeWalker to the next visible node in document order relative
        /// to the current node, and returns the new node. If the current node has no
        /// next node, or if the search for nextNode attempts to step upward from the
        /// TreeWalker's root node, returns null, and retains the current node.

    protected:
        int accept(Node * pNode) const;
        Node * next(Node * pNode) const;
        Node * previous(Node * pNode) const;

    private:
        TreeWalker();

        Node * _pRoot;
        unsigned long _whatToShow;
        NodeFilter * _pFilter;
        Node * _pCurrent;
    };


    //
    // inlines
    //
    inline Node * TreeWalker::root() const
    {
        return _pRoot;
    }


    inline unsigned long TreeWalker::whatToShow() const
    {
        return _whatToShow;
    }


    inline NodeFilter * TreeWalker::filter() const
    {
        return _pFilter;
    }


    inline bool TreeWalker::expandEntityReferences() const
    {
        return false;
    }


    inline Node * TreeWalker::currentNode() const
    {
        return _pCurrent;
    }


    inline Node * TreeWalker::getCurrentNode() const
    {
        return _pCurrent;
    }


}
} // namespace Poco::XML


#endif // DOM_TreeWalker_INCLUDED