muskitty_css_parser/entry_points.rs
1//! §5.4 Parser Entry Points.
2//!
3//! Nine entry points producing high-level CSS objects from input. The
4//! grammar-based hooks §5.4.1 (`parse something according to a CSS
5//! grammar`) and §5.4.2 (`parse a comma-separated list according to a
6//! CSS grammar`) are implemented in [`crate::grammar`] (using the
7//! [`Grammar`](crate::grammar::Grammar) trait).
8//!
9//! # References
10//!
11//! - CSS Syntax Module Level 3 §5.4 L1816-2206.
12//! - Source: `D:\CSSWG\css-syntax-3\Overview.md`.
13
14use crate::algorithms::{
15 consume_a_blocks_contents, consume_a_component_value, consume_a_declaration,
16 consume_a_list_of_component_values, consume_a_qualified_rule, consume_a_stylesheets_contents,
17 consume_an_at_rule, BlockContents,
18};
19use crate::token_stream::TokenStream;
20use crate::types::{ComponentValue, Declaration, Rule, Stylesheet};
21use muskitty_css_tokenizer::{CssTokenizer, Token, Tokenizer};
22
23/// §5.4 (L1827-1842) Normalize into a token stream.
24///
25/// Per §5.4 L1837-1840 (the "string" case): filter code points,
26/// tokenize the result, return the stream of tokens. Our tokenizer
27/// applies §5.3 preprocessing (filter code points) internally, so we
28/// just drain all tokens up to and including the `<EOF-token>`.
29pub(crate) fn normalize_from_string(input: &str) -> TokenStream {
30 let mut tz = CssTokenizer::new(input);
31 let mut tokens = Vec::new();
32 while let Some(token) = tz.next_token() {
33 let is_eof = matches!(token, Token::Eof);
34 tokens.push(token);
35 if is_eof {
36 break;
37 }
38 }
39 TokenStream::new(tokens)
40}
41
42/// §5.4.3 (L2005-2033) Parse a stylesheet.
43///
44/// Normalize → consume a stylesheet's contents → wrap in `Stylesheet`.
45///
46/// The spec also accepts an optional location; we do not model the
47/// stylesheet location here (deferred to CSSOM integration).
48pub fn parse_a_stylesheet(input: &str) -> Stylesheet {
49 let mut stream = normalize_from_string(input);
50 let rules = consume_a_stylesheets_contents(&mut stream);
51 Stylesheet { rules }
52}
53
54/// §5.4.4 (L2037-2051) Parse a stylesheet's contents.
55///
56/// Normalize → consume a stylesheet's contents → return the rule list.
57pub fn parse_a_stylesheets_contents(input: &str) -> Vec<Rule> {
58 let mut stream = normalize_from_string(input);
59 consume_a_stylesheets_contents(&mut stream)
60}
61
62/// §5.4.5 (L2055-2069) Parse a block's contents.
63///
64/// Normalize → consume a block's contents → return `BlockContents`.
65pub fn parse_a_blocks_contents(input: &str) -> BlockContents {
66 let mut stream = normalize_from_string(input);
67 consume_a_blocks_contents(&mut stream)
68}
69
70/// §5.4.6 (L2073-2109) Parse a rule.
71///
72/// # Algorithm
73///
74/// 1. Normalize input.
75/// 2. Discard whitespace.
76/// 3. If next token is EOF → syntax error (`None`).
77/// If next token is at-keyword → consume an at-rule; on `None`,
78/// syntax error (`None`).
79/// Otherwise → consume a qualified rule (non-nested); on nothing or
80/// invalid rule error, syntax error (`None`).
81/// 4. Discard whitespace.
82/// 5. If next token is EOF → return rule; otherwise syntax error
83/// (`None`).
84pub fn parse_a_rule(input: &str) -> Option<Rule> {
85 let mut stream = normalize_from_string(input);
86 stream.discard_whitespace();
87 let rule = match stream.next_token() {
88 // §5.4.6 L2088-2089: EOF → syntax error.
89 Token::Eof => return None,
90 // §5.4.6 L2091-2094: at-keyword → consume an at-rule.
91 Token::AtKeyword(_) => consume_an_at_rule(&mut stream, false).map(Rule::AtRule),
92 // §5.4.6 L2096-2100: otherwise → consume a qualified rule. If
93 // nothing or invalid rule error → syntax error (None).
94 _ => consume_a_qualified_rule(&mut stream, None, false)
95 .ok()
96 .flatten()
97 .map(Rule::QualifiedRule),
98 };
99 // §5.4.6 L2103: discard whitespace.
100 stream.discard_whitespace();
101 // §5.4.6 L2106-2108: if EOF → return rule; otherwise syntax error.
102 if stream.is_empty() {
103 rule
104 } else {
105 None
106 }
107}
108
109/// §5.4.7 (L2113-2134) Parse a declaration.
110///
111/// Normalize → discard whitespace → consume a declaration (non-nested).
112/// If anything was returned, return it; otherwise syntax error
113/// (`None`).
114pub fn parse_a_declaration(input: &str) -> Option<Declaration> {
115 let mut stream = normalize_from_string(input);
116 stream.discard_whitespace();
117 consume_a_declaration(&mut stream, false)
118}
119
120/// §5.4.8 (L2138-2168) Parse a component value.
121///
122/// # Algorithm
123///
124/// 1. Normalize input.
125/// 2. Discard whitespace.
126/// 3. If input is empty → syntax error (`None`).
127/// 4. Consume a component value, let `value` be the return value.
128/// 5. Discard whitespace.
129/// 6. If input is empty → return `value`; otherwise syntax error
130/// (`None`).
131pub fn parse_a_component_value(input: &str) -> Option<ComponentValue> {
132 let mut stream = normalize_from_string(input);
133 stream.discard_whitespace();
134 // §5.4.8 L2153-2154: empty → syntax error.
135 if stream.is_empty() {
136 return None;
137 }
138 // §5.4.8 L2157-2158: consume a component value.
139 let value = consume_a_component_value(&mut stream);
140 // §5.4.8 L2161: discard whitespace.
141 stream.discard_whitespace();
142 // §5.4.8 L2164-2167: if empty → return value; else syntax error.
143 if stream.is_empty() {
144 Some(value)
145 } else {
146 None
147 }
148}
149
150/// §5.4.9 (L2172-2183) Parse a list of component values.
151///
152/// Normalize → consume a list of component values (no stop token,
153/// non-nested) → return the result.
154pub fn parse_a_list_of_component_values(input: &str) -> Vec<ComponentValue> {
155 let mut stream = normalize_from_string(input);
156 consume_a_list_of_component_values(&mut stream, None, false)
157}
158
159/// §5.4.10 (L2186-2204) Parse a comma-separated list of component
160/// values.
161///
162/// # Algorithm
163///
164/// 1. Normalize input.
165/// 2. Let `groups` be an empty list.
166/// 3. While input is not empty:
167/// a. Consume a list of component values with `,` as the stop token and append to `groups`.
168/// b. Discard a token (the comma; `discard_token` is a no-op on EOF).
169/// 4. Return `groups`.
170pub fn parse_a_comma_separated_list_of_component_values(input: &str) -> Vec<Vec<ComponentValue>> {
171 let mut stream = normalize_from_string(input);
172 let mut groups = Vec::new();
173 while !stream.is_empty() {
174 // §5.4.10 L2199-2201: consume a list of component values with
175 // `,` as the stop token.
176 let group = consume_a_list_of_component_values(&mut stream, Some(Token::Comma), false);
177 groups.push(group);
178 // §5.4.10 L2202: discard a token (the comma). On EOF, this is
179 // a no-op (§5.3 L1784-1786).
180 stream.discard_token();
181 }
182 groups
183}