Publish Cursor::matchInPlace() and deprecate the anchored RegexHelper constants (#1147)

Author: colinodell

CHANGELOG.md

@@ -8,12 +8,18 @@ Updates should follow the [Keep a CHANGELOG](https://keepachangelog.com/) princi
 
 ### Added
 - Added a new `table_of_contents/max_placeholder_entries` option to limit how many table of contents entries a document may render across all of its placeholders (#1134)
+- Added `Cursor::matchInPlace()`, which matches a regular expression at the cursor's position within the line using PCRE's native offset semantics instead of copying the remainder (#1145)
+    - `\G` anchors at the cursor, `^` anchors at the start of the line, and lookbehinds and `\b` see the characters actually preceding the cursor; this keeps scanning loops linear and enables left-context assertions that `match()` cannot express
+- Added `RegexHelper::PARTIAL_LINK_TITLE_UNANCHORED` and `RegexHelper::PARTIAL_LINK_DESTINATION_BRACES`, unanchored fragments so each call site can supply its own anchor
 
 ### Changed
 - Changed the `TableOfContents` extension to render the table of contents once and share it across all placeholders instead of cloning it into each one (#1134)
     - A custom renderer registered for the `TableOfContents` node is no longer called once per placeholder, so it must return the same markup each time it is called for a given document (#1134)
     - The first placeholder receives the table of contents itself, so a document still contains a `TableOfContents` node for listeners which locate and reposition it (#1143)
 
+### Deprecated
+- Deprecated `RegexHelper::PARTIAL_LINK_TITLE` and `RegexHelper::REGEX_LINK_DESTINATION_BRACES`; use the unanchored variants with an explicit anchor instead
+
 ## [2.9.2] - 2026-08-10
 
 This release fixes a regression introduced in 2.9.0 which changed the behavior of `Cursor::match()` for certain regular expression patterns.

docs/2.x/customization/cursor.md

@@ -57,11 +57,33 @@ You can then call any of the following methods to parse the string within that `
 | `advanceToNextNonSpaceOrTab()`     | Advances forward past all spaces and tabs found, returning the number of such characters found                                  |
 | `advanceToNextNonSpaceOrNewline()` | Advances forward past all spaces and newlines found, returning the number of such characters found                              |
 | `advanceToEnd()`                   | Advances the position to the very end of the string, returning the number of such characters passed                             |
-| `match(string $regex)`             | Attempts to match the given `$regex`; returns `null` if matching fails, otherwise it advances past and returns the matched text |
+| `match(string $regex)`             | Attempts to match the given `$regex` against the remainder; returns `null` if matching fails, otherwise it advances past and returns the matched text |
+| `matchInPlace(string $regex)`      | Like `match()`, but matches at the cursor's position within the whole line instead of copying the remainder; see below          |
 | `getPreviousText()`                | Returns the text that was just advanced through during the last `advance__()` or `match()` operation                            |
 | `getRemainder()`                   | Returns the contents of the string from the current position through the end of the string                                      |
 | `isBlank()`                        | Returns whether the remainder is blank (we're at the end or only space characters remain)                                       |
 | `isAtEnd()`                        | Returns whether the cursor has reached the end of the string                                                                    |
 | `saveState()`                      | Encapsulates the current state of the cursor into an `array` in case you need to `restoreState()` later                         |
 | `restoreState($state)`             | Pass the result of `saveState()` back into here to restore the original state of the `Cursor`                                   |
 | `getLine()`                        | Returns the entire string (not taking the position into account)                                                                |
+
+## Regular Expression Matching
+
+The `Cursor` offers two ways to match a regular expression at the current position.  They differ in what the pattern is matched against:
+
+- **`match()`** copies the remainder and matches against that copy, so the subject begins at the cursor.  `^` and `\A` anchor at the cursor, and constructs which examine what precedes the match position (lookbehinds, `\b`) see the start of the subject there — never the actual preceding characters.
+- **`matchInPlace()`** (available since 2.10) matches against the whole line starting at the cursor's position, using PCRE's native offset semantics.  `\G` anchors at the cursor, `^` means the start of the line, and lookbehinds and `\b` see the characters actually preceding the cursor.
+
+`matchInPlace()` has two advantages:
+
+- It avoids copying the remainder, so repeated calls (such as a scanning loop) stay fast instead of paying for a copy of everything left in the line on every call.
+- Because the text before the cursor stays visible to the pattern, it can answer contextual questions `match()` cannot — for example, `/(?<!\w)@\w+/` only matching a mention when the preceding character isn't a word character.
+
+One exception: when the cursor has partially consumed a tab, no position within the line can represent it, so `matchInPlace()` falls back to matching a copy of the remainder with the leftover tab expanded into spaces.  `\G` still anchors at the cursor there, but the text before the cursor is not visible to the pattern in that state.
+
+To migrate a pattern from `match()` to `matchInPlace()`, replace its leading `^` (or `\A`) with `\G`, and double-check that any `\b` or lookbehind still means what you want now that it can see the preceding text:
+
+```php
+$cursor->match('/^#+/');         // anchors at the cursor
+$cursor->matchInPlace('/\G#+/'); // equivalent, without copying the remainder
+```

src/Extension/CommonMark/Parser/Inline/BacktickParser.php

@@ -56,13 +56,13 @@ public function parse(InlineParserContext $inlineContext): bool
         if ($this->findMatchingTicks(\strlen($ticks), $cursor)) {
             $code = $cursor->getSubstring($currentPosition, $cursor->getPosition() - $currentPosition - \strlen($ticks));
 
-            $c = \preg_replace('/\n/', ' ', $code) ?? '';
+            $c = \str_replace("\n", ' ', $code);
 
             if (
                 $c !== '' &&
                 $c[0] === ' ' &&
                 \substr($c, -1, 1) === ' ' &&
-                \preg_match('/[^ ]/', $c)
+                \strspn($c, ' ') !== \strlen($c)
             ) {
                 $c = \substr($c, 1, -1);
             }

src/Parser/Cursor.php

@@ -607,9 +607,6 @@ public function match(string $regex): ?string
      * spaces; "\G" still anchors at the cursor there, but the line content before it is not
      * visible in that case.
      *
-     * @internal Planned to become public API in 2.10; until then the name and contract may
-     *           change without notice.
-     *
      * @psalm-param non-empty-string $regex
      */
     public function matchInPlace(string $regex): ?string

src/Util/RegexHelper.php

@@ -62,14 +62,14 @@ final class RegexHelper
     public const PARTIAL_HTMLBLOCKOPEN         = '<(?:' . self::PARTIAL_BLOCKTAGNAME . '(?:[\s\/>]|$)' . '|' .
         '\/' . self::PARTIAL_BLOCKTAGNAME . '(?:[\s>]|$)' . '|' . '[?!])';
     /**
-     * @internal Unanchored so each call site can supply its own anchor ("^" against a detached
-     *           string, "\G" at a cursor position). PARTIAL_LINK_TITLE is composed from this
-     *           and must keep its value, so only this fragment should be used in new code.
+     * Unanchored so each call site can supply its own anchor: "^" against a detached string,
+     * or "\G" at a cursor position (see Cursor::matchInPlace()).
      */
     public const PARTIAL_LINK_TITLE_UNANCHORED = '(?:"(' . self::PARTIAL_ESCAPED_CHAR . '|[^"\x00])*+"' .
         '|' . '\'(' . self::PARTIAL_ESCAPED_CHAR . '|[^\'\x00])*+\'' .
         '|' . '\((' . self::PARTIAL_ESCAPED_CHAR . '|[^()\x00])*+\))';
-    public const PARTIAL_LINK_TITLE            = '^' . self::PARTIAL_LINK_TITLE_UNANCHORED;
+    /** @deprecated since 2.10; use {@link RegexHelper::PARTIAL_LINK_TITLE_UNANCHORED} with an explicit anchor instead */
+    public const PARTIAL_LINK_TITLE = '^' . self::PARTIAL_LINK_TITLE_UNANCHORED;
 
     public const REGEX_PUNCTUATION        = '/^[\p{P}\p{S}]/u';
     public const REGEX_UNSAFE_PROTOCOL    = '/^(?:javascript|vbscript|file|data):/i';
@@ -80,13 +80,12 @@ final class RegexHelper
     public const REGEX_UNICODE_WHITESPACE_CHAR = '/^\pZ|\s/u';
     public const REGEX_THEMATIC_BREAK          = '/^(?:(?:\*[ \t]*){3,}|(?:_[ \t]*){3,}|(?:-[ \t]*){3,})$/';
     /**
-     * @internal Unanchored so each call site can supply its own anchor ("^" against a detached
-     *           string, "\G" at a cursor position). REGEX_LINK_DESTINATION_BRACES is composed
-     *           from this and must keep its value, so only this fragment should be used in new
-     *           code.
+     * Unanchored so each call site can supply its own anchor: "^" against a detached string,
+     * or "\G" at a cursor position (see Cursor::matchInPlace()).
      */
     public const PARTIAL_LINK_DESTINATION_BRACES = '(?:<(?:[^<>\\n\\\\\\x00]|\\\\.)*>)';
-    public const REGEX_LINK_DESTINATION_BRACES   = '/^' . self::PARTIAL_LINK_DESTINATION_BRACES . '/';
+    /** @deprecated since 2.10; use {@link RegexHelper::PARTIAL_LINK_DESTINATION_BRACES} with an explicit anchor instead */
+    public const REGEX_LINK_DESTINATION_BRACES = '/^' . self::PARTIAL_LINK_DESTINATION_BRACES . '/';
 
     /**
      * @psalm-pure

tests/unit/Util/RegexHelperTest.php

@@ -456,9 +456,8 @@ public static function dataForTestIsLinkPotentiallyUnsafe(): iterable
     }
 
     /**
-     * These public constants are now composed from internal unanchored fragments (which the
-     * cursor-based call sites anchor with "\G" instead). The public values are part of the BC
-     * surface and must not change before 3.0, so pin them to their exact historical values.
+     * The deprecated anchored constants remain part of the BC surface until 3.0 and must keep
+     * their exact historical values, so pin them here.
      */
     public function testAnchoredConstantsKeepTheirHistoricalValues(): void
     {