diff --git a/src/Compiler/CompilerInterface.php b/src/Compiler/CompilerInterface.php index 8fe769f..2c349a0 100644 --- a/src/Compiler/CompilerInterface.php +++ b/src/Compiler/CompilerInterface.php @@ -7,13 +7,14 @@ /** * @deprecated since phplrt 3.6 and will be removed in 4.0. * - * @internal This is an internal library interface, please do not use it in your code. + * @internal this is an internal library interface, please do not use it in your code * @psalm-internal Phplrt\Lexer */ interface CompilerInterface { /** * @param array $tokens + * * @return non-empty-string */ public function compile(array $tokens): string; diff --git a/src/Compiler/Markers.php b/src/Compiler/Markers.php index d7399f4..83f3952 100644 --- a/src/Compiler/Markers.php +++ b/src/Compiler/Markers.php @@ -7,7 +7,7 @@ /** * @deprecated since phplrt 3.6 and will be removed in 4.0. * - * @internal This is an internal library class, please do not use it in your code. + * @internal this is an internal library class, please do not use it in your code * @psalm-internal Phplrt\Lexer */ class Markers extends PCRECompiler @@ -24,6 +24,7 @@ class Markers extends PCRECompiler /** * @param array $chunks + * * @return non-empty-string * * @psalm-suppress MoreSpecificReturnType @@ -37,6 +38,7 @@ protected function buildTokens(array $chunks): string /** * @param non-empty-string $name * @param non-empty-string $pattern + * * @return non-empty-string */ protected function buildToken(string $name, string $pattern): string diff --git a/src/Compiler/PCRECompiler.php b/src/Compiler/PCRECompiler.php index 8c9ef47..932bc05 100644 --- a/src/Compiler/PCRECompiler.php +++ b/src/Compiler/PCRECompiler.php @@ -9,7 +9,7 @@ /** * @deprecated since phplrt 3.6 and will be removed in 4.0. * - * @internal This is an internal library class, please do not use it in your code. + * @internal this is an internal library class, please do not use it in your code * @psalm-internal Phplrt\Lexer */ abstract class PCRECompiler implements CompilerInterface @@ -172,9 +172,8 @@ abstract class PCRECompiler implements CompilerInterface /** * @param array|null $flags - * @param bool|null $debug */ - public function __construct(array $flags = null, bool $debug = null) + public function __construct(?array $flags = null, ?bool $debug = null) { /** @psalm-suppress PropertyTypeCoercion */ $this->flags = $flags ?? self::DEFAULT_FLAGS; @@ -189,6 +188,7 @@ public function __construct(array $flags = null, bool $debug = null) /** * @param array $tokens + * * @return non-empty-string * @throws CompilationException */ @@ -203,12 +203,14 @@ public function compile(array $tokens): string /** * @param array $chunks + * * @return non-empty-string */ abstract protected function buildTokens(array $chunks): string; /** * @param array $tokens + * * @return array */ private function buildChunks(array $tokens): array @@ -227,12 +229,14 @@ private function buildChunks(array $tokens): array /** * @param non-empty-string $name * @param non-empty-string $pattern + * * @return non-empty-string */ abstract protected function buildToken(string $name, string $pattern): string; /** * @param non-empty-string $name + * * @return non-empty-string */ protected function name(string $name): string @@ -243,6 +247,7 @@ protected function name(string $name): string /** * @param non-empty-string $pattern + * * @return non-empty-string */ protected function pattern(string $pattern): string @@ -255,7 +260,7 @@ protected function pattern(string $pattern): string * @param non-empty-string $pattern * @param non-empty-string|null $original */ - protected function test(string $pattern, string $original = null): void + protected function test(string $pattern, ?string $original = null): void { if ($this->debug) { \error_clear_last(); @@ -272,6 +277,7 @@ protected function test(string $pattern, string $original = null): void /** * @param non-empty-string $pcre + * * @return non-empty-string */ protected function wrap(string $pcre): string @@ -279,7 +285,7 @@ protected function wrap(string $pcre): string return $this->delimiter . $pcre . $this->delimiter . \implode('', $this->flags); } - protected function formatException(string $message, string $token = null): string + protected function formatException(string $message, ?string $token = null): string { $suffix = \sprintf(' in %s token definition', $token ?? ''); diff --git a/src/Config/HandlerInterface.php b/src/Config/HandlerInterface.php index d572a8a..a78b9f1 100644 --- a/src/Config/HandlerInterface.php +++ b/src/Config/HandlerInterface.php @@ -16,7 +16,7 @@ interface HandlerInterface /** * The method itself, which is executed while processing a token. * - * @throws LexerRuntimeExceptionInterface May throw an exception while handling the token. + * @throws LexerRuntimeExceptionInterface may throw an exception while handling the token */ public function handle(ReadableInterface $source, TokenInterface $token): ?TokenInterface; } diff --git a/src/Config/PassthroughWhenTokenHandler.php b/src/Config/PassthroughWhenTokenHandler.php index ad25800..d13a8b1 100644 --- a/src/Config/PassthroughWhenTokenHandler.php +++ b/src/Config/PassthroughWhenTokenHandler.php @@ -14,6 +14,7 @@ final class PassthroughWhenTokenHandler implements HandlerInterface { /** * @var non-empty-string + * * @readonly */ private string $name; diff --git a/src/Driver/Driver.php b/src/Driver/Driver.php index c8c01f1..5131a3c 100644 --- a/src/Driver/Driver.php +++ b/src/Driver/Driver.php @@ -9,7 +9,7 @@ /** * @deprecated since phplrt 3.6 and will be removed in 4.0. * - * @internal This is an internal library class, please do not use it in your code. + * @internal this is an internal library class, please do not use it in your code * @psalm-internal Phplrt\Lexer */ abstract class Driver implements DriverInterface @@ -38,6 +38,7 @@ public function getCompiler(): CompilerInterface /** * @param array $tokens + * * @return non-empty-string */ protected function getPattern(array $tokens): string @@ -51,6 +52,7 @@ protected function getPattern(array $tokens): string /** * @param array $tokens + * * @return non-empty-string */ protected function compile(array $tokens): string diff --git a/src/Driver/DriverInterface.php b/src/Driver/DriverInterface.php index 6d4969b..6040b96 100644 --- a/src/Driver/DriverInterface.php +++ b/src/Driver/DriverInterface.php @@ -11,7 +11,7 @@ /** * @deprecated since phplrt 3.6 and will be removed in 4.0. * - * @internal This is an internal library interface, please do not use it in your code. + * @internal this is an internal library interface, please do not use it in your code * @psalm-internal Phplrt\Lexer */ interface DriverInterface diff --git a/src/Driver/Markers.php b/src/Driver/Markers.php index d7d6ae0..c52dd2c 100644 --- a/src/Driver/Markers.php +++ b/src/Driver/Markers.php @@ -4,17 +4,17 @@ namespace Phplrt\Lexer\Driver; -use Phplrt\Contracts\Source\SourceExceptionInterface; -use Phplrt\Lexer\Token\Token; -use Phplrt\Lexer\Token\Composite; use Phplrt\Contracts\Lexer\TokenInterface; use Phplrt\Contracts\Source\ReadableInterface; +use Phplrt\Contracts\Source\SourceExceptionInterface; use Phplrt\Lexer\Compiler\Markers as MarkersCompiler; +use Phplrt\Lexer\Token\Composite; +use Phplrt\Lexer\Token\Token; /** * @deprecated since phplrt 3.6 and will be removed in 4.0. * - * @internal This is an internal library class, please do not use it in your code. + * @internal this is an internal library class, please do not use it in your code * @psalm-internal Phplrt\Lexer */ class Markers extends Driver @@ -26,15 +26,13 @@ class Markers extends Driver /** * @var non-empty-string + * * @readonly */ private string $unknown; - /** - * @param MarkersCompiler|null $compiler - */ public function __construct( - MarkersCompiler $compiler = null, + ?MarkersCompiler $compiler = null, string $unknown = self::UNKNOWN_TOKEN_NAME ) { $this->unknown = $unknown; @@ -69,6 +67,7 @@ public function run(array $tokens, ReadableInterface $source, int $offset = 0): /** * @param non-empty-string $pattern * @param int<0, max> $offset + * * @return array, array{string, int}>|array{MARK: non-empty-string}> */ private function match(string $pattern, string $source, int $offset): array @@ -94,6 +93,7 @@ private function make(string $name, array $payload): TokenInterface /** * @param non-empty-string $name * @param non-empty-array}> $payload + * * @return non-empty-array */ private function transform(string $name, array $payload): array diff --git a/src/Exception/EndlessRecursionException.php b/src/Exception/EndlessRecursionException.php index 162efea..9dde85e 100644 --- a/src/Exception/EndlessRecursionException.php +++ b/src/Exception/EndlessRecursionException.php @@ -4,12 +4,12 @@ namespace Phplrt\Lexer\Exception; -use Phplrt\Contracts\Source\ReadableInterface; use Phplrt\Contracts\Lexer\TokenInterface; +use Phplrt\Contracts\Source\ReadableInterface; class EndlessRecursionException extends UnexpectedStateException { - public static function fromState($state, ReadableInterface $src, ?TokenInterface $tok, \Throwable $e = null): self + public static function fromState($state, ReadableInterface $src, ?TokenInterface $tok, ?\Throwable $e = null): self { $message = \vsprintf('An unsolvable infinite lexer state transitions was found at %s', [ $state, diff --git a/src/Exception/LexerRuntimeException.php b/src/Exception/LexerRuntimeException.php index e11db8b..ba03aa8 100644 --- a/src/Exception/LexerRuntimeException.php +++ b/src/Exception/LexerRuntimeException.php @@ -5,9 +5,9 @@ namespace Phplrt\Lexer\Exception; use Phplrt\Contracts\Lexer\LexerRuntimeExceptionInterface; +use Phplrt\Contracts\Lexer\TokenInterface; use Phplrt\Contracts\Source\ReadableInterface; use Phplrt\Exception\RuntimeException; -use Phplrt\Contracts\Lexer\TokenInterface; abstract class LexerRuntimeException extends RuntimeException implements LexerExceptionInterface, @@ -17,7 +17,7 @@ final public function __construct( string $message, ReadableInterface $src, ?TokenInterface $tok = null, - \Throwable $prev = null + ?\Throwable $prev = null ) { parent::__construct($message, 0, $prev); diff --git a/src/Exception/UnexpectedStateException.php b/src/Exception/UnexpectedStateException.php index bcfc1fa..1bb3a8b 100644 --- a/src/Exception/UnexpectedStateException.php +++ b/src/Exception/UnexpectedStateException.php @@ -4,12 +4,12 @@ namespace Phplrt\Lexer\Exception; -use Phplrt\Contracts\Source\ReadableInterface; use Phplrt\Contracts\Lexer\TokenInterface; +use Phplrt\Contracts\Source\ReadableInterface; class UnexpectedStateException extends LexerRuntimeException { - public static function fromEmptyStates(ReadableInterface $src, \Throwable $e = null): self + public static function fromEmptyStates(ReadableInterface $src, ?\Throwable $e = null): self { $message = 'No state defined for the selected multistate lexer'; @@ -19,7 +19,7 @@ public static function fromEmptyStates(ReadableInterface $src, \Throwable $e = n /** * @param string|int $state */ - public static function fromState($state, ReadableInterface $src, ?TokenInterface $tok, \Throwable $e = null): self + public static function fromState($state, ReadableInterface $src, ?TokenInterface $tok, ?\Throwable $e = null): self { $message = \sprintf('Unrecognized token state #%s', $state); diff --git a/src/Exception/UnrecognizedTokenException.php b/src/Exception/UnrecognizedTokenException.php index 9d1d3ed..79b52d3 100644 --- a/src/Exception/UnrecognizedTokenException.php +++ b/src/Exception/UnrecognizedTokenException.php @@ -4,13 +4,13 @@ namespace Phplrt\Lexer\Exception; +use Phplrt\Contracts\Lexer\TokenInterface; use Phplrt\Contracts\Source\ReadableInterface; use Phplrt\Lexer\Token\Renderer; -use Phplrt\Contracts\Lexer\TokenInterface; class UnrecognizedTokenException extends LexerRuntimeException { - public static function fromToken(ReadableInterface $src, TokenInterface $tok, \Throwable $prev = null): self + public static function fromToken(ReadableInterface $src, TokenInterface $tok, ?\Throwable $prev = null): self { $message = \vsprintf('Syntax error, unrecognized %s', [ (new Renderer())->render($tok), diff --git a/src/Lexer.php b/src/Lexer.php index 8ea57b0..22b5f04 100644 --- a/src/Lexer.php +++ b/src/Lexer.php @@ -6,6 +6,8 @@ use Phplrt\Contracts\Lexer\LexerExceptionInterface; use Phplrt\Contracts\Lexer\LexerRuntimeExceptionInterface; +use Phplrt\Contracts\Lexer\TokenInterface; +use Phplrt\Contracts\Source\ReadableInterface; use Phplrt\Contracts\Source\SourceExceptionInterface; use Phplrt\Contracts\Source\SourceFactoryInterface; use Phplrt\Lexer\Compiler\Markers as MarkersCompiler; @@ -13,13 +15,11 @@ use Phplrt\Lexer\Config\NullHandler; use Phplrt\Lexer\Config\PassthroughHandler; use Phplrt\Lexer\Config\ThrowErrorHandler; -use Phplrt\Lexer\Exception\LexerException; -use Phplrt\Lexer\Token\UnknownToken; +use Phplrt\Lexer\Driver\DriverInterface; use Phplrt\Lexer\Driver\Markers; +use Phplrt\Lexer\Exception\LexerException; use Phplrt\Lexer\Token\EndOfInput; -use Phplrt\Lexer\Driver\DriverInterface; -use Phplrt\Contracts\Lexer\TokenInterface; -use Phplrt\Contracts\Source\ReadableInterface; +use Phplrt\Lexer\Token\UnknownToken; use Phplrt\Source\SourceFactory; /** @@ -31,6 +31,7 @@ class Lexer implements PositionalLexerInterface, MutableLexerInterface * Default token name for unidentified tokens. * * @var non-empty-string + * * @final */ public const DEFAULT_UNKNOWN_TOKEN_NAME = UnknownToken::DEFAULT_TOKEN_NAME; @@ -39,6 +40,7 @@ class Lexer implements PositionalLexerInterface, MutableLexerInterface * Default token name for end of input. * * @var non-empty-string + * * @final */ public const DEFAULT_EOI_TOKEN_NAME = EndOfInput::DEFAULT_TOKEN_NAME; @@ -63,12 +65,14 @@ class Lexer implements PositionalLexerInterface, MutableLexerInterface /** * @var non-empty-string + * * @readonly */ private string $unknown; /** * @var non-empty-string + * * @readonly */ private string $eoi; @@ -79,9 +83,9 @@ class Lexer implements PositionalLexerInterface, MutableLexerInterface private SourceFactoryInterface $sources; /** - * @param array $tokens List of - * token names/identifiers and its patterns. - * @param list $skip List of hidden token names/identifiers. + * @param array $tokens list of + * token names/identifiers and its patterns + * @param list $skip list of hidden token names/identifiers * @param HandlerInterface $onUnknownToken This setting is responsible for * the behavior of the lexer in case of detection of unrecognized * tokens. @@ -115,7 +119,7 @@ class Lexer implements PositionalLexerInterface, MutableLexerInterface public function __construct( array $tokens = [], array $skip = [], - DriverInterface $driver = null, + ?DriverInterface $driver = null, ?HandlerInterface $onHiddenToken = null, ?HandlerInterface $onUnknownToken = null, ?HandlerInterface $onEndOfInput = null, @@ -154,12 +158,13 @@ public function disableUnrecognizedTokenException(): void } /** - * @param HandlerInterface $handler A handler that defines the behavior of - * the lexer in the case of a "hidden" token. - * * @psalm-immutable This method returns a new {@see LexerInterface} instance * and does not change the current state of the lexer. + * * @api + * + * @param HandlerInterface $handler a handler that defines the behavior of + * the lexer in the case of a "hidden" token */ public function withHiddenTokenHandler(HandlerInterface $handler): self { @@ -170,12 +175,13 @@ public function withHiddenTokenHandler(HandlerInterface $handler): self } /** - * @param HandlerInterface $handler A handler that defines the behavior of - * the lexer in the case of an "unknown" token. - * * @psalm-immutable This method returns a new {@see LexerInterface} instance * and does not change the current state of the lexer. + * * @api + * + * @param HandlerInterface $handler a handler that defines the behavior of + * the lexer in the case of an "unknown" token */ public function withUnknownTokenHandler(HandlerInterface $handler): self { @@ -186,12 +192,13 @@ public function withUnknownTokenHandler(HandlerInterface $handler): self } /** - * @param HandlerInterface $handler A handler that defines the behavior of - * the lexer in the case of an "end of input" token. - * * @psalm-immutable This method returns a new {@see LexerInterface} instance * and does not change the current state of the lexer. + * * @api + * + * @param HandlerInterface $handler a handler that defines the behavior of + * the lexer in the case of an "end of input" token */ public function withEndOfInputHandler(HandlerInterface $handler): self { @@ -203,6 +210,7 @@ public function withEndOfInputHandler(HandlerInterface $handler): self /** * @deprecated since phplrt 3.6 and will be removed in 4.0. + * * @api */ public function getDriver(): DriverInterface @@ -216,6 +224,7 @@ public function getDriver(): DriverInterface /** * @deprecated since phplrt 3.6 and will be removed in 4.0. + * * @api */ public function setDriver(DriverInterface $driver): self @@ -298,18 +307,17 @@ public function remove(string ...$tokens): self * the internal state of the lexer and can be used in * asynchronous and parallel computing. * - * @param mixed $source Any source supported by the {@see SourceFactoryInterface::create()}. - * @param int<0, max> $offset Offset, starting from which you should - * start analyzing the source. - * - * @return iterable List of analyzed tokens. + * @param mixed $source any source supported by the {@see SourceFactoryInterface::create()} + * @param int<0, max> $offset offset, starting from which you should + * start analyzing the source * - * @throws LexerExceptionInterface An error occurs before source processing + * @return iterable list of analyzed tokens + * @throws LexerExceptionInterface an error occurs before source processing * starts, when the given source cannot be recognized or if the - * lexer settings contain errors. - * @throws LexerRuntimeExceptionInterface An exception that occurs after + * lexer settings contain errors + * @throws LexerRuntimeExceptionInterface an exception that occurs after * starting the lexical analysis and indicates problems in the - * analyzed source. + * analyzed source */ public function lex($source, int $offset = 0): iterable { diff --git a/src/Multistate.php b/src/Multistate.php index c119c56..7eba65b 100644 --- a/src/Multistate.php +++ b/src/Multistate.php @@ -4,23 +4,16 @@ namespace Phplrt\Lexer; -use Phplrt\Contracts\Exception\RuntimeExceptionInterface; use Phplrt\Contracts\Lexer\LexerExceptionInterface; use Phplrt\Contracts\Lexer\LexerRuntimeExceptionInterface; use Phplrt\Contracts\Lexer\TokenInterface; -use Phplrt\Contracts\Source\ReadableInterface; -use Phplrt\Contracts\Source\SourceExceptionInterface; use Phplrt\Contracts\Source\SourceFactoryInterface; use Phplrt\Lexer\Config\HandlerInterface; -use Phplrt\Lexer\Config\NullHandler; -use Phplrt\Lexer\Config\PassthroughHandler; use Phplrt\Lexer\Config\PassthroughWhenTokenHandler; -use Phplrt\Lexer\Config\ThrowErrorHandler; +use Phplrt\Lexer\Exception\EndlessRecursionException; use Phplrt\Lexer\Exception\LexerException; use Phplrt\Lexer\Exception\UnexpectedStateException; -use Phplrt\Lexer\Exception\EndlessRecursionException; use Phplrt\Lexer\Token\EndOfInput; -use Phplrt\Source\File; use Phplrt\Source\SourceFactory; class Multistate implements PositionalLexerInterface @@ -55,7 +48,6 @@ class Multistate implements PositionalLexerInterface * * Note that you can also define your own {@see HandlerInterface} to * override behavior. - * @param non-empty-string $eoi */ public function __construct( array $states, @@ -79,8 +71,9 @@ public function __construct( } /** - * @param array-key|null $state * @api + * + * @param array-key|null $state */ public function startsWith($state): self { @@ -92,9 +85,10 @@ public function startsWith($state): self } /** + * @api + * * @param array-key $name * @param array|PositionalLexerInterface $data - * @api */ public function setState($name, $data): self { @@ -111,8 +105,9 @@ public function setState($name, $data): self } /** - * @param array-key $name * @api + * + * @param array-key $name */ public function removeState($name): self { @@ -122,10 +117,11 @@ public function removeState($name): self } /** + * @api + * * @param non-empty-string $token * @param array-key $in * @param array-key $then - * @api */ public function when(string $token, $in, $then): self { @@ -141,18 +137,17 @@ public function when(string $token, $in, $then): self * the internal state of the lexer and can be used in * asynchronous and parallel computing. * - * @param mixed $source Any source supported by the {@see SourceFactoryInterface::create()}. - * @param int<0, max> $offset Offset, starting from which you should - * start analyzing the source. + * @param mixed $source any source supported by the {@see SourceFactoryInterface::create()} + * @param int<0, max> $offset offset, starting from which you should + * start analyzing the source * - * @return iterable List of analyzed tokens. - * - * @throws LexerExceptionInterface An error occurs before source processing + * @return iterable list of analyzed tokens + * @throws LexerExceptionInterface an error occurs before source processing * starts, when the given source cannot be recognized or if the - * lexer settings contain errors. - * @throws LexerRuntimeExceptionInterface An exception that occurs after + * lexer settings contain errors + * @throws LexerRuntimeExceptionInterface an exception that occurs after * starting the lexical analysis and indicates problems in the - * analyzed source. + * analyzed source * * @psalm-suppress TypeDoesNotContainType */ @@ -190,6 +185,7 @@ public function lex($source, int $offset = 0): iterable if (!isset($this->states[$state])) { /** * @noinspection IssetArgumentExistenceInspection + * * @psalm-suppress UndefinedVariable */ throw UnexpectedStateException::fromState($state, $source, $token ?? null); diff --git a/src/MutableLexerInterface.php b/src/MutableLexerInterface.php index 4cf48d8..0b85e25 100644 --- a/src/MutableLexerInterface.php +++ b/src/MutableLexerInterface.php @@ -9,12 +9,14 @@ interface MutableLexerInterface /** * @param non-empty-string $token * @param non-empty-string $pattern + * * @return MutableLexerInterface|$this */ public function append(string $token, string $pattern): self; /** * @param array $tokens + * * @return MutableLexerInterface|$this */ public function appendMany(array $tokens): self; @@ -22,24 +24,28 @@ public function appendMany(array $tokens): self; /** * @param non-empty-string $token * @param non-empty-string $pattern + * * @return MutableLexerInterface|$this */ public function prepend(string $token, string $pattern): self; /** * @param array $tokens + * * @return MutableLexerInterface|$this */ public function prependMany(array $tokens, bool $reverseOrder = true): self; /** * @param non-empty-string ...$tokens + * * @return MutableLexerInterface|$this */ public function skip(string ...$tokens): self; /** * @param non-empty-string ...$tokens + * * @return MutableLexerInterface|$this */ public function remove(string ...$tokens): self; diff --git a/src/PositionalLexerInterface.php b/src/PositionalLexerInterface.php index 5b953c0..40c37fd 100644 --- a/src/PositionalLexerInterface.php +++ b/src/PositionalLexerInterface.php @@ -23,17 +23,16 @@ interface PositionalLexerInterface extends LexerInterface * the internal state of the lexer and can be used in * asynchronous and parallel computing. * - * @param int<0, max> $offset Offset, starting from which you should - * start analyzing the source. + * @param int<0, max> $offset offset, starting from which you should + * start analyzing the source * - * @return iterable List of analyzed tokens. - * - * @throws LexerExceptionInterface An error occurs before source processing + * @return iterable list of analyzed tokens + * @throws LexerExceptionInterface an error occurs before source processing * starts, when the given source cannot be recognized or if the - * lexer settings contain errors. - * @throws LexerRuntimeExceptionInterface An exception that occurs after + * lexer settings contain errors + * @throws LexerRuntimeExceptionInterface an exception that occurs after * starting the lexical analysis and indicates problems in the - * analyzed source. + * analyzed source */ public function lex(ReadableInterface $source, int $offset = 0): iterable; } diff --git a/src/polyfill.php b/src/polyfill.php index 757f55e..d2fdb06 100644 --- a/src/polyfill.php +++ b/src/polyfill.php @@ -1,28 +1,27 @@