diff --git a/src/phpDocumentor/Reflection/DocBlock/Tag.php b/src/phpDocumentor/Reflection/DocBlock/Tag.php index a628f20..df86428 100644 --- a/src/phpDocumentor/Reflection/DocBlock/Tag.php +++ b/src/phpDocumentor/Reflection/DocBlock/Tag.php @@ -53,6 +53,8 @@ class Tag implements \Reflector => '\phpDocumentor\Reflection\DocBlock\Tag\CoversTag', 'deprecated' => '\phpDocumentor\Reflection\DocBlock\Tag\DeprecatedTag', + 'example' + => '\phpDocumentor\Reflection\DocBlock\Tag\ExampleTag', 'link' => '\phpDocumentor\Reflection\DocBlock\Tag\LinkTag', 'method' @@ -71,6 +73,8 @@ class Tag implements \Reflector => '\phpDocumentor\Reflection\DocBlock\Tag\SeeTag', 'since' => '\phpDocumentor\Reflection\DocBlock\Tag\SinceTag', + 'source' + => '\phpDocumentor\Reflection\DocBlock\Tag\SourceTag', 'throw' => '\phpDocumentor\Reflection\DocBlock\Tag\ThrowsTag', 'throws' diff --git a/src/phpDocumentor/Reflection/DocBlock/Tag/ExampleTag.php b/src/phpDocumentor/Reflection/DocBlock/Tag/ExampleTag.php new file mode 100644 index 0000000..603b016 --- /dev/null +++ b/src/phpDocumentor/Reflection/DocBlock/Tag/ExampleTag.php @@ -0,0 +1,76 @@ + + * @copyright 2010-2011 Mike van Riel / Naenius (http://www.naenius.com) + * @license http://www.opensource.org/licenses/mit-license.php MIT + * @link http://phpdoc.org + */ + +namespace phpDocumentor\Reflection\DocBlock\Tag; + +use phpDocumentor\Reflection\DocBlock; +use phpDocumentor\Reflection\DocBlock\Tag; + +/** + * Reflection class for a @example tag in a Docblock. + * + * @author Vasil Rangelov + * @license http://www.opensource.org/licenses/mit-license.php MIT + * @link http://phpdoc.org + */ +class ExampleTag extends SourceTag +{ + /** @var string Path to a file to use as an example. Can also be an URI. */ + protected $filePath = ''; + + /** + * Parses a tag and populates the member variables. + * + * @param string $type Tag identifier for this tag (should be 'example'). + * @param string $content Contents for this tag. + * @param DocBlock $docblock The DocBlock which this tag belongs to. + */ + public function __construct($type, $content, DocBlock $docblock = null) + { + Tag::__construct($type, $content, $docblock); + if (preg_match( + '/^(?:\"([^\"]+)\"|(\S+))(?:\s+(.*))?$/su', + $this->description, + $matches + )) { + if ('' !== $matches[1]) { + //Quoted file path. + $this->filePath = trim($matches[1]); + } elseif (false === strpos($matches[2], ':')) { + //Relative URL or a file path with no spaces in it. + $this->filePath = rawurldecode( + str_replace(array('/', '\\'), '%2F', $matches[2]) + ); + } else { + //Absolute URL or URI. + $this->filePath = $matches[2]; + } + + if (isset($matches[3])) { + parent::__construct($type, $matches[3]); + $this->content = $content; + } else { + $this->description = ''; + } + } + } + + /** + * Returns the file path. + * + * @return string Path to a file to use as an example. Can also be an URI. + */ + public function getFilePath() + { + return $this->filePath; + } +} diff --git a/src/phpDocumentor/Reflection/DocBlock/Tag/SourceTag.php b/src/phpDocumentor/Reflection/DocBlock/Tag/SourceTag.php new file mode 100644 index 0000000..09b4612 --- /dev/null +++ b/src/phpDocumentor/Reflection/DocBlock/Tag/SourceTag.php @@ -0,0 +1,83 @@ + + * @copyright 2010-2011 Mike van Riel / Naenius (http://www.naenius.com) + * @license http://www.opensource.org/licenses/mit-license.php MIT + * @link http://phpdoc.org + */ + +namespace phpDocumentor\Reflection\DocBlock\Tag; + +use phpDocumentor\Reflection\DocBlock\Tag; + +/** + * Reflection class for a @source tag in a Docblock. + * + * @author Vasil Rangelov + * @license http://www.opensource.org/licenses/mit-license.php MIT + * @link http://phpdoc.org + */ +class SourceTag extends Tag +{ + /** + * @var int The starting line, relative to the structural element's + * location. + */ + protected $startingLine = 1; + + /** + * @var int|null The number of lines, relative to the starting line. NULL + * means "to the end". + */ + protected $lineCount = null; + + /** + * Parses a tag and populates the member variables. + * + * @param string $type Tag identifier for this tag (should be 'source'). + * @param string $content Contents for this tag. + * @param DocBlock $docblock The DocBlock which this tag belongs to. + */ + public function __construct($type, $content, DocBlock $docblock = null) + { + parent::__construct($type, $content, $docblock); + $content = preg_split('/[\ \t]+/u', $this->description, 2); + if (preg_match( + '/^([1-9]\d*)\s*(?:([1-9]\d*)\s+)?(.*)$/su', + $this->description, + $matches + )) { + $this->startingLine = (int)$matches[1]; + if (isset($matches[2]) && '' !== $matches[2]) { + $this->lineCount = (int)$matches[2]; + } + $this->description = $matches[3]; + } + } + + /** + * Returns the starting line. + * + * @return int The starting line, relative to the structural element's + * location. + */ + public function getStartingLine() + { + return $this->startingLine; + } + + /** + * Returns the number of lines. + * + * @return int|null The number of lines, relative to the starting line. NULL + * means "to the end". + */ + public function getLineCount() + { + return $this->lineCount; + } +} diff --git a/tests/phpDocumentor/Reflection/DocBlock/Tag/ExampleTagTest.php b/tests/phpDocumentor/Reflection/DocBlock/Tag/ExampleTagTest.php new file mode 100644 index 0000000..5d20100 --- /dev/null +++ b/tests/phpDocumentor/Reflection/DocBlock/Tag/ExampleTagTest.php @@ -0,0 +1,198 @@ + + * @copyright 2010-2011 Mike van Riel / Naenius. (http://www.naenius.com) + * @license http://www.opensource.org/licenses/mit-license.php MIT + * @link http://phpdoc.org + */ + +namespace phpDocumentor\Reflection\DocBlock\Tag; + +/** + * Test class for \phpDocumentor\Reflection\DocBlock\Tag\ExampleTag + * + * @author Vasil Rangelov + * @copyright 2010-2011 Mike van Riel / Naenius. (http://www.naenius.com) + * @license http://www.opensource.org/licenses/mit-license.php MIT + * @link http://phpdoc.org + */ +class ExampleTagTest extends \PHPUnit_Framework_TestCase +{ + /** + * Test that the \phpDocumentor\Reflection\DocBlock\Tag\SourceTag can + * understand the @source DocBlock. + * + * @param string $type + * @param string $content + * @param string $exContent + * @param string $exStartingLine + * @param string $exLineCount + * @param string $exFilepath + * + * @covers \phpDocumentor\Reflection\DocBlock\Tag\ExampleTag::__construct + * @covers \phpDocumentor\Reflection\DocBlock\Tag\ExampleTag::getFilePath + * @dataProvider provideDataForConstuctor + * + * @return void + */ + public function testConstructorParesInputsIntoCorrectFields( + $type, + $content, + $exContent, + $exDescription, + $exStartingLine, + $exLineCount, + $exFilePath + ) { + $tag = new ExampleTag($type, $content); + + $this->assertEquals($type, $tag->getName()); + $this->assertEquals($exContent, $tag->getContent()); + $this->assertEquals($exDescription, $tag->getDescription()); + $this->assertEquals($exStartingLine, $tag->getStartingLine()); + $this->assertEquals($exLineCount, $tag->getLineCount()); + $this->assertEquals($exFilePath, $tag->getFilePath()); + } + + /** + * Data provider for testConstructorParesInputsIntoCorrectFields + * + * @return array + */ + public function provideDataForConstuctor() + { + // $type, $content, $exContent, $exDescription, $exStartingLine, $exLineCount, $exFilePath + return array( + array( + 'example', + 'file.php', + 'file.php', + '', + 1, + null, + 'file.php' + ), + array( + 'example', + 'Testing comments', + 'Testing comments', + 'comments', + 1, + null, + 'Testing' + ), + array( + 'example', + 'file.php 2 Testing', + 'file.php 2 Testing', + 'Testing', + 2, + null, + 'file.php' + ), + array( + 'example', + 'file.php 2 3 Testing comments', + 'file.php 2 3 Testing comments', + 'Testing comments', + 2, + 3, + 'file.php' + ), + array( + 'example', + 'file.php 2 -1 Testing comments', + 'file.php 2 -1 Testing comments', + '-1 Testing comments', + 2, + null, + 'file.php' + ), + array( + 'example', + 'file.php -1 1 Testing comments', + 'file.php -1 1 Testing comments', + '-1 1 Testing comments', + 1, + null, + 'file.php' + ), + array( + 'example', + '"file with spaces.php" Testing comments', + '"file with spaces.php" Testing comments', + 'Testing comments', + 1, + null, + 'file with spaces.php' + ), + array( + 'example', + '"file with spaces.php" 2 Testing comments', + '"file with spaces.php" 2 Testing comments', + 'Testing comments', + 2, + null, + 'file with spaces.php' + ), + array( + 'example', + '"file with spaces.php" 2 3 Testing comments', + '"file with spaces.php" 2 3 Testing comments', + 'Testing comments', + 2, + 3, + 'file with spaces.php' + ), + array( + 'example', + '"file with spaces.php" 2 -3 Testing comments', + '"file with spaces.php" 2 -3 Testing comments', + '-3 Testing comments', + 2, + null, + 'file with spaces.php' + ), + array( + 'example', + '"file with spaces.php" -2 3 Testing comments', + '"file with spaces.php" -2 3 Testing comments', + '-2 3 Testing comments', + 1, + null, + 'file with spaces.php' + ), + array( + 'example', + 'file%20with%20spaces.php Testing comments', + 'file%20with%20spaces.php Testing comments', + 'Testing comments', + 1, + null, + 'file with spaces.php' + ), + array( + 'example', + 'folder/file%20with%20spaces.php Testing comments', + 'folder/file%20with%20spaces.php Testing comments', + 'Testing comments', + 1, + null, + 'folder/file with spaces.php' + ), + array( + 'example', + 'http://example.com/file%20with%20spaces.php Testing comments', + 'http://example.com/file%20with%20spaces.php Testing comments', + 'Testing comments', + 1, + null, + 'http://example.com/file%20with%20spaces.php' + ) + ); + } +} diff --git a/tests/phpDocumentor/Reflection/DocBlock/Tag/SourceTagTest.php b/tests/phpDocumentor/Reflection/DocBlock/Tag/SourceTagTest.php new file mode 100644 index 0000000..fa77057 --- /dev/null +++ b/tests/phpDocumentor/Reflection/DocBlock/Tag/SourceTagTest.php @@ -0,0 +1,118 @@ + + * @copyright 2010-2011 Mike van Riel / Naenius. (http://www.naenius.com) + * @license http://www.opensource.org/licenses/mit-license.php MIT + * @link http://phpdoc.org + */ + +namespace phpDocumentor\Reflection\DocBlock\Tag; + +/** + * Test class for \phpDocumentor\Reflection\DocBlock\Tag\SourceTag + * + * @author Vasil Rangelov + * @copyright 2010-2011 Mike van Riel / Naenius. (http://www.naenius.com) + * @license http://www.opensource.org/licenses/mit-license.php MIT + * @link http://phpdoc.org + */ +class SourceTagTest extends \PHPUnit_Framework_TestCase +{ + /** + * Test that the \phpDocumentor\Reflection\DocBlock\Tag\SourceTag can + * understand the @source DocBlock. + * + * @param string $type + * @param string $content + * @param string $exContent + * @param string $exStartingLine + * @param string $exLineCount + * + * @covers \phpDocumentor\Reflection\DocBlock\Tag\SourceTag::__construct + * @covers \phpDocumentor\Reflection\DocBlock\Tag\SourceTag::getStartingLine + * @covers \phpDocumentor\Reflection\DocBlock\Tag\SourceTag::getLineCount + * @dataProvider provideDataForConstuctor + * + * @return void + */ + public function testConstructorParesInputsIntoCorrectFields( + $type, + $content, + $exContent, + $exDescription, + $exStartingLine, + $exLineCount + ) { + $tag = new SourceTag($type, $content); + + $this->assertEquals($type, $tag->getName()); + $this->assertEquals($exContent, $tag->getContent()); + $this->assertEquals($exDescription, $tag->getDescription()); + $this->assertEquals($exStartingLine, $tag->getStartingLine()); + $this->assertEquals($exLineCount, $tag->getLineCount()); + } + + /** + * Data provider for testConstructorParesInputsIntoCorrectFields + * + * @return array + */ + public function provideDataForConstuctor() + { + // $type, $content, $exContent, $exDescription, $exStartingLine, $exLineCount + return array( + array( + 'source', + '2', + '2', + '', + 2, + null + ), + array( + 'source', + 'Testing', + 'Testing', + 'Testing', + 1, + null + ), + array( + 'source', + '2 Testing', + '2 Testing', + 'Testing', + 2, + null + ), + array( + 'source', + '2 3 Testing comments', + '2 3 Testing comments', + 'Testing comments', + 2, + 3 + ), + array( + 'source', + '2 -1 Testing comments', + '2 -1 Testing comments', + '-1 Testing comments', + 2, + null + ), + array( + 'source', + '-1 1 Testing comments', + '-1 1 Testing comments', + '-1 1 Testing comments', + 1, + null + ) + ); + } +}