354 lines
9.5 KiB
PHP
354 lines
9.5 KiB
PHP
|
<?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-2011 Squiz Pty Ltd (ABN 77 084 670 600)
|
||
|
* @license http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence
|
||
|
* @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-2011 Squiz Pty Ltd (ABN 77 084 670 600)
|
||
|
* @license http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence
|
||
|
* @version Release: 1.3.3
|
||
|
* @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 comment tokens.
|
||
|
*
|
||
|
* @return array
|
||
|
*/
|
||
|
public function getTokens()
|
||
|
{
|
||
|
return $this->tokens;
|
||
|
|
||
|
}//end getTokens()
|
||
|
|
||
|
|
||
|
/**
|
||
|
* 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
|
||
|
|
||
|
?>
|