TASK: Prepare Lexer interface for parser use cases

src/Language/Lexer/CharacterStream/CharacterStream.php

@@ -24,6 +24,9 @@
 
 use PackageFactory\ComponentEngine\Parser\Source\Position;
 
+/**
+ * @internal
+ */
 final class CharacterStream
 {
     private int $byte;
@@ -81,4 +84,25 @@ public function getPreviousPosition(): Position
     {
         return $this->cursor->getPreviousPosition();
     }
+
+    public function makeSnapshot(): CharacterStreamSnapshot
+    {
+        return new CharacterStreamSnapshot(
+            byte: $this->byte,
+            cursor: $this->cursor->makeSnapshot(),
+            characterUnderCursor: $this->characterUnderCursor
+        );
+    }
+
+    public function restoreSnapshot(CharacterStreamSnapshot $snapshot): void
+    {
+        $this->byte = $snapshot->byte;
+        $this->cursor->restoreSnapshot($snapshot->cursor);
+        $this->characterUnderCursor = $snapshot->characterUnderCursor;
+    }
+
+    public function getRest(): string
+    {
+        return $this->characterUnderCursor . substr($this->source, $this->byte);
+    }
 }

src/Language/Lexer/CharacterStream/CharacterStreamSnapshot.php

@@ -0,0 +1,36 @@
+<?php
+
+/**
+ * PackageFactory.ComponentEngine - Universal View Components for PHP
+ *   Copyright (C) 2023 Contributors of PackageFactory.ComponentEngine
+ *
+ *   This program is free software: you can redistribute it and/or modify
+ *   it under the terms of the GNU General Public License as published by
+ *   the Free Software Foundation, either version 3 of the License, or
+ *   (at your option) any later version.
+ *
+ *   This program is distributed in the hope that it will be useful,
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *   GNU General Public License for more details.
+ *
+ *   You should have received a copy of the GNU General Public License
+ *   along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+declare(strict_types=1);
+
+namespace PackageFactory\ComponentEngine\Language\Lexer\CharacterStream;
+
+/**
+ * @internal
+ */
+final class CharacterStreamSnapshot
+{
+    public function __construct(
+        public readonly int $byte,
+        public readonly CursorSnapshot $cursor,
+        public readonly ?string $characterUnderCursor = null
+    ) {
+    }
+}

src/Language/Lexer/CharacterStream/Cursor.php

@@ -24,6 +24,9 @@
 
 use PackageFactory\ComponentEngine\Parser\Source\Position;
 
+/**
+ * @internal
+ */
 final class Cursor
 {
     private int $currentLineNumber = 0;
@@ -58,4 +61,22 @@ public function getPreviousPosition(): Position
 
         return new Position($this->previousLineNumber, $this->previousColumnNumber);
     }
+
+    public function makeSnapshot(): CursorSnapshot
+    {
+        return new CursorSnapshot(
+            currentLineNumber: $this->currentLineNumber,
+            currentColumnNumber: $this->currentColumnNumber,
+            previousLineNumber: $this->previousLineNumber,
+            previousColumnNumber: $this->previousColumnNumber
+        );
+    }
+
+    public function restoreSnapshot(CursorSnapshot $snapshot): void
+    {
+        $this->currentLineNumber = $snapshot->currentLineNumber;
+        $this->currentColumnNumber = $snapshot->currentColumnNumber;
+        $this->previousLineNumber = $snapshot->previousLineNumber;
+        $this->previousColumnNumber = $snapshot->previousColumnNumber;
+    }
 }

src/Language/Lexer/CharacterStream/CursorSnapshot.php

@@ -0,0 +1,37 @@
+<?php
+
+/**
+ * PackageFactory.ComponentEngine - Universal View Components for PHP
+ *   Copyright (C) 2023 Contributors of PackageFactory.ComponentEngine
+ *
+ *   This program is free software: you can redistribute it and/or modify
+ *   it under the terms of the GNU General Public License as published by
+ *   the Free Software Foundation, either version 3 of the License, or
+ *   (at your option) any later version.
+ *
+ *   This program is distributed in the hope that it will be useful,
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *   GNU General Public License for more details.
+ *
+ *   You should have received a copy of the GNU General Public License
+ *   along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+declare(strict_types=1);
+
+namespace PackageFactory\ComponentEngine\Language\Lexer\CharacterStream;
+
+/**
+ * @internal
+ */
+final class CursorSnapshot
+{
+    public function __construct(
+        public readonly int $currentLineNumber,
+        public readonly int $currentColumnNumber,
+        public readonly int $previousLineNumber,
+        public readonly int $previousColumnNumber
+    ) {
+    }
+}