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::Token;
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. 使用
27/// [`TokenStream::with_source`] 以保留原始 source text,供 §5.5.6
28/// `original_text`(custom property)使用。
29pub(crate) fn normalize_from_string(input: &str) -> TokenStream {
30    TokenStream::with_source(input)
31}
32
33/// §5.4.3 (L2005-2033) Parse a stylesheet.
34///
35/// Normalize → consume a stylesheet's contents → wrap in `Stylesheet`.
36///
37/// The spec also accepts an optional location; we do not model the
38/// stylesheet location here (deferred to CSSOM integration).
39pub fn parse_a_stylesheet(input: &str) -> Stylesheet {
40    let mut stream = normalize_from_string(input);
41    let rules = consume_a_stylesheets_contents(&mut stream);
42    Stylesheet { rules }
43}
44
45/// §5.4.4 (L2037-2051) Parse a stylesheet's contents.
46///
47/// Normalize → consume a stylesheet's contents → return the rule list.
48pub fn parse_a_stylesheets_contents(input: &str) -> Vec<Rule> {
49    let mut stream = normalize_from_string(input);
50    consume_a_stylesheets_contents(&mut stream)
51}
52
53/// §5.4.5 (L2055-2069) Parse a block's contents.
54///
55/// Normalize → consume a block's contents → return `BlockContents`.
56pub fn parse_a_blocks_contents(input: &str) -> BlockContents {
57    let mut stream = normalize_from_string(input);
58    consume_a_blocks_contents(&mut stream)
59}
60
61/// §5.4.6 (L2073-2109) Parse a rule.
62///
63/// # Algorithm
64///
65/// 1. Normalize input.
66/// 2. Discard whitespace.
67/// 3. If next token is EOF → syntax error (`None`).
68///    If next token is at-keyword → consume an at-rule; on `None`,
69///    syntax error (`None`).
70///    Otherwise → consume a qualified rule (non-nested); on nothing or
71///    invalid rule error, syntax error (`None`).
72/// 4. Discard whitespace.
73/// 5. If next token is EOF → return rule; otherwise syntax error
74///    (`None`).
75pub fn parse_a_rule(input: &str) -> Option<Rule> {
76    let mut stream = normalize_from_string(input);
77    stream.discard_whitespace();
78    let rule = match stream.next_token() {
79        // §5.4.6 L2088-2089: EOF → syntax error.
80        Token::Eof => return None,
81        // §5.4.6 L2091-2094: at-keyword → consume an at-rule.
82        Token::AtKeyword(_) => consume_an_at_rule(&mut stream, false).map(Rule::AtRule),
83        // §5.4.6 L2096-2100: otherwise → consume a qualified rule. If
84        // nothing or invalid rule error → syntax error (None).
85        _ => consume_a_qualified_rule(&mut stream, None, false)
86            .ok()
87            .flatten()
88            .map(Rule::QualifiedRule),
89    };
90    // §5.4.6 L2103: discard whitespace.
91    stream.discard_whitespace();
92    // §5.4.6 L2106-2108: if EOF → return rule; otherwise syntax error.
93    if stream.is_empty() {
94        rule
95    } else {
96        None
97    }
98}
99
100/// §5.4.7 (L2113-2134) Parse a declaration.
101///
102/// Normalize → discard whitespace → consume a declaration (non-nested).
103/// If anything was returned, return it; otherwise syntax error
104/// (`None`).
105pub fn parse_a_declaration(input: &str) -> Option<Declaration> {
106    let mut stream = normalize_from_string(input);
107    stream.discard_whitespace();
108    consume_a_declaration(&mut stream, false)
109}
110
111/// §5.4.8 (L2138-2168) Parse a component value.
112///
113/// # Algorithm
114///
115/// 1. Normalize input.
116/// 2. Discard whitespace.
117/// 3. If input is empty → syntax error (`None`).
118/// 4. Consume a component value, let `value` be the return value.
119/// 5. Discard whitespace.
120/// 6. If input is empty → return `value`; otherwise syntax error
121///    (`None`).
122pub fn parse_a_component_value(input: &str) -> Option<ComponentValue> {
123    let mut stream = normalize_from_string(input);
124    stream.discard_whitespace();
125    // §5.4.8 L2153-2154: empty → syntax error.
126    if stream.is_empty() {
127        return None;
128    }
129    // §5.4.8 L2157-2158: consume a component value.
130    let value = consume_a_component_value(&mut stream);
131    // §5.4.8 L2161: discard whitespace.
132    stream.discard_whitespace();
133    // §5.4.8 L2164-2167: if empty → return value; else syntax error.
134    if stream.is_empty() {
135        Some(value)
136    } else {
137        None
138    }
139}
140
141/// §5.4.9 (L2172-2183) Parse a list of component values.
142///
143/// Normalize → consume a list of component values (no stop token,
144/// non-nested) → return the result.
145pub fn parse_a_list_of_component_values(input: &str) -> Vec<ComponentValue> {
146    let mut stream = normalize_from_string(input);
147    consume_a_list_of_component_values(&mut stream, None, false)
148}
149
150/// §5.4.10 (L2186-2204) Parse a comma-separated list of component
151/// values.
152///
153/// # Algorithm
154///
155/// 1. Normalize input.
156/// 2. Let `groups` be an empty list.
157/// 3. While input is not empty:
158///    a. Consume a list of component values with `,` as the stop token and append to `groups`.
159///    b. Discard a token (the comma; `discard_token` is a no-op on EOF).
160/// 4. Return `groups`.
161pub fn parse_a_comma_separated_list_of_component_values(input: &str) -> Vec<Vec<ComponentValue>> {
162    let mut stream = normalize_from_string(input);
163    let mut groups = Vec::new();
164    while !stream.is_empty() {
165        // §5.4.10 L2199-2201: consume a list of component values with
166        // `,` as the stop token.
167        let group = consume_a_list_of_component_values(&mut stream, Some(Token::Comma), false);
168        groups.push(group);
169        // §5.4.10 L2202: discard a token (the comma). On EOF, this is
170        // a no-op (§5.3 L1784-1786).
171        stream.discard_token();
172    }
173    groups
174}