New Implementation

.php_cs.dist

@@ -4,7 +4,7 @@ $finder = PhpCsFixer\Finder::create()
     ->in('lib')
     ->in('tests')
     ->exclude([
-        'tests/Workspace'
+        'tests/Workspace',
     ])
 ;
 
@@ -13,6 +13,11 @@ return PhpCsFixer\Config::create()
         '@PSR2' => true,
         'no_unused_imports' => true,
         'array_syntax' => ['syntax' => 'short'],
+        'void_return' => true,
+        'ordered_class_elements' => true,
+        'single_quote' => true,
+        'heredoc_indentation' => true,
+        'global_namespace_import' => true,
     ])
     ->setFinder($finder)
 ;

README.md

@@ -1,26 +1,11 @@
 Docblock Parser
 ===============
 
-Sub-standard docblock parser.
+PHP Docblock parser with the following aims:
 
-```php
-$docblock = (new DocblockFactory())->create('/** @var Foobar */');
-$vars = $docblock->tags()->byName('var');
-
-foreach ($vars as $var) {
-    $var->type();
-    $var->varName();
-}
-```
-
-Why?
-----
-
-There is already a [standards-compliant
-library](https://github.com/phpDocumentor/ReflectionDocBlock) for
-PHP-Documentor, however it is coupled to the PHPDocumentor type reflection
-library. This library only cares about parsing docblocks badly for
-[Phpactor](https://github.com/phpactor/phpactor).
+- Fast: has to be fast enough for IDE analysis.
+- Isomorphic: can be transformed back to the original text representation.
+- Positional: the positions of nodes are captured.
 
 Contributing
 ------------

composer.json

@@ -13,11 +13,15 @@
         "php": "^7.3"
     },
     "require-dev": {
+        "phpbench/phpbench": "dev-master",
         "ergebnis/composer-normalize": "^2.0",
         "friendsofphp/php-cs-fixer": "^2.17",
         "phpstan/phpstan": "~0.12.0",
         "phpunit/phpunit": "^9.0",
-        "phpspec/prophecy-phpunit": "^2.0"
+        "phpspec/prophecy-phpunit": "^2.0",
+        "symfony/var-dumper": "^5.2",
+        "phpstan/phpdoc-parser": "^0.4.10",
+        "jetbrains/phpstorm-stubs": "^2020.2"
     },
     "extra": {
         "branch-alias": {
@@ -35,5 +39,12 @@
         }
     },
     "minimum-stability": "dev",
-    "prefer-stable": true
+    "prefer-stable": true,
+    "scripts": {
+        "integrate": [
+            "vendor/bin/phpunit",
+            "vendor/bin/php-cs-fixer fix --allow-risky=yes",
+            "vendor/bin/phpstan analyse"
+        ]
+    }
 }

lib/Ast/Docblock.php

@@ -0,0 +1,75 @@
+<?php
+
+namespace Phpactor\Docblock\Ast;
+
+use Generator;
+
+class Docblock extends Node
+{
+    protected const CHILD_NAMES = [
+        'children'
+    ];
+
+    /**
+     * @var ElementList
+     */
+    public $children = [];
+
+    /**
+     * @param Element[] $children
+     */
+    public function __construct(array $children)
+    {
+        $this->children = new ElementList($children);
+    }
+
+    /**
+     * @param class-string $tagFqn
+     */
+    public function hasTag(string $tagFqn): bool
+    {
+        foreach ($this->tags() as $tag) {
+            if ($tag instanceof $tagFqn) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * @template T
+     * @param class-string<T>|null $tagFqn
+     * @return Generator<T>
+     */
+    public function tags(?string $tagFqn = null): Generator
+    {
+        foreach ($this->children as $child) {
+            if ($tagFqn && $child instanceof $tagFqn) {
+                yield $child;
+                continue;
+            }
+            if (!$tagFqn && $child instanceof TagNode) {
+                yield $child;
+                continue;
+            }
+        }
+    }
+
+    public function prose(): string
+    {
+        return trim(implode('', array_map(function (Element $token): string {
+            if ($token instanceof Token) {
+                if (in_array($token->type, [
+                    Token::T_PHPDOC_OPEN,
+                    Token::T_PHPDOC_CLOSE,
+                    Token::T_PHPDOC_LEADING
+                ])) {
+                    return '';
+                }
+                return $token->value;
+            }
+            return '';
+        }, iterator_to_array($this->children, false))));
+    }
+}

lib/Ast/Element.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Phpactor\Docblock\Ast;
+
+interface Element
+{
+    /**
+     * Return the string aggregation of all tokens in this element
+     */
+    public function toString(): string;
+
+    /**
+     * Return the start byte offset, starting at 0
+     */
+    public function start(): int;
+
+    /**
+     * Return the end byte offset, starting at 0
+     */
+    public function end(): int;
+}

lib/Ast/ElementList.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace Phpactor\Docblock\Ast;
+
+use ArrayIterator;
+use Iterator;
+use IteratorAggregate;
+
+/**
+ * @template T of Element
+ * @implements IteratorAggregate<int,T>
+ */
+class ElementList extends Node implements IteratorAggregate
+{
+    protected const CHILD_NAMES = [
+        'elements',
+    ];
+
+    /**
+     * @var T[]
+     */
+    public $elements;
+
+    /**
+     * @param T[] $elements
+     */
+    public function __construct(array $elements)
+    {
+        $this->elements = $elements;
+    }
+
+    /**
+     * @return ArrayIterator<int,T>
+     */
+    public function getIterator(): Iterator
+    {
+        return new ArrayIterator($this->elements);
+    }
+
+    /**
+     * @return Element[]
+     */
+    public function toArray(): array
+    {
+        return $this->elements;
+    }
+}