<?php

/** @file recursiveiteratoriterator.inc
 * @ingroup SPL
 * @brief class RecursiveIteratorIterator
 * @author  Marcus Boerger
 * @date    2003 - 2009
 *
 * SPL - Standard PHP Library
 */

/**
 * @brief   Iterates through recursive iterators
 * @author  Marcus Boerger
 * @version 1.2
 * @since PHP 5.0
 *
 * The objects of this class are created by instances of RecursiveIterator. 
 * Elements of those iterators may be traversable themselves. If so these 
 * sub elements are recursed into.
 */
class RecursiveIteratorIterator implements OuterIterator
{
    /** Mode: Only show leaves */
    const LEAVES_ONLY         = 0;
    /** Mode: Show parents prior to their children */
    const SELF_FIRST        = 1;
    /** Mode: Show all children prior to their parent */
    const CHILD_FIRST        = 2;

    /** Flag: Catches exceptions during getChildren() calls and simply jumps
     * to the next element. */
    const CATCH_GET_CHILD    = 0x00000002;

    private $ait = array();
    private $count = 0;
    private $mode  = self::LEAVES_ONLY;
    private $flags = 0;

    /** Construct from RecursiveIterator
     *
     * @param it     RecursiveIterator to iterate
     * @param mode   Operation mode (one of):
     *               - LEAVES_ONLY only show leaves
     *               - SELF_FIRST  show parents prior to their childs
     *               - CHILD_FIRST show all children prior to their parent
     * @param flags  Control flags, zero or any combination of the following
     *               (since PHP 5.1).
     *               - CATCH_GET_CHILD which catches exceptions during
     *                 getChildren() calls and simply jumps to the next 
     *                 element.
     */
    function __construct(RecursiveIterator $it, $mode = self::LEAVES_ONLY, $flags = 0)
    {
        $this->ait[0] = $it;
        $this->mode   = $mode;
        $this->flags  = $flags;
    }

    /** Rewind to top iterator as set in constructor
     */
    function rewind()
    {
        while ($this->count) {
            unset($this->ait[$this->count--]);
            $this->endChildren();
        }
        $this->ait[0]->rewind();
        $this->ait[0]->recursed = false;
        callNextElement(true);
    }
    
    /** @return whether iterator is valid
     */
    function valid()
    {
        $count = $this->count;
        while ($count) {
            $it = $this->ait[$count];
            if ($it->valid()) {
                return true;
            }
            $count--;
            $this->endChildren();
        }
        return false;
    }
    
    /** @return current key
     */
    function key()
    {
        $it = $this->ait[$this->count];
        return $it->key();
    }
    
    /** @return current element
     */
    function current()
    {
        $it = $this->ait[$this->count];
        return $it->current();
    }
    
    /** Forward to next element
     */
    function next()
    {
        while ($this->count) {
            $it = $this->ait[$this->count];
            if ($it->valid()) {
                if (!$it->recursed && callHasChildren()) {
                    $it->recursed = true;
                    try
                    {
                        $sub = callGetChildren();
                    }
                    catch (Exception $e)
                    {
                        if (!($this->flags & self::CATCH_GET_CHILD))
                        {
                            throw $e;
                        }
                        $it->next();
                        continue;
                    }
                    $sub->recursed = false;
                    $sub->rewind();
                    if ($sub->valid()) {
                        $this->ait[++$this->count] = $sub;
                        if (!$sub instanceof RecursiveIterator) {
                            throw new Exception(get_class($sub).'::getChildren() must return an object that implements RecursiveIterator');
                        }
                        $this->beginChildren();
                        return;
                    }
                    unset($sub);
                }
                $it->next();
                $it->recursed = false;
                if ($it->valid()) {
                    return;
                }
                $it->recursed = false;
            }
            if ($this->count) {
                unset($this->ait[$this->count--]);
                $it = $this->ait[$this->count];
                $this->endChildren();
                callNextElement(false);
            }
        }
        callNextElement(true);
    }

    /** @return Sub Iterator at given level or if unspecified the current sub 
     *          Iterator
     */
    function getSubIterator($level = NULL)
    {
        if (is_null($level)) {
            $level = $this->count;
        }
        return @$this->ait[$level];
    }

    /**
     * @return The inner iterator
     */    
    function getInnerIterator()
    {
        return $this->it;
    }

    /** @return Current Depth (Number of parents)
     */
    function getDepth()
    {
        return $this->level;
    }

    /** @return whether current sub iterators current element has children
     * @since PHP 5.1
     */
    function callHasChildren()
    {
        return $this->ait[$this->count]->hasChildren();
    }

    /** @return current sub iterators current children
     * @since PHP 5.1
     */
    function callGetChildren()
    {
        return $this->ait[$this->count]->getChildren();
    }

    /** Called right after calling getChildren() and its rewind().
     * @since PHP 5.1
     */
    function beginChildren()
    {
    }
    
    /** Called after current child iterator is invalid and right before it
     * gets destructed.
     * @since PHP 5.1
     */
    function endChildren()
    {
    }

    private function callNextElement($after_move)
    {
        if ($this->valid())
        {
            if ($after_move)
            {
                if (($this->mode == self::SELF_FIRST && $this->callHasChildren())
                ||   $this->mode == self::LEAVES_ONLY)
                $this->nextElement();
            }
            else
            {
                $this->nextElement();
            }
        }
    }
    
    /** Called when the next element is available
     */
    function nextElement()
    {
    }
}

?>