[CLEANUP] Clean up ParserState a bit (#1173)

oliverklee · web-flow · commit b3c1936ea710 · 2025-03-16T18:39:13.000Z
diff --git a/config/phpstan-baseline.neon b/config/phpstan-baseline.neon
@@ -42,18 +42,6 @@ parameters:
 			count: 1
 			path: ../src/CSSList/Document.php
 
-		-
-			message: '#^Loose comparison via "\=\=" is not allowed\.$#'
-			identifier: equal.notAllowed
-			count: 1
-			path: ../src/Parsing/ParserState.php
-
-		-
-			message: '#^PHPDoc tag @return with type array\<int, Sabberworm\\CSS\\Comment\\Comment\>\|void is not subtype of native type array\.$#'
-			identifier: return.phpDocType
-			count: 1
-			path: ../src/Parsing/ParserState.php
-
 		-
 			message: '#^Cannot call method render\(\) on string\.$#'
 			identifier: method.nonObject
diff --git a/src/Parsing/ParserState.php b/src/Parsing/ParserState.php
@@ -129,6 +129,7 @@ public function parseIdentifier(bool $ignoreCase = true): string
         if ($ignoreCase) {
             $result = $this->strtolower($result);
         }
+
         return $result;
     }
 
@@ -181,11 +182,12 @@ public function parseCharacter(bool $isForIdentifier): ?string
         } else {
             return $this->consume(1);
         }
+
         return null;
     }
 
     /**
-     * @return array<int, Comment>|void
+     * @return list<Comment>
      *
      * @throws UnexpectedEOFException
      * @throws UnexpectedTokenException
@@ -202,24 +204,27 @@ public function consumeWhiteSpace(): array
                     $comment = $this->consumeComment();
                 } catch (UnexpectedEOFException $e) {
                     $this->currentPosition = \count($this->characters);
-                    return $comments;
+                    break;
                 }
             } else {
                 $comment = $this->consumeComment();
             }
-            if ($comment !== false) {
+            if ($comment instanceof Comment) {
                 $comments[] = $comment;
             }
-        } while ($comment !== false);
+        } while ($comment instanceof Comment);
+
         return $comments;
     }
 
+    /**
+     * @param non-empty-string $string
+     */
     public function comes(string $string, bool $caseInsensitive = false): bool
     {
         $peek = $this->peek(\strlen($string));
-        return ($peek == '')
-            ? false
-            : $this->streql($peek, $string, $caseInsensitive);
+
+        return ($peek !== '') && $this->streql($peek, $string, $caseInsensitive);
     }
 
     /**
@@ -232,6 +237,7 @@ public function peek(int $length = 1, int $offset = 0): string
         if ($offset >= \count($this->characters)) {
             return '';
         }
+
         return $this->substr($offset, $length);
     }
 
@@ -254,19 +260,22 @@ public function consume($value = 1): string
                     $this->lineNumber
                 );
             }
+
             $this->lineNumber += $numberOfLines;
             $this->currentPosition += $this->strlen($value);
-            return $value;
+            $result = $value;
         } else {
             if ($this->currentPosition + $value > \count($this->characters)) {
                 throw new UnexpectedEOFException((string) $value, $this->peek(5), 'count', $this->lineNumber);
             }
+
             $result = $this->substr($this->currentPosition, $value);
             $numberOfLines = \substr_count($result, "\n");
             $this->lineNumber += $numberOfLines;
             $this->currentPosition += $value;
-            return $result;
         }
+
+        return $result;
     }
 
     /**
@@ -279,21 +288,23 @@ public function consume($value = 1): string
     public function consumeExpression(string $expression, ?int $maximumLength = null): string
     {
         $matches = null;
-        $input = $maximumLength !== null ? $this->peek($maximumLength) : $this->inputLeft();
-        if (\preg_match($expression, $input, $matches, PREG_OFFSET_CAPTURE) === 1) {
-            return $this->consume($matches[0][0]);
+        $input = ($maximumLength !== null) ? $this->peek($maximumLength) : $this->inputLeft();
+        if (\preg_match($expression, $input, $matches, PREG_OFFSET_CAPTURE) !== 1) {
+            throw new UnexpectedTokenException($expression, $this->peek(5), 'expression', $this->lineNumber);
         }
-        throw new UnexpectedTokenException($expression, $this->peek(5), 'expression', $this->lineNumber);
+
+        return $this->consume($matches[0][0]);
     }
 
     /**
      * @return Comment|false
      */
     public function consumeComment()
     {
-        $comment = false;
+        $lineNumber = $this->lineNumber;
+        $comment = null;
+
         if ($this->comes('/*')) {
-            $lineNumber = $this->lineNumber;
             $this->consume(1);
             $comment = '';
             while (($char = $this->consume(1)) !== '') {
@@ -305,12 +316,8 @@ public function consumeComment()
             }
         }
 
-        if ($comment !== false) {
-            // We skip the * which was included in the comment.
-            return new Comment(\substr($comment, 1), $lineNumber);
-        }
-
-        return $comment;
+        // We skip the * which was included in the comment.
+        return \is_string($comment) ? new Comment(\substr($comment, 1), $lineNumber) : false;
     }
 
     public function isEnd(): bool
@@ -319,7 +326,7 @@ public function isEnd(): bool
     }
 
     /**
-     * @param array<array-key, string>|string $stopCharacters
+     * @param list<string>|string $stopCharacters
      * @param array<int, Comment> $comments
      *
      * @throws UnexpectedEOFException
@@ -346,7 +353,8 @@ public function consumeUntil(
                 return $consumedCharacters;
             }
             $consumedCharacters .= $character;
-            if ($comment = $this->consumeComment()) {
+            $comment = $this->consumeComment();
+            if ($comment instanceof Comment) {
                 $comments[] = $comment;
             }
         }
@@ -371,11 +379,9 @@ private function inputLeft(): string
 
     public function streql(string $string1, string $string2, bool $caseInsensitive = true): bool
     {
-        if ($caseInsensitive) {
-            return $this->strtolower($string1) === $this->strtolower($string2);
-        } else {
-            return $string1 === $string2;
-        }
+        return $caseInsensitive
+            ? ($this->strtolower($string1) === $this->strtolower($string2))
+            : ($string1 === $string2);
     }
 
     /**
@@ -391,11 +397,9 @@ public function backtrack(int $numberOfCharacters): void
      */
     public function strlen(string $string): int
     {
-        if ($this->parserSettings->hasMultibyteSupport()) {
-            return \mb_strlen($string, $this->charset);
-        } else {
-            return \strlen($string);
-        }
+        return $this->parserSettings->hasMultibyteSupport()
+            ? \mb_strlen($string, $this->charset)
+            : \strlen($string);
     }
 
     /**
@@ -415,20 +419,22 @@ private function substr(int $offset, int $length): string
             $offset++;
             $length--;
         }
+
         return $result;
     }
 
+    /**
+     * @return ($string is non-empty-string ? non-empty-string : string)
+     */
     private function strtolower(string $string): string
     {
-        if ($this->parserSettings->hasMultibyteSupport()) {
-            return \mb_strtolower($string, $this->charset);
-        } else {
-            return \strtolower($string);
-        }
+        return $this->parserSettings->hasMultibyteSupport()
+            ? \mb_strtolower($string, $this->charset)
+            : \strtolower($string);
     }
 
     /**
-     * @return array<int, string>
+     * @return list<string>
      *
      * @throws SourceException if the charset is UTF-8 and the string contains invalid byte sequences
      */
@@ -440,33 +446,27 @@ private function strsplit(string $string): array
                 if (!\is_array($result)) {
                     throw new SourceException('`preg_split` failed with error ' . \preg_last_error());
                 }
-                return $result;
             } else {
                 $length = \mb_strlen($string, $this->charset);
                 $result = [];
                 for ($i = 0; $i < $length; ++$i) {
                     $result[] = \mb_substr($string, $i, 1, $this->charset);
                 }
-                return $result;
             }
         } else {
-            if ($string === '') {
-                return [];
-            } else {
-                return \str_split($string);
-            }
+            $result = ($string !== '') ? \str_split($string) : [];
         }
+
+        return $result;
     }
 
     /**
-     * @return int|false
+     * @return int<0, max>|false
      */
     private function strpos(string $haystack, string $needle, int $offset)
     {
-        if ($this->parserSettings->hasMultibyteSupport()) {
-            return \mb_strpos($haystack, $needle, $offset, $this->charset);
-        } else {
-            return \strpos($haystack, $needle, $offset);
-        }
+        return $this->parserSettings->hasMultibyteSupport()
+            ? \mb_strpos($haystack, $needle, $offset, $this->charset)
+            : \strpos($haystack, $needle, $offset);
     }
 }

Original file line number	Diff line number	Diff line change
`@@ -129,6 +129,7 @@ public function parseIdentifier(bool $ignoreCase = true): string`
`129`	`129`	`if ($ignoreCase) {`
`130`	`130`	`$result = $this->strtolower($result);`
`131`	`131`	`}`
	`132`	`+`
`132`	`133`	`return $result;`
`133`	`134`	`}`
`134`	`135`
`@@ -181,11 +182,12 @@ public function parseCharacter(bool $isForIdentifier): ?string`
`181`	`182`	`} else {`
`182`	`183`	`return $this->consume(1);`
`183`	`184`	`}`
	`185`	`+`
`184`	`186`	`return null;`
`185`	`187`	`}`
`186`	`188`
`187`	`189`	`/**`
`188`		`- * @return array<int, Comment>\|void`
	`190`	`+ * @return list<Comment>`
`189`	`191`	`*`
`190`	`192`	`* @throws UnexpectedEOFException`
`191`	`193`	`* @throws UnexpectedTokenException`
`@@ -202,24 +204,27 @@ public function consumeWhiteSpace(): array`
`202`	`204`	`$comment = $this->consumeComment();`
`203`	`205`	`} catch (UnexpectedEOFException $e) {`
`204`	`206`	`$this->currentPosition = \count($this->characters);`
`205`		`- return $comments;`
	`207`	`+ break;`
`206`	`208`	`}`
`207`	`209`	`} else {`
`208`	`210`	`$comment = $this->consumeComment();`
`209`	`211`	`}`
`210`		`- if ($comment !== false) {`
	`212`	`+ if ($comment instanceof Comment) {`
`211`	`213`	`$comments[] = $comment;`
`212`	`214`	`}`
`213`		`- } while ($comment !== false);`
	`215`	`+ } while ($comment instanceof Comment);`
	`216`	`+`
`214`	`217`	`return $comments;`
`215`	`218`	`}`
`216`	`219`
	`220`	`+ /**`
	`221`	`+ * @param non-empty-string $string`
	`222`	`+ */`
`217`	`223`	`public function comes(string $string, bool $caseInsensitive = false): bool`
`218`	`224`	`{`
`219`	`225`	`$peek = $this->peek(\strlen($string));`
`220`		`- return ($peek == '')`
`221`		`- ? false`
`222`		`- : $this->streql($peek, $string, $caseInsensitive);`
	`226`	`+`
	`227`	`+ return ($peek !== '') && $this->streql($peek, $string, $caseInsensitive);`
`223`	`228`	`}`
`224`	`229`
`225`	`230`	`/**`
`@@ -232,6 +237,7 @@ public function peek(int $length = 1, int $offset = 0): string`
`232`	`237`	`if ($offset >= \count($this->characters)) {`
`233`	`238`	`return '';`
`234`	`239`	`}`
	`240`	`+`
`235`	`241`	`return $this->substr($offset, $length);`
`236`	`242`	`}`
`237`	`243`
`@@ -254,19 +260,22 @@ public function consume($value = 1): string`
`254`	`260`	`$this->lineNumber`
`255`	`261`	`);`
`256`	`262`	`}`
	`263`	`+`
`257`	`264`	`$this->lineNumber += $numberOfLines;`
`258`	`265`	`$this->currentPosition += $this->strlen($value);`
`259`		`- return $value;`
	`266`	`+ $result = $value;`
`260`	`267`	`} else {`
`261`	`268`	`if ($this->currentPosition + $value > \count($this->characters)) {`
`262`	`269`	`throw new UnexpectedEOFException((string) $value, $this->peek(5), 'count', $this->lineNumber);`
`263`	`270`	`}`
	`271`	`+`
`264`	`272`	`$result = $this->substr($this->currentPosition, $value);`
`265`	`273`	`$numberOfLines = \substr_count($result, "\n");`
`266`	`274`	`$this->lineNumber += $numberOfLines;`
`267`	`275`	`$this->currentPosition += $value;`
`268`		`- return $result;`
`269`	`276`	`}`
	`277`	`+`
	`278`	`+ return $result;`
`270`	`279`	`}`
`271`	`280`
`272`	`281`	`/**`
`@@ -279,21 +288,23 @@ public function consume($value = 1): string`
`279`	`288`	`public function consumeExpression(string $expression, ?int $maximumLength = null): string`
`280`	`289`	`{`
`281`	`290`	`$matches = null;`
`282`		`- $input = $maximumLength !== null ? $this->peek($maximumLength) : $this->inputLeft();`
`283`		`- if (\preg_match($expression, $input, $matches, PREG_OFFSET_CAPTURE) === 1) {`
`284`		`- return $this->consume($matches[0][0]);`
	`291`	`+ $input = ($maximumLength !== null) ? $this->peek($maximumLength) : $this->inputLeft();`
	`292`	`+ if (\preg_match($expression, $input, $matches, PREG_OFFSET_CAPTURE) !== 1) {`
	`293`	`+ throw new UnexpectedTokenException($expression, $this->peek(5), 'expression', $this->lineNumber);`
`285`	`294`	`}`
`286`		`- throw new UnexpectedTokenException($expression, $this->peek(5), 'expression', $this->lineNumber);`
	`295`	`+`
	`296`	`+ return $this->consume($matches[0][0]);`
`287`	`297`	`}`
`288`	`298`
`289`	`299`	`/**`
`290`	`300`	`* @return Comment\|false`
`291`	`301`	`*/`
`292`	`302`	`public function consumeComment()`
`293`	`303`	`{`
`294`		`- $comment = false;`
	`304`	`+ $lineNumber = $this->lineNumber;`
	`305`	`+ $comment = null;`
	`306`	`+`
`295`	`307`	`if ($this->comes('/*')) {`
`296`		`- $lineNumber = $this->lineNumber;`
`297`	`308`	`$this->consume(1);`
`298`	`309`	`$comment = '';`
`299`	`310`	`while (($char = $this->consume(1)) !== '') {`
`@@ -305,12 +316,8 @@ public function consumeComment()`
`305`	`316`	`}`
`306`	`317`	`}`
`307`	`318`
`308`		`- if ($comment !== false) {`
`309`		`- // We skip the * which was included in the comment.`
`310`		`- return new Comment(\substr($comment, 1), $lineNumber);`
`311`		`- }`
`312`		`-`
`313`		`- return $comment;`
	`319`	`+ // We skip the * which was included in the comment.`
	`320`	`+ return \is_string($comment) ? new Comment(\substr($comment, 1), $lineNumber) : false;`
`314`	`321`	`}`
`315`	`322`
`316`	`323`	`public function isEnd(): bool`
`@@ -319,7 +326,7 @@ public function isEnd(): bool`
`319`	`326`	`}`
`320`	`327`
`321`	`328`	`/**`
`322`		`- * @param array<array-key, string>\|string $stopCharacters`
	`329`	`+ * @param list<string>\|string $stopCharacters`
`323`	`330`	`* @param array<int, Comment> $comments`
`324`	`331`	`*`
`325`	`332`	`* @throws UnexpectedEOFException`
`@@ -346,7 +353,8 @@ public function consumeUntil(`
`346`	`353`	`return $consumedCharacters;`
`347`	`354`	`}`
`348`	`355`	`$consumedCharacters .= $character;`
`349`		`- if ($comment = $this->consumeComment()) {`
	`356`	`+ $comment = $this->consumeComment();`
	`357`	`+ if ($comment instanceof Comment) {`
`350`	`358`	`$comments[] = $comment;`
`351`	`359`	`}`
`352`	`360`	`}`
`@@ -371,11 +379,9 @@ private function inputLeft(): string`
`371`	`379`
`372`	`380`	`public function streql(string $string1, string $string2, bool $caseInsensitive = true): bool`
`373`	`381`	`{`
`374`		`- if ($caseInsensitive) {`
`375`		`- return $this->strtolower($string1) === $this->strtolower($string2);`
`376`		`- } else {`
`377`		`- return $string1 === $string2;`
`378`		`- }`
	`382`	`+ return $caseInsensitive`
	`383`	`+ ? ($this->strtolower($string1) === $this->strtolower($string2))`
	`384`	`+ : ($string1 === $string2);`
`379`	`385`	`}`
`380`	`386`
`381`	`387`	`/**`
`@@ -391,11 +397,9 @@ public function backtrack(int $numberOfCharacters): void`
`391`	`397`	`*/`
`392`	`398`	`public function strlen(string $string): int`
`393`	`399`	`{`
`394`		`- if ($this->parserSettings->hasMultibyteSupport()) {`
`395`		`- return \mb_strlen($string, $this->charset);`
`396`		`- } else {`
`397`		`- return \strlen($string);`
`398`		`- }`
	`400`	`+ return $this->parserSettings->hasMultibyteSupport()`
	`401`	`+ ? \mb_strlen($string, $this->charset)`
	`402`	`+ : \strlen($string);`
`399`	`403`	`}`
`400`	`404`
`401`	`405`	`/**`
`@@ -415,20 +419,22 @@ private function substr(int $offset, int $length): string`
`415`	`419`	`$offset++;`
`416`	`420`	`$length--;`
`417`	`421`	`}`
	`422`	`+`
`418`	`423`	`return $result;`
`419`	`424`	`}`
`420`	`425`
	`426`	`+ /**`
	`427`	`+ * @return ($string is non-empty-string ? non-empty-string : string)`
	`428`	`+ */`
`421`	`429`	`private function strtolower(string $string): string`
`422`	`430`	`{`
`423`		`- if ($this->parserSettings->hasMultibyteSupport()) {`
`424`		`- return \mb_strtolower($string, $this->charset);`
`425`		`- } else {`
`426`		`- return \strtolower($string);`
`427`		`- }`
	`431`	`+ return $this->parserSettings->hasMultibyteSupport()`
	`432`	`+ ? \mb_strtolower($string, $this->charset)`
	`433`	`+ : \strtolower($string);`
`428`	`434`	`}`
`429`	`435`
`430`	`436`	`/**`
`431`		`- * @return array<int, string>`
	`437`	`+ * @return list<string>`
`432`	`438`	`*`
`433`	`439`	`* @throws SourceException if the charset is UTF-8 and the string contains invalid byte sequences`
`434`	`440`	`*/`
`@@ -440,33 +446,27 @@ private function strsplit(string $string): array`
`440`	`446`	`if (!\is_array($result)) {`
`441`	`447`	throw new SourceException('`preg_split` failed with error ' . \preg_last_error());
`442`	`448`	`}`
`443`		`- return $result;`
`444`	`449`	`} else {`
`445`	`450`	`$length = \mb_strlen($string, $this->charset);`
`446`	`451`	`$result = [];`
`447`	`452`	`for ($i = 0; $i < $length; ++$i) {`
`448`	`453`	`$result[] = \mb_substr($string, $i, 1, $this->charset);`
`449`	`454`	`}`
`450`		`- return $result;`
`451`	`455`	`}`
`452`	`456`	`} else {`
`453`		`- if ($string === '') {`
`454`		`- return [];`
`455`		`- } else {`
`456`		`- return \str_split($string);`
`457`		`- }`
	`457`	`+ $result = ($string !== '') ? \str_split($string) : [];`
`458`	`458`	`}`
	`459`	`+`
	`460`	`+ return $result;`
`459`	`461`	`}`
`460`	`462`
`461`	`463`	`/**`
`462`		`- * @return int\|false`
	`464`	`+ * @return int<0, max>\|false`
`463`	`465`	`*/`
`464`	`466`	`private function strpos(string $haystack, string $needle, int $offset)`
`465`	`467`	`{`
`466`		`- if ($this->parserSettings->hasMultibyteSupport()) {`
`467`		`- return \mb_strpos($haystack, $needle, $offset, $this->charset);`
`468`		`- } else {`
`469`		`- return \strpos($haystack, $needle, $offset);`
`470`		`- }`
	`468`	`+ return $this->parserSettings->hasMultibyteSupport()`
	`469`	`+ ? \mb_strpos($haystack, $needle, $offset, $this->charset)`
	`470`	`+ : \strpos($haystack, $needle, $offset);`
`471`	`471`	`}`
`472`	`472`	`}`