Merge pull request #514 from phpDocumentor/feature-role-directive

[FEATURE] Enable configurable custom and default text roles

Author: jaapio

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)
@@ -189,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/DependencyInjection/Compiler/TextRolePass.php

@@ -4,7 +4,7 @@
 
 namespace phpDocumentor\Guides\RestructuredText\DependencyInjection\Compiler;
 
-use phpDocumentor\Guides\RestructuredText\TextRoles\DefaultTextRoleFactory;
+use phpDocumentor\Guides\RestructuredText\TextRoles\TextRoleFactory;
 use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\DependencyInjection\Reference;
@@ -13,7 +13,7 @@ class TextRolePass implements CompilerPassInterface
 {
     public function process(ContainerBuilder $container): void
     {
-        $textRoleFactory = $container->findDefinition(DefaultTextRoleFactory::class);
+        $textRoleFactory = $container->findDefinition(TextRoleFactory::class);
         $domains = [];
         $textRoles = [];
 

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

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\RestructuredText\Directives;
+
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
+
+/**
+ * Extend this class to create a directive that does some actions, for example on the parser context, without
+ * creating a node.
+ */
+abstract class ActionDirective extends BaseDirective
+{
+    public function process(
+        DocumentParserContext $documentParserContext,
+        Directive $directive,
+    ): Node|null {
+        $this->processAction($documentParserContext, $directive);
+
+        return null;
+    }
+
+    /**
+     * @param DocumentParserContext $documentParserContext the current document context with the content
+     *    of the directive
+     * @param Directive $directive parsed directive containing options and variable
+     */
+    abstract public function processAction(
+        DocumentParserContext $documentParserContext,
+        Directive $directive,
+    ): void;
+}

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

@@ -76,22 +76,6 @@ public function processNode(
         return new GenericNode($directive->getVariable(), $directive->getData());
     }
 
-    /**
-     * This can be overloaded to write a directive that just do an action without changing
-     * the nodes of the document
-     *
-     * The arguments are the same that process
-     *
-     * @param mixed[] $options
-     */
-    public function processAction(
-        DocumentParserContext $documentParserContext,
-        string $variable,
-        string $data,
-        array $options,
-    ): void {
-    }
-
     /**
      * @param DirectiveOption[] $options
      *

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

@@ -0,0 +1,38 @@
+<?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;
+
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
+
+/**
+ * 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 ActionDirective
+{
+    public function getName(): string
+    {
+        return 'default-role';
+    }
+
+    public function processAction(
+        DocumentParserContext $documentParserContext,
+        Directive $directive,
+    ): void {
+        $name = $directive->getData();
+        $documentParserContext->getTextRoleFactoryForDocument()->setDefaultTextRole($name);
+    }
+}

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

@@ -13,10 +13,62 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Directives;
 
-class RoleDirective extends SubDirective
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
+use phpDocumentor\Guides\RestructuredText\TextRoles\BaseTextRole;
+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 ActionDirective
 {
+    public function __construct(
+        private readonly LoggerInterface $logger,
+    ) {
+    }
+
     public function getName(): string
     {
         return 'role';
     }
+
+    public function processAction(
+        DocumentParserContext $documentParserContext,
+        Directive $directive,
+    ): void {
+        $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 = $documentParserContext->getTextRoleFactoryForDocument()->getTextRole($role);
+        if (!$baseRole instanceof BaseTextRole) {
+            $this->logger->error('Text role "' . $role . '", class ' . $baseRole::class . ' cannot be extended. ');
+
+            return;
+        }
+
+        $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);
+        }
+
+        $documentParserContext->getTextRoleFactoryForDocument()->replaceTextRole($customRole);
+    }
 }

packages/guides-restructured-text/src/RestructuredText/MarkupLanguageParser.php

@@ -10,6 +10,7 @@
 use phpDocumentor\Guides\ParserContext;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
+use phpDocumentor\Guides\RestructuredText\TextRoles\TextRoleFactory;
 use RuntimeException;
 use Webmozart\Assert\Assert;
 
@@ -26,6 +27,7 @@ class MarkupLanguageParser implements ParserInterface
     /** @param Rule<DocumentNode> $startingRule */
     public function __construct(
         private readonly Rule $startingRule,
+        private readonly TextRoleFactory $textRoleFactory,
     ) {
     }
 
@@ -39,6 +41,7 @@ public function getSubParser(): MarkupLanguageParser
     {
         return new MarkupLanguageParser(
             $this->startingRule,
+            $this->textRoleFactory,
         );
     }
 
@@ -74,6 +77,7 @@ public function parse(ParserContext $parserContext, string $contents): DocumentN
         $this->documentParser = new DocumentParserContext(
             $contents,
             $parserContext,
+            $this->textRoleFactory,
             $this,
         );
 

packages/guides-restructured-text/src/RestructuredText/Parser/DocumentParserContext.php

@@ -17,6 +17,7 @@
 use phpDocumentor\Guides\Nodes\ProjectNode;
 use phpDocumentor\Guides\ParserContext;
 use phpDocumentor\Guides\RestructuredText\MarkupLanguageParser;
+use phpDocumentor\Guides\RestructuredText\TextRoles\TextRoleFactory;
 use RuntimeException;
 
 /**
@@ -31,16 +32,21 @@ class DocumentParserContext
 
     private LinesIterator $documentIterator;
     private int $currentTitleLevel;
+    /* Each Document has its own text role factory as text roles can be changed on a per document base
+        by directives */
+    private TextRoleFactory $textRoleFactoryForDocument;
 
     /** @var string[] */
     private array $titleLetters = [];
 
     public function __construct(
         string $content,
         private readonly ParserContext $context,
+        TextRoleFactory $textRoleFactory,
         private readonly MarkupLanguageParser $markupLanguageParser,
     ) {
         $this->documentIterator = new LinesIterator();
+        $this->textRoleFactoryForDocument = clone $textRoleFactory;
         $this->documentIterator->load($content);
         $this->currentTitleLevel = $context->getInitialHeaderLevel() - 1;
     }
@@ -115,4 +121,9 @@ public function withContentsPreserveSpace(string $contents): self
 
         return $that;
     }
+
+    public function getTextRoleFactoryForDocument(): TextRoleFactory
+    {
+        return $this->textRoleFactoryForDocument;
+    }
 }

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

@@ -5,7 +5,6 @@
 namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
 
 use phpDocumentor\Guides\Nodes\Inline\InlineNode;
-use phpDocumentor\Guides\Nodes\Inline\LiteralInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
 
@@ -36,7 +35,10 @@ public function apply(DocumentParserContext $documentParserContext, InlineLexer
 
                     $lexer->moveNext();
 
-                    return new LiteralInlineNode($text);
+                    return $documentParserContext
+                        ->getTextRoleFactoryForDocument()
+                        ->getDefaultTextRole()
+                        ->processNode($documentParserContext, '', $text, $text);
 
                 default:
                     $text .= $token->value;

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

@@ -7,7 +7,6 @@
 use phpDocumentor\Guides\Nodes\Inline\InlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
-use phpDocumentor\Guides\RestructuredText\TextRoles\TextRoleFactory;
 
 use function substr;
 
@@ -16,10 +15,6 @@
  */
 class TextRoleRule extends AbstractInlineRule
 {
-    public function __construct(private readonly TextRoleFactory $textRoleFactory)
-    {
-    }
-
     public function applies(InlineLexer $lexer): bool
     {
         return $lexer->token?->type === InlineLexer::COLON;
@@ -54,7 +49,7 @@ public function apply(DocumentParserContext $documentParserContext, InlineLexer
                     }
 
                     if ($inText) {
-                        $textRole = $this->textRoleFactory->getTextRole($role, $domain);
+                        $textRole = $documentParserContext->getTextRoleFactoryForDocument()->getTextRole($role, $domain);
                         $fullRole = ($domain ? $domain . ':' : '') . $role;
                         $lexer->moveNext();