!!![TASK] Improve Reference parsing

linawolf · jaapio · commit ac1786bc0bb1 · 2024-01-02T20:34:09.000+01:00
Renamed the trait EmbeddedUriParser to EmbeddedReferenceParser as it can be used for all kind of references including internals.

Let the EmbeddedReferenceParser return a DTO.

Unify the naming an usage of URL parts.
diff --git a/packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/AnonymousPhraseRule.php b/packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/AnonymousPhraseRule.php
@@ -6,8 +6,8 @@
 
 use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
-use phpDocumentor\Guides\RestructuredText\Parser\EmbeddedUriParser;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
+use phpDocumentor\Guides\RestructuredText\Parser\References\EmbeddedReferenceParser;
 
 /**
  * Rule to parse for anonymous references
@@ -21,7 +21,7 @@
  */
 class AnonymousPhraseRule extends ReferenceRule
 {
-    use EmbeddedUriParser;
+    use EmbeddedReferenceParser;
 
     public function applies(InlineLexer $lexer): bool
     {
@@ -61,16 +61,10 @@ public function apply(BlockContext $blockContext, InlineLexer $lexer): AbstractL
 
     private function createAnonymousReference(BlockContext $blockContext, string $value): AbstractLinkInlineNode
     {
-        $parsed = $this->extractEmbeddedUri($value);
-        $link = $parsed['text'];
-        $uri = $parsed['uri'];
-        if ($link === null) {
-            $link = $uri;
-            $uri = null;
-        }
+        $referenceData = $this->extractEmbeddedReference($value);
 
-        $node = $this->createReference($blockContext, $link, $uri, false);
-        $blockContext->getDocumentParserContext()->pushAnonymous($link);
+        $node = $this->createReference($blockContext, $referenceData->reference, $referenceData->text, false);
+        $blockContext->getDocumentParserContext()->pushAnonymous($referenceData->reference);
 
         return $node;
     }
diff --git a/packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/NamedPhraseRule.php b/packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/NamedPhraseRule.php
@@ -6,8 +6,8 @@
 
 use phpDocumentor\Guides\Nodes\Inline\InlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
-use phpDocumentor\Guides\RestructuredText\Parser\EmbeddedUriParser;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
+use phpDocumentor\Guides\RestructuredText\Parser\References\EmbeddedReferenceParser;
 
 /**
  * Rule to parse for named references
@@ -21,7 +21,7 @@
  */
 class NamedPhraseRule extends ReferenceRule
 {
-    use EmbeddedUriParser;
+    use EmbeddedReferenceParser;
 
     public function applies(InlineLexer $lexer): bool
     {
@@ -45,15 +45,9 @@ public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNod
 
                     $lexer->moveNext();
 
-                    $parsed = $this->extractEmbeddedUri($value);
-                    $text = $parsed['text'];
-                    $uri = $parsed['uri'];
-                    if ($text === null) {
-                        $text = $uri;
-                        $uri = null;
-                    }
+                    $referenceData = $this->extractEmbeddedReference($value);
 
-                    return $this->createReference($blockContext, $text, $uri);
+                    return $this->createReference($blockContext, $referenceData->reference, $referenceData->text);
 
                 case InlineLexer::WHITESPACE:
                     $value .= ' ';
diff --git a/packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/ReferenceRule.php b/packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/ReferenceRule.php
@@ -20,24 +20,23 @@
 
 abstract class ReferenceRule extends AbstractInlineRule
 {
-    protected function createReference(BlockContext $blockContext, string $link, string|null $embeddedUrl = null, bool $registerLink = true): AbstractLinkInlineNode
+    protected function createReference(BlockContext $blockContext, string $reference, string|null $text = null, bool $registerLink = true): AbstractLinkInlineNode
     {
         // the link may have a new line in it, so we need to strip it
         // before setting the link and adding a token to be replaced
-        $link = str_replace("\n", ' ', $link);
-        $link = trim(preg_replace('/\s+/', ' ', $link) ?? '');
+        $reference = str_replace("\n", ' ', $reference);
+        $reference = trim(preg_replace('/\s+/', ' ', $reference) ?? '');
 
-        $targetLink = $embeddedUrl ?? $link;
-        if (str_ends_with($targetLink, '.rst') && filter_var($targetLink, FILTER_VALIDATE_URL) === false) {
-            $targetLink = substr($targetLink, 0, -4);
+        if (str_ends_with($reference, '.rst') && filter_var($reference, FILTER_VALIDATE_URL) === false) {
+            $reference = substr($reference, 0, -4);
 
-            return new DocReferenceNode($targetLink, $link);
+            return new DocReferenceNode($reference, $text ?? $reference);
         }
 
-        if ($registerLink && $embeddedUrl !== null) {
-            $blockContext->getDocumentParserContext()->setLink($link, $embeddedUrl);
+        if ($registerLink && $text !== null) {
+            $blockContext->getDocumentParserContext()->setLink($text, $reference);
         }
 
-        return new HyperLinkNode($link, $targetLink);
+        return new HyperLinkNode($text ?? $reference, $reference);
     }
 }
diff --git a/packages/guides-restructured-text/src/RestructuredText/Parser/References/EmbeddedReferenceParser.php b/packages/guides-restructured-text/src/RestructuredText/Parser/References/EmbeddedReferenceParser.php
@@ -2,27 +2,26 @@
 
 declare(strict_types=1);
 
-namespace phpDocumentor\Guides\RestructuredText\Parser;
+namespace phpDocumentor\Guides\RestructuredText\Parser\References;
 
 use function preg_match;
 
-trait EmbeddedUriParser
+trait EmbeddedReferenceParser
 {
-    /** @return array{text:?string,uri:string} */
-    private function extractEmbeddedUri(string $text): array
+    private function extractEmbeddedReference(string $text): ReferenceData
     {
         preg_match('/^(.*?)(?:(?:\s|^)<([^<]+)>)?$/s', $text, $matches);
 
         $text = $matches[1] === '' ? null : $matches[1];
-        $uri = $matches[1];
+        $reference = $matches[1];
 
         if (isset($matches[2])) {
             // there is an embedded URI, text and URI are different
-            $uri = $matches[2];
+            $reference = $matches[2];
         } else {
             $text = null;
         }
 
-        return ['text' => $text, 'uri' => $uri];
+        return new ReferenceData($reference, $text);
     }
 }
diff --git a/packages/guides-restructured-text/src/RestructuredText/Parser/References/ReferenceData.php b/packages/guides-restructured-text/src/RestructuredText/Parser/References/ReferenceData.php
@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\RestructuredText\Parser\References;
+
+final class ReferenceData
+{
+    public function __construct(
+        public readonly string $reference,
+        public readonly string|null $text,
+    ) {
+    }
+}
diff --git a/packages/guides-restructured-text/src/RestructuredText/TextRoles/AbstractReferenceTextRole.php b/packages/guides-restructured-text/src/RestructuredText/TextRoles/AbstractReferenceTextRole.php
@@ -6,22 +6,22 @@
 
 use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
-use phpDocumentor\Guides\RestructuredText\Parser\EmbeddedUriParser;
+use phpDocumentor\Guides\RestructuredText\Parser\References\EmbeddedReferenceParser;
 
 /** @see https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#embedded-uris-and-aliases */
 abstract class AbstractReferenceTextRole implements TextRole
 {
-    use EmbeddedUriParser;
+    use EmbeddedReferenceParser;
 
     public function processNode(
         DocumentParserContext $documentParserContext,
         string $role,
         string $content,
         string $rawContent,
     ): AbstractLinkInlineNode {
-        $parsed = $this->extractEmbeddedUri($content);
+        $referenceData = $this->extractEmbeddedReference($content);
 
-        return $this->createNode($parsed['uri'], $parsed['text'], $role);
+        return $this->createNode($referenceData->reference, $referenceData->text, $role);
     }
 
     abstract protected function createNode(string $referenceTarget, string|null $referenceName, string $role): AbstractLinkInlineNode;
diff --git a/packages/guides-restructured-text/src/RestructuredText/Toc/ToctreeBuilder.php b/packages/guides-restructured-text/src/RestructuredText/Toc/ToctreeBuilder.php
@@ -6,15 +6,15 @@
 
 use phpDocumentor\Guides\Nodes\Menu\MenuDefinitionLineNode;
 use phpDocumentor\Guides\ParserContext;
-use phpDocumentor\Guides\RestructuredText\Parser\EmbeddedUriParser;
 use phpDocumentor\Guides\RestructuredText\Parser\LinesIterator;
+use phpDocumentor\Guides\RestructuredText\Parser\References\EmbeddedReferenceParser;
 
 use function array_filter;
 use function array_map;
 
 class ToctreeBuilder
 {
-    use EmbeddedUriParser;
+    use EmbeddedReferenceParser;
 
     /**
      * @param mixed[] $options
@@ -45,8 +45,8 @@ private function parseToctreeEntryLines(LinesIterator $lines): array
 
         $result = [];
         foreach ($linesArray as $line) {
-            $parsed = $this->extractEmbeddedUri($line);
-            $result[] = new MenuDefinitionLineNode($parsed['uri'], $parsed['text']);
+            $referenceData = $this->extractEmbeddedReference($line);
+            $result[] = new MenuDefinitionLineNode($referenceData->reference, $referenceData->text);
         }
 
         return $result;

Original file line number	Diff line number	Diff line change
`@@ -20,24 +20,23 @@`
`20`	`20`
`21`	`21`	`abstract class ReferenceRule extends AbstractInlineRule`
`22`	`22`	`{`
`23`		`- protected function createReference(BlockContext $blockContext, string $link, string\|null $embeddedUrl = null, bool $registerLink = true): AbstractLinkInlineNode`
	`23`	`+ protected function createReference(BlockContext $blockContext, string $reference, string\|null $text = null, bool $registerLink = true): AbstractLinkInlineNode`
`24`	`24`	`{`
`25`	`25`	`// the link may have a new line in it, so we need to strip it`
`26`	`26`	`// before setting the link and adding a token to be replaced`
`27`		`- $link = str_replace("\n", ' ', $link);`
`28`		`- $link = trim(preg_replace('/\s+/', ' ', $link) ?? '');`
	`27`	`+ $reference = str_replace("\n", ' ', $reference);`
	`28`	`+ $reference = trim(preg_replace('/\s+/', ' ', $reference) ?? '');`
`29`	`29`
`30`		`- $targetLink = $embeddedUrl ?? $link;`
`31`		`- if (str_ends_with($targetLink, '.rst') && filter_var($targetLink, FILTER_VALIDATE_URL) === false) {`
`32`		`- $targetLink = substr($targetLink, 0, -4);`
	`30`	`+ if (str_ends_with($reference, '.rst') && filter_var($reference, FILTER_VALIDATE_URL) === false) {`
	`31`	`+ $reference = substr($reference, 0, -4);`
`33`	`32`
`34`		`- return new DocReferenceNode($targetLink, $link);`
	`33`	`+ return new DocReferenceNode($reference, $text ?? $reference);`
`35`	`34`	`}`
`36`	`35`
`37`		`- if ($registerLink && $embeddedUrl !== null) {`
`38`		`- $blockContext->getDocumentParserContext()->setLink($link, $embeddedUrl);`
	`36`	`+ if ($registerLink && $text !== null) {`
	`37`	`+ $blockContext->getDocumentParserContext()->setLink($text, $reference);`
`39`	`38`	`}`
`40`	`39`
`41`		`- return new HyperLinkNode($link, $targetLink);`
	`40`	`+ return new HyperLinkNode($text ?? $reference, $reference);`
`42`	`41`	`}`
`43`	`42`	`}`
Original file line number	Diff line number	Diff line change
`@@ -2,27 +2,26 @@`
`2`	`2`
`3`	`3`	`declare(strict_types=1);`
`4`	`4`
`5`		`-namespace phpDocumentor\Guides\RestructuredText\Parser;`
	`5`	`+namespace phpDocumentor\Guides\RestructuredText\Parser\References;`
`6`	`6`
`7`	`7`	`use function preg_match;`
`8`	`8`
`9`		`-trait EmbeddedUriParser`
	`9`	`+trait EmbeddedReferenceParser`
`10`	`10`	`{`
`11`		`- /** @return array{text:?string,uri:string} */`
`12`		`- private function extractEmbeddedUri(string $text): array`
	`11`	`+ private function extractEmbeddedReference(string $text): ReferenceData`
`13`	`12`	`{`
`14`	`13`	`preg_match('/^(.*?)(?:(?:\s\|^)<([^<]+)>)?$/s', $text, $matches);`
`15`	`14`
`16`	`15`	`$text = $matches[1] === '' ? null : $matches[1];`
`17`		`- $uri = $matches[1];`
	`16`	`+ $reference = $matches[1];`
`18`	`17`
`19`	`18`	`if (isset($matches[2])) {`
`20`	`19`	`// there is an embedded URI, text and URI are different`
`21`		`- $uri = $matches[2];`
	`20`	`+ $reference = $matches[2];`
`22`	`21`	`} else {`
`23`	`22`	`$text = null;`
`24`	`23`	`}`
`25`	`24`
`26`		`- return ['text' => $text, 'uri' => $uri];`
	`25`	`+ return new ReferenceData($reference, $text);`
`27`	`26`	`}`
`28`	`27`	`}`