Merge pull request #12 from boenrobot/source-and-example

Reflections for @source and @example

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'

src/phpDocumentor/Reflection/DocBlock/Tag/ExampleTag.php

@@ -0,0 +1,76 @@
+<?php
+/**
+ * phpDocumentor
+ *
+ * PHP Version 5.3
+ *
+ * @author    Vasil Rangelov <[email protected]>
+ * @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 <[email protected]>
+ * @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;
+    }
+}

src/phpDocumentor/Reflection/DocBlock/Tag/SourceTag.php

@@ -0,0 +1,83 @@
+<?php
+/**
+ * phpDocumentor
+ *
+ * PHP Version 5.3
+ *
+ * @author    Vasil Rangelov <[email protected]>
+ * @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 <[email protected]>
+ * @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;
+    }
+}

tests/phpDocumentor/Reflection/DocBlock/Tag/ExampleTagTest.php

@@ -0,0 +1,198 @@
+<?php
+/**
+ * phpDocumentor Example Tag Test
+ * 
+ * PHP version 5.3
+ *
+ * @author    Vasil Rangelov <[email protected]>
+ * @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 <[email protected]>
+ * @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'
+            )
+        );
+    }
+}

tests/phpDocumentor/Reflection/DocBlock/Tag/SourceTagTest.php

@@ -0,0 +1,118 @@
+<?php
+/**
+ * phpDocumentor Source Tag Test
+ * 
+ * PHP version 5.3
+ *
+ * @author    Vasil Rangelov <[email protected]>
+ * @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 <[email protected]>
+ * @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
+            )
+        );
+    }
+}