[FEATURE] Enable configurable default text roles

See https://docutils.sourceforge.io/docs/ref/rst/directives.html#setting-the-default-interpreted-text-role

Author: linawolf

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

@@ -193,6 +193,7 @@
 
         ->set(DefaultTextRoleFactory::class, DefaultTextRoleFactory::class)
         ->arg('$genericTextRole', inline_service(GenericTextRole::class))
+        ->arg('$defaultTextRole', inline_service(LiteralTextRole::class))
         ->arg('$textRoles', tagged_iterator('phpdoc.guides.parser.rst.text_role'))
         ->alias(TextRoleFactory::class, DefaultTextRoleFactory::class)
 

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

@@ -13,15 +13,35 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Directives;
 
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
+use phpDocumentor\Guides\RestructuredText\TextRoles\DefaultTextRoleFactory;
+
 /**
  * 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
+class DefaultRoleDirective extends BaseDirective
 {
+    public function __construct(
+        private readonly DefaultTextRoleFactory $textRoleFactory,
+    ) {
+    }
+
     public function getName(): string
     {
         return 'default-role';
     }
+
+    public function process(
+        DocumentParserContext $documentParserContext,
+        Directive $directive,
+    ): Node|null {
+        $name = $directive->getData();
+        $this->textRoleFactory->setDefaultTextRole($name);
+
+        return null;
+    }
 }

packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/DefaultTextRoleRule.php

@@ -5,15 +5,21 @@
 namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
 
 use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\ParserContext;
 use phpDocumentor\Guides\Nodes\Inline\LiteralInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
+use phpDocumentor\Guides\RestructuredText\TextRoles\DefaultTextRoleFactory;
 
 /**
  * Rule to parse for default text roles such as `something`
  */
 class DefaultTextRoleRule extends AbstractInlineRule
 {
+    public function __construct(private readonly DefaultTextRoleFactory $textRoleFactory)
+    {
+    }
+
     public function applies(InlineLexer $lexer): bool
     {
         return $lexer->token?->type === InlineLexer::BACKTICK;
@@ -36,7 +42,7 @@ public function apply(DocumentParserContext $documentParserContext, InlineLexer
 
                     $lexer->moveNext();
 
-                    return new LiteralInlineNode($text);
+                    return $this->textRoleFactory->getDefaultTextRole()->processNode($parserContext, '', $text, $text);
 
                 default:
                     $text .= $token->value;

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

@@ -17,6 +17,7 @@ class DefaultTextRoleFactory implements TextRoleFactory
      */
     public function __construct(
         private readonly TextRole $genericTextRole,
+        private TextRole $defaultTextRole,
         iterable $textRoles = [],
         private array $domains = [],
     ) {
@@ -43,6 +44,10 @@ public function replaceTextRole(TextRole $newTextRole): void
 
     public function getTextRole(string $name, string|null $domain = null): TextRole
     {
+        if ($name === 'default') {
+            return $this->defaultTextRole;
+        }
+
         if ($domain === null) {
             return $this->findTextRole($this->textRoles, $name);
         }
@@ -73,4 +78,19 @@ private function findTextRole(array $textRoles, string $name): TextRole
 
         return $this->genericTextRole;
     }
+
+    public function setDefaultTextRole(string $roleName): void
+    {
+        $newDefault = $this->getTextRole($roleName);
+        if ($newDefault instanceof GenericTextRole) {
+            $newDefault->setBaseRole($roleName);
+        }
+
+        $this->defaultTextRole = $this->getTextRole($roleName);
+    }
+
+    public function getDefaultTextRole(): TextRole
+    {
+        return $this->defaultTextRole;
+    }
 }

packages/guides-restructured-text/tests/unit/Parser/InlineTokenParserTest.php

@@ -9,6 +9,7 @@
 use phpDocumentor\Guides\Nodes\Inline\DocReferenceNode;
 use phpDocumentor\Guides\Nodes\Inline\EmphasisInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\FootnoteInlineNode;
+use phpDocumentor\Guides\Nodes\Inline\GenericTextRoleInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
 use phpDocumentor\Guides\Nodes\Inline\LiteralInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
@@ -33,6 +34,7 @@
 use phpDocumentor\Guides\RestructuredText\TextRoles\DefaultTextRoleFactory;
 use phpDocumentor\Guides\RestructuredText\TextRoles\DocReferenceTextRole;
 use phpDocumentor\Guides\RestructuredText\TextRoles\GenericTextRole;
+use phpDocumentor\Guides\RestructuredText\TextRoles\LiteralTextRole;
 use phpDocumentor\Guides\RestructuredText\TextRoles\ReferenceTextRole;
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\MockObject\MockObject;
@@ -50,6 +52,7 @@ public function setUp(): void
         $this->documentParserContext = $this->createMock(DocumentParserContext::class);
         $defaultTextRoleFactory = new DefaultTextRoleFactory(
             new GenericTextRole(),
+            new LiteralTextRole(),
             [
                 new ReferenceTextRole($this->logger),
                 new DocReferenceTextRole($this->logger),
@@ -65,7 +68,7 @@ public function setUp(): void
             new AnonymousPhraseRule(),
             new AnnotationRoleRule(),
             new LiteralRule(),
-            new DefaultTextRoleRule(),
+            new DefaultTextRoleRule($defaultTextRoleFactory),
             new StandaloneHyperlinkRule(),
             new EmphasisRule(),
             new StrongRule(),
@@ -219,7 +222,7 @@ public static function inlineNodeProvider(): array
             ],
             'Default Textrole' => [
                 '`simple`',
-                new InlineCompoundNode([new LiteralInlineNode('simple')]),
+                new InlineCompoundNode([new GenericTextRoleInlineNode('literal', 'simple')]),
             ],
             'Hyperlink' => [
                 'https://example.com',

packages/guides-restructured-text/tests/unit/TextRoles/DefaultTextRoleFactoryTest.php

@@ -17,6 +17,7 @@ public function setUp(): void
         $this->logger = new Logger('test');
         $this->defaultTextRoleFactory = new DefaultTextRoleFactory(
             new GenericTextRole(),
+            new LiteralTextRole(),
             [],
             [],
         );

tests/Integration/tests/role-directive/expected/index.html

@@ -12,6 +12,8 @@ <h1>Some Title</h1>
             <p><em class="custom">text</em></p>
             <p><code class="raw raw-role">raw text</code></p>
             <p><span class="special">interpreted text</span></p>
+            <p>An example of a <sub>default</sub> role.</p>
+            <p>An example of a <span class="special">custom default</span> role.</p>
     </div>
 
 </body>

tests/Integration/tests/role-directive/input/index.rst

@@ -18,3 +18,11 @@ An example of using :custom:`interpreted text`
    :class: special
 
 :custom:`interpreted text`
+
+.. default-role:: subscript
+
+An example of a `default` role.
+
+.. default-role:: custom
+
+An example of a `custom default` role.