Use list<T> in ArrayBuffer instead of custom keys (possibly keys duplication fix).

Author: SerafimArts

.github/workflows/main.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        php: [ '7.4', '8.0', '8.1', '8.2', '8.3', '8.4' ]
+        php: [ '8.1', '8.2', '8.3', '8.4' ]
         os: [ ubuntu-latest, macos-latest, windows-latest ]
         stability: [ prefer-lowest, prefer-stable ]
     steps:

composer.json

@@ -17,12 +17,13 @@
     ],
     "require": {
         "php": "^8.1",
-        "phplrt/source": "^4.0",
-        "phplrt/buffer": "^4.0",
-        "phplrt/exception": "^4.0",
-        "phplrt/parser-contracts": "^4.0",
-        "phplrt/lexer-contracts": "^4.0",
-        "phplrt/ast-contracts": "^4.0"
+        "phplrt/source": "^3.7",
+        "phplrt/buffer": "^3.7",
+        "phplrt/exception": "^3.7",
+        "phplrt/parser-contracts": "^3.7",
+        "phplrt/lexer-contracts": "^3.7",
+        "phplrt/ast-contracts": "^3.7",
+        "symfony/deprecation-contracts": "^2.5|^3.0"
     },
     "replace": {
         "phplrt/grammar": "<=3.1",
@@ -31,11 +32,14 @@
     "autoload": {
         "psr-4": {
             "Phplrt\\Parser\\": "src"
-        }
+        },
+        "files": [
+            "src/polyfill.php"
+        ]
     },
     "require-dev": {
-        "phplrt/visitor": "^4.0",
-        "phplrt/lexer": "^4.0",
+        "phplrt/visitor": "^3.7",
+        "phplrt/lexer": "^3.7",
         "phpunit/phpunit": "^10.5|^11.0",
         "phpstan/extension-installer": "^1.4",
         "phpstan/phpstan": "^1.11",
@@ -48,16 +52,19 @@
         }
     },
     "provide": {
-        "phplrt/parser-contracts-implementation": "^4.0"
+        "phplrt/parser-contracts-implementation": "^3.7"
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "4.x-dev",
-            "dev-main": "4.x-dev"
+            "dev-master": "3.x-dev",
+            "dev-main": "3.x-dev"
         }
     },
     "config": {
-        "sort-packages": true
+        "sort-packages": true,
+        "allow-plugins": {
+            "phpstan/extension-installer": true
+        }
     },
     "minimum-stability": "dev",
     "prefer-stable": true

resources/.deprecations.php

@@ -0,0 +1,91 @@
+<?php
+
+namespace Phplrt\Grammar {
+
+    /**
+     * @deprecated since phplrt 3.2 and will be removed in 4.0, use {@see \Phplrt\Parser\Grammar\Terminal} instead.
+     */
+    abstract class Terminal extends \Phplrt\Parser\Grammar\Terminal
+    {
+    }
+
+    /**
+     * @deprecated since phplrt 3.2 and will be removed in 4.0, use {@see \Phplrt\Parser\Grammar\Repetition} instead.
+     */
+    class Repetition extends \Phplrt\Parser\Grammar\Repetition
+    {
+    }
+
+    /**
+     * @deprecated since phplrt 3.2 and will be removed in 4.0, use {@see \Phplrt\Parser\Grammar\Optional} instead.
+     */
+    class Optional extends \Phplrt\Parser\Grammar\Optional
+    {
+    }
+
+    /**
+     * @deprecated since phplrt 3.2 and will be removed in 4.0, use {@see \Phplrt\Parser\Grammar\Production} instead.
+     */
+    abstract class Production extends \Phplrt\Parser\Grammar\Production
+    {
+    }
+
+    /**
+     * @deprecated since phplrt 3.2 and will be removed in 4.0, use {@see \Phplrt\Parser\Grammar\Concatenation} instead.
+     */
+    class Concatenation extends \Phplrt\Parser\Grammar\Concatenation
+    {
+    }
+
+    /**
+     * @deprecated since phplrt 3.2 and will be removed in 4.0, use {@see \Phplrt\Parser\Grammar\Builder} instead.
+     */
+    class Builder extends \Phplrt\Parser\Grammar\Builder
+    {
+    }
+
+    /**
+     * @deprecated since phplrt 3.2 and will be removed in 4.0, use {@see \Phplrt\Parser\Grammar\Rule} instead.
+     */
+    class Rule extends \Phplrt\Parser\Grammar\Rule
+    {
+    }
+
+    /**
+     * @deprecated since phplrt 3.2 and will be removed in 4.0, use {@see \Phplrt\Parser\Grammar\Lexeme} instead.
+     */
+    class Lexeme extends \Phplrt\Parser\Grammar\Lexeme
+    {
+    }
+
+    /**
+     * @deprecated since phplrt 3.2 and will be removed in 4.0, use {@see \Phplrt\Parser\Grammar\Alternation} instead.
+     */
+    class Alternation extends \Phplrt\Parser\Grammar\Alternation
+    {
+    }
+}
+
+namespace Phplrt\Contracts\Grammar {
+
+    /**
+     * @deprecated since phplrt 3.2 and will be removed in 4.0, use {@see \Phplrt\Parser\Grammar\ProductionInterface} instead.
+     */
+    interface ProductionInterface extends \Phplrt\Parser\Grammar\ProductionInterface
+    {
+    }
+
+    /**
+     * @deprecated since phplrt 3.2 and will be removed in 4.0, use {@see \Phplrt\Parser\Grammar\RuleInterface} instead.
+     */
+    interface RuleInterface extends \Phplrt\Parser\Grammar\RuleInterface
+    {
+    }
+
+    /**
+     * @deprecated since phplrt 3.2 and will be removed in 4.0, use {@see \Phplrt\Parser\Grammar\TerminalInterface} instead.
+     */
+    interface TerminalInterface extends \Phplrt\Parser\Grammar\TerminalInterface
+    {
+    }
+}

src/BuilderInterface.php

@@ -10,7 +10,10 @@
 interface BuilderInterface
 {
     /**
+     * Note: Native type hints will be added in phplrt 4.0, as adding them
+     *       clearly breaks backward compatibility with inheritance.
+     *
      * @param NodeInterface|TokenInterface|iterable<NodeInterface|TokenInterface> $result
      */
-    public function build(Context $context, mixed $result);
+    public function build(Context $context, /* mixed */ $result)/* : mixed */;
 }

src/Context.php

@@ -17,8 +17,13 @@
  * The presence of public modifiers in fields is required only to speed up the
  * parser, since direct access is several times faster than using methods of
  * setting values or creating a new class at each step of the parser.
+ *
+ * @property-read ReadableInterface $source
+ * @property-read BufferInterface $buffer
+ *
+ * @final marked as final since phplrt 3.4 and will be final since 4.0
  */
-final class Context
+class Context implements ContextInterface
 {
     use ContextOptionsTrait;
 
@@ -55,7 +60,6 @@ final class Context
     public ?RuleInterface $rule = null;
 
     /**
-     * @param array-key $state
      * @param array<non-empty-string, mixed> $options
      */
     public function __construct(
@@ -73,9 +77,11 @@ public function __construct(
          * Note: This is a stateful data and may cause a race condition error. In
          * the future, it is necessary to delete this data with a replacement for
          * the stateless structure.
+         *
+         * @var array-key
          */
-        public string|int $state,
-        array $options
+        public int|string $state,
+        array $options,
     ) {
         $this->options = $options;
         $this->lastOrdinalToken = $this->lastProcessedToken = $this->buffer->current();

src/ContextInterface.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phplrt\Parser;
+
+use Phplrt\Buffer\BufferInterface;
+use Phplrt\Contracts\Lexer\TokenInterface;
+use Phplrt\Contracts\Source\ReadableInterface;
+use Phplrt\Parser\Grammar\RuleInterface;
+
+/**
+ * Interface provides full information about execution context.
+ *
+ * @deprecated since phplrt 3.4 and will be removed in 4.0, please use {@see Context} instead.
+ */
+interface ContextInterface extends ContextOptionsInterface
+{
+    /**
+     * Returns the source being processed.
+     */
+    public function getSource(): ReadableInterface;
+
+    /**
+     * Returns a lexer's buffer.
+     */
+    public function getBuffer(): BufferInterface;
+
+    /**
+     * Returns the parser's current state identifier.
+     *
+     * Note: Please note that this value is mutable and may change over time.
+     *
+     * @return array-key
+     */
+    public function getState();
+
+    /**
+     * Returns the parser's current state rule.
+     *
+     * Note: Please note that this value is mutable and may change over time.
+     */
+    public function getRule(): ?RuleInterface;
+
+    /**
+     * Returns the parser's current AST node.
+     *
+     * If the parser does not contain any nodes of the abstract syntax tree,
+     * then the method will return NULL.
+     *
+     * Note: Please note that this value is mutable and may change over time.
+     */
+    public function getNode(): ?object;
+
+    /**
+     * Returns the current parsing token.
+     *
+     * Note: Please note that this value is mutable and may change over time.
+     */
+    public function getToken(): TokenInterface;
+}

src/ContextOptionsInterface.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phplrt\Parser;
+
+use Phplrt\Parser\Context\ContextOptionsProviderInterface;
+
+/**
+ * @deprecated since phplrt 3.4 and will be removed in 4.0, please
+ *             use {@see ContextOptionsProviderInterface} instead.
+ */
+interface ContextOptionsInterface extends ContextOptionsProviderInterface {}

src/Environment/XdebugSelector.php

@@ -33,11 +33,11 @@ final class XdebugSelector implements SelectorInterface
      */
     private readonly bool $enabled;
 
-    /**
-     * @param int<0, max> $expectedRecursionDepth
-     */
     public function __construct(
-        private readonly int $expectedRecursionDepth = self::DEFAULT_EXPECTED_RECURSION_DEPTH,
+        /**
+         * @var int<0, max>
+         */
+        private readonly int $expectedRecursionDepth = self::DEFAULT_EXPECTED_RECURSION_DEPTH
     ) {
         $this->enabled = \extension_loaded('xdebug');
         $this->actualRecursionDepth = (int) \ini_get('xdebug.max_nesting_level');

src/Exception/UnexpectedTokenWithHintsException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phplrt\Parser\Exception;
+
+/**
+ * @deprecated since phplrt 3.4 and will be removed in 4.0, please
+ *             use {@see UnexpectedTokenException} exception instead.
+ */
+class UnexpectedTokenWithHintsException extends UnexpectedTokenException {}

src/Grammar/Alternation.php

@@ -11,10 +11,10 @@
  */
 class Alternation extends Production
 {
-    /**
-     * @param list<array-key> $sequence
-     */
     public function __construct(
+        /**
+         * @var list<array-key>
+         */
         public readonly array $sequence,
     ) {}
 
@@ -31,7 +31,7 @@ public function getTerminals(array $rules): iterable
         return $result;
     }
 
-    public function reduce(BufferInterface $buffer, \Closure $reduce)
+    public function reduce(BufferInterface $buffer, \Closure $reduce): mixed
     {
         $rollback = $buffer->key();