[FEATURE] Enable configurable custom text roles

See https://docutils.sourceforge.io/docs/ref/rst/directives.html#role

Author: linawolf

packages/guides-restructured-text/resources/config/guides-restructured-text.php

@@ -13,6 +13,7 @@
 use phpDocumentor\Guides\RestructuredText\Directives\ContainerDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\ContentsDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\DangerDirective;
+use phpDocumentor\Guides\RestructuredText\Directives\DefaultRoleDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\DeprecatedDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\DocumentBlockDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\ErrorDirective;
@@ -90,6 +91,7 @@
 use phpDocumentor\Guides\RestructuredText\TextRoles\LiteralTextRole;
 use phpDocumentor\Guides\RestructuredText\TextRoles\MathTextRole;
 use phpDocumentor\Guides\RestructuredText\TextRoles\ReferenceTextRole;
+use phpDocumentor\Guides\RestructuredText\TextRoles\SpanTextRole;
 use phpDocumentor\Guides\RestructuredText\TextRoles\TextRole;
 use phpDocumentor\Guides\RestructuredText\TextRoles\TextRoleFactory;
 use phpDocumentor\Guides\RestructuredText\Toc\GlobSearcher;
@@ -135,6 +137,7 @@
         ->set(AbbreviationTextRole::class)
         ->set(MathTextRole::class)
         ->set(LiteralTextRole::class)
+        ->set(SpanTextRole::class)
 
         ->set(AdmonitionDirective::class)
         ->set(AttentionDirective::class)
@@ -150,6 +153,7 @@
         ->set(ContentsDirective::class)
         ->arg('$urlGenerator', service(UrlGeneratorInterface::class))
         ->set(DangerDirective::class)
+        ->set(DefaultRoleDirective::class)
         ->set(DeprecatedDirective::class)
         ->set(DocumentBlockDirective::class)
         ->set(ErrorDirective::class)

packages/guides-restructured-text/src/RestructuredText/Directives/DefaultRoleDirective.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace phpDocumentor\Guides\RestructuredText\Directives;
+
+/**
+ * sets the default interpreted text role, the role that is used for interpreted text without an explicit role.
+ *
+ * https://docutils.sourceforge.io/docs/ref/rst/directives.html#default-role
+ */
+class DefaultRoleDirective extends SubDirective
+{
+    public function getName(): string
+    {
+        return 'default-role';
+    }
+}

packages/guides-restructured-text/src/RestructuredText/Directives/RoleDirective.php

@@ -13,10 +13,67 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Directives;
 
-class RoleDirective extends SubDirective
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
+use phpDocumentor\Guides\RestructuredText\TextRoles\BaseTextRole;
+use phpDocumentor\Guides\RestructuredText\TextRoles\DefaultTextRoleFactory;
+use phpDocumentor\Guides\RestructuredText\TextRoles\GenericTextRole;
+use Psr\Log\LoggerInterface;
+
+use function is_string;
+use function preg_match;
+use function trim;
+
+/**
+ * The "role" directive dynamically creates a custom interpreted text role and registers it with the parser.
+ *
+ * https://docutils.sourceforge.io/docs/ref/rst/directives.html#role
+ */
+class RoleDirective extends BaseDirective
 {
+    public function __construct(
+        private readonly LoggerInterface $logger,
+        private readonly DefaultTextRoleFactory $textRoleFactory,
+    ) {
+    }
+
     public function getName(): string
     {
         return 'role';
     }
+
+    public function process(
+        DocumentParserContext $documentParserContext,
+        Directive $directive,
+    ): Node|null {
+        $name = $directive->getData();
+        $role = 'span';
+        if (preg_match('/^([A-Za-z-]*)\(([A-Za-z-]*)\)$/', trim($name), $match) > 0) {
+            $name = $match[1];
+            $role = $match[2];
+        }
+
+        $baseRole = $this->textRoleFactory->getTextRole($role);
+        if (!$baseRole instanceof BaseTextRole) {
+            $this->logger->error('Text role "' . $role . '", class ' . $baseRole::class . ' cannot be extended. ');
+
+            return null;
+        }
+
+        $customRole = $baseRole->withName($name);
+        if (is_string($directive->getOption('class')->getValue())) {
+            $customRole->setClass($directive->getOption('class')->getValue());
+        } else {
+            $customRole->setClass($name);
+        }
+
+        if ($customRole instanceof GenericTextRole) {
+            $customRole->setBaseRole($role);
+        }
+
+        $this->textRoleFactory->replaceTextRole($customRole);
+
+        return null;
+    }
 }

packages/guides-restructured-text/src/RestructuredText/TextRoles/AbbreviationTextRole.php

@@ -12,26 +12,15 @@
 use function preg_match;
 use function trim;
 
-class AbbreviationTextRole implements TextRole
+class AbbreviationTextRole extends BaseTextRole
 {
-    final public const NAME = 'abbreviation';
+    protected string $name = 'abbreviation';
 
     public function __construct(
         private readonly LoggerInterface $logger,
     ) {
     }
 
-    public function getName(): string
-    {
-        return self::NAME;
-    }
-
-    /** @inheritDoc */
-    public function getAliases(): array
-    {
-        return [];
-    }
-
     /** @return AbbreviationInlineNode */
     public function processNode(
         DocumentParserContext $documentParserContext,

packages/guides-restructured-text/src/RestructuredText/TextRoles/BaseTextRole.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\RestructuredText\TextRoles;
+
+abstract class BaseTextRole implements TextRole
+{
+    protected string $name;
+    protected string $class = '';
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    /** @return string[] */
+    public function getAliases(): array
+    {
+        return [];
+    }
+
+    public function getClass(): string
+    {
+        return $this->class;
+    }
+
+    public function setClass(string $class): void
+    {
+        $this->class = $class;
+    }
+
+    public function withName(string $name): BaseTextRole
+    {
+        $role = clone $this;
+        $role->name = $name;
+
+        return $role;
+    }
+}

packages/guides-restructured-text/src/RestructuredText/TextRoles/DefaultTextRoleFactory.php

@@ -23,9 +23,22 @@ public function __construct(
         $this->textRoles = [...$textRoles];
     }
 
-    public function registerTextRole(TextRole $textRoles): void
+    public function registerTextRole(TextRole $textRole): void
     {
-        $this->textRoles[] = $textRoles;
+        $this->textRoles[] = $textRole;
+    }
+
+    public function replaceTextRole(TextRole $newTextRole): void
+    {
+        foreach ($this->textRoles as &$textRole) {
+            if ($textRole->getName() !== $newTextRole->getName()) {
+                continue;
+            }
+
+            $textRole = $newTextRole;
+        }
+
+        $this->textRoles[] = $newTextRole;
     }
 
     public function getTextRole(string $name, string|null $domain = null): TextRole

packages/guides-restructured-text/src/RestructuredText/TextRoles/GenericTextRole.php

@@ -7,27 +7,27 @@
 use phpDocumentor\Guides\Nodes\Inline\GenericTextRoleInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
 
-class GenericTextRole implements TextRole
+class GenericTextRole extends BaseTextRole
 {
-    final public const NAME = 'default';
-
-    public function getName(): string
-    {
-        return self::NAME;
-    }
-
-    /** @inheritDoc */
-    public function getAliases(): array
-    {
-        return [];
-    }
+    protected string $name = 'default';
+    protected string|null $baseRole = null;
 
     public function processNode(
         DocumentParserContext $documentParserContext,
         string $role,
         string $content,
         string $rawContent,
     ): GenericTextRoleInlineNode {
-        return new GenericTextRoleInlineNode($role, $content);
+        return new GenericTextRoleInlineNode($this->baseRole ?? $role, $content, $this->getClass());
+    }
+
+    public function getBaseRole(): string|null
+    {
+        return $this->baseRole;
+    }
+
+    public function setBaseRole(string|null $baseRole): void
+    {
+        $this->baseRole = $baseRole;
     }
 }

packages/guides-restructured-text/src/RestructuredText/TextRoles/LiteralTextRole.php

@@ -7,27 +7,16 @@
 use phpDocumentor\Guides\Nodes\Inline\GenericTextRoleInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
 
-class LiteralTextRole implements TextRole
+class LiteralTextRole extends BaseTextRole
 {
-    final public const NAME = 'literal';
-
-    public function getName(): string
-    {
-        return self::NAME;
-    }
-
-    /** @inheritDoc */
-    public function getAliases(): array
-    {
-        return [];
-    }
+    protected string $name = 'literal';
 
     public function processNode(
         DocumentParserContext $documentParserContext,
         string $role,
         string $content,
         string $rawContent,
     ): GenericTextRoleInlineNode {
-        return new GenericTextRoleInlineNode('literal', $rawContent);
+        return new GenericTextRoleInlineNode('literal', $rawContent, $this->getClass());
     }
 }

packages/guides-restructured-text/src/RestructuredText/TextRoles/MathTextRole.php

@@ -7,27 +7,16 @@
 use phpDocumentor\Guides\Nodes\Inline\GenericTextRoleInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
 
-class MathTextRole implements TextRole
+class MathTextRole extends BaseTextRole
 {
-    final public const NAME = 'math';
-
-    public function getName(): string
-    {
-        return self::NAME;
-    }
-
-    /** @inheritDoc */
-    public function getAliases(): array
-    {
-        return [];
-    }
+    protected string $name = 'math';
 
     public function processNode(
         DocumentParserContext $documentParserContext,
         string $role,
         string $content,
         string $rawContent,
     ): GenericTextRoleInlineNode {
-        return new GenericTextRoleInlineNode('math', $rawContent);
+        return new GenericTextRoleInlineNode('math', $rawContent, $this->getClass());
     }
 }

packages/guides-restructured-text/src/RestructuredText/TextRoles/SpanTextRole.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\RestructuredText\TextRoles;
+
+use phpDocumentor\Guides\Nodes\Inline\GenericTextRoleInlineNode;
+use phpDocumentor\Guides\ParserContext;
+
+/**
+ * This text role is extended by custom text roles that do not feature a base text role:
+ *
+ * ```
+ * .. role:: custom
+ *    :class: special
+ *
+ *    :custom:`interpreted text`
+ *
+ * ```
+ */
+class SpanTextRole extends BaseTextRole
+{
+    protected string $name = 'span';
+
+    public function processNode(
+        ParserContext $parserContext,
+        string $role,
+        string $content,
+        string $rawContent,
+    ): GenericTextRoleInlineNode {
+        return new GenericTextRoleInlineNode('span', $rawContent, $this->getClass());
+    }
+}