Skip to main content

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}