Document/src/document/rst/visitor.php - zetacomponents - Git at Google

 <?php
 /**
  * File containing the abstract ezcDocumentRstVisitor base class.
  *
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
  * regarding copyright ownership.  The ASF licenses this file
  * to you under the Apache License, Version 2.0 (the
  * "License"); you may not use this file except in compliance
  * with the License.  You may obtain a copy of the License at
  *
  *   http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  * KIND, either express or implied.  See the License for the
  * specific language governing permissions and limitations
  * under the License.
  *
  * @package Document
  * @version //autogen//
  * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
  */

 /**
  * Abstract visitor base for RST documents represented by the parser AST.
  *
  * @package Document
  * @version //autogen//
  */
 abstract class ezcDocumentRstVisitor implements ezcDocumentErrorReporting
 {
     /**
      * RST document handler
      *
      * @var ezcDocumentRst
      */
     protected $rst;

     /**
      * Reference to the AST root node.
      *
      * @var ezcDocumentRstDocumentNode
      */
     protected $ast;

     /**
      * Location of the currently processed RST file, relevant for inclusion.
      *
      * @var string
      */
     protected $path;

     /**
      * Collected refrence targets.
      *
      * @var array
      */
     protected $references = array();

     /**
      * Counter of duplicate references for duplicate references.
      *
      * @var array
      */
     protected $referenceCounter = array();

     /**
      * Collected named external reference targets
      *
      * @var array
      */
     protected $namedExternalReferences = array();

     /**
      * Collected anonymous externals reference targets
      *
      * @var array
      */
     protected $anonymousReferences = array();

     /**
      * Index of last requested anonymous reference target.
      *
      * @var int
      */
     protected $anonymousReferenceCounter = 0;

     /**
      * Collected substitutions.
      *
      * @var array
      */
     protected $substitutions = array();

     /**
      * List with footnotes for later rendering.
      *
      * @var array
      */
     protected $footnotes = array();

     /**
      * Label dependant foot note counters for footnote auto enumeration.
      *
      * @var array
      */
     protected $footnoteCounter = array( 0 );

     /**
      * Foot note symbol signs, as defined at
      * http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#auto-symbol-footnotes
      *
      * @var array
      */
     protected $footnoteSymbols = array(
         "*",
         "\xE2\x80\xA0",
         "\xE2\x80\xA1",
         "\xC2\xA7",
         "\xC2\xB6",
         "#",
         "\xE2\x99\xA0",
         "\xE2\x99\xA5",
         "\xE2\x99\xA6",
         "\xE2\x99\xA3",
     );

     /**
      * Aggregated minor errors during document processing.
      *
      * @var array
      */
     protected $errors = array();

     /**
      * Array of already generated IDs, so none will be used twice.
      *
      * @var array
      */
     protected $usedIDs = array();

     /**
      * Unused reference target
      */
     const UNUSED    = 1;

     /**
      * Used reference target
      */
     const USED      = 2;

     /**
      * Duplicate reference target. Will throw an error on use.
      */
     const DUBLICATE = 4;

     /**
      * Create visitor from RST document handler.
      *
      * @param ezcDocumentRst $document
      * @param string $path
      * @return void
      */
     public function __construct( ezcDocumentRst $document, $path )
     {
         $this->rst  = $document;
         $this->path = $path;
     }

     /**
      * Trigger visitor error
      *
      * Emit a vistitor error, and convert it to an exception depending on the
      * error reporting settings.
      *
      * @param int $level
      * @param string $message
      * @param string $file
      * @param int $line
      * @param int $position
      * @return void
      */
     public function triggerError( $level, $message, $file = null, $line = null, $position = null )
     {
         if ( $level & $this->rst->options->errorReporting )
         {
             throw new ezcDocumentVisitException( $level, $message, $file, $line, $position );
         }
         else
         {
             // If the error should not been reported, we aggregate it to maybe
             // display it later.
             $this->errors[] = new ezcDocumentVisitException( $level, $message, $file, $line, $position );
         }
     }

     /**
      * Return list of errors occured during visiting the document.
      *
      * May be an empty array, if on errors occured, or a list of
      * ezcDocumentVisitException objects.
      *
      * @return array
      */
     public function getErrors()
     {
         return $this->errors;
     }

     /**
      * Docarate RST AST
      *
      * Visit the RST abstract syntax tree.
      *
      * @param ezcDocumentRstDocumentNode $ast
      * @return mixed
      */
     public function visit( ezcDocumentRstDocumentNode $ast )
     {
         $this->ast = $ast;
         $this->preProcessAst( $ast );

         // Reset footnote counters
         foreach ( $this->footnoteCounter as $label => $counter )
         {
             $this->footnoteCounter[$label] = 0;
         }
         reset( $this->footnoteSymbols );

         // Reset duplicate reference counter
         $this->referenceCounter = array();
     }

     /**
      * Add a reference target
      *
      * @param string $string
      * @return void
      */
     private function addReferenceTarget( $string )
     {
         $id = $this->calculateId( $string );
         $this->references[$id] = isset( $this->references[$id] ) ? self::DUBLICATE : self::UNUSED;

         if ( $this->references[$id] === self::UNUSED )
         {
             $this->referenceCounter[$id] = 0;
             return $id;
         }
         else
         {
             return $id . '__' . ( ++$this->referenceCounter[$id] );
         }
     }

     /**
      * Transform a node tree into a string
      *
      * Transform a node tree, with all its subnodes into a string by only
      * getting the textuual contents from ezcDocumentRstTextLineNode objects.
      *
      * @param ezcDocumentRstNode $node
      * @return string
      */
     public function nodeToString( ezcDocumentRstNode $node )
     {
         $text = '';

         foreach ( $node->nodes as $child )
         {
             if ( ( $child instanceof ezcDocumentRstTextLineNode ) ||
                  ( $child instanceof ezcDocumentRstLiteralNode ) )
             {
                 $text .= $child->token->content;
             }
             else
             {
                 $text .= $this->nodeToString( $child );
             }
         }

         return $text;
     }

     /**
      * Get string from token list.
      *
      * @param array $tokens
      * @return string
      */
     protected function tokenListToString( array $tokens )
     {
         $text = '';

         foreach ( $tokens as $token )
         {
             $text .= $token->content;
         }

         return $text;
     }

     /**
      * Compare two list items
      *
      * Check if the given list item may be a successor in the same list, as the
      * last item in the list. Returns the boolean status o the check.
      *
      * @param ezcDocumentRstNode $item
      * @param ezcDocumentRstNode $lastItem
      * @return bool
      */
     protected function compareListType( ezcDocumentRstNode $item, ezcDocumentRstNode $lastItem )
     {
         // Those always belong to each other... .oO( ♡ )
         if ( $item instanceof ezcDocumentRstDefinitionListNode )
         {
             return true;
         }

         // For bullet lists, just compare the tokens
         if ( $item instanceof ezcDocumentRstBulletListNode )
         {
             return ( $item->token->content === $lastItem->token->content );
         }

         // For enumerated lists, we need to check if the current value is a
         // valid successor of the prior value.
         if ( $item instanceof ezcDocumentRstEnumeratedListNode )
         {
             return ( $lastItem instanceof ezcDocumentRstEnumeratedListNode ) &&
                 ( $item->listType === $lastItem->listType );
         }

         return true;
     }

     /**
      * Aggregate list items
      *
      * Aggregate list items into lists. In RST there are only list items, which
      * are aggregated to lists depending on their bullet type. The related list
      * items are aggregated into one list.
      *
      * @param ezcDocumentRstNode $node
      * @return void
      */
     protected function aggregateListItems( ezcDocumentRstNode $node )
     {
         $listTypeMapping = array(
             'ezcDocumentRstBulletListNode'     => 'ezcDocumentRstBulletListListNode',
             'ezcDocumentRstEnumeratedListNode' => 'ezcDocumentRstEnumeratedListListNode',
             'ezcDocumentRstDefinitionListNode' => 'ezcDocumentRstDefinitionListListNode',
         );

         $lastItem = null;
         $list     = null;
         $children = array();
         foreach ( $node->nodes as $nr => $child )
         {
             if ( isset( $listTypeMapping[$class = get_class( $child )] ) )
             {
                 if ( ( $lastItem === null ) ||
                      ( $list === null ) ||
                      ( !$this->compareListType( $child, $lastItem ) ) )
                 {
                     // Create a new list.
                     $listType = $listTypeMapping[$class];
                     $list = new $listType( $child->token );
                     $list->nodes[] = $child;
                     $children[]    = $list;
                 }
                 else
                 {
                     // Append to current list
                     $list->nodes[] = $child;
                 }
                 $lastItem = $child;
             }
             else
             {
                 $children[] = $child;
                 $lastItem = null;
             }
         }

         $node->nodes = $children;
     }

     /**
      * Add footnote
      *
      * @param ezcDocumentRstNode $node
      * @return void
      */
     protected function addFootnote( ezcDocumentRstNode $node )
     {
         $identifier = $this->tokenListToString( $node->name );

         switch ( $node->footnoteType )
         {
             case ezcDocumentRstFootnoteNode::NUMBERED:
                 $label  = 0;
                 $number = (int) $identifier;
                 $this->footnoteCounter[0] = max( $number, $this->footnoteCounter[0] );
                 break;
             case ezcDocumentRstFootnoteNode::AUTO_NUMBERED:
                 $label  = 0;
                 $number = !isset( $this->footnoteCounter[$label] ) ? ( $this->footnoteCounter[$label] = 1 ) : ++$this->footnoteCounter[$label];
                 break;
             case ezcDocumentRstFootnoteNode::LABELED:
                 $label  = substr( $identifier, 1 );
                 $number = !isset( $this->footnoteCounter[$label] ) ? ( $this->footnoteCounter[$label] = 1 ) : ++$this->footnoteCounter[$label];
                 break;
             case ezcDocumentRstFootnoteNode::SYMBOL:
                 $label  = '*';
                 $number = next( $this->footnoteSymbols );
                 break;
             case ezcDocumentRstFootnoteNode::CITATION:
                 $label  = '#';
                 $number = $identifier;
                 break;
         }

         // Store footnote for later rendering in footnote array
         $node->name   = $label;
         $node->number = $number;
         $this->footnotes[$label][$number] = $node;
     }

     /**
      * Pre process AST
      *
      * Performs multiple preprocessing steps on the AST:
      *
      * Collect all possible reference targets in the AST to know the actual
      * destianation for references while decorating. The references are stored
      * in an internal structure and you may request the actual link by using
      * the getReferenceTarget() method.
      *
      * Aggregate list items into lists. In RST there are only list items, which
      * are aggregated to lists depending on their bullet type. The related list
      * items are aggregated into one list.
      *
      * @param ezcDocumentRstNode $node
      * @return void
      */
     protected function preProcessAst( ezcDocumentRstNode $node )
     {
         switch ( true )
         {
             case $node instanceof ezcDocumentRstDocumentNode:
                 $this->aggregateListItems( $node );
                 break;

             case $node instanceof ezcDocumentRstSectionNode:
                 $node->reference = $this->addReferenceTarget( $this->nodeToString( $node->title ) );
                 $this->aggregateListItems( $node );

                 // Also recurse into special title subtree
                 foreach ( $node->title->nodes as $child )
                 {
                     $this->preProcessAst( $child );
                 }
                 break;

             case $node instanceof ezcDocumentRstTableCellNode:
             case $node instanceof ezcDocumentRstBulletListNode:
             case $node instanceof ezcDocumentRstEnumeratedListNode:
                 $this->aggregateListItems( $node );
                 break;

             case $node instanceof ezcDocumentRstTargetNode:
                 $this->addReferenceTarget( $target = $this->nodeToString( $node ) );
                 break;

             case $node instanceof ezcDocumentRstNamedReferenceNode:
                 if ( count( $node->nodes ) )
                 {
                     // This is a direct reference to an external URL, just add
                     // to the list of named external references.
                     $this->namedExternalReferences[$this->calculateId( $this->tokenListToString( $node->name ) )] =
                         trim( $this->nodeToString( $node ) );
                 }
                 break;

             case $node instanceof ezcDocumentRstAnonymousReferenceNode:
                 $this->anonymousReferences[] = trim( $this->nodeToString( $node ) );
                 break;

             case $node instanceof ezcDocumentRstSubstitutionNode:
                 $substitutionName = strtolower( $this->tokenListToString( $node->name ) );
                 $this->substitutions[$substitutionName] = $node->nodes;
                 break;

             case $node instanceof ezcDocumentRstFootnoteNode:
                 $this->addFootnote( $node );
                 break;
         }

         // Check for forward references of empty named references.
         $children = $node->nodes;
         reset( $children );
         while ( $child = next( $children ) )
         {
             $stack = array();
             while ( ( $child instanceof ezcDocumentRstNamedReferenceNode ) &&
                     ( count( $child->nodes ) === 0 ) )
             {
                 $stack[] = $child;
                 $child = next( $children );
             }

             if ( $child && count( $stack ) )
             {
                 // We found a element, which is not an empty named reference
                 // node, so get the identifier from it and assign it to all
                 // named references on the stack.
                 if ( $child instanceof ezcDocumentRstNamedReferenceNode )
                 {
                     // Child is a named reference with content, so use the
                     // content as assignement.
                     $reference = trim( $this->nodeToString( $child ) );
                 }
                 else
                 {
                     // Generate a reference name and assign it to the element.
                     $last = end( $stack );
                     $reference = $this->calculateId( $this->tokenListToString( $last->name ) );
                     $child->identifier = $reference;
                 }

                 // Assign calculated reference to all aggregated stack
                 // elements.
                 foreach ( $stack as $refNode )
                 {
                     $this->namedExternalReferences[$this->calculateId( $this->tokenListToString( $refNode->name ) )] = $reference;
                 }
             }
         }

         // Recurse into childs to collect reference targets all over the
         // document.
         foreach ( $node->nodes as $child )
         {
             $this->preProcessAst( $child );
         }
     }

     /**
      * Check for internal footnote reference target
      *
      * Returns the target name, when an internal reference target exists and
      * sets it to used, and false otherwise.
      *
      * @param string $string
      * @param ezcDocumentRstNode $node
      * @return ezcDocumentRstFootnoteNode
      */
     public function hasFootnoteTarget( $string, ezcDocumentRstNode $node )
     {
         switch ( $node->footnoteType )
         {
             case ezcDocumentRstFootnoteNode::NUMBERED:
                 $label  = 0;
                 $string = (int) $string;
                 $this->footnoteCounter[0] = max( $string, $this->footnoteCounter[0] );
                 break;
             case ezcDocumentRstFootnoteNode::AUTO_NUMBERED:
                 $label  = 0;
                 $string = ++$this->footnoteCounter[$label];
                 break;
             case ezcDocumentRstFootnoteNode::LABELED:
                 $label  = substr( $string, 1 );
                 $string = ++$this->footnoteCounter[$label];
                 break;
             case ezcDocumentRstFootnoteNode::SYMBOL:
                 $label  = '*';
                 $string = next( $this->footnoteSymbols );
                 break;
             case ezcDocumentRstFootnoteNode::CITATION:
                 $label  = '#';
                 break;
         }

         if ( isset( $this->footnotes[$label][$string] ) )
         {
             return $this->footnotes[$label][$string];
         }

         return $this->triggerError(
             E_WARNING, "Unknown reference target '{$string}'.", null,
             ( $node !== null ? $node->token->line : null ),
             ( $node !== null ? $node->token->position : null )
         );
     }

     /**
      * Check for internal reference target
      *
      * Returns the target name, when an internal reference target exists and
      * sets it to used, and false otherwise. For duplicate reference targets
      * and missing reference targets an error will be triggered.
      *
      * An optional third parameter may enforce the fetching of the reference,
      * even if there are duplicates, so that they still can be referenced in
      * some way.
      *
      * @param string $string
      * @param ezcDocumentRstNode $node
      * @param bool $force
      * @return string
      */
     public function hasReferenceTarget( $string, ezcDocumentRstNode $node = null, $force = false )
     {
         $id = $this->calculateId( $string );
         if ( isset( $this->references[$id] ) &&
              ( $this->references[$id] !== self::DUBLICATE ) )
         {
             $this->references[$id] = self::USED;
             return $id;
         }

         if ( !isset( $this->references[$id] ) )
         {
             return $this->triggerError(
                 E_WARNING, "Missing reference target '{$id}'.", null,
                 ( $node !== null ? $node->token->line : null ),
                 ( $node !== null ? $node->token->position : null )
             );
         }
         elseif ( $force === true )
         {
             // Check if the reference target has been force-requested.
             if ( !isset( $this->referenceCounter[$id] ) )
             {
                 $this->referenceCounter[$id] = 0;
                 return $id;
             }
             else
             {
                 return $id . '__' . ( ++$this->referenceCounter[$id] );
             }
         }
         else
         {
             return $this->triggerError(
                 E_NOTICE, "Duplicate reference target '{$id}'.", null,
                 ( $node !== null ? $node->token->line : null ),
                 ( $node !== null ? $node->token->position : null )
             );
         }
     }

     /**
      * Return named external reference target
      *
      * Get the target value of a named external reference.
      *
      * @param string $name
      * @return string
      */
     public function getNamedExternalReference( $name )
     {
         $name = $this->calculateId( $name );

         if ( isset( $this->namedExternalReferences[$name] ) )
         {
             return $this->namedExternalReferences[$name];
         }

         return false;
     }

     /**
      * Get anonymous reference target
      *
      * Get the target URL of an anonomyous reference target.
      *
      * @return string
      */
     public function getAnonymousReferenceTarget()
     {
         if ( isset( $this->anonymousReferences[$this->anonymousReferenceCounter] ) )
         {
             return $this->anonymousReferences[$this->anonymousReferenceCounter++];
         }

         return $this->triggerError(
             E_WARNING, "Too few anonymous reference targets.", null
         );
     }

     /**
      * Get substitution contents
      *
      * @param string $string
      * @return void
      */
     protected function substitute( $string )
     {
         $string = strtolower( $string );
         if ( isset( $this->substitutions[$string] ) )
         {
             return $this->substitutions[$string];
         }

         $this->triggerError(
             E_ERROR, "Could not find substitution for '{$string}'.", null
         );
         return array();
     }

     /**
      * Get a valid identifier string
      *
      * Get a valid identifier string from an arbritrary string.
      *
      * @param string $string
      * @return string
      */
     protected function calculateId( $string )
     {
         $id = trim( preg_replace( '([^a-z0-9-]+)', '_', strtolower( trim( $string ) ) ), '_' );
         if ( !preg_match( '(^[a-z])', $id ) )
         {
             $id = 'id_' . $id;
         }

         return $id;
     }

     /**
      * Calculate unique ID
      *
      * Calculate a valid identifier, which is unique for this document.
      *
      * @param string $string
      * @return string
      */
     protected function calculateUniqueId( $string )
     {
         $id = $this->calculateId( $string );

         // Ensure uniqueness of IDs
         if ( isset( $this->usedIDs[$id] ) )
         {
             $i = 2;
             do {
                 $tryId = $id . '_' . $i++;
             } while ( isset( $this->usedIDs[$tryId] ) );
             $id = $tryId;
         }
         $this->usedIDs[$id] = true;

         return $id;
     }

     /**
      * Visit text node
      *
      * @param DOMNode $root
      * @param ezcDocumentRstNode $node
      * @return void
      */
     protected function visitText( DOMNode $root, ezcDocumentRstNode $node )
     {
         $root->appendChild(
             new DOMText( $node->token->content )
         );
     }

     /**
      * Visit children
      *
      * Just recurse into node and visit its children, ignoring the actual
      * node.
      *
      * @param DOMNode $root
      * @param ezcDocumentRstNode $node
      * @return void
      */
     protected function visitChildren( DOMNode $root, ezcDocumentRstNode $node )
     {
         foreach ( $node->nodes as $child )
         {
             $this->visitNode( $root, $child );
         }
     }

     /**
      * Visit substitution reference node
      *
      * @param DOMNode $root
      * @param ezcDocumentRstNode $node
      * @return void
      */
     protected function visitSubstitutionReference( DOMNode $root, ezcDocumentRstNode $node )
     {
         if ( ( $substitution = $this->substitute( $this->nodeToString( $node ) ) ) !== null )
         {
             foreach ( $substitution as $child )
             {
                 $this->visitNode( $root, $child );
             }
         }
     }
 }

 ?>
	<?php
	/**
	* File containing the abstract ezcDocumentRstVisitor base class.
	*
	* Licensed to the Apache Software Foundation (ASF) under one
	* or more contributor license agreements. See the NOTICE file
	* distributed with this work for additional information
	* regarding copyright ownership. The ASF licenses this file
	* to you under the Apache License, Version 2.0 (the
	* "License"); you may not use this file except in compliance
	* with the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing,
	* software distributed under the License is distributed on an
	* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	* KIND, either express or implied. See the License for the
	* specific language governing permissions and limitations
	* under the License.
	*
	* @package Document
	* @version //autogen//
	* @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
	*/

	/**
	* Abstract visitor base for RST documents represented by the parser AST.
	*
	* @package Document
	* @version //autogen//
	*/
	abstract class ezcDocumentRstVisitor implements ezcDocumentErrorReporting
	{
	/**
	* RST document handler
	*
	* @var ezcDocumentRst
	*/
	protected $rst;

	/**
	* Reference to the AST root node.
	*
	* @var ezcDocumentRstDocumentNode
	*/
	protected $ast;

	/**
	* Location of the currently processed RST file, relevant for inclusion.
	*
	* @var string
	*/
	protected $path;

	/**
	* Collected refrence targets.
	*
	* @var array
	*/
	protected $references = array();

	/**
	* Counter of duplicate references for duplicate references.
	*
	* @var array
	*/
	protected $referenceCounter = array();

	/**
	* Collected named external reference targets
	*
	* @var array
	*/
	protected $namedExternalReferences = array();

	/**
	* Collected anonymous externals reference targets
	*
	* @var array
	*/
	protected $anonymousReferences = array();

	/**
	* Index of last requested anonymous reference target.
	*
	* @var int
	*/
	protected $anonymousReferenceCounter = 0;

	/**
	* Collected substitutions.
	*
	* @var array
	*/
	protected $substitutions = array();

	/**
	* List with footnotes for later rendering.
	*
	* @var array
	*/
	protected $footnotes = array();

	/**
	* Label dependant foot note counters for footnote auto enumeration.
	*
	* @var array
	*/
	protected $footnoteCounter = array( 0 );

	/**
	* Foot note symbol signs, as defined at
	* http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#auto-symbol-footnotes
	*
	* @var array
	*/
	protected $footnoteSymbols = array(
	"*",
	"\xE2\x80\xA0",
	"\xE2\x80\xA1",
	"\xC2\xA7",
	"\xC2\xB6",
	"#",
	"\xE2\x99\xA0",
	"\xE2\x99\xA5",
	"\xE2\x99\xA6",
	"\xE2\x99\xA3",
	);

	/**
	* Aggregated minor errors during document processing.
	*
	* @var array
	*/
	protected $errors = array();

	/**
	* Array of already generated IDs, so none will be used twice.
	*
	* @var array
	*/
	protected $usedIDs = array();

	/**
	* Unused reference target
	*/
	const UNUSED = 1;

	/**
	* Used reference target
	*/
	const USED = 2;

	/**
	* Duplicate reference target. Will throw an error on use.
	*/
	const DUBLICATE = 4;

	/**
	* Create visitor from RST document handler.
	*
	* @param ezcDocumentRst $document
	* @param string $path
	* @return void
	*/
	public function __construct( ezcDocumentRst $document, $path )
	{
	$this->rst = $document;
	$this->path = $path;
	}

	/**
	* Trigger visitor error
	*
	* Emit a vistitor error, and convert it to an exception depending on the
	* error reporting settings.
	*
	* @param int $level
	* @param string $message
	* @param string $file
	* @param int $line
	* @param int $position
	* @return void
	*/
	public function triggerError( $level, $message, $file = null, $line = null, $position = null )
	{
	if ( $level & $this->rst->options->errorReporting )
	{
	throw new ezcDocumentVisitException( $level, $message, $file, $line, $position );
	}
	else
	{
	// If the error should not been reported, we aggregate it to maybe
	// display it later.
	$this->errors[] = new ezcDocumentVisitException( $level, $message, $file, $line, $position );
	}
	}

	/**
	* Return list of errors occured during visiting the document.
	*
	* May be an empty array, if on errors occured, or a list of
	* ezcDocumentVisitException objects.
	*
	* @return array
	*/
	public function getErrors()
	{
	return $this->errors;
	}

	/**
	* Docarate RST AST
	*
	* Visit the RST abstract syntax tree.
	*
	* @param ezcDocumentRstDocumentNode $ast
	* @return mixed
	*/
	public function visit( ezcDocumentRstDocumentNode $ast )
	{
	$this->ast = $ast;
	$this->preProcessAst( $ast );

	// Reset footnote counters
	foreach ( $this->footnoteCounter as $label => $counter )
	{
	$this->footnoteCounter[$label] = 0;
	}
	reset( $this->footnoteSymbols );

	// Reset duplicate reference counter
	$this->referenceCounter = array();
	}

	/**
	* Add a reference target
	*
	* @param string $string
	* @return void
	*/
	private function addReferenceTarget( $string )
	{
	$id = $this->calculateId( $string );
	$this->references[$id] = isset( $this->references[$id] ) ? self::DUBLICATE : self::UNUSED;

	if ( $this->references[$id] === self::UNUSED )
	{
	$this->referenceCounter[$id] = 0;
	return $id;
	}
	else
	{
	return $id . '__' . ( ++$this->referenceCounter[$id] );
	}
	}

	/**
	* Transform a node tree into a string
	*
	* Transform a node tree, with all its subnodes into a string by only
	* getting the textuual contents from ezcDocumentRstTextLineNode objects.
	*
	* @param ezcDocumentRstNode $node
	* @return string
	*/
	public function nodeToString( ezcDocumentRstNode $node )
	{
	$text = '';

	foreach ( $node->nodes as $child )
	{
	if ( ( $child instanceof ezcDocumentRstTextLineNode ) \|\|
	( $child instanceof ezcDocumentRstLiteralNode ) )
	{
	$text .= $child->token->content;
	}
	else
	{
	$text .= $this->nodeToString( $child );
	}
	}

	return $text;
	}

	/**
	* Get string from token list.
	*
	* @param array $tokens
	* @return string
	*/
	protected function tokenListToString( array $tokens )
	{
	$text = '';

	foreach ( $tokens as $token )
	{
	$text .= $token->content;
	}

	return $text;
	}

	/**
	* Compare two list items
	*
	* Check if the given list item may be a successor in the same list, as the
	* last item in the list. Returns the boolean status o the check.
	*
	* @param ezcDocumentRstNode $item
	* @param ezcDocumentRstNode $lastItem
	* @return bool
	*/
	protected function compareListType( ezcDocumentRstNode $item, ezcDocumentRstNode $lastItem )
	{
	// Those always belong to each other... .oO( ♡ )
	if ( $item instanceof ezcDocumentRstDefinitionListNode )
	{
	return true;
	}

	// For bullet lists, just compare the tokens
	if ( $item instanceof ezcDocumentRstBulletListNode )
	{
	return ( $item->token->content === $lastItem->token->content );
	}

	// For enumerated lists, we need to check if the current value is a
	// valid successor of the prior value.
	if ( $item instanceof ezcDocumentRstEnumeratedListNode )
	{
	return ( $lastItem instanceof ezcDocumentRstEnumeratedListNode ) &&
	( $item->listType === $lastItem->listType );
	}

	return true;
	}

	/**
	* Aggregate list items
	*
	* Aggregate list items into lists. In RST there are only list items, which
	* are aggregated to lists depending on their bullet type. The related list
	* items are aggregated into one list.
	*
	* @param ezcDocumentRstNode $node
	* @return void
	*/
	protected function aggregateListItems( ezcDocumentRstNode $node )
	{
	$listTypeMapping = array(
	'ezcDocumentRstBulletListNode' => 'ezcDocumentRstBulletListListNode',
	'ezcDocumentRstEnumeratedListNode' => 'ezcDocumentRstEnumeratedListListNode',
	'ezcDocumentRstDefinitionListNode' => 'ezcDocumentRstDefinitionListListNode',
	);

	$lastItem = null;
	$list = null;
	$children = array();
	foreach ( $node->nodes as $nr => $child )
	{
	if ( isset( $listTypeMapping[$class = get_class( $child )] ) )
	{
	if ( ( $lastItem === null ) \|\|
	( $list === null ) \|\|
	( !$this->compareListType( $child, $lastItem ) ) )
	{
	// Create a new list.
	$listType = $listTypeMapping[$class];
	$list = new $listType( $child->token );
	$list->nodes[] = $child;
	$children[] = $list;
	}
	else
	{
	// Append to current list
	$list->nodes[] = $child;
	}
	$lastItem = $child;
	}
	else
	{
	$children[] = $child;
	$lastItem = null;
	}
	}

	$node->nodes = $children;
	}

	/**
	* Add footnote
	*
	* @param ezcDocumentRstNode $node
	* @return void
	*/
	protected function addFootnote( ezcDocumentRstNode $node )
	{
	$identifier = $this->tokenListToString( $node->name );

	switch ( $node->footnoteType )
	{
	case ezcDocumentRstFootnoteNode::NUMBERED:
	$label = 0;
	$number = (int) $identifier;
	$this->footnoteCounter[0] = max( $number, $this->footnoteCounter[0] );
	break;
	case ezcDocumentRstFootnoteNode::AUTO_NUMBERED:
	$label = 0;
	$number = !isset( $this->footnoteCounter[$label] ) ? ( $this->footnoteCounter[$label] = 1 ) : ++$this->footnoteCounter[$label];
	break;
	case ezcDocumentRstFootnoteNode::LABELED:
	$label = substr( $identifier, 1 );
	$number = !isset( $this->footnoteCounter[$label] ) ? ( $this->footnoteCounter[$label] = 1 ) : ++$this->footnoteCounter[$label];
	break;
	case ezcDocumentRstFootnoteNode::SYMBOL:
	$label = '*';
	$number = next( $this->footnoteSymbols );
	break;
	case ezcDocumentRstFootnoteNode::CITATION:
	$label = '#';
	$number = $identifier;
	break;
	}

	// Store footnote for later rendering in footnote array
	$node->name = $label;
	$node->number = $number;
	$this->footnotes[$label][$number] = $node;
	}

	/**
	* Pre process AST
	*
	* Performs multiple preprocessing steps on the AST:
	*
	* Collect all possible reference targets in the AST to know the actual
	* destianation for references while decorating. The references are stored
	* in an internal structure and you may request the actual link by using
	* the getReferenceTarget() method.
	*
	* Aggregate list items into lists. In RST there are only list items, which
	* are aggregated to lists depending on their bullet type. The related list
	* items are aggregated into one list.
	*
	* @param ezcDocumentRstNode $node
	* @return void
	*/
	protected function preProcessAst( ezcDocumentRstNode $node )
	{
	switch ( true )
	{
	case $node instanceof ezcDocumentRstDocumentNode:
	$this->aggregateListItems( $node );
	break;

	case $node instanceof ezcDocumentRstSectionNode:
	$node->reference = $this->addReferenceTarget( $this->nodeToString( $node->title ) );
	$this->aggregateListItems( $node );

	// Also recurse into special title subtree
	foreach ( $node->title->nodes as $child )
	{
	$this->preProcessAst( $child );
	}
	break;

	case $node instanceof ezcDocumentRstTableCellNode:
	case $node instanceof ezcDocumentRstBulletListNode:
	case $node instanceof ezcDocumentRstEnumeratedListNode:
	$this->aggregateListItems( $node );
	break;

	case $node instanceof ezcDocumentRstTargetNode:
	$this->addReferenceTarget( $target = $this->nodeToString( $node ) );
	break;

	case $node instanceof ezcDocumentRstNamedReferenceNode:
	if ( count( $node->nodes ) )
	{
	// This is a direct reference to an external URL, just add
	// to the list of named external references.
	$this->namedExternalReferences[$this->calculateId( $this->tokenListToString( $node->name ) )] =
	trim( $this->nodeToString( $node ) );
	}
	break;

	case $node instanceof ezcDocumentRstAnonymousReferenceNode:
	$this->anonymousReferences[] = trim( $this->nodeToString( $node ) );
	break;

	case $node instanceof ezcDocumentRstSubstitutionNode:
	$substitutionName = strtolower( $this->tokenListToString( $node->name ) );
	$this->substitutions[$substitutionName] = $node->nodes;
	break;

	case $node instanceof ezcDocumentRstFootnoteNode:
	$this->addFootnote( $node );
	break;
	}

	// Check for forward references of empty named references.
	$children = $node->nodes;
	reset( $children );
	while ( $child = next( $children ) )
	{
	$stack = array();
	while ( ( $child instanceof ezcDocumentRstNamedReferenceNode ) &&
	( count( $child->nodes ) === 0 ) )
	{
	$stack[] = $child;
	$child = next( $children );
	}

	if ( $child && count( $stack ) )
	{
	// We found a element, which is not an empty named reference
	// node, so get the identifier from it and assign it to all
	// named references on the stack.
	if ( $child instanceof ezcDocumentRstNamedReferenceNode )
	{
	// Child is a named reference with content, so use the
	// content as assignement.
	$reference = trim( $this->nodeToString( $child ) );
	}
	else
	{
	// Generate a reference name and assign it to the element.
	$last = end( $stack );
	$reference = $this->calculateId( $this->tokenListToString( $last->name ) );
	$child->identifier = $reference;
	}

	// Assign calculated reference to all aggregated stack
	// elements.
	foreach ( $stack as $refNode )
	{
	$this->namedExternalReferences[$this->calculateId( $this->tokenListToString( $refNode->name ) )] = $reference;
	}
	}
	}

	// Recurse into childs to collect reference targets all over the
	// document.
	foreach ( $node->nodes as $child )
	{
	$this->preProcessAst( $child );
	}
	}

	/**
	* Check for internal footnote reference target
	*
	* Returns the target name, when an internal reference target exists and
	* sets it to used, and false otherwise.
	*
	* @param string $string
	* @param ezcDocumentRstNode $node
	* @return ezcDocumentRstFootnoteNode
	*/
	public function hasFootnoteTarget( $string, ezcDocumentRstNode $node )
	{
	switch ( $node->footnoteType )
	{
	case ezcDocumentRstFootnoteNode::NUMBERED:
	$label = 0;
	$string = (int) $string;
	$this->footnoteCounter[0] = max( $string, $this->footnoteCounter[0] );
	break;
	case ezcDocumentRstFootnoteNode::AUTO_NUMBERED:
	$label = 0;
	$string = ++$this->footnoteCounter[$label];
	break;
	case ezcDocumentRstFootnoteNode::LABELED:
	$label = substr( $string, 1 );
	$string = ++$this->footnoteCounter[$label];
	break;
	case ezcDocumentRstFootnoteNode::SYMBOL:
	$label = '*';
	$string = next( $this->footnoteSymbols );
	break;
	case ezcDocumentRstFootnoteNode::CITATION:
	$label = '#';
	break;
	}

	if ( isset( $this->footnotes[$label][$string] ) )
	{
	return $this->footnotes[$label][$string];
	}

	return $this->triggerError(
	E_WARNING, "Unknown reference target '{$string}'.", null,
	( $node !== null ? $node->token->line : null ),
	( $node !== null ? $node->token->position : null )
	);
	}

	/**
	* Check for internal reference target
	*
	* Returns the target name, when an internal reference target exists and
	* sets it to used, and false otherwise. For duplicate reference targets
	* and missing reference targets an error will be triggered.
	*
	* An optional third parameter may enforce the fetching of the reference,
	* even if there are duplicates, so that they still can be referenced in
	* some way.
	*
	* @param string $string
	* @param ezcDocumentRstNode $node
	* @param bool $force
	* @return string
	*/
	public function hasReferenceTarget( $string, ezcDocumentRstNode $node = null, $force = false )
	{
	$id = $this->calculateId( $string );
	if ( isset( $this->references[$id] ) &&
	( $this->references[$id] !== self::DUBLICATE ) )
	{
	$this->references[$id] = self::USED;
	return $id;
	}

	if ( !isset( $this->references[$id] ) )
	{
	return $this->triggerError(
	E_WARNING, "Missing reference target '{$id}'.", null,
	( $node !== null ? $node->token->line : null ),
	( $node !== null ? $node->token->position : null )
	);
	}
	elseif ( $force === true )
	{
	// Check if the reference target has been force-requested.
	if ( !isset( $this->referenceCounter[$id] ) )
	{
	$this->referenceCounter[$id] = 0;
	return $id;
	}
	else
	{
	return $id . '__' . ( ++$this->referenceCounter[$id] );
	}
	}
	else
	{
	return $this->triggerError(
	E_NOTICE, "Duplicate reference target '{$id}'.", null,
	( $node !== null ? $node->token->line : null ),
	( $node !== null ? $node->token->position : null )
	);
	}
	}

	/**
	* Return named external reference target
	*
	* Get the target value of a named external reference.
	*
	* @param string $name
	* @return string
	*/
	public function getNamedExternalReference( $name )
	{
	$name = $this->calculateId( $name );

	if ( isset( $this->namedExternalReferences[$name] ) )
	{
	return $this->namedExternalReferences[$name];
	}

	return false;
	}

	/**
	* Get anonymous reference target
	*
	* Get the target URL of an anonomyous reference target.
	*
	* @return string
	*/
	public function getAnonymousReferenceTarget()
	{
	if ( isset( $this->anonymousReferences[$this->anonymousReferenceCounter] ) )
	{
	return $this->anonymousReferences[$this->anonymousReferenceCounter++];
	}

	return $this->triggerError(
	E_WARNING, "Too few anonymous reference targets.", null
	);
	}

	/**
	* Get substitution contents
	*
	* @param string $string
	* @return void
	*/
	protected function substitute( $string )
	{
	$string = strtolower( $string );
	if ( isset( $this->substitutions[$string] ) )
	{
	return $this->substitutions[$string];
	}

	$this->triggerError(
	E_ERROR, "Could not find substitution for '{$string}'.", null
	);
	return array();
	}

	/**
	* Get a valid identifier string
	*
	* Get a valid identifier string from an arbritrary string.
	*
	* @param string $string
	* @return string
	*/
	protected function calculateId( $string )
	{
	$id = trim( preg_replace( '([^a-z0-9-]+)', '_', strtolower( trim( $string ) ) ), '_' );
	if ( !preg_match( '(^[a-z])', $id ) )
	{
	$id = 'id_' . $id;
	}

	return $id;
	}

	/**
	* Calculate unique ID
	*
	* Calculate a valid identifier, which is unique for this document.
	*
	* @param string $string
	* @return string
	*/
	protected function calculateUniqueId( $string )
	{
	$id = $this->calculateId( $string );

	// Ensure uniqueness of IDs
	if ( isset( $this->usedIDs[$id] ) )
	{
	$i = 2;
	do {
	$tryId = $id . '_' . $i++;
	} while ( isset( $this->usedIDs[$tryId] ) );
	$id = $tryId;
	}
	$this->usedIDs[$id] = true;

	return $id;
	}

	/**
	* Visit text node
	*
	* @param DOMNode $root
	* @param ezcDocumentRstNode $node
	* @return void
	*/
	protected function visitText( DOMNode $root, ezcDocumentRstNode $node )
	{
	$root->appendChild(
	new DOMText( $node->token->content )
	);
	}

	/**
	* Visit children
	*
	* Just recurse into node and visit its children, ignoring the actual
	* node.
	*
	* @param DOMNode $root
	* @param ezcDocumentRstNode $node
	* @return void
	*/
	protected function visitChildren( DOMNode $root, ezcDocumentRstNode $node )
	{
	foreach ( $node->nodes as $child )
	{
	$this->visitNode( $root, $child );
	}
	}

	/**
	* Visit substitution reference node
	*
	* @param DOMNode $root
	* @param ezcDocumentRstNode $node
	* @return void
	*/
	protected function visitSubstitutionReference( DOMNode $root, ezcDocumentRstNode $node )
	{
	if ( ( $substitution = $this->substitute( $this->nodeToString( $node ) ) ) !== null )
	{
	foreach ( $substitution as $child )
	{
	$this->visitNode( $root, $child );
	}
	}
	}
	}

	?>