Add tag factory support

Author: Kirill Nesmeyanov

src/Factory.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc;
+
+use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
+use TypeLang\PHPDoc\Tag\Tag;
+
+final class Factory implements MutableFactoryInterface
+{
+    /**
+     * @param array<non-empty-string, FactoryInterface> $factories
+     */
+    public function __construct(
+        private array $factories = [],
+    ) {}
+
+    public function add(array|string $tags, FactoryInterface $delegate): void
+    {
+        foreach ((array)$tags as $tag) {
+            $this->factories[$tag] = $delegate;
+        }
+    }
+
+    public function create(string $name, string $content, DescriptionParserInterface $descriptions): Tag
+    {
+        if (($delegate = $this->factories[$name]) !== null) {
+            return $delegate->create($name, $content, $descriptions);
+        }
+
+        return new Tag($name, $descriptions->parse($content));
+    }
+}

src/FactoryInterface.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc;
+
+use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
+use TypeLang\PHPDoc\Tag\Tag;
+
+interface FactoryInterface
+{
+    /**
+     * Returns a tag object with the specified name and description.
+     *
+     * @param non-empty-string $name
+     */
+    public function create(string $name, string $content, DescriptionParserInterface $descriptions): Tag;
+}

src/MutableFactoryInterface.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc;
+
+interface MutableFactoryInterface extends FactoryInterface
+{
+    public function add(string|array $tags, FactoryInterface $delegate): void;
+}

src/Parser.php

@@ -21,11 +21,19 @@
  */
 class Parser implements ParserInterface
 {
+    private readonly CommentParserInterface $comments;
+
+    private readonly DescriptionParserInterface $descriptions;
+
+    private readonly TagParserInterface $tags;
+
     public function __construct(
-        private readonly CommentParserInterface $comments = new RegexCommentParser(),
-        private readonly DescriptionParserInterface $descriptions = new SprintfDescriptionReader(),
-        private readonly TagParserInterface $tags = new TagParser(),
-    ) {}
+        FactoryInterface $tags = new Factory(),
+    ) {
+        $this->tags = new TagParser($tags);
+        $this->descriptions = new SprintfDescriptionReader($this->tags);
+        $this->comments = new RegexCommentParser();
+    }
 
     /**
      * @throws RuntimeExceptionInterface
@@ -75,7 +83,7 @@ private function analyze(string $docblock): \Generator
         foreach ($blocks->getReturn() as $block) {
             try {
                 if ($description === null) {
-                    $description = $this->descriptions->parse($block, $this->tags);
+                    $description = $this->descriptions->parse($block);
                 } else {
                     $tags[] = $this->tags->parse($block, $this->descriptions);
                 }

src/Parser/Description/DescriptionParser.php

@@ -9,16 +9,11 @@
 
 abstract class DescriptionParser implements DescriptionParserInterface
 {
-    public function parse(string $description, TagParserInterface $parser = null): Description
-    {
-        if ($parser === null || $description === '') {
-            return new Description($description);
-        }
-
-        return $this->doParseDescription($description, $parser);
-    }
+    public function __construct(
+        private readonly TagParserInterface $tags,
+    ) {}
 
-    private function doParseDescription(string $description, TagParserInterface $parser): Description
+    public function parse(string $description): Description
     {
         $tags = [];
         $tagIdentifier = 0;
@@ -32,7 +27,7 @@ private function doParseDescription(string $description, TagParserInterface $par
 
             if (\str_starts_with($chunk, '@')) {
                 try {
-                    $tags[] = $parser->parse($chunk, $this);
+                    $tags[] = $this->tags->parse($chunk, $this);
                     $result .= $this->createDescriptionChunkPlaceholder(++$tagIdentifier);
                 } catch (\Throwable) {
                     $result .= "{{$chunk}}";

src/Parser/Description/DescriptionParserInterface.php

@@ -4,7 +4,6 @@
 
 namespace TypeLang\PHPDoc\Parser\Description;
 
-use TypeLang\PHPDoc\Parser\Tag\TagParserInterface;
 use TypeLang\PHPDoc\Tag\Description;
 
 interface DescriptionParserInterface
@@ -26,5 +25,5 @@ interface DescriptionParserInterface
      * // }
      * ```
      */
-    public function parse(string $description, TagParserInterface $parser = null): Description;
+    public function parse(string $description): Description;
 }

src/Parser/Tag/TagParser.php

@@ -5,6 +5,7 @@
 namespace TypeLang\PHPDoc\Parser\Tag;
 
 use TypeLang\PHPDoc\Exception\InvalidTagNameException;
+use TypeLang\PHPDoc\FactoryInterface;
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
 use TypeLang\PHPDoc\Tag\Tag;
 
@@ -15,6 +16,10 @@ final class TagParser implements TagParserInterface
      */
     private const PATTERN_TAG = '\G@[a-zA-Z_\x80-\xff\\\][\w\x80-\xff\-:\\\]*';
 
+    public function __construct(
+        private readonly FactoryInterface $tags,
+    ) {}
+
     /**
      * Read tag name from passed content.
      *
@@ -54,33 +59,17 @@ private function getTagName(string $content): string
     }
 
     /**
-     * @return array{non-empty-string, string}
      * @throws InvalidTagNameException
      */
-    private function getTagParts(string $content): array
+    public function parse(string $tag, DescriptionParserInterface $parser): Tag
     {
-        $name = $this->getTagName($content);
+        $name = $this->getTagName($tag);
         /** @var non-empty-string $name */
         $name = \substr($name, 1);
 
-        $content = \substr($content, \strlen($name) + 1);
+        $content = \substr($tag, \strlen($name) + 1);
         $content = \ltrim($content);
 
-        return [$name, $content];
-    }
-
-    /**
-     * @throws InvalidTagNameException
-     */
-    public function parse(string $tag, DescriptionParserInterface $parser = null): Tag
-    {
-        // Tag name like ["var", "example"] extracted from "@var example"
-        [$name, $content] = $this->getTagParts($tag);
-
-        if ($parser !== null) {
-            $content = $parser->parse($content, $this);
-        }
-
-        return new Tag($name, $content);
+        return $this->tags->create($name, $content, $parser);
     }
 }

src/Parser/Tag/TagParserInterface.php

@@ -24,5 +24,5 @@ interface TagParserInterface
      * // }
      * ```
      */
-    public function parse(string $tag, DescriptionParserInterface $parser = null): Tag;
+    public function parse(string $tag, DescriptionParserInterface $parser): Tag;
 }