Add template tag support

Author: Kirill Nesmeyanov

src/DocBlock/Extractor/TagTypeExtractor.php

@@ -50,6 +50,18 @@ public function extractTypeOrMixed(string $body): array
         }
     }
 
+    /**
+     * @return array{TypeStatement|null, non-empty-string|null}
+     */
+    public function extractTypeOrNull(string $body): array
+    {
+        try {
+            return $this->extractTypeOrFail($body);
+        } catch (InvalidTagTypeException) {
+            return [null, $body ?: null];
+        }
+    }
+
     protected function createMixedType(): NamedTypeNode
     {
         return self::$mixed ??= new NamedTypeNode(

src/DocBlock/Tag/InvalidTag.php

@@ -7,4 +7,21 @@
 /**
  * This tag is created if a parsing error occurs while parsing the original tag.
  */
-final class InvalidTag extends Tag implements InvalidTagInterface {}
+final class InvalidTag extends Tag implements InvalidTagInterface
+{
+    /**
+     * @param non-empty-string $name
+     */
+    public function __construct(
+        string $name,
+        private readonly \Throwable $reason,
+        \Stringable|string|null $description = null,
+    ) {
+        parent::__construct($name, $description);
+    }
+
+    public function getReason(): \Throwable
+    {
+        return $this->reason;
+    }
+}

src/DocBlock/Tag/InvalidTagInterface.php

@@ -8,4 +8,10 @@
  * Marks all tags that were not correctly recognized by the parser or for
  * some other reason were not processed and classified.
  */
-interface InvalidTagInterface extends TagInterface {}
+interface InvalidTagInterface extends TagInterface
+{
+    /**
+     * Returns {@see InvalidTagInterface} invalid tag creation reason.
+     */
+    public function getReason(): \Throwable;
+}

src/DocBlock/Tag/InvalidTypedTag.php

@@ -10,4 +10,22 @@
  * This tag is created if a parsing error occurs while parsing the original
  * tag that contain {@see TypeStatement} reference.
  */
-final class InvalidTypedTag extends TypedTag implements InvalidTagInterface {}
+final class InvalidTypedTag extends TypedTag implements InvalidTagInterface
+{
+    /**
+     * @param non-empty-string $name
+     */
+    public function __construct(
+        string $name,
+        TypeStatement $type,
+        private readonly \Throwable $reason,
+        \Stringable|string|null $description = null
+    ) {
+        parent::__construct($name, $type, $description);
+    }
+
+    public function getReason(): \Throwable
+    {
+        return $this->reason;
+    }
+}

src/DocBlock/Tag/OptionalTypeProviderInterface.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PhpDocParser\DocBlock\Tag;
+
+use TypeLang\Parser\Node\Stmt\TypeStatement;
+
+interface OptionalTypeProviderInterface extends TagInterface
+{
+    /**
+     * @psalm-immutable
+     */
+    public function getType(): ?TypeStatement;
+}

src/DocBlock/Tag/TemplateTag.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PhpDocParser\DocBlock\Tag;
+
+use TypeLang\Parser\Node\Stmt\TypeStatement;
+
+final class TemplateTag extends Tag implements OptionalTypeProviderInterface
+{
+    /**
+     * @param non-empty-string $typeName
+     * @param TypeStatement|null $type
+     * @param \Stringable|string|null $description
+     */
+    public function __construct(
+        private readonly string $typeName,
+        private readonly ?TypeStatement $type = null,
+        \Stringable|string|null $description = null
+    ) {
+        parent::__construct('template', $description);
+    }
+
+    /**
+     * @return non-empty-string
+     */
+    public function getTypeName(): string
+    {
+        return $this->typeName;
+    }
+
+    public function getType(): ?TypeStatement
+    {
+        return $this->type;
+    }
+
+    /**
+     * @psalm-immutable
+     */
+    public function __toString(): string
+    {
+        if ($this->type === null) {
+            return \rtrim(\vsprintf('@%s %s %s', [
+                $this->name,
+                $this->typeName,
+                (string)$this->description,
+            ]));
+        }
+
+        return \rtrim(\vsprintf('@%s %s of %s %s', [
+            $this->name,
+            $this->typeName,
+            TypedTag::getTypeAsString($this->type),
+            (string)$this->description,
+        ]));
+    }
+}

src/DocBlock/Tag/TypeProviderInterface.php

@@ -6,7 +6,7 @@
 
 use TypeLang\Parser\Node\Stmt\TypeStatement;
 
-interface TypeProviderInterface extends TagInterface
+interface TypeProviderInterface extends OptionalTypeProviderInterface
 {
     /**
      * @psalm-immutable

src/DocBlock/Tag/TypedTag.php

@@ -27,25 +27,30 @@ public function getType(): TypeStatement
     }
 
     /**
-     * @psalm-immutable
+     * @return non-empty-string
      */
-    public function __toString(): string
+    public static function getTypeAsString(TypeStatement $type): string
     {
-        $type = $this->type::class;
+        if (\class_exists(PrettyPrinter::class)) {
+            return (new PrettyPrinter())->print($type);
+        }
 
         /** @psalm-suppress UndefinedPropertyFetch : Psalm false-positive */
-        if (\property_exists($this->type, 'name')
-            && $this->type->name instanceof Name) {
-            $type = (string)$this->type->name;
+        if (\property_exists($type, 'name') && $type->name instanceof Name) {
+            return (string)$type->name;
         }
 
-        if (\class_exists(PrettyPrinter::class)) {
-            $type = (new PrettyPrinter())->print($this->type);
-        }
+        return $type::class;
+    }
 
+    /**
+     * @psalm-immutable
+     */
+    public function __toString(): string
+    {
         return \rtrim(\vsprintf('@%s %s %s', [
             $this->name,
-            $type,
+            self::getTypeAsString($this->type),
             (string)$this->description,
         ]));
     }

src/DocBlock/TagFactory/TemplateTagFactory.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PhpDocParser\DocBlock\TagFactory;
+
+use TypeLang\PhpDocParser\DocBlock\Tag\TemplateTag;
+
+/**
+ * @template-extends TypedTagFactory<TemplateTag>
+ */
+final class TemplateTagFactory extends TypedTagFactory
+{
+    public function create(string $tag): TemplateTag
+    {
+        if (\trim($tag) === '') {
+            throw new \InvalidArgumentException('Template parameter name required');
+        }
+
+        $suffix = \strpbrk($tag, " \t\n\r\0\x0B");
+
+        if ($suffix === false) {
+            return new TemplateTag($tag);
+        }
+
+        $typeName = \substr($tag, 0, -\strlen($suffix));
+
+        \preg_match('/^\s+of\s+(.+?)$/isum', $suffix, $matches);
+
+        if ($matches === []) {
+            return new TemplateTag(
+                typeName: $typeName,
+                description: $this->createDescription($suffix),
+            );
+        }
+
+        [$type, $description] = $this->types->extractTypeOrNull($matches[1]);
+
+        return new TemplateTag(
+            typeName: $typeName,
+            type: $type,
+            description: $this->createDescription($description),
+        );
+    }
+}

src/DocBlock/TagFactorySelector.php

@@ -66,12 +66,12 @@ public function create(string $tag): TagInterface
                 $body = $this->createDescription(\substr($body, $e->getTypeOffset()));
 
                 if ($type === null) {
-                    return new InvalidTag($name, $body);
+                    return new InvalidTag($name, $e, $body);
                 }
 
-                return new InvalidTypedTag($name, $type, $body);
-            } catch (\InvalidArgumentException) {
-                return new InvalidTag($name, $this->createDescription($body));
+                return new InvalidTypedTag($name, $type, $e, $body);
+            } catch (\InvalidArgumentException $e) {
+                return new InvalidTag($name, $e, $this->createDescription($body));
             }
         }