[FEATURE] Introduce Action Directive

An Action Directive does not return a node but does an action on the context

Author: linawolf

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

@@ -13,7 +13,6 @@
 
 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\TextRoleFactory;
@@ -23,7 +22,7 @@
  *
  * https://docutils.sourceforge.io/docs/ref/rst/directives.html#default-role
  */
-class DefaultRoleDirective extends BaseDirective
+class DefaultRoleDirective extends ActionDirective
 {
     public function __construct(
         private readonly TextRoleFactory $textRoleFactory,
@@ -35,13 +34,11 @@ public function getName(): string
         return 'default-role';
     }
 
-    public function process(
+    public function processAction(
         DocumentParserContext $documentParserContext,
         Directive $directive,
-    ): Node|null {
+    ): void {
         $name = $directive->getData();
         $this->textRoleFactory->setDefaultTextRole($name);
-
-        return null;
     }
 }

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

@@ -13,7 +13,6 @@
 
 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\BaseTextRole;
@@ -30,7 +29,7 @@
  *
  * https://docutils.sourceforge.io/docs/ref/rst/directives.html#role
  */
-class RoleDirective extends BaseDirective
+class RoleDirective extends ActionDirective
 {
     public function __construct(
         private readonly LoggerInterface $logger,
@@ -43,10 +42,10 @@ public function getName(): string
         return 'role';
     }
 
-    public function process(
+    public function processAction(
         DocumentParserContext $documentParserContext,
         Directive $directive,
-    ): Node|null {
+    ): void {
         $name = $directive->getData();
         $role = 'span';
         if (preg_match('/^([A-Za-z-]*)\(([A-Za-z-]*)\)$/', trim($name), $match) > 0) {
@@ -58,7 +57,7 @@ public function process(
         if (!$baseRole instanceof BaseTextRole) {
             $this->logger->error('Text role "' . $role . '", class ' . $baseRole::class . ' cannot be extended. ');
 
-            return null;
+            return;
         }
 
         $customRole = $baseRole->withName($name);
@@ -73,7 +72,5 @@ public function process(
         }
 
         $this->textRoleFactory->replaceTextRole($customRole);
-
-        return null;
     }
 }

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

@@ -5,8 +5,6 @@
 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\TextRoleFactory;
@@ -42,7 +40,7 @@ public function apply(DocumentParserContext $documentParserContext, InlineLexer
 
                     $lexer->moveNext();
 
-                    return $this->textRoleFactory->getDefaultTextRole()->processNode($parserContext, '', $text, $text);
+                    return $this->textRoleFactory->getDefaultTextRole()->processNode($documentParserContext, '', $text, $text);
 
                 default:
                     $text .= $token->value;

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

@@ -5,7 +5,7 @@
 namespace phpDocumentor\Guides\RestructuredText\TextRoles;
 
 use phpDocumentor\Guides\Nodes\Inline\GenericTextRoleInlineNode;
-use phpDocumentor\Guides\ParserContext;
+use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
 
 /**
  * This text role is extended by custom text roles that do not feature a base text role:
@@ -23,7 +23,7 @@ class SpanTextRole extends BaseTextRole
     protected string $name = 'span';
 
     public function processNode(
-        ParserContext $parserContext,
+        DocumentParserContext $documentParserContext,
         string $role,
         string $content,
         string $rawContent,