Deprecate legacy tilde-to-NBSP behavior

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

@@ -373,6 +373,7 @@
         ->set(DocumentRule::class)
         ->set(InlineParser::class)
         ->arg('$inlineRules', tagged_iterator('phpdoc.guides.parser.rst.inline_rule'))
+        ->arg('$disableLegacyTilde', false)
         ->set(GlobSearcher::class)
         ->set(ToctreeBuilder::class)
         ->set(InlineMarkupRule::class)

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

@@ -34,6 +34,10 @@
 /** @extends AbstractLexer<int, string> */
 final class InlineLexer extends AbstractLexer
 {
+    public function __construct(private readonly bool $disableLegacyTilde = false)
+    {
+    }
+
     public const WORD = 1;
     public const UNDERSCORE = 2;
     public const ANONYMOUS_END = 3;
@@ -131,7 +135,7 @@ protected function getType(string &$value)
             '#' => self::OCTOTHORPE,
             '[' => self::ANNOTATION_START,
             ']' => self::ANNOTATION_END,
-            '~' => self::NBSP,
+            '~' => $this->disableLegacyTilde ? null : self::NBSP,
             '\\' => self::BACKSLASH,
             default => null,
         };

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

@@ -33,8 +33,11 @@
     private array $cache = [];
 
     /** @param iterable<InlineRule> $inlineRules */
-    public function __construct(iterable $inlineRules)
+    public function __construct(
+        iterable $inlineRules,
+        private readonly bool $disableLegacyTilde = false,
+    )
     {
         $this->rules = array_filter([...$inlineRules], static fn ($rule) => $rule instanceof CachableInlineRule === false);
         usort($this->rules, static fn (InlineRule $a, InlineRule $b): int => $a->getPriority() > $b->getPriority() ? -1 : 1);
         foreach ($inlineRules as $rule) {
@@ -48,7 +51,7 @@
 
     public function parse(string $content, BlockContext $blockContext): InlineCompoundNode
     {
-        $lexer = new InlineLexer();
+        $lexer = new InlineLexer($this->disableLegacyTilde);
         $lexer->setInput($content);
         $lexer->moveNext();
         $lexer->moveNext();

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

@@ -34,6 +34,24 @@ public function testLexer(string $input, array $result): void
         }
     }
 
+    public function testTildeIsNbspByDefault(): void
+    {
+        $lexer = new InlineLexer();
+        $lexer->setInput('~');
+        $lexer->moveNext();
+        $lexer->moveNext();
+        assertEquals(InlineLexer::NBSP, $lexer->token?->type);
+    }
+
+    public function testTildeIsWordWhenLegacyTildeDisabled(): void
+    {
+        $lexer = new InlineLexer(disableLegacyTilde: true);
+        $lexer->setInput('~');
+        $lexer->moveNext();
+        $lexer->moveNext();
+        assertEquals(InlineLexer::WORD, $lexer->token?->type);
+    }
+
     /** @return array<string, array<string | int[]>> */
     public static function inlineLexerProvider(): array
     {