Subversion Repositories Applications.framework

<?php

/**

 * A class to handle most of the parsing operations of a doc comment element.

 *

 * PHP version 5

 *

 * @category  PHP

 * @package   PHP_CodeSniffer

 * @author    Greg Sherwood <gsherwood@squiz.net>

 * @author    Marc McIntyre <mmcintyre@squiz.net>

 * @copyright 2006 Squiz Pty Ltd (ABN 77 084 670 600)

 * @license   http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence

 * @version   CVS: $Id: AbstractDocElement.php,v 1.11 2008/12/02 02:38:33 squiz Exp $

 * @link      http://pear.php.net/package/PHP_CodeSniffer

 */

if (interface_exists('PHP_CodeSniffer_CommentParser_DocElement', true) === false) {

    $error = 'Interface PHP_CodeSniffer_CommentParser_DocElement not found';

    throw new PHP_CodeSniffer_Exception($error);

}

/**

 * A class to handle most of the parsing operations of a doc comment element.

 *

 * Extending classes should implement the getSubElements method to return

 * a list of elements that the doc comment element contains, in the order that

 * they appear in the element. For example a function parameter element has a

 * type, a variable name and a comment. It should therefore implement the method

 * as follows:

 *

 * <code>

 *    protected function getSubElements()

 *    {

 *        return array(

 *                'type',

 *                'variable',

 *                'comment',

 *               );

 *    }

 * </code>

 *

 * The processSubElement will be called for each of the sub elements to allow

 * the extending class to process them. So for the parameter element we would

 * have:

 *

 * <code>

 *    protected function processSubElement($name, $content, $whitespaceBefore)

 *    {

 *        if ($name === 'type') {

 *            echo 'The name of the variable was '.$content;

 *        }

 *        // Process other tags.

 *    }

 * </code>

 *

 * @category  PHP

 * @package   PHP_CodeSniffer

 * @author    Greg Sherwood <gsherwood@squiz.net>

 * @author    Marc McIntyre <mmcintyre@squiz.net>

 * @copyright 2006 Squiz Pty Ltd (ABN 77 084 670 600)

 * @license   http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence

 * @version   Release: 1.2.0RC1

 * @link      http://pear.php.net/package/PHP_CodeSniffer

 */

abstract class PHP_CodeSniffer_CommentParser_AbstractDocElement implements PHP_CodeSniffer_CommentParser_DocElement

{

    /**

     * The element previous to this element.

     *

     * @var PHP_CodeSniffer_CommentParser_DocElement

     */

    protected $previousElement = null;

    /**

     * The element proceeding this element.

     *

     * @var PHP_CodeSniffer_CommentParser_DocElement

     */

    protected $nextElement = null;

    /**

     * The whitespace the occurs after this element and its sub elements.

     *

     * @var string

     */

    protected $afterWhitespace = '';

    /**

     * The tokens that comprise this element.

     *

     * @var array(string)

     */

    protected $tokens = array();

    /**

     * The file this element is in.

     *

     * @var array(string)

     */

    protected $phpcsFile = null;

    /**

     * The tag that this element represents (omiting the @ symbol).

     *

     * @var string

     */

    protected $tag = '';

    /**

     * Constructs a Doc Element.

     *

     * @param PHP_CodeSniffer_CommentParser_DocElement $previousElement The element

     *                                                                  that ocurred

     *                                                                  before this.

     * @param array                                    $tokens          The tokens of

     *                                                                  this element.

     * @param string                                   $tag             The doc

     *                                                                  element tag

     *                                                                  this element

     *                                                                  represents.

     * @param PHP_CodeSniffer_File                     $phpcsFile       The file that

     *                                                                  this element

     *                                                                  is in.

     *

     * @throws Exception If $previousElement in not a DocElement or if

     *                   getSubElements() does not return an array.

     */

    public function __construct(

        $previousElement,

        array $tokens,

        $tag,

        PHP_CodeSniffer_File $phpcsFile

    ) {

        if ($previousElement !== null

            && ($previousElement instanceof PHP_CodeSniffer_CommentParser_DocElement) === false

        ) {

            $error = '$previousElement must be an instance of DocElement';

            throw new Exception($error);

        }

        $this->phpcsFile = $phpcsFile;

        $this->previousElement = $previousElement;

        if ($previousElement !== null) {

            $this->previousElement->nextElement = $this;

        }

        $this->tag    = $tag;

        $this->tokens = $tokens;

        $subElements = $this->getSubElements();

        if (is_array($subElements) === false) {

            throw new Exception('getSubElements() must return an array');

        }

        $whitespace            = '';

        $currElem              = 0;

        $lastElement           = '';

        $lastElementWhitespace = null;

        $numSubElements        = count($subElements);

        foreach ($this->tokens as $token) {

            if (trim($token) === '') {

                $whitespace .= $token;

            } else {

                if ($currElem < ($numSubElements - 1)) {

                    $element = $subElements[$currElem];

                    $this->processSubElement($element, $token, $whitespace);

                    $whitespace = '';

                    $currElem++;

                } else {

                    if ($lastElementWhitespace === null) {

                        $lastElementWhitespace = $whitespace;

                    }

                    $lastElement .= $whitespace.$token;

                    $whitespace   = '';

                }

            }

        }//end foreach

        $lastElement     = ltrim($lastElement);

        $lastElementName = $subElements[($numSubElements - 1)];

        // Process the last element in this tag.

        $this->processSubElement(

            $lastElementName,

            $lastElement,

            $lastElementWhitespace

        );

        $this->afterWhitespace = $whitespace;

    }//end __construct()

    /**

     * Returns the element that exists before this.

     *

     * @return PHP_CodeSniffer_CommentParser_DocElement

     */

    public function getPreviousElement()

    {

        return $this->previousElement;

    }//end getPreviousElement()

    /**

     * Returns the element that exists after this.

     *

     * @return PHP_CodeSniffer_CommentParser_DocElement

     */

    public function getNextElement()

    {

        return $this->nextElement;

    }//end getNextElement()

    /**

     * Returns the whitespace that exists before this element.

     *

     * @return string

     */

    public function getWhitespaceBefore()

    {

        if ($this->previousElement !== null) {

            return $this->previousElement->getWhitespaceAfter();

        }

        return '';

    }//end getWhitespaceBefore()

    /**

     * Returns the whitespace that exists after this element.

     *

     * @return string

     */

    public function getWhitespaceAfter()

    {

        return $this->afterWhitespace;

    }//end getWhitespaceAfter()

    /**

     * Returns the order that this element appears in the comment.

     *

     * @return int

     */

    public function getOrder()

    {

        if ($this->previousElement === null) {

            return 1;

        } else {

            return ($this->previousElement->getOrder() + 1);

        }

    }//end getOrder()

    /**

     * Returns the tag that this element represents, ommiting the @ symbol.

     *

     * @return string

     */

    public function getTag()

    {

        return $this->tag;

    }//end getTag()

    /**

     * Returns the raw content of this element, ommiting the tag.

     *

     * @return string

     */

    public function getRawContent()

    {

        return implode('', $this->tokens);

    }//end getRawContent()

    /**

     * Returns the line in which this element first occured.

     *

     * @return int

     */

    public function getLine()

    {

        if ($this->previousElement === null) {

            // First element is on line one.

            return 1;

        } else {

            $previousContent = $this->previousElement->getRawContent();

            $previousLine    = $this->previousElement->getLine();

            return ($previousLine + substr_count($previousContent, $this->phpcsFile->eolChar));

        }

    }//end getLine()

    /**

     * Returns the sub element names that make up this element in the order they

     * appear in the element.

     *

     * @return array(string)

     * @see processSubElement()

     */

    abstract protected function getSubElements();

    /**

     * Called to process each sub element as sepcified in the return value

     * of getSubElements().

     *

     * @param string $name             The name of the element to process.

     * @param string $content          The content of the the element.

     * @param string $whitespaceBefore The whitespace found before this element.

     *

     * @return void

     * @see getSubElements()

     */

    abstract protected function processSubElement(

        $name,

        $content,

        $whitespaceBefore

    );

}//end class

?>