Document/src/document/bbcode/parser.php - zetacomponents - Git at Google

 <?php
 /**
  * File containing the ezcDocumentBBCodeParser 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
  */

 /**
  * Parser for bbcode documents.
  *
  * @package Document
  * @version //autogen//
  */
 class ezcDocumentBBCodeParser extends ezcDocumentParser
 {
     /**
      * Array containing simplified shift ruleset.
      *
      * We cannot express the BBCode syntax as a usual grammar using a BNF. With
      * the pumping lemma for context free grammars [1] you can easily prove,
      * that the word a^n b c^n d e^n is not a context free grammar, and this is
      * what the title definitions are.
      *
      * This structure contains an array with callbacks implementing the shift
      * rules for all tokens. There may be multiple rules for one single token.
      *
      * The callbacks itself create syntax elements and push them to the
      * document stack. After each push the reduction callbacks will be called
      * for the pushed elements.
      *
      * The array should look like:
      * <code>
      *  array(
      *      WHITESPACE => array(
      *          reductionMethod,
      *          ...
      *      ),
      *      ...
      *  )
      * </code>
      *
      * [1] http://en.bbcodepedia.org/bbcode/Pumping_lemma_for_context-free_languages
      *
      * @var array
      */
     protected $shifts = array(
         'ezcDocumentBBCodeTagOpenToken'
             => 'shiftOpeningToken',
         'ezcDocumentBBCodeTagCloseToken'
             => 'shiftClosingToken',
         'ezcDocumentBBCodeListItemToken'
             => 'shiftListItemToken',
         'ezcDocumentBBCodeWhitespaceToken'
             => 'shiftWhitespaceToken',
         'ezcDocumentBBCodeTextLineToken'
             => 'shiftTextToken',
         'ezcDocumentBBCodeLiteralBlockToken'
             => 'shiftLiteralBlockToken',
         'ezcDocumentBBCodeNewLineToken'
             => 'shiftNewLineToken',
         'ezcDocumentBBCodeEndOfFileToken'
             => 'shiftEndOfFileToken',
     );

     /**
      * Array containing simplified reduce ruleset.
      *
      * We cannot express the BBCode syntax as a usual grammar using a BNF. This
      * structure implements a pseudo grammar by assigning a number of callbacks
      * for internal methods implementing reduction rules for a detected syntax
      * element.
      *
      * <code>
      *  array(
      *      ezcDocumentBBCodeNode::DOCUMENT => 'reduceDocument'
      *      ...
      *  )
      * </code>
      *
      * @var array
      */
     protected $reductions = array(
         'ezcDocumentBBCodeClosingTagNode' => array(
             'reduceTags',
         ),
         'ezcDocumentBBCodeParagraphNode' => array(
             'reduceParagraph',
         ),
         'ezcDocumentBBCodeDocumentNode' => array(
             'reduceDocument',
         ),
         'ezcDocumentBBCodeListItemNode' => array(
             'reduceListItem',
         ),
         'ezcDocumentBBCodeListEndNode' => array(
             'reduceList',
         ),
     );

     /**
      * Contains a list of detected syntax elements.
      *
      * At the end of a successfull parsing process this should only contain one
      * document syntax element. During the process it may contain a list of
      * elements, which are up to reduction.
      *
      * Each element in the stack has to be an object extending from
      * ezcDocumentRstNode, which may again contain any amount such objects.
      * This way an abstract syntax tree is constructed.
      *
      * @var array
      */
     protected $documentStack = array();

     /**
      * Parse token stream.
      *
      * Parse an array of ezcDocumentBBCodeToken objects into a bbcode abstract
      * syntax tree.
      *
      * @param array $tokens
      * @return ezcDocumentBBCodeDocumentNode
      */
     public function parse( array $tokens )
     {
         /* DEBUG
         echo "\n\nStart parser\n============\n\n";
         // /DEBUG */

         while ( ( $token = array_shift( $tokens ) ) !== null )
         {
             /* DEBUG
             echo "[T] ({$token->line}:{$token->position}) Token: " . get_class( $token ) . " at {$token->line}:{$token->position}.\n";
             // /DEBUG */

             // First shift given token by the defined reduction methods
             $node = false;
             foreach ( $this->shifts as $class => $method )
             {
                 if ( $token instanceof $class )
                 {
                     /* DEBUG
                     echo " - Handle token with ->$method\n";
                     // /DEBUG */

                     // Try to shift the token with current method
                     if ( ( $node = $this->$method( $token, $tokens ) ) !== false )
                     {
                         break;
                     }
                 }
             }

             // If the node is still null there was not matching shift rule.
             if ( $node === false )
             {
                 return $this->triggerError( E_PARSE,
                     "Could not find shift rule for token '" . get_class( $token ) . "'.",
                     $token->line, $token->position
                 );
             }

             // Token did not result in any node, it should just be ignored.
             if ( $node === null )
             {
                 continue;
             }

             /* DEBUG
             echo "[N] Node: " . get_class( $node ) . " at {$node->token->line}:{$node->token->position}.\n";
             // /DEBUG */

             // Apply reductions to shifted node
             do {
                 foreach ( $this->reductions as $class => $methods )
                 {
                     if ( $node instanceof $class )
                     {
                         foreach ( $methods as $method )
                         {
                             /* DEBUG
                             echo " - Handle node with ->$method\n";
                             // /DEBUG */

                             if ( ( $node = $this->$method( $node ) ) === null )
                             {
                                 /* DEBUG
                                 echo "   - Reduced.\n";
                                 // /DEBUG */
                                 // The node has been handled, exit loop.
                                 break 3;
                             }

                             // Check if the node class has changed and rehandle
                             // node in this case.
                             if ( !$node instanceof $class )
                             {
                                 /* DEBUG
                                 echo "   - Try subsequent reductions...\n";
                                 // /DEBUG */

                                 continue 2;
                             }
                         }
                     }
                 }
             } while ( false );

             // Check if reductions have been applied, but still returned a
             // node, just add to document stack in this case.
             if ( $node !== null )
             {
                 /* DEBUG
                 echo " => Prepend " . get_class( $node ) . " to document stack.\n";
                 // /DEBUG */
                 array_unshift( $this->documentStack, $node );
             }
         }

         // Check if we successfully reduced the document stack
         if ( ( count( $this->documentStack ) !== 1 ) ||
              ( !( $document = reset( $this->documentStack ) ) instanceof ezcDocumentBBCodeDocumentNode ) )
         {
             $node = isset( $document ) ? $document : reset( $this->documentStack );
             $this->triggerError(
                 E_PARSE,
                 'Expected end of file, got: ' . get_class( $this->documentStack[1] ) . ".",
                 $this->documentStack[1]->token->line, $this->documentStack[1]->token->position
             );
         }

         return $document;
     }

     /**
      * Shift list item token
      *
      * List item tokens indicate a new list item. Just put them on the stack,
      * they will be aggregated later.
      *
      * @param ezcDocumentBBCodeToken $token
      * @param array $tokens
      * @return mixed
      */
     protected function shiftListItemToken( ezcDocumentBBCodeToken $token, array &$tokens )
     {
         /* DEBUG
         echo " - Shift list item.\n";
         // /DEBUG */
         return new ezcDocumentBBCodeListItemNode( $token );
     }

     /**
      * Shift tag opening token
      *
      * Opening tags mean that the following contents will be aggregated, once a
      * matching closing tag is found. Is just shifted to the document stack.
      *
      * @param ezcDocumentBBCodeToken $token
      * @param array $tokens
      * @return mixed
      */
     protected function shiftOpeningToken( ezcDocumentBBCodeToken $token, array &$tokens )
     {
         if ( $token->content !== 'list' )
         {
             /* DEBUG
             echo " - Shift opening token {$token->content}.\n";
             // /DEBUG */
             return new ezcDocumentBBCodeTagNode( $token );
         }

         switch ( true )
         {
             case $token->parameters === null:
                 /* DEBUG
                 echo " - Shift bullet list.\n";
                 // /DEBUG */
                 return new ezcDocumentBBCodeBulletListNode( $token );

             default:
                 /* DEBUG
                 echo " - Shift enumerated list.\n";
                 // /DEBUG */
                 return new ezcDocumentBBCodeEnumeratedListNode( $token );
         }
     }

     /**
      * Shift tag clsoing token
      *
      * Closing tags mean that the preceeding contents will be aggregated, once a
      * matching opening tag is found. Is just shifted to the document stack,
      * and the appropriate reduce call will follow right away.
      *
      * @param ezcDocumentBBCodeToken $token
      * @param array $tokens
      * @return mixed
      */
     protected function shiftClosingToken( ezcDocumentBBCodeToken $token, array &$tokens )
     {
         if ( $token->content === 'list' )
         {
             /* DEBUG
             echo " - Shift list end node.\n";
             // /DEBUG */
             return new ezcDocumentBBCodeListEndNode( $token );
         }

         /* DEBUG
         echo " - Shift closing token {$token->content}.\n";
         // /DEBUG */
         return new ezcDocumentBBCodeClosingTagNode( $token );
     }

     /**
      * Shift whitespace token.
      *
      * Shift whitespace tokens. Whitespaces are only considered significant, if
      * the prior token was not a block level element.
      *
      * @param ezcDocumentBBCodeToken $token
      * @param array $tokens
      * @return mixed
      */
     protected function shiftWhitespaceToken( ezcDocumentBBCodeToken $token, array &$tokens )
     {
         if ( isset( $this->documentStack[0] ) &&
              ( !$this->documentStack[0] instanceof ezcDocumentBBCodeBlockLevelNode ) )
         {
             /* DEBUG
             echo " - Shift whitespace text node.\n";
             // /DEBUG */
             return new ezcDocumentBBCodeTextNode( $token );
         }

         /* DEBUG
         echo " - Ignore whitespace node.\n";
         // /DEBUG */
         return null;
     }

     /**
      * Shift text token.
      *
      * @param ezcDocumentBBCodeToken $token
      * @param array $tokens
      * @return mixed
      */
     protected function shiftTextToken( ezcDocumentBBCodeToken $token, array &$tokens )
     {
         /* DEBUG
         echo " - Shift text node.\n";
         // /DEBUG */
         return new ezcDocumentBBCodeTextNode( $token );
     }

     /**
      * Shift literal block token
      *
      * Literal blocks are just a chunk of code or similar, where the token can
      * jsut be converted into an apropriate node.
      *
      * @param ezcDocumentBBCodeToken $token
      * @param array $tokens
      * @return mixed
      */
     protected function shiftLiteralBlockToken( ezcDocumentBBCodeToken $token, array &$tokens )
     {
         if ( isset( $this->documentStack[0] ) &&
              ( $this->documentStack[0] instanceof ezcDocumentBBCodeParagraphNode ) &&
              isset( $tokens[0] ) &&
              ( $tokens[0] instanceof ezcDocumentBBCodeNewLineToken ) )
         {
             // Remove following new line tokens.
             do {
                 array_shift( $tokens );
             } while ( isset( $tokens[0] ) &&
                       ( ( $tokens[0] instanceof ezcDocumentBBCodeNewlineToken ) ||
                         ( $tokens[0] instanceof ezcDocumentBBCodeWhitespaceToken ) ) );

             /* DEBUG
             echo " - Shift literal block node.\n";
             // /DEBUG */
             return new ezcDocumentBBCodeLiteralBlockNode( $token );
         }
         else
         {
             /* DEBUG
             echo " - Shift inline literal node.\n";
             // /DEBUG */
             return new ezcDocumentBBCodeInlineLiteralNode( $token );
         }
     }

     /**
      * Shift new line token.
      *
      * Double new lines are considered as paragraphs. All other new lines are
      * just shifted as single whitespace text nodes.
      *
      * @param ezcDocumentBBCodeToken $token
      * @param array $tokens
      * @return mixed
      */
     protected function shiftNewLineToken( ezcDocumentBBCodeToken $token, array &$tokens )
     {
         while ( isset( $tokens[0] ) &&
                 ( $tokens[0] instanceof ezcDocumentBBCodeWhitespaceToken ) )
         {
             array_shift( $tokens );
         }

         if ( isset( $tokens[0] ) &&
              ( $tokens[0] instanceof ezcDocumentBBCodeNewlineToken ) )
         {
             do {
                 array_shift( $tokens );
             } while ( isset( $tokens[0] ) &&
                       ( ( $tokens[0] instanceof ezcDocumentBBCodeNewlineToken ) ||
                         ( $tokens[0] instanceof ezcDocumentBBCodeWhitespaceToken ) ) );
             /* DEBUG
             echo " - Shift paragraph node.\n";
             // /DEBUG */
             return new ezcDocumentBBCodeParagraphNode( $token );
         }
         elseif ( isset( $this->documentStack[0] ) &&
                  ( !$this->documentStack[0] instanceof ezcDocumentBBCodeBlockLevelNode ) )
         {
             /* DEBUG
             echo " - Shift newline as whitespace node.\n";
             // /DEBUG */
             return new ezcDocumentBBCodeTextNode( $token );
         }

         /* DEBUG
         echo " - Ignore whitespace node.\n";
         // /DEBUG */
         return null;
     }

     /**
      * Shift EOF token.
      *
      * Shift End-Of-File token. We reached the end of the document, and
      * therefore shift a document node onto the stack.
      *
      * @param ezcDocumentBBCodeToken $token
      * @param array $tokens
      * @return mixed
      */
     protected function shiftEndOfFileToken( ezcDocumentBBCodeToken $token, array &$tokens )
     {
         /* DEBUG
         echo " - Shift document node.\n";
         // /DEBUG */
         return new ezcDocumentBBCodeDocumentNode( $token );
     }

     /**
      * Reduce tags.
      *
      * Locates the matching opening tag for a closing tag and reduces the
      * contents found on the way back.
      *
      * @param ezcDocumentBBCodeClosingTagNode $node
      * @return mixed
      */
     protected function reduceTags( ezcDocumentBBCodeClosingTagNode $node )
     {
         $nodes = array();
         while ( isset( $this->documentStack[0] ) &&
                 ( ( !$this->documentStack[0] instanceof ezcDocumentBBCodeTagNode ) ||
                   ( $this->documentStack[0]->token->content !== $node->token->content ) ) )
         {
             $nodes[] = $child = array_shift( $this->documentStack );

             if ( ( $child instanceof ezcDocumentBBCodeTagNode ) &&
                  ( !count( $child->nodes ) ) )
             {
                 return $this->triggerError( E_PARSE,
                     "Opening tag, without matching closing tag found: '" . $child->token->content . "'.",
                     $child->token->line, $child->token->position
                 );
             }

             if ( $child instanceof ezcDocumentBBCodeClosingTagNode )
             {
                 return $this->triggerError( E_PARSE,
                     "Closing tag, without matching opening tag found: '" . $child->token->content . "'.",
                     $child->token->line, $child->token->position
                 );
             }
         }

         if ( ( !$this->documentStack[0] instanceof ezcDocumentBBCodeTagNode ) ||
              ( $this->documentStack[0]->token->content !== $node->token->content ) )
         {
             return $this->triggerError( E_PARSE,
                 "Closing tag, without matching opening tag found: '" . $node->token->content . "'.",
                 $node->token->line, $node->token->position
             );
         }

         $node = array_shift( $this->documentStack );
         $node->nodes = array_reverse( $nodes );
         return $node;
     }

     /**
      * Reduce list items.
      *
      * Aggregates list items and puts them into a found list.
      *
      * @param ezcDocumentBBCodeParagraphNode $node
      * @return mixed
      */
     protected function reduceListItem( ezcDocumentBBCodeNode $node )
     {
         $nodes = array();
         while ( isset( $this->documentStack[0] ) &&
                 ( !$this->documentStack[0] instanceof ezcDocumentBBCodeListItemNode ) &&
                 ( ( !$this->documentStack[0] instanceof ezcDocumentBBCodeListNode ) ||
                   ( ( $this->documentStack[0] instanceof ezcDocumentBBCodeListNode ) &&
                     ( count( $this->documentStack[0]->nodes ) ) ) ) )
         {
             $nodes[] = $child = array_shift( $this->documentStack );

             if ( ( $child instanceof ezcDocumentBBCodeTagNode ) &&
                  ( !count( $child->nodes ) ) )
             {
                 return $this->triggerError( E_PARSE,
                     "Opening tag, without matching closing tag found: '" . $child->token->content . "'.",
                     $child->token->line, $child->token->position
                 );
             }

             if ( $child instanceof ezcDocumentBBCodeClosingTagNode )
             {
                 return $this->triggerError( E_PARSE,
                     "Closing tag, without matching opening tag found: '" . $child->token->content . "'.",
                     $child->token->line, $child->token->position
                 );
             }
         }

         if ( !isset( $this->documentStack[0] ) )
         {
             return $this->triggerError( E_PARSE,
                 "Missing list item node.",
                 $child->token->line, $child->token->position
             );
         }

         // Wrap non-block-level nodes into paragraphs
         $wrapped = array();
         $temp    = array();
         foreach ( $nodes as $child )
         {
             if ( !$child instanceof ezcDocumentBBCodeBlockLevelNode )
             {
                 $temp[] = $child;
             }
             elseif ( count( $temp ) )
             {
                 $wrapped[]   = $para = new ezcDocumentBBCodeParagraphNode( $temp[0]->token );
                 $para->nodes = array_reverse( $temp );
                 $temp        = array();
                 $wrapped[]   = $child;
             }
             else
             {
                 $wrapped[] = $child;
             }
         }

         if ( count( $temp ) )
         {
             $wrapped[]   = $para = new ezcDocumentBBCodeParagraphNode( $temp[0]->token );
             $para->nodes = array_reverse( $temp );
         }

         if ( $this->documentStack[0] instanceof ezcDocumentBBCodeListItemNode )
         {
             $this->documentStack[0]->nodes = array_reverse( $wrapped );
         }

         return $node;
     }

     /**
      * Reduce list.
      *
      * Aggregates list items and puts them into a found list.
      *
      * @param ezcDocumentBBCodeParagraphNode $node
      * @return mixed
      */
     protected function reduceList( ezcDocumentBBCodeNode $node )
     {
         $this->reduceListItem( $node );

         $nodes = array();
         while ( isset( $this->documentStack[0] ) &&
                 ( $this->documentStack[0] instanceof ezcDocumentBBCodeListItemNode ) )
         {
             $nodes[] = array_shift( $this->documentStack );
         }

         if ( !isset( $this->documentStack[0] ) ||
              ( !$this->documentStack[0] instanceof ezcDocumentBBCodeListNode ) )
         {
             return $this->triggerError( E_PARSE,
                 "Missing list start node.",
                 $child->token->line, $child->token->position
             );
         }

         $this->documentStack[0]->nodes = array_reverse( $nodes );
         return null;
     }

     /**
      * Reduce paragraph.
      *
      * Paragraphs are reduce with all inline tokens, which have been added to
      * the document stack before. If there are no inline nodes, the paragraph
      * will be ommitted.
      *
      * @param ezcDocumentBBCodeParagraphNode $node
      * @return mixed
      */
     protected function reduceParagraph( ezcDocumentBBCodeParagraphNode $node )
     {
         $nodes = array();
         while ( isset( $this->documentStack[0] ) &&
                 ( !$this->documentStack[0] instanceof ezcDocumentBBCodeParagraphNode ) &&
                 ( !$this->documentStack[0] instanceof ezcDocumentBBCodeListNode ) &&
                 ( !$this->documentStack[0] instanceof ezcDocumentBBCodeLiteralBlockNode ) )
         {
             $nodes[] = $child = array_shift( $this->documentStack );

             if ( ( $child instanceof ezcDocumentBBCodeTagNode ) &&
                  ( !count( $child->nodes ) ) )
             {
                 return $this->triggerError( E_PARSE,
                     "Opening tag, without matching closing tag found: '" . $child->token->content . "'.",
                     $child->token->line, $child->token->position
                 );
             }

             if ( $child instanceof ezcDocumentBBCodeClosingTagNode )
             {
                 return $this->triggerError( E_PARSE,
                     "Closing tag, without matching opening tag found: '" . $child->token->content . "'.",
                     $child->token->line, $child->token->position
                 );
             }
         }

         // Omit empty paragraphs
         if ( !count( $nodes ) )
         {
             return null;
         }

         $node->nodes = array_reverse( $nodes );
         return $node;
     }

     /**
      * Reduce prior sections, if a new section has been found.
      *
      * If a new section has been found all sections with a higher depth level
      * can be closed, and all items fitting into sections may be aggregated by
      * the respective sections as well.
      *
      * @param ezcDocumentBBCodeDocumentNode $node
      */
     protected function reduceDocument( ezcDocumentBBCodeDocumentNode $node )
     {
         $nodes = array();
         while ( isset( $this->documentStack[0] ) &&
                 ( ( $this->documentStack[0] instanceof ezcDocumentBBCodeParagraphNode ) ||
                   ( $this->documentStack[0] instanceof ezcDocumentBBCodeListNode ) ||
                   ( $this->documentStack[0] instanceof ezcDocumentBBCodeLiteralBlockNode ) ) )
         {
             $nodes[] = array_shift( $this->documentStack );
         }
         $node->nodes = array_reverse( $nodes );

         return $node;
     }
 }

 ?>
	<?php
	/**
	* File containing the ezcDocumentBBCodeParser 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
	*/

	/**
	* Parser for bbcode documents.
	*
	* @package Document
	* @version //autogen//
	*/
	class ezcDocumentBBCodeParser extends ezcDocumentParser
	{
	/**
	* Array containing simplified shift ruleset.
	*
	* We cannot express the BBCode syntax as a usual grammar using a BNF. With
	* the pumping lemma for context free grammars [1] you can easily prove,
	* that the word a^n b c^n d e^n is not a context free grammar, and this is
	* what the title definitions are.
	*
	* This structure contains an array with callbacks implementing the shift
	* rules for all tokens. There may be multiple rules for one single token.
	*
	* The callbacks itself create syntax elements and push them to the
	* document stack. After each push the reduction callbacks will be called
	* for the pushed elements.
	*
	* The array should look like:
	* <code>
	* array(
	* WHITESPACE => array(
	* reductionMethod,
	* ...
	* ),
	* ...
	* )
	* </code>
	*
	* [1] http://en.bbcodepedia.org/bbcode/Pumping_lemma_for_context-free_languages
	*
	* @var array
	*/
	protected $shifts = array(
	'ezcDocumentBBCodeTagOpenToken'
	=> 'shiftOpeningToken',
	'ezcDocumentBBCodeTagCloseToken'
	=> 'shiftClosingToken',
	'ezcDocumentBBCodeListItemToken'
	=> 'shiftListItemToken',
	'ezcDocumentBBCodeWhitespaceToken'
	=> 'shiftWhitespaceToken',
	'ezcDocumentBBCodeTextLineToken'
	=> 'shiftTextToken',
	'ezcDocumentBBCodeLiteralBlockToken'
	=> 'shiftLiteralBlockToken',
	'ezcDocumentBBCodeNewLineToken'
	=> 'shiftNewLineToken',
	'ezcDocumentBBCodeEndOfFileToken'
	=> 'shiftEndOfFileToken',
	);

	/**
	* Array containing simplified reduce ruleset.
	*
	* We cannot express the BBCode syntax as a usual grammar using a BNF. This
	* structure implements a pseudo grammar by assigning a number of callbacks
	* for internal methods implementing reduction rules for a detected syntax
	* element.
	*
	* <code>
	* array(
	* ezcDocumentBBCodeNode::DOCUMENT => 'reduceDocument'
	* ...
	* )
	* </code>
	*
	* @var array
	*/
	protected $reductions = array(
	'ezcDocumentBBCodeClosingTagNode' => array(
	'reduceTags',
	),
	'ezcDocumentBBCodeParagraphNode' => array(
	'reduceParagraph',
	),
	'ezcDocumentBBCodeDocumentNode' => array(
	'reduceDocument',
	),
	'ezcDocumentBBCodeListItemNode' => array(
	'reduceListItem',
	),
	'ezcDocumentBBCodeListEndNode' => array(
	'reduceList',
	),
	);

	/**
	* Contains a list of detected syntax elements.
	*
	* At the end of a successfull parsing process this should only contain one
	* document syntax element. During the process it may contain a list of
	* elements, which are up to reduction.
	*
	* Each element in the stack has to be an object extending from
	* ezcDocumentRstNode, which may again contain any amount such objects.
	* This way an abstract syntax tree is constructed.
	*
	* @var array
	*/
	protected $documentStack = array();

	/**
	* Parse token stream.
	*
	* Parse an array of ezcDocumentBBCodeToken objects into a bbcode abstract
	* syntax tree.
	*
	* @param array $tokens
	* @return ezcDocumentBBCodeDocumentNode
	*/
	public function parse( array $tokens )
	{
	/* DEBUG
	echo "\n\nStart parser\n============\n\n";
	// /DEBUG */

	while ( ( $token = array_shift( $tokens ) ) !== null )
	{
	/* DEBUG
	echo "[T] ({$token->line}:{$token->position}) Token: " . get_class( $token ) . " at {$token->line}:{$token->position}.\n";
	// /DEBUG */

	// First shift given token by the defined reduction methods
	$node = false;
	foreach ( $this->shifts as $class => $method )
	{
	if ( $token instanceof $class )
	{
	/* DEBUG
	echo " - Handle token with ->$method\n";
	// /DEBUG */

	// Try to shift the token with current method
	if ( ( $node = $this->$method( $token, $tokens ) ) !== false )
	{
	break;
	}
	}
	}

	// If the node is still null there was not matching shift rule.
	if ( $node === false )
	{
	return $this->triggerError( E_PARSE,
	"Could not find shift rule for token '" . get_class( $token ) . "'.",
	$token->line, $token->position
	);
	}

	// Token did not result in any node, it should just be ignored.
	if ( $node === null )
	{
	continue;
	}

	/* DEBUG
	echo "[N] Node: " . get_class( $node ) . " at {$node->token->line}:{$node->token->position}.\n";
	// /DEBUG */

	// Apply reductions to shifted node
	do {
	foreach ( $this->reductions as $class => $methods )
	{
	if ( $node instanceof $class )
	{
	foreach ( $methods as $method )
	{
	/* DEBUG
	echo " - Handle node with ->$method\n";
	// /DEBUG */

	if ( ( $node = $this->$method( $node ) ) === null )
	{
	/* DEBUG
	echo " - Reduced.\n";
	// /DEBUG */
	// The node has been handled, exit loop.
	break 3;
	}

	// Check if the node class has changed and rehandle
	// node in this case.
	if ( !$node instanceof $class )
	{
	/* DEBUG
	echo " - Try subsequent reductions...\n";
	// /DEBUG */

	continue 2;
	}
	}
	}
	}
	} while ( false );

	// Check if reductions have been applied, but still returned a
	// node, just add to document stack in this case.
	if ( $node !== null )
	{
	/* DEBUG
	echo " => Prepend " . get_class( $node ) . " to document stack.\n";
	// /DEBUG */
	array_unshift( $this->documentStack, $node );
	}
	}

	// Check if we successfully reduced the document stack
	if ( ( count( $this->documentStack ) !== 1 ) \|\|
	( !( $document = reset( $this->documentStack ) ) instanceof ezcDocumentBBCodeDocumentNode ) )
	{
	$node = isset( $document ) ? $document : reset( $this->documentStack );
	$this->triggerError(
	E_PARSE,
	'Expected end of file, got: ' . get_class( $this->documentStack[1] ) . ".",
	$this->documentStack[1]->token->line, $this->documentStack[1]->token->position
	);
	}

	return $document;
	}

	/**
	* Shift list item token
	*
	* List item tokens indicate a new list item. Just put them on the stack,
	* they will be aggregated later.
	*
	* @param ezcDocumentBBCodeToken $token
	* @param array $tokens
	* @return mixed
	*/
	protected function shiftListItemToken( ezcDocumentBBCodeToken $token, array &$tokens )
	{
	/* DEBUG
	echo " - Shift list item.\n";
	// /DEBUG */
	return new ezcDocumentBBCodeListItemNode( $token );
	}

	/**
	* Shift tag opening token
	*
	* Opening tags mean that the following contents will be aggregated, once a
	* matching closing tag is found. Is just shifted to the document stack.
	*
	* @param ezcDocumentBBCodeToken $token
	* @param array $tokens
	* @return mixed
	*/
	protected function shiftOpeningToken( ezcDocumentBBCodeToken $token, array &$tokens )
	{
	if ( $token->content !== 'list' )
	{
	/* DEBUG
	echo " - Shift opening token {$token->content}.\n";
	// /DEBUG */
	return new ezcDocumentBBCodeTagNode( $token );
	}

	switch ( true )
	{
	case $token->parameters === null:
	/* DEBUG
	echo " - Shift bullet list.\n";
	// /DEBUG */
	return new ezcDocumentBBCodeBulletListNode( $token );

	default:
	/* DEBUG
	echo " - Shift enumerated list.\n";
	// /DEBUG */
	return new ezcDocumentBBCodeEnumeratedListNode( $token );
	}
	}

	/**
	* Shift tag clsoing token
	*
	* Closing tags mean that the preceeding contents will be aggregated, once a
	* matching opening tag is found. Is just shifted to the document stack,
	* and the appropriate reduce call will follow right away.
	*
	* @param ezcDocumentBBCodeToken $token
	* @param array $tokens
	* @return mixed
	*/
	protected function shiftClosingToken( ezcDocumentBBCodeToken $token, array &$tokens )
	{
	if ( $token->content === 'list' )
	{
	/* DEBUG
	echo " - Shift list end node.\n";
	// /DEBUG */
	return new ezcDocumentBBCodeListEndNode( $token );
	}

	/* DEBUG
	echo " - Shift closing token {$token->content}.\n";
	// /DEBUG */
	return new ezcDocumentBBCodeClosingTagNode( $token );
	}

	/**
	* Shift whitespace token.
	*
	* Shift whitespace tokens. Whitespaces are only considered significant, if
	* the prior token was not a block level element.
	*
	* @param ezcDocumentBBCodeToken $token
	* @param array $tokens
	* @return mixed
	*/
	protected function shiftWhitespaceToken( ezcDocumentBBCodeToken $token, array &$tokens )
	{
	if ( isset( $this->documentStack[0] ) &&
	( !$this->documentStack[0] instanceof ezcDocumentBBCodeBlockLevelNode ) )
	{
	/* DEBUG
	echo " - Shift whitespace text node.\n";
	// /DEBUG */
	return new ezcDocumentBBCodeTextNode( $token );
	}

	/* DEBUG
	echo " - Ignore whitespace node.\n";
	// /DEBUG */
	return null;
	}

	/**
	* Shift text token.
	*
	* @param ezcDocumentBBCodeToken $token
	* @param array $tokens
	* @return mixed
	*/
	protected function shiftTextToken( ezcDocumentBBCodeToken $token, array &$tokens )
	{
	/* DEBUG
	echo " - Shift text node.\n";
	// /DEBUG */
	return new ezcDocumentBBCodeTextNode( $token );
	}

	/**
	* Shift literal block token
	*
	* Literal blocks are just a chunk of code or similar, where the token can
	* jsut be converted into an apropriate node.
	*
	* @param ezcDocumentBBCodeToken $token
	* @param array $tokens
	* @return mixed
	*/
	protected function shiftLiteralBlockToken( ezcDocumentBBCodeToken $token, array &$tokens )
	{
	if ( isset( $this->documentStack[0] ) &&
	( $this->documentStack[0] instanceof ezcDocumentBBCodeParagraphNode ) &&
	isset( $tokens[0] ) &&
	( $tokens[0] instanceof ezcDocumentBBCodeNewLineToken ) )
	{
	// Remove following new line tokens.
	do {
	array_shift( $tokens );
	} while ( isset( $tokens[0] ) &&
	( ( $tokens[0] instanceof ezcDocumentBBCodeNewlineToken ) \|\|
	( $tokens[0] instanceof ezcDocumentBBCodeWhitespaceToken ) ) );

	/* DEBUG
	echo " - Shift literal block node.\n";
	// /DEBUG */
	return new ezcDocumentBBCodeLiteralBlockNode( $token );
	}
	else
	{
	/* DEBUG
	echo " - Shift inline literal node.\n";
	// /DEBUG */
	return new ezcDocumentBBCodeInlineLiteralNode( $token );
	}
	}

	/**
	* Shift new line token.
	*
	* Double new lines are considered as paragraphs. All other new lines are
	* just shifted as single whitespace text nodes.
	*
	* @param ezcDocumentBBCodeToken $token
	* @param array $tokens
	* @return mixed
	*/
	protected function shiftNewLineToken( ezcDocumentBBCodeToken $token, array &$tokens )
	{
	while ( isset( $tokens[0] ) &&
	( $tokens[0] instanceof ezcDocumentBBCodeWhitespaceToken ) )
	{
	array_shift( $tokens );
	}

	if ( isset( $tokens[0] ) &&
	( $tokens[0] instanceof ezcDocumentBBCodeNewlineToken ) )
	{
	do {
	array_shift( $tokens );
	} while ( isset( $tokens[0] ) &&
	( ( $tokens[0] instanceof ezcDocumentBBCodeNewlineToken ) \|\|
	( $tokens[0] instanceof ezcDocumentBBCodeWhitespaceToken ) ) );
	/* DEBUG
	echo " - Shift paragraph node.\n";
	// /DEBUG */
	return new ezcDocumentBBCodeParagraphNode( $token );
	}
	elseif ( isset( $this->documentStack[0] ) &&
	( !$this->documentStack[0] instanceof ezcDocumentBBCodeBlockLevelNode ) )
	{
	/* DEBUG
	echo " - Shift newline as whitespace node.\n";
	// /DEBUG */
	return new ezcDocumentBBCodeTextNode( $token );
	}

	/* DEBUG
	echo " - Ignore whitespace node.\n";
	// /DEBUG */
	return null;
	}

	/**
	* Shift EOF token.
	*
	* Shift End-Of-File token. We reached the end of the document, and
	* therefore shift a document node onto the stack.
	*
	* @param ezcDocumentBBCodeToken $token
	* @param array $tokens
	* @return mixed
	*/
	protected function shiftEndOfFileToken( ezcDocumentBBCodeToken $token, array &$tokens )
	{
	/* DEBUG
	echo " - Shift document node.\n";
	// /DEBUG */
	return new ezcDocumentBBCodeDocumentNode( $token );
	}

	/**
	* Reduce tags.
	*
	* Locates the matching opening tag for a closing tag and reduces the
	* contents found on the way back.
	*
	* @param ezcDocumentBBCodeClosingTagNode $node
	* @return mixed
	*/
	protected function reduceTags( ezcDocumentBBCodeClosingTagNode $node )
	{
	$nodes = array();
	while ( isset( $this->documentStack[0] ) &&
	( ( !$this->documentStack[0] instanceof ezcDocumentBBCodeTagNode ) \|\|
	( $this->documentStack[0]->token->content !== $node->token->content ) ) )
	{
	$nodes[] = $child = array_shift( $this->documentStack );

	if ( ( $child instanceof ezcDocumentBBCodeTagNode ) &&
	( !count( $child->nodes ) ) )
	{
	return $this->triggerError( E_PARSE,
	"Opening tag, without matching closing tag found: '" . $child->token->content . "'.",
	$child->token->line, $child->token->position
	);
	}

	if ( $child instanceof ezcDocumentBBCodeClosingTagNode )
	{
	return $this->triggerError( E_PARSE,
	"Closing tag, without matching opening tag found: '" . $child->token->content . "'.",
	$child->token->line, $child->token->position
	);
	}
	}

	if ( ( !$this->documentStack[0] instanceof ezcDocumentBBCodeTagNode ) \|\|
	( $this->documentStack[0]->token->content !== $node->token->content ) )
	{
	return $this->triggerError( E_PARSE,
	"Closing tag, without matching opening tag found: '" . $node->token->content . "'.",
	$node->token->line, $node->token->position
	);
	}

	$node = array_shift( $this->documentStack );
	$node->nodes = array_reverse( $nodes );
	return $node;
	}

	/**
	* Reduce list items.
	*
	* Aggregates list items and puts them into a found list.
	*
	* @param ezcDocumentBBCodeParagraphNode $node
	* @return mixed
	*/
	protected function reduceListItem( ezcDocumentBBCodeNode $node )
	{
	$nodes = array();
	while ( isset( $this->documentStack[0] ) &&
	( !$this->documentStack[0] instanceof ezcDocumentBBCodeListItemNode ) &&
	( ( !$this->documentStack[0] instanceof ezcDocumentBBCodeListNode ) \|\|
	( ( $this->documentStack[0] instanceof ezcDocumentBBCodeListNode ) &&
	( count( $this->documentStack[0]->nodes ) ) ) ) )
	{
	$nodes[] = $child = array_shift( $this->documentStack );

	if ( ( $child instanceof ezcDocumentBBCodeTagNode ) &&
	( !count( $child->nodes ) ) )
	{
	return $this->triggerError( E_PARSE,
	"Opening tag, without matching closing tag found: '" . $child->token->content . "'.",
	$child->token->line, $child->token->position
	);
	}

	if ( $child instanceof ezcDocumentBBCodeClosingTagNode )
	{
	return $this->triggerError( E_PARSE,
	"Closing tag, without matching opening tag found: '" . $child->token->content . "'.",
	$child->token->line, $child->token->position
	);
	}
	}

	if ( !isset( $this->documentStack[0] ) )
	{
	return $this->triggerError( E_PARSE,
	"Missing list item node.",
	$child->token->line, $child->token->position
	);
	}

	// Wrap non-block-level nodes into paragraphs
	$wrapped = array();
	$temp = array();
	foreach ( $nodes as $child )
	{
	if ( !$child instanceof ezcDocumentBBCodeBlockLevelNode )
	{
	$temp[] = $child;
	}
	elseif ( count( $temp ) )
	{
	$wrapped[] = $para = new ezcDocumentBBCodeParagraphNode( $temp[0]->token );
	$para->nodes = array_reverse( $temp );
	$temp = array();
	$wrapped[] = $child;
	}
	else
	{
	$wrapped[] = $child;
	}
	}

	if ( count( $temp ) )
	{
	$wrapped[] = $para = new ezcDocumentBBCodeParagraphNode( $temp[0]->token );
	$para->nodes = array_reverse( $temp );
	}

	if ( $this->documentStack[0] instanceof ezcDocumentBBCodeListItemNode )
	{
	$this->documentStack[0]->nodes = array_reverse( $wrapped );
	}

	return $node;
	}

	/**
	* Reduce list.
	*
	* Aggregates list items and puts them into a found list.
	*
	* @param ezcDocumentBBCodeParagraphNode $node
	* @return mixed
	*/
	protected function reduceList( ezcDocumentBBCodeNode $node )
	{
	$this->reduceListItem( $node );

	$nodes = array();
	while ( isset( $this->documentStack[0] ) &&
	( $this->documentStack[0] instanceof ezcDocumentBBCodeListItemNode ) )
	{
	$nodes[] = array_shift( $this->documentStack );
	}

	if ( !isset( $this->documentStack[0] ) \|\|
	( !$this->documentStack[0] instanceof ezcDocumentBBCodeListNode ) )
	{
	return $this->triggerError( E_PARSE,
	"Missing list start node.",
	$child->token->line, $child->token->position
	);
	}

	$this->documentStack[0]->nodes = array_reverse( $nodes );
	return null;
	}

	/**
	* Reduce paragraph.
	*
	* Paragraphs are reduce with all inline tokens, which have been added to
	* the document stack before. If there are no inline nodes, the paragraph
	* will be ommitted.
	*
	* @param ezcDocumentBBCodeParagraphNode $node
	* @return mixed
	*/
	protected function reduceParagraph( ezcDocumentBBCodeParagraphNode $node )
	{
	$nodes = array();
	while ( isset( $this->documentStack[0] ) &&
	( !$this->documentStack[0] instanceof ezcDocumentBBCodeParagraphNode ) &&
	( !$this->documentStack[0] instanceof ezcDocumentBBCodeListNode ) &&
	( !$this->documentStack[0] instanceof ezcDocumentBBCodeLiteralBlockNode ) )
	{
	$nodes[] = $child = array_shift( $this->documentStack );

	if ( ( $child instanceof ezcDocumentBBCodeTagNode ) &&
	( !count( $child->nodes ) ) )
	{
	return $this->triggerError( E_PARSE,
	"Opening tag, without matching closing tag found: '" . $child->token->content . "'.",
	$child->token->line, $child->token->position
	);
	}

	if ( $child instanceof ezcDocumentBBCodeClosingTagNode )
	{
	return $this->triggerError( E_PARSE,
	"Closing tag, without matching opening tag found: '" . $child->token->content . "'.",
	$child->token->line, $child->token->position
	);
	}
	}

	// Omit empty paragraphs
	if ( !count( $nodes ) )
	{
	return null;
	}

	$node->nodes = array_reverse( $nodes );
	return $node;
	}

	/**
	* Reduce prior sections, if a new section has been found.
	*
	* If a new section has been found all sections with a higher depth level
	* can be closed, and all items fitting into sections may be aggregated by
	* the respective sections as well.
	*
	* @param ezcDocumentBBCodeDocumentNode $node
	*/
	protected function reduceDocument( ezcDocumentBBCodeDocumentNode $node )
	{
	$nodes = array();
	while ( isset( $this->documentStack[0] ) &&
	( ( $this->documentStack[0] instanceof ezcDocumentBBCodeParagraphNode ) \|\|
	( $this->documentStack[0] instanceof ezcDocumentBBCodeListNode ) \|\|
	( $this->documentStack[0] instanceof ezcDocumentBBCodeLiteralBlockNode ) ) )
	{
	$nodes[] = array_shift( $this->documentStack );
	}
	$node->nodes = array_reverse( $nodes );

	return $node;
	}
	}

	?>