[FEATURE] Represent Selector as Component objects

Part of #1325.

Author: JakeQZ

src/Property/Selector.php

@@ -11,18 +11,19 @@
 use Sabberworm\CSS\Property\Selector\Combinator;
 use Sabberworm\CSS\Property\Selector\Component;
 use Sabberworm\CSS\Property\Selector\CompoundSelector;
-use Sabberworm\CSS\Property\Selector\SpecificityCalculator;
 use Sabberworm\CSS\Renderable;
+use Sabberworm\CSS\Settings;
 
 use function Safe\preg_match;
-use function Safe\preg_replace;
 
 /**
  * Class representing a single CSS selector. Selectors have to be split by the comma prior to being passed into this
  * class.
  */
 class Selector implements Renderable
 {
+    use ShortClassNameProvider;
+
     /**
      * @internal since 8.5.2
      */
@@ -54,9 +55,9 @@ class Selector implements Renderable
         /ux';
 
     /**
-     * @var string
+     * @var list<Component>
      */
-    private $selector;
+    private $components = [];
 
     /**
      * @internal since V8.8.0
@@ -69,9 +70,13 @@ public static function isValid(string $selector): bool
         return $numberOfMatches === 1;
     }
 
-    final public function __construct(string $selector)
+    final public function __construct(string $selector = '')
     {
-        $this->setSelector($selector);
+        // Allow construction of empty object for content to be set via `setComponents()`.
+        // (`setSelector()` will throw an exception when provided with an empty string.)
+        if ($selector !== '') {
+            $this->setSelector($selector);
+        }
     }
 
     /**
@@ -134,45 +139,73 @@ public static function parse(ParserState $parserState, array &$comments = []): s
             );
         }
 
-        $selectorString = '';
-        foreach ($selectorParts as $selectorPart) {
-            $selectorPartValue = $selectorPart->getValue();
-            if (\in_array($selectorPartValue, ['>', '+', '~'], true)) {
-                $selectorString .= ' ' . $selectorPartValue . ' ';
-            } else {
-                $selectorString .= $selectorPartValue;
-            }
-        }
+        return (new static())->setComponents($selectorParts);
+    }
 
-        return new static($selectorString);
+    /**
+     * @return list<Component>
+     */
+    public function getComponents(): array
+    {
+        return $this->components;
+    }
+
+    /**
+     * @param list<Component> $components
+     *        This should be an alternating sequence of `CompoundSelector` and `Combinator`, starting and ending with a
+     *        `CompoundSelector`, and may be a single `CompoundSelector`.
+     */
+    public function setComponents(array $components): self
+    {
+        $this->components = $components;
+
+        return $this;
     }
 
     public function getSelector(): string
     {
-        return $this->selector;
+        return $this->render(new OutputFormat());
     }
 
     public function setSelector(string $selector): void
     {
-        $selector = \trim($selector);
+        $parserState = new ParserState($selector, Settings::create());
+
+        $components = self::parseComponents($parserState);
 
-        $hasAttribute = \strpos($selector, '[') !== false;
+        // Check that the selector has been fully parsed:
+        if (!$parserState->isEnd()) {
+            throw new UnexpectedTokenException(
+                'EOF',
+                $parserState->peek(5),
+                'literal'
+            );
+        }
 
-        // Whitespace can't be adjusted within an attribute selector, as it would change its meaning
-        $this->selector = !$hasAttribute ? preg_replace('/\\s++/', ' ', $selector) : $selector;
+        $this->components = $components;
     }
 
     /**
      * @return int<0, max>
      */
     public function getSpecificity(): int
     {
-        return SpecificityCalculator::calculate($this->selector);
+        return \array_sum(\array_map(
+            static function (Component $component): int {
+                return $component->getSpecificity();
+            },
+            $this->components
+        ));
     }
 
     public function render(OutputFormat $outputFormat): string
     {
-        return $this->getSelector();
+        return \implode('', \array_map(
+            static function (Component $component) use ($outputFormat): string {
+                return $component->render($outputFormat);
+            },
+            $this->components
+        ));
     }
 
     /**
@@ -182,6 +215,14 @@ public function render(OutputFormat $outputFormat): string
      */
     public function getArrayRepresentation(): array
     {
-        throw new \BadMethodCallException('`getArrayRepresentation` is not yet implemented for `' . self::class . '`');
+        return [
+            'class' => $this->getShortClassName(),
+            'components' => \array_map(
+                static function (Component $component): array {
+                    return $component->getArrayRepresentation();
+                },
+                $this->components
+            ),
+        ];
     }
 }

tests/Unit/Property/SelectorTest.php

@@ -198,8 +198,6 @@ public static function provideInvalidSelectorsForParse(): array
     /**
      * @test
      *
-     * @param non-empty-string $selector
-     *
      * @dataProvider provideInvalidSelectors
      * @dataProvider provideInvalidSelectorsForParse
      */
@@ -317,6 +315,40 @@ public function parseExtractsTwoCommentsFromSelector(): void
         self::assertSame('comment2', $result[1]->getComment());
     }
 
+    /**
+     * @test
+     *
+     * @dataProvider provideInvalidSelectors
+     * @dataProvider provideInvalidSelectorsForParse
+     */
+    public function constructorThrowsExceptionWithInvalidSelector(string $selector): void
+    {
+        // An empty string is allowed to construct an empty object
+        if ($selector === '') {
+            self::expectNotToPerformAssertions();
+            return;
+        }
+
+        $this->expectException(UnexpectedTokenException::class);
+
+        new Selector($selector);
+    }
+
+    /**
+     * @test
+     *
+     * @dataProvider provideInvalidSelectors
+     * @dataProvider provideInvalidSelectorsForParse
+     */
+    public function setSelectorThrowsExceptionWithInvalidSelector(string $selector): void
+    {
+        $this->expectException(UnexpectedTokenException::class);
+
+        $subject = new Selector('a');
+
+        $subject->setSelector($selector);
+    }
+
     /**
      * @test
      *