[FEATURE] Introduce textroles for component (#28)

* [TASK] Move shared functionality of textroles to common abstract class * [Feature] Introduce :php:class: TextRole * [Feature] Introduce :php:enum: TextRole * [Feature] Introduce :php:trait: TextRole * [Feature] Introduce :php:exception: TextRole * Update src/TextRoles/PhpComponentTextRole.php Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --------- Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com>
TYPO3-Documentation · Dec 12, 2023 · e92c96e · e92c96e
1 parent 55fba46
commit e92c96e
Show file tree

Hide file tree

Showing 18 changed files with 486 additions and 94 deletions.
diff --git a/resources/config/php-domain.php b/resources/config/php-domain.php
@@ -16,6 +16,10 @@
 use T3Docs\GuidesPhpDomain\Directives\Php\GlobalDirective;
 use T3Docs\GuidesPhpDomain\Directives\Php\TraitDirective;
 use T3Docs\GuidesPhpDomain\PhpDomain\ModifierService;
+use T3Docs\GuidesPhpDomain\TextRoles\ClassTextRole;
+use T3Docs\GuidesPhpDomain\TextRoles\EnumTextRole;
+use T3Docs\GuidesPhpDomain\TextRoles\ExceptionTextRole;
+use T3Docs\GuidesPhpDomain\TextRoles\TraitTextRole;
 use function Symfony\Component\DependencyInjection\Loader\Configurator\service;
 
 use T3Docs\GuidesPhpDomain\Directives\Php\EnumDirective;
@@ -53,7 +57,15 @@
         ->set(ModifierService::class)
         ->set(NamespaceRepository::class)
 
+        ->set(ClassTextRole::class)
+        ->tag('phpdoc.guides.parser.rst.text_role', ['domain' => 'php'])
+        ->set(EnumTextRole::class)
+        ->tag('phpdoc.guides.parser.rst.text_role', ['domain' => 'php'])
+        ->set(ExceptionTextRole::class)
+        ->tag('phpdoc.guides.parser.rst.text_role', ['domain' => 'php'])
         ->set(InterfaceTextRole::class)
         ->tag('phpdoc.guides.parser.rst.text_role', ['domain' => 'php'])
+        ->set(TraitTextRole::class)
+        ->tag('phpdoc.guides.parser.rst.text_role', ['domain' => 'php'])
     ;
 };
diff --git a/src/TextRoles/ClassTextRole.php b/src/TextRoles/ClassTextRole.php
@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace T3Docs\GuidesPhpDomain\TextRoles;
+
+use Doctrine\Common\Lexer\Token;
+use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
+use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
+use phpDocumentor\Guides\ReferenceResolvers\AnchorReducer;
+use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
+use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
+use phpDocumentor\Guides\RestructuredText\TextRoles\TextRole;
+use Psr\Log\LoggerInterface;
+
+final class ClassTextRole extends PhpComponentTextRole
+{
+    private const TYPE = 'class';
+
+    public function getName(): string
+    {
+        return self::TYPE;
+    }
+}
diff --git a/src/TextRoles/EnumTextRole.php b/src/TextRoles/EnumTextRole.php
@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace T3Docs\GuidesPhpDomain\TextRoles;
+
+use Doctrine\Common\Lexer\Token;
+use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
+use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
+use phpDocumentor\Guides\ReferenceResolvers\AnchorReducer;
+use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
+use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
+use phpDocumentor\Guides\RestructuredText\TextRoles\TextRole;
+use Psr\Log\LoggerInterface;
+
+final class EnumTextRole extends PhpComponentTextRole
+{
+    private const TYPE = 'enum';
+
+    public function getName(): string
+    {
+        return self::TYPE;
+    }
+}
diff --git a/src/TextRoles/ExceptionTextRole.php b/src/TextRoles/ExceptionTextRole.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace T3Docs\GuidesPhpDomain\TextRoles;
+
+use Doctrine\Common\Lexer\Token;
+use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
+use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
+use phpDocumentor\Guides\ReferenceResolvers\AnchorReducer;
+use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
+use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
+use phpDocumentor\Guides\RestructuredText\TextRoles\TextRole;
+use Psr\Log\LoggerInterface;
+
+final class ExceptionTextRole extends PhpComponentTextRole
+{
+    private const TYPE = 'exception';
+
+    public function getAliases(): array
+    {
+        return ['exc'];
+    }
+
+    public function getName(): string
+    {
+        return self::TYPE;
+    }
+
+    public function processNode(
+        DocumentParserContext $documentParserContext,
+        string $role,
+        string $content,
+        string $rawContent,
+    ): AbstractLinkInlineNode {
+        if ($role !== 'php:exception') {
+            $this->logger->warning(sprintf('Text role :%s: is deprecated. Use :php:exception: instead. ', $role), $documentParserContext->getLoggerInformation());
+        }
+        return parent::processNode($documentParserContext, $role, $content, $rawContent);
+    }
+}
diff --git a/src/TextRoles/InterfaceTextRole.php b/src/TextRoles/InterfaceTextRole.php
@@ -13,103 +13,12 @@
 use phpDocumentor\Guides\RestructuredText\TextRoles\TextRole;
 use Psr\Log\LoggerInterface;
 
-final class InterfaceTextRole implements TextRole
+final class InterfaceTextRole extends PhpComponentTextRole
 {
-    /**
-     * @see https://regex101.com/r/OyN05v/1
-     */
-    private const INTERLINK_NAME_REGEX = '/^([a-zA-Z0-9]+):(.*$)/';
-
-    private readonly InlineLexer $lexer;
-
-    public function __construct(
-        private readonly LoggerInterface $logger,
-        private readonly AnchorReducer $anchorReducer,
-    ) {
-        // Do not inject the $lexer. It contains a state.
-        $this->lexer = new InlineLexer();
-    }
-    final public const NAME = 'interface';
+    private const TYPE = 'interface';
 
     public function getName(): string
     {
-        return self::NAME;
-    }
-    public function getAliases(): array
-    {
-        return [];
-    }
-
-    public function processNode(
-        DocumentParserContext $documentParserContext,
-        string $role,
-        string $content,
-        string $rawContent,
-    ): AbstractLinkInlineNode {
-        $referenceTarget = null;
-        $value = null;
-
-        $part = '';
-        $this->lexer->setInput($rawContent);
-        $this->lexer->moveNext();
-        $this->lexer->moveNext();
-        while ($this->lexer->token instanceof Token) {
-            $token = $this->lexer->token;
-            switch ($token->type) {
-                case InlineLexer::EMBEDED_URL_START:
-                    $value = trim($part);
-                    $part = '';
-
-                    break;
-                case InlineLexer::EMBEDED_URL_END:
-                    if ($value === null) {
-                        // not inside the embedded URL
-                        $part .= $token->value;
-                        break;
-                    }
-
-                    if ($this->lexer->peek() !== null) {
-                        $this->logger->warning(
-                            sprintf(
-                                'Reference contains unexpected content after closing `>`: "%s"',
-                                $content,
-                            ),
-                            $documentParserContext->getLoggerInformation(),
-                        );
-                    }
-
-                    $referenceTarget = $part;
-                    $part = '';
-
-                    break 2;
-                default:
-                    $part .= $token->value;
-            }
-
-            $this->lexer->moveNext();
-        }
-
-        $value .= trim($part);
-
-        if ($referenceTarget === null) {
-            $referenceTarget = $value;
-            $value = null;
-        }
-
-        return $this->createNode($referenceTarget, $value, $role);
-    }
-
-    /** @return ReferenceNode */
-    protected function createNode(string $referenceTarget, string|null $referenceName, string $role): AbstractLinkInlineNode
-    {
-        if (preg_match(self::INTERLINK_NAME_REGEX, $referenceTarget, $matches)) {
-            $interlinkDomain = $matches[1];
-            $id = $this->anchorReducer->reduceAnchor($matches[2]);
-        } else {
-            $interlinkDomain = '';
-            $id = $this->anchorReducer->reduceAnchor($referenceTarget);
-        }
-
-        return new ReferenceNode($id, $referenceName ?? '', $interlinkDomain, 'php:interface');
+        return self::TYPE;
     }
 }
diff --git a/src/TextRoles/PhpComponentTextRole.php b/src/TextRoles/PhpComponentTextRole.php
@@ -0,0 +1,113 @@
+<?php
+
+declare(strict_types=1);
+
+namespace T3Docs\GuidesPhpDomain\TextRoles;
+
+use Doctrine\Common\Lexer\Token;
+use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
+use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
+use phpDocumentor\Guides\ReferenceResolvers\AnchorReducer;
+use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
+use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
+use phpDocumentor\Guides\RestructuredText\TextRoles\TextRole;
+use Psr\Log\LoggerInterface;
+
+abstract class PhpComponentTextRole implements TextRole
+{
+    /**
+     * @see https://regex101.com/r/OyN05v/1
+     */
+    private const INTERLINK_NAME_REGEX = '/^([a-zA-Z0-9]+):(.*$)/';
+
+    private readonly InlineLexer $lexer;
+
+    public function __construct(
+        protected readonly LoggerInterface $logger,
+        private readonly AnchorReducer $anchorReducer,
+    ) {
+        // Do not inject the $lexer. It contains a state.
+        $this->lexer = new InlineLexer();
+    }
+
+    /**
+     * @return list<string>
+     */
+    public function getAliases(): array
+    {
+        return [];
+    }
+
+    public function processNode(
+        DocumentParserContext $documentParserContext,
+        string $role,
+        string $content,
+        string $rawContent,
+    ): AbstractLinkInlineNode {
+        $referenceTarget = null;
+        $value = null;
+
+        $part = '';
+        $this->lexer->setInput($rawContent);
+        $this->lexer->moveNext();
+        $this->lexer->moveNext();
+        while ($this->lexer->token instanceof Token) {
+            $token = $this->lexer->token;
+            switch ($token->type) {
+                case InlineLexer::EMBEDED_URL_START:
+                    $value = trim($part);
+                    $part = '';
+
+                    break;
+                case InlineLexer::EMBEDED_URL_END:
+                    if ($value === null) {
+                        // not inside the embedded URL
+                        $part .= $token->value;
+                        break;
+                    }
+
+                    if ($this->lexer->peek() !== null) {
+                        $this->logger->warning(
+                            sprintf(
+                                'Reference contains unexpected content after closing `>`: "%s"',
+                                $content,
+                            ),
+                            $documentParserContext->getLoggerInformation(),
+                        );
+                    }
+
+                    $referenceTarget = $part;
+                    $part = '';
+
+                    break 2;
+                default:
+                    $part .= $token->value;
+            }
+
+            $this->lexer->moveNext();
+        }
+
+        $value .= trim($part);
+
+        if ($referenceTarget === null) {
+            $referenceTarget = $value;
+            $value = null;
+        }
+
+        return $this->createNode($referenceTarget, $value, $role);
+    }
+
+    /** @return ReferenceNode */
+    protected function createNode(string $referenceTarget, string|null $referenceName, string $role): AbstractLinkInlineNode
+    {
+        if (preg_match(self::INTERLINK_NAME_REGEX, $referenceTarget, $matches)) {
+            $interlinkDomain = $matches[1];
+            $id = $this->anchorReducer->reduceAnchor($matches[2]);
+        } else {
+            $interlinkDomain = '';
+            $id = $this->anchorReducer->reduceAnchor($referenceTarget);
+        }
+
+        return new ReferenceNode($id, $referenceName ?? '', $interlinkDomain, 'php:' . $this->getName());
+    }
+}
diff --git a/src/TextRoles/TraitTextRole.php b/src/TextRoles/TraitTextRole.php
@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace T3Docs\GuidesPhpDomain\TextRoles;
+
+use Doctrine\Common\Lexer\Token;
+use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
+use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
+use phpDocumentor\Guides\ReferenceResolvers\AnchorReducer;
+use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
+use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
+use phpDocumentor\Guides\RestructuredText\TextRoles\TextRole;
+use Psr\Log\LoggerInterface;
+
+final class TraitTextRole extends PhpComponentTextRole
+{
+    private const TYPE = 'trait';
+
+    public function getName(): string
+    {
+        return self::TYPE;
+    }
+}