Redirect processing in compiler pass

Author: jaapio

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

@@ -372,6 +372,10 @@
         ->set(GlobSearcher::class)
         ->set(ToctreeBuilder::class)
         ->set(InlineMarkupRule::class)
+
+        ->set(\phpDocumentor\Guides\RestructuredText\Compiler\Passes\DirectiveProcessPass::class)
+        ->arg('$directives', tagged_iterator('phpdoc.guides.directive'))
+        ->tag('phpdoc.guides.compiler.nodeTransformers')
         ->set(DefaultCodeNodeOptionMapper::class)
         ->alias(CodeNodeOptionMapper::class, DefaultCodeNodeOptionMapper::class);
 };

packages/guides-restructured-text/src/RestructuredText/Compiler/Passes/DirectiveProcessPass.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\RestructuredText\Compiler\Passes;
+
+use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\NodeTransformer;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Directives\BaseDirective as DirectiveHandler;
+use phpDocumentor\Guides\RestructuredText\Directives\GeneralDirective;
+use phpDocumentor\Guides\RestructuredText\Nodes\DirectiveNode;
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use Psr\Log\LoggerInterface;
+
+class DirectiveProcessPass implements NodeTransformer
+{
+    /** @var array<string, DirectiveHandler> */
+    private array $directives;
+
+    /** @param iterable<DirectiveHandler> $directives */
+    public function __construct(
+        private readonly LoggerInterface $logger,
+        private readonly GeneralDirective $generalDirective,
+        iterable $directives = [],
+    ) {
+        foreach ($directives as $directive) {
+            $this->registerDirective($directive);
+        }
+    }
+
+    private function registerDirective(DirectiveHandler $directive): void
+    {
+        $this->directives[strtolower($directive->getName())] = $directive;
+        foreach ($directive->getAliases() as $alias) {
+            $this->directives[strtolower($alias)] = $directive;
+        }
+    }
+
+    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    {
+        return $node;
+    }
+
+    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    {
+        return $this->getDirectiveHandler($node->getDirective())->createNode($node->getDirective());
+    }
+
+    private function getDirectiveHandler(Directive $directive): DirectiveHandler
+    {
+        return $this->directives[strtolower($directive->getName())] ?? $this->generalDirective;
+    }
+
+    public function supports(Node $node): bool
+    {
+        return $node instanceof DirectiveNode;
+    }
+
+    public function getPriority(): int
+    {
+        return PHP_INT_MAX;
+    }
+}

packages/guides-restructured-text/src/RestructuredText/Directives/Attributes/Directive.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\RestructuredText\Directives\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS)]
+final class Directive
+{
+    public function __construct(
+        public readonly string $name,
+        public readonly array $aliases = [],
+    ) {
+
+    }
+}

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

@@ -40,10 +40,29 @@ abstract class BaseDirective
     /** @var array<string, Option|null> Cache of Option attributes indexed by option name */
     private array $optionAttributeCache;
 
+    private string $name;
+
+    private array $aliases;
+
     /**
      * Get the directive name
      */
-    abstract public function getName(): string;
+    public function getName(): string
+    {
+        if (isset($this->name)) {
+            return $this->name;
+        }
+
+        $reflection = new \ReflectionClass($this);
+        $attributes = $reflection->getAttributes(Attributes\Directive::class);
+
+        if (count($attributes) === 0) {
+            throw new \LogicException('Directive class must have a Directive attribute');
+        }
+
+        $this->name = $attributes[0]->newInstance()->name;
+        return $this->name;
+    }
 
     /**
      * Allow a directive to be registered under multiple names.
@@ -54,7 +73,35 @@ abstract public function getName(): string;
      */
     public function getAliases(): array
     {
-        return [];
+        if (isset($this->aliases)) {
+            return $this->aliases;
+        }
+
+        $reflection = new \ReflectionClass($this);
+        $attributes = $reflection->getAttributes(Attributes\Directive::class);
+        $this->aliases = [];
+        if (count($attributes) !== 0) {
+            $this->aliases = $attributes[0]->newInstance()->aliases;
+        }
+
+        return $this->aliases;
+    }
+
+    /**
+     * Returns whether this directive has been upgraded to a new version.
+     *
+     * In the new version of directives, the processing is done during the compile phase.
+     * This method only exists to allow for backward compatibility with directives that
+     * were written before the upgrade.
+     *
+     * @internal
+     */
+    final public function isUpgraded(): bool
+    {
+        $reflection = new \ReflectionClass($this);
+        $attributes = $reflection->getAttributes(Attributes\Directive::class);
+
+        return count($attributes) === 1;
     }
 
     /**
@@ -89,6 +136,11 @@ public function processNode(
         return new GenericNode($directive->getVariable(), $directive->getData());
     }
 
+    public function createNode(Directive $directive): Node|null
+    {
+        return null;
+    }
+
     /**
      * @param DirectiveOption[] $options
      *

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

@@ -26,6 +26,7 @@
  *      This is a note admonition.
  * ```
  */
+#[Attributes\Directive(name: 'note')]
 final class NoteDirective extends AbstractAdmonitionDirective
 {
     public function __construct(protected Rule $startingRule)

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

@@ -26,6 +26,7 @@
  *      This is a warning admonition.
  * ```
  */
+#[Attributes\Directive(name: 'warning')]
 final class WarningDirective extends AbstractAdmonitionDirective
 {
     public function __construct(protected Rule $startingRule)

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

@@ -14,6 +14,8 @@
 namespace phpDocumentor\Guides\RestructuredText\Directives;
 
 use phpDocumentor\Guides\Nodes\EmbeddedFrame;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RestructuredText\Directives\Attributes;
 use phpDocumentor\Guides\RestructuredText\Directives\Attributes\Option;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
@@ -37,6 +39,7 @@
  * - string allow The allow attribute of the iframe, default is 'encrypted-media; picture-in-picture; web-share'
  * - bool allowfullscreen Whether the video should be allowed to go fullscreen, default is true
  */
+#[Attributes\Directive(name: 'youtube')]
 #[Option('width', type: OptionType::Integer, default: 560, description: 'Width of the video')]
 #[Option('title', type: OptionType::String, description: 'Title of the video')]
 #[Option('height', type: OptionType::Integer, default: 315, description: 'Height of the video')]
@@ -53,6 +56,11 @@ public function process(
         BlockContext $blockContext,
         Directive $directive,
     ): EmbeddedFrame {
+        return $this->createNode($directive);
+    }
+
+    public function createNode(Directive $directive): EmbeddedFrame
+    {
         $node = new EmbeddedFrame(
             'https://www.youtube-nocookie.com/embed/' . $directive->getData(),
         );

packages/guides-restructured-text/src/RestructuredText/Nodes/DirectiveNode.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\RestructuredText\Nodes;
+
+use phpDocumentor\Guides\Nodes\AbstractNode;
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+
+/** @extends AbstractNode<Directive> */
+final class DirectiveNode extends AbstractNode
+{
+    public function __construct(private Directive $directive)
+    {
+
+    }
+
+    public function getDirective(): Directive
+    {
+        return $this->directive;
+    }
+}

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

@@ -18,6 +18,7 @@
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\RestructuredText\Directives\BaseDirective as DirectiveHandler;
 use phpDocumentor\Guides\RestructuredText\Directives\GeneralDirective;
+use phpDocumentor\Guides\RestructuredText\Nodes\DirectiveNode;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Buffer;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
@@ -84,10 +85,15 @@ public function apply(BlockContext $blockContext, CompoundNode|null $on = null):
         }
 
         $this->parseDirectiveContent($directive, $blockContext);
+        $this->interpretDirectiveOptions($documentIterator, $directive);
 
         $directiveHandler = $this->getDirectiveHandler($directive);
+        if ($directiveHandler->isUpgraded()) {
+            //What do we do with the content of the directive?
+            // Child nodes need to be parsed. and the content needs to be collected as a string.
+            return new DirectiveNode($directive);
+        }
 
-        $this->interpretDirectiveOptions($documentIterator, $directive);
         $buffer = $this->collectDirectiveContents($documentIterator);
 
         // Processing the Directive, the handler is responsible for adding the right Nodes to the document.