muskitty_css_parser/algorithms.rs
1//! §5.5 Parser Algorithms.
2//!
3//! Implementation of the 11 algorithms defined in CSS Syntax Module
4//! Level 3 §5.5. This module covers:
5//! - CP-3 (lower-level algorithms): §5.5.7-§5.5.11.
6//! - CP-4 (declaration algorithms): §5.5.6.
7//! - CP-5 (stylesheet/rule/block algorithms): §5.5.1-§5.5.5.
8
9use crate::token_stream::TokenStream;
10use crate::types::{
11 AtRule, BlockKind, ComponentValue, Declaration, Function, ParseError, QualifiedRule, Rule,
12 SimpleBlock,
13};
14use muskitty_css_tokenizer::Token;
15
16/// §5.5.8 (L2776-2796) Consume a component value.
17///
18/// Dispatch on the next token:
19/// - `{-token` / `[-token` / `(-token` → consume_a_simple_block
20/// - `function-token` → consume_a_function
21/// - anything else → consume and return the token as PreservedToken
22pub fn consume_a_component_value(input: &mut TokenStream) -> ComponentValue {
23 match input.next_token() {
24 Token::OpenBrace | Token::OpenBracket | Token::OpenParen => {
25 ComponentValue::SimpleBlock(consume_a_simple_block(input))
26 }
27 Token::Function(_) => ComponentValue::Function(consume_a_function(input)),
28 other => {
29 input.consume_token();
30 ComponentValue::PreservedToken(other)
31 }
32 }
33}
34
35/// §5.5.9 (L2799-2829) Consume a simple block.
36///
37/// Precondition: next token is `{-token` / `[-token` / `(-token`. The
38/// mirror variant becomes the ending token (e.g. `[` → `]`).
39/// Repeatedly consume component values until the ending token or EOF.
40pub fn consume_a_simple_block(input: &mut TokenStream) -> SimpleBlock {
41 let opening = input.next_token();
42 let kind = match opening {
43 Token::OpenBrace => BlockKind::Curly,
44 Token::OpenBracket => BlockKind::Square,
45 Token::OpenParen => BlockKind::Paren,
46 _ => unreachable!("consume_a_simple_block called on non-opening token"),
47 };
48 let ending = match kind {
49 BlockKind::Curly => Token::CloseBrace,
50 BlockKind::Square => Token::CloseBracket,
51 BlockKind::Paren => Token::CloseParen,
52 };
53 // §5.5.9 L2818: discard the opening token.
54 input.discard_token();
55
56 let mut block = SimpleBlock {
57 kind,
58 value: Vec::new(),
59 };
60 loop {
61 // §5.5.9 L2822-2825: EOF or ending token → discard, return block.
62 let next = input.next_token();
63 if matches!(next, Token::Eof) || next == ending {
64 input.discard_token();
65 return block;
66 }
67 // §5.5.9 L2827-2829: anything else → consume a component value
68 // and append.
69 block.value.push(consume_a_component_value(input));
70 }
71}
72
73/// §5.5.10 (L2832-2854) Consume a function.
74///
75/// Precondition: next token is a `function-token`. Consume the function
76/// token, then consume component values until `)-token` or EOF.
77pub fn consume_a_function(input: &mut TokenStream) -> Function {
78 let name = match input.consume_token() {
79 Token::Function(name) => name,
80 _ => unreachable!("consume_a_function called on non-function token"),
81 };
82 let mut function = Function {
83 name,
84 value: Vec::new(),
85 };
86 loop {
87 // §5.5.10 L2847-2850: EOF or `)-token` → discard, return function.
88 match input.next_token() {
89 Token::Eof | Token::CloseParen => {
90 input.discard_token();
91 return function;
92 }
93 // §5.5.10 L2852-2854: anything else → consume a component
94 // value and append.
95 _ => function.value.push(consume_a_component_value(input)),
96 }
97 }
98}
99
100/// §5.5.7 (L2745-2774) Consume a list of component values.
101///
102/// `stop_token`: optional token that ends the list (e.g. `;` for
103/// declarations). `nested`: when true, an unbalanced `}-token` ends
104/// the list without consuming; when false, `}-token` is a parse
105/// error and is consumed into the list.
106pub fn consume_a_list_of_component_values(
107 input: &mut TokenStream,
108 stop_token: Option<Token>,
109 nested: bool,
110) -> Vec<ComponentValue> {
111 let mut values = Vec::new();
112 loop {
113 let next = input.next_token();
114 // §5.5.7 L2757-2759: EOF → return values.
115 if matches!(next, Token::Eof) {
116 return values;
117 }
118 // §5.5.7 L2757-2759: stop_token → return values.
119 if stop_token.as_ref().is_some_and(|s| *s == next) {
120 return values;
121 }
122 match next {
123 Token::CloseBrace => {
124 if nested {
125 // §5.5.7 L2761-2764: nested → return values without
126 // consuming the `}-token (caller handles it).
127 return values;
128 }
129 // §5.5.7 L2766-2769: parse error. Consume and append.
130 input.consume_token();
131 values.push(ComponentValue::PreservedToken(next));
132 }
133 // §5.5.7 L2771-2773: anything else → consume a component
134 // value and append.
135 _ => values.push(consume_a_component_value(input)),
136 }
137 }
138}
139
140/// §5.5.11 (L2857-2872) Consume the value of a
141/// `@font-face/unicode-range` descriptor.
142///
143/// Tokenize `input_string` with `unicode_ranges_allowed=true`, then
144/// consume a list of component values from the resulting stream.
145///
146/// Per §5.5.11 L2869-2871 note: "The existence of this algorithm is
147/// due to a design mistake in early CSS. It should never be
148/// reproduced."
149pub fn consume_a_unicode_range_value(input_string: &str) -> Vec<ComponentValue> {
150 use muskitty_css_tokenizer::{CssTokenizer, Tokenizer};
151 let mut tz = CssTokenizer::new(input_string);
152 tz.set_unicode_ranges_allowed(true);
153 let mut tokens: Vec<Token> = Vec::new();
154 while let Some(token) = tz.next_token() {
155 let is_eof = matches!(token, Token::Eof);
156 tokens.push(token);
157 if is_eof {
158 break;
159 }
160 }
161 let mut stream = TokenStream::new(tokens);
162 consume_a_list_of_component_values(&mut stream, None, false)
163}
164
165// ─── §5.5.6 Declaration algorithms ───────────────────────────────────
166
167/// §5.5.6 (L2639-2717) Consume a declaration.
168///
169/// `nested`: when true, an unbalanced `}-token` returns `None` without
170/// consuming (caller will handle the closing brace); when false, it
171/// is consumed as part of the declaration's value.
172///
173/// # Algorithm steps
174///
175/// 1. If next token is ident, consume it as the declaration name.
176/// Otherwise, consume remnants of a bad declaration, return `None`.
177/// 2. Discard whitespace.
178/// 3. If next token is `:`, discard it. Otherwise, bad declaration,
179/// return `None`.
180/// 4. Discard whitespace.
181/// 5. Consume a list of component values with `;` as stop token.
182/// 6. If last two non-whitespace values are `!` + `important` (ASCII
183/// case-insensitive), remove them and set `important` flag.
184/// 7. Strip trailing whitespace tokens.
185/// 8. Custom property (`--foo`): set `original_text` (deferred —
186/// requires source-text tracking in `TokenStream`). Otherwise,
187/// if value contains a top-level {}-block AND any other non-ws
188/// value, return `None` (only the whole value may be a {}-block
189/// for non-custom properties).
190/// 9. (§5.5.6 L2707-2712: `unicode-range` descriptor handling
191/// deferred — requires source-text tracking.)
192pub fn consume_a_declaration(input: &mut TokenStream, nested: bool) -> Option<Declaration> {
193 // Step 1 (§5.5.6 L2650-2659): ident-token as declaration name.
194 let name = match input.next_token() {
195 Token::Ident(name) => {
196 input.consume_token();
197 name
198 }
199 _ => {
200 consume_the_remnants_of_a_bad_declaration(input, nested);
201 return None;
202 }
203 };
204
205 // Step 2 (§5.5.6 L2661-2662): discard whitespace.
206 input.discard_whitespace();
207
208 // Step 3 (§5.5.6 L2664-2671): colon.
209 match input.next_token() {
210 Token::Colon => input.discard_token(),
211 _ => {
212 consume_the_remnants_of_a_bad_declaration(input, nested);
213 return None;
214 }
215 }
216
217 // Step 4 (§5.5.6 L2673-2674): discard whitespace.
218 input.discard_whitespace();
219
220 // Step 5 (§5.5.6 L2676-2680): consume value until `;`.
221 let mut value = consume_a_list_of_component_values(input, Some(Token::Semicolon), nested);
222
223 // Step 6 (§5.5.6 L2682-2687): strip !important from the tail.
224 let important = strip_important(&mut value);
225
226 // Step 7 (§5.5.6 L2689-2691): strip trailing whitespace.
227 while matches!(
228 value.last(),
229 Some(ComponentValue::PreservedToken(Token::Whitespace))
230 ) {
231 value.pop();
232 }
233
234 let decl = Declaration {
235 name,
236 value,
237 important,
238 original_text: None,
239 };
240
241 // Step 8 (§5.5.6 L2693-2705): custom property original_text +
242 // top-level {}-block validity check.
243 if is_custom_property_name(&decl.name) {
244 // §5.5.6 L2693-2698: original_text should be set. Deferred —
245 // requires `TokenStream` to retain original source text. For
246 // now, leave `None`.
247 } else {
248 // §5.5.6 L2700-2705: if value contains a top-level {}-block
249 // AND any other non-whitespace value, return nothing.
250 if has_top_level_curly_block_with_other_values(&decl.value) {
251 return None;
252 }
253 }
254
255 // §5.5.6 L2707-2712: `unicode-range` descriptor handling deferred
256 // (requires source-text tracking for re-tokenization).
257
258 // §5.5.6 L2714-2717: if the declaration is valid, return it;
259 // otherwise return nothing. We treat "valid" as "we successfully
260 // parsed a name + colon + value", which is the syntactic validity.
261 // Grammar-level validity is left to higher-level callers (CSSOM).
262 Some(decl)
263}
264
265/// §5.5.6 (L2721-2741) Consume the remnants of a bad declaration.
266///
267/// Repeatedly process input:
268/// - EOF or `;` → discard, return.
269/// - `}-token`: if `nested`, return without consuming; else discard.
270/// - anything else → consume a component value (discard result).
271pub fn consume_the_remnants_of_a_bad_declaration(input: &mut TokenStream, nested: bool) {
272 loop {
273 match input.next_token() {
274 Token::Eof | Token::Semicolon => {
275 input.discard_token();
276 return;
277 }
278 Token::CloseBrace => {
279 if nested {
280 return;
281 }
282 input.discard_token();
283 }
284 _ => {
285 // Discard the consumed component value.
286 let _ = consume_a_component_value(input);
287 }
288 }
289 }
290}
291
292/// §5.5.6 step 6 (L2682-2687): If the last two non-whitespace values are
293/// a `!` delim token followed by an `important` ident (ASCII
294/// case-insensitive), remove them (and any trailing whitespace
295/// between/after) and return `true`. Otherwise return `false`.
296///
297/// This does NOT strip trailing whitespace after the `!important` —
298/// that is the caller's responsibility (step 7).
299fn strip_important(value: &mut Vec<ComponentValue>) -> bool {
300 // Find the index just past the last non-whitespace value.
301 let mut end = value.len();
302 while end > 0
303 && matches!(
304 value[end - 1],
305 ComponentValue::PreservedToken(Token::Whitespace)
306 )
307 {
308 end -= 1;
309 }
310 if end < 2 {
311 return false;
312 }
313 let last = &value[end - 1];
314 let prev = &value[end - 2];
315 let is_important_ident = |v: &ComponentValue| match v {
316 ComponentValue::PreservedToken(Token::Ident(s)) => s.eq_ignore_ascii_case("important"),
317 _ => false,
318 };
319 let is_bang_delim =
320 |v: &ComponentValue| matches!(v, ComponentValue::PreservedToken(Token::Delim('!')));
321 if is_bang_delim(prev) && is_important_ident(last) {
322 // Truncate to `end - 2`, removing the `!important` (and any
323 // trailing whitespace after it).
324 value.truncate(end - 2);
325 return true;
326 }
327 false
328}
329
330/// §5.5.6 L2693: A "custom property name string" is an ident-token
331/// whose value starts with `--` (two hyphens).
332fn is_custom_property_name(name: &str) -> bool {
333 name.starts_with("--")
334}
335
336/// §5.5.6 L2700-2705: A declaration value contains a top-level
337/// {}-block AND any other non-whitespace value. (Only the whole
338/// value may be a {}-block for non-custom properties.)
339fn has_top_level_curly_block_with_other_values(value: &[ComponentValue]) -> bool {
340 let mut has_curly_block = false;
341 let mut has_other = false;
342 for v in value {
343 match v {
344 ComponentValue::SimpleBlock(SimpleBlock {
345 kind: BlockKind::Curly,
346 ..
347 }) => {
348 has_curly_block = true;
349 }
350 ComponentValue::PreservedToken(Token::Whitespace) => {}
351 _ => {
352 has_other = true;
353 }
354 }
355 }
356 has_curly_block && has_other
357}
358
359// ─── §5.5.1-§5.5.5 Stylesheet/rule/block algorithms ──────────────────
360
361/// §5.5.1 (L2223-2279) Consume a stylesheet's contents.
362///
363/// Repeatedly process input:
364/// - whitespace / CDO / CDC → discard.
365/// - EOF → return rules.
366/// - at-keyword → consume_an_at_rule; if `Some`, append.
367/// - else → consume_a_qualified_rule; if `Some(rule)`, append.
368pub fn consume_a_stylesheets_contents(input: &mut TokenStream) -> Vec<Rule> {
369 let mut rules = Vec::new();
370 loop {
371 match input.next_token() {
372 Token::Whitespace | Token::Cdo | Token::Cdc => {
373 input.discard_token();
374 }
375 Token::Eof => return rules,
376 Token::AtKeyword(_) => {
377 if let Some(rule) = consume_an_at_rule(input, false) {
378 rules.push(Rule::AtRule(rule));
379 }
380 }
381 _ => {
382 if let Ok(Some(rule)) = consume_a_qualified_rule(input, None, false) {
383 rules.push(Rule::QualifiedRule(rule));
384 }
385 }
386 }
387 }
388}
389
390/// §5.5.2 (L2281-2337) Consume an at-rule.
391///
392/// `nested`: when true, an unbalanced `}-token` returns the rule
393/// without consuming (caller will close the block); when false,
394/// `}-token` is part of the prelude.
395pub fn consume_an_at_rule(input: &mut TokenStream, nested: bool) -> Option<AtRule> {
396 let name = match input.consume_token() {
397 Token::AtKeyword(name) => name,
398 _ => unreachable!("consume_an_at_rule called on non-at-keyword"),
399 };
400 let mut rule = AtRule {
401 name,
402 prelude: Vec::new(),
403 declarations: None,
404 child_rules: None,
405 };
406 loop {
407 match input.next_token() {
408 Token::Semicolon | Token::Eof => {
409 input.discard_token();
410 return Some(rule);
411 }
412 Token::CloseBrace => {
413 if nested {
414 // §5.5.2 L2307-2310: nested → return rule (caller
415 // handles the closing brace).
416 return Some(rule);
417 }
418 // §5.5.2 L2313-2316: non-nested → consume to prelude
419 // (parse error, but tolerated).
420 let t = input.consume_token();
421 rule.prelude.push(ComponentValue::PreservedToken(t));
422 }
423 Token::OpenBrace => {
424 // §5.5.2 L2317-2331: consume_a_block → split into
425 // declarations + child rules.
426 let block = consume_a_block(input);
427 let (decls, rules) = split_block_contents(block);
428 rule.declarations = Some(decls);
429 rule.child_rules = Some(rules);
430 return Some(rule);
431 }
432 _ => {
433 // §5.5.2 L2333-2336: anything else → consume a
434 // component value, append to prelude.
435 rule.prelude.push(consume_a_component_value(input));
436 }
437 }
438 }
439}
440
441/// §5.5.3 (L2340-2466) Consume a qualified rule.
442///
443/// `stop_token`: optional token that aborts (returns `Ok(None)`).
444/// `nested`: passed down to consume_a_block's contents (controls
445/// `}-token` handling in nested contexts).
446///
447/// # Return values
448///
449/// - `Ok(Some(rule))` — rule successfully consumed.
450/// - `Ok(None)` — "return nothing" (e.g. EOF or stop_token).
451/// - `Err(ParseError)` — "invalid rule error" (e.g. custom-property-in-prelude
452/// at top level after consuming the block).
453pub fn consume_a_qualified_rule(
454 input: &mut TokenStream,
455 stop_token: Option<Token>,
456 nested: bool,
457) -> Result<Option<QualifiedRule>, ParseError> {
458 let mut rule = QualifiedRule {
459 prelude: Vec::new(),
460 declarations: Vec::new(),
461 child_rules: Vec::new(),
462 };
463 loop {
464 let next = input.next_token();
465 // §5.5.3 L2355-2359: EOF or stop_token → parse error, return
466 // nothing.
467 if matches!(next, Token::Eof) {
468 return Ok(None);
469 }
470 if stop_token.as_ref().is_some_and(|s| *s == next) {
471 return Ok(None);
472 }
473 match next {
474 Token::CloseBrace => {
475 // §5.5.3 L2361-2368: parse error.
476 if nested {
477 return Ok(None);
478 }
479 let t = input.consume_token();
480 rule.prelude.push(ComponentValue::PreservedToken(t));
481 }
482 Token::OpenBrace => {
483 // §5.5.3 L2370-2460.
484 // §5.5.3 L2372-2383: check if prelude looks like
485 // `--<ident> :` (custom-property-like). If so:
486 // nested → consume remnants of bad declaration, return
487 // nothing.
488 // non-nested → consume a block, return invalid rule
489 // error.
490 if looks_like_custom_property_in_prelude(&rule.prelude) {
491 if nested {
492 consume_the_remnants_of_a_bad_declaration(input, true);
493 return Ok(None);
494 } else {
495 let _ = consume_a_block(input);
496 return Err(ParseError); // invalid rule error
497 }
498 }
499 let block = consume_a_block(input);
500 let (decls, rules) = split_block_contents(block);
501 rule.declarations = decls;
502 rule.child_rules = rules;
503 return Ok(Some(rule));
504 }
505 _ => {
506 // §5.5.3 L2462-2465: anything else → consume a
507 // component value, append to prelude.
508 rule.prelude.push(consume_a_component_value(input));
509 }
510 }
511 }
512}
513
514/// §5.5.4 (L2469-2484) Consume a block.
515///
516/// Precondition: next token is `{-token`. Discard it, consume block
517/// contents, discard `}-token (or EOF), return the contents.
518pub fn consume_a_block(input: &mut TokenStream) -> BlockContents {
519 debug_assert!(matches!(input.next_token(), Token::OpenBrace));
520 input.discard_token();
521 let contents = consume_a_blocks_contents(input);
522 // §5.5.4 L2481: discard the closing `}-token (or EOF if implicit).
523 input.discard_token();
524 contents
525}
526
527/// §5.5.5 (L2486-2636) Consume a block's contents.
528///
529/// Returns a list of rules and lists-of-declarations (modeled as
530/// [`BlockContents`] carrying `Vec<Declaration>` and `Vec<Rule>`).
531/// Algorithm:
532/// - whitespace / `;` → discard.
533/// - EOF / `}` → return.
534/// - at-keyword → flush decls into rules (as `Rule::Declarations`),
535/// then `consume_an_at_rule(nested=true)`.
536/// - else → mark; `consume_a_declaration(nested=true)`; if
537/// `Some(decl)`, append to decls and discard mark. Otherwise
538/// `restore_mark`, then `consume_a_qualified_rule(nested=true,
539/// stop=`;`)`; on `Ok(Some(rule))`, flush decls to rules, append
540/// rule; on `Err(())`, flush decls to rules; on `Ok(None)`, do
541/// nothing.
542pub fn consume_a_blocks_contents(input: &mut TokenStream) -> BlockContents {
543 let mut rules: Vec<Rule> = Vec::new();
544 let mut decls: Vec<Declaration> = Vec::new();
545 loop {
546 match input.next_token() {
547 Token::Whitespace | Token::Semicolon => {
548 input.discard_token();
549 }
550 Token::Eof | Token::CloseBrace => {
551 // §5.5.5 L2514-2517: end of block — flush decls.
552 if !decls.is_empty() {
553 rules.push(Rule::Declarations(std::mem::take(&mut decls)));
554 }
555 return BlockContents {
556 decls: Vec::new(),
557 rules,
558 };
559 }
560 Token::AtKeyword(_) => {
561 // §5.5.5 L2519-2528: at-keyword flushes decls.
562 if !decls.is_empty() {
563 rules.push(Rule::Declarations(std::mem::take(&mut decls)));
564 }
565 if let Some(at_rule) = consume_an_at_rule(input, true) {
566 rules.push(Rule::AtRule(at_rule));
567 }
568 }
569 _ => {
570 // §5.5.5 L2530-2562: mark + declaration/rule ambiguity.
571 input.mark();
572 if let Some(decl) = consume_a_declaration(input, true) {
573 decls.push(decl);
574 input.discard_mark();
575 } else {
576 input.restore_mark();
577 match consume_a_qualified_rule(input, Some(Token::Semicolon), true) {
578 Ok(Some(rule)) => {
579 // §5.5.5 L2556-2561: rule returned.
580 if !decls.is_empty() {
581 rules.push(Rule::Declarations(std::mem::take(&mut decls)));
582 }
583 rules.push(Rule::QualifiedRule(rule));
584 }
585 Ok(None) => {
586 // §5.5.5 L2546-2547: "If nothing was
587 // returned, do nothing."
588 }
589 Err(ParseError) => {
590 // §5.5.5 L2549-2554: invalid rule error.
591 if !decls.is_empty() {
592 rules.push(Rule::Declarations(std::mem::take(&mut decls)));
593 }
594 }
595 }
596 }
597 }
598 }
599 }
600}
601
602/// Result of `consume_a_block` / `consume_a_blocks_contents`. Combines
603/// a list of declarations (possibly empty) and a list of child rules.
604///
605/// Note: when `consume_a_blocks_contents` returns, the declarations are
606/// always empty — any pending decls have been flushed into `rules` as
607/// `Rule::Declarations` variants (§5.5.5 L2514-2562). The `decls`
608/// field is kept for forward-compatibility with future CSSOM
609/// integration that may want a separate declaration list.
610#[derive(Debug, Clone, Default)]
611pub struct BlockContents {
612 pub decls: Vec<Declaration>,
613 pub rules: Vec<Rule>,
614}
615
616/// Split block contents from CP-5's `consume_a_block` into the
617/// AtRule / QualifiedRule's expected shape:
618/// - declarations → `Some(decls)` for AtRule, `decls` field for
619/// QualifiedRule
620/// - rules → `Some(rules)` for AtRule, `child_rules` field for
621/// QualifiedRule
622fn split_block_contents(block: BlockContents) -> (Vec<Declaration>, Vec<Rule>) {
623 (block.decls, block.rules)
624}
625
626/// §5.5.3 L2372-2383: Detect whether a qualified rule's prelude
627/// looks like `--<ident> :` (a custom property declaration
628/// masquerading as a rule). The first two non-whitespace tokens of
629/// the prelude must be:
630/// - Ident starting with `--`
631/// - Colon
632fn looks_like_custom_property_in_prelude(prelude: &[ComponentValue]) -> bool {
633 let mut iter = prelude
634 .iter()
635 .filter(|v| !matches!(v, ComponentValue::PreservedToken(Token::Whitespace)));
636 let first = iter.next();
637 let second = iter.next();
638 matches!(
639 (first, second),
640 (
641 Some(ComponentValue::PreservedToken(Token::Ident(name))),
642 Some(ComponentValue::PreservedToken(Token::Colon))
643 ) if name.starts_with("--")
644 )
645}