Debian Codegraph @

vendor/sabberworm/php-css-parser/src/Property/Selector.php

raw
1 <?php
2
3 declare(strict_types=1);
4
5 namespace Sabberworm\CSS\Property;
6
7 use Sabberworm\CSS\Comment\Comment;
8 use Sabberworm\CSS\OutputFormat;
9 use Sabberworm\CSS\Parsing\ParserState;
10 use Sabberworm\CSS\Parsing\UnexpectedTokenException;
11 use Sabberworm\CSS\Property\Selector\Combinator;
12 use Sabberworm\CSS\Property\Selector\Component;
13 use Sabberworm\CSS\Property\Selector\CompoundSelector;
14 use Sabberworm\CSS\Renderable;
15 use Sabberworm\CSS\Settings;
16 use Sabberworm\CSS\ShortClassNameProvider;
17
18 use function Safe\preg_match;
19
20 /**
21 * Class representing a single CSS selector. Selectors have to be split by the comma prior to being passed into this
22 * class.
23 */
24 class Selector implements Renderable
25 {
26 use ShortClassNameProvider;
27
28 /**
29 * @internal since 8.5.2
30 */
31 public const SELECTOR_VALIDATION_RX = '/
32 ^(
33 # not whitespace only
34 (?!\\s*+$)
35 (?:
36 # any sequence of valid unescaped characters, except quotes
37 [a-zA-Z0-9\\x{00A0}-\\x{FFFF}_^$|*=~\\[\\]()\\-\\s\\.:#+>,]++
38 |
39 # one or more escaped characters
40 (?:\\\\.)++
41 |
42 # quoted text, like in `[id="example"]`
43 (?:
44 # opening quote
45 ([\'"])
46 (?:
47 # sequence of characters except closing quote or backslash
48 (?:(?!\\g{-1}|\\\\).)++
49 |
50 # one or more escaped characters
51 (?:\\\\.)++
52 )*+ # zero or more times
53 # closing quote or end (unmatched quote is currently allowed)
54 (?:\\g{-1}|$)
55 )
56 )*+ # zero or more times
57 )$
58 /ux';
59
60 /**
61 * @var non-empty-list<Component>
62 */
63 private $components;
64
65 /**
66 * @internal since V8.8.0
67 */
68 public static function isValid(string $selector): bool
69 {
70 // Note: We need to use `static::` here as the constant is overridden in the `KeyframeSelector` class.
71 $numberOfMatches = preg_match(static::SELECTOR_VALIDATION_RX, $selector);
72
73 return $numberOfMatches === 1;
74 }
75
76 /**
77 * @param non-empty-string|non-empty-list<Component> $selector
78 * Providing a string is deprecated in version 9.2 and will not work from v10.0
79 *
80 * @throws UnexpectedTokenException if the selector is not valid
81 */
82 final public function __construct($selector)
83 {
84 if (\is_string($selector)) {
85 $this->setSelector($selector);
86 } else {
87 $this->setComponents($selector);
88 }
89 }
90
91 /**
92 * @param list<Comment> $comments
93 *
94 * @return non-empty-list<Component>
95 *
96 * @throws UnexpectedTokenException
97 */
98 private static function parseComponents(ParserState $parserState, array &$comments = []): array
99 {
100 // Whitespace is a descendent combinator, not allowed around a compound selector.
101 // (It is allowed within, e.g. as part of a string or within a function like `:not()`.)
102 // Gobble any up now to get a clean start.
103 $parserState->consumeWhiteSpace($comments);
104
105 $selectorParts = [];
106 while (true) {
107 try {
108 $selectorParts[] = CompoundSelector::parse($parserState, $comments);
109 } catch (UnexpectedTokenException $e) {
110 if ($selectorParts !== [] && \end($selectorParts)->getValue() === ' ') {
111 // The whitespace was not a descendent combinator, and was, in fact, arbitrary,
112 // after the end of the selector. Discard it.
113 \array_pop($selectorParts);
114 break;
115 } else {
116 throw $e;
117 }
118 }
119 try {
120 $selectorParts[] = Combinator::parse($parserState, $comments);
121 } catch (UnexpectedTokenException $e) {
122 // End of selector has been reached.
123 break;
124 }
125 }
126
127 return $selectorParts;
128 }
129
130 /**
131 * @param list<Comment> $comments
132 *
133 * @throws UnexpectedTokenException
134 *
135 * @internal
136 */
137 public static function parse(ParserState $parserState, array &$comments = []): self
138 {
139 $selectorParts = self::parseComponents($parserState, $comments);
140
141 // Check that the selector has been fully parsed:
142 if (!\in_array($parserState->peek(), ['{', '}', ',', ''], true)) {
143 throw new UnexpectedTokenException(
144 '`,`, `{`, `}` or EOF',
145 $parserState->peek(5),
146 'literal',
147 $parserState->currentLine()
148 );
149 }
150
151 return new static($selectorParts);
152 }
153
154 /**
155 * @return non-empty-list<Component>
156 */
157 public function getComponents(): array
158 {
159 return $this->components;
160 }
161
162 /**
163 * @param non-empty-list<Component> $components
164 * This should be an alternating sequence of `CompoundSelector` and `Combinator`, starting and ending with a
165 * `CompoundSelector`, and may be a single `CompoundSelector`.
166 */
167 public function setComponents(array $components): self
168 {
169 $this->components = $components;
170
171 return $this;
172 }
173
174 /**
175 * @return non-empty-string
176 *
177 * @deprecated in version 9.2, will be removed in v10.0. Use either `getComponents()` or `render()` instead.
178 */
179 public function getSelector(): string
180 {
181 return $this->render(new OutputFormat());
182 }
183
184 /**
185 * @param non-empty-string $selector
186 *
187 * @throws UnexpectedTokenException if the selector is not valid
188 *
189 * @deprecated in version 9.2, will be removed in v10.0. Use `setComponents()` instead.
190 */
191 public function setSelector(string $selector): void
192 {
193 $parserState = new ParserState($selector, Settings::create());
194
195 $components = self::parseComponents($parserState);
196
197 // Check that the selector has been fully parsed:
198 if (!$parserState->isEnd()) {
199 throw new UnexpectedTokenException(
200 'EOF',
201 $parserState->peek(5),
202 'literal'
203 );
204 }
205
206 $this->components = $components;
207 }
208
209 /**
210 * @return int<0, max>
211 */
212 public function getSpecificity(): int
213 {
214 return \array_sum(\array_map(
215 static function (Component $component): int {
216 return $component->getSpecificity();
217 },
218 $this->components
219 ));
220 }
221
222 public function render(OutputFormat $outputFormat): string
223 {
224 return \implode('', \array_map(
225 static function (Component $component) use ($outputFormat): string {
226 return $component->render($outputFormat);
227 },
228 $this->components
229 ));
230 }
231
232 /**
233 * @return array<string, bool|int|float|string|array<mixed>|null>
234 *
235 * @internal
236 */
237 public function getArrayRepresentation(): array
238 {
239 return [
240 'class' => $this->getShortClassName(),
241 'components' => \array_map(
242 static function (Component $component): array {
243 return $component->getArrayRepresentation();
244 },
245 $this->components
246 ),
247 ];
248 }
249 }