muskitty_css_parser/lib.rs
1//! MusKitty CSS Parser
2//!
3//! Implements the parsing stage of the CSS Syntax Module Level 3 (§5
4//! "Parser Algorithms"). Extracted from `muskitty-css` as a standalone
5//! crate for independent versioning and publication.
6//!
7//! Re-exports [`Token`] / [`Tokenizer`] / [`CssTokenizer`] from
8//! `muskitty-css-tokenizer` so downstream crates (e.g.
9//! `muskitty-selectors`) can depend on this single crate to access
10//! the full CSS Syntax stack.
11//!
12//! # Architecture
13//!
14//! The parser follows the two-stage model described in CSS Syntax §3.1:
15//! 1. **Tokenization** — handled by `muskitty-css-tokenizer` (re-exported
16//! here for convenience).
17//! 2. **Parsing** — consumes tokens and produces CSS objects:
18//! stylesheets, rules, declarations, component values (§5, fully
19//! implemented).
20//!
21//! # Top-level API
22//!
23//! - [`parse_stylesheet`] — full stylesheet parse (§5.4.3)
24//! - [`parse_rule`] — single rule parse (§5.4.6)
25//! - [`parse_declaration`] — single declaration parse (§5.4.7)
26//! - [`parse_component_value`] — single component value (§5.4.8)
27//! - [`parse_list_of_component_values`] — list of component values (§5.4.9)
28//! - [`parse_comma_separated_list_of_component_values`] — comma-separated list (§5.4.10)
29//! - [`parse_a_grammar`] / [`parse_a_comma_separated_list_with_grammar`] — generic grammar hooks (§5.4.1 / §5.4.2)
30//! - [`tokenize`] — token stream only (§4.3)
31//!
32//! # References
33//!
34//! - CSS Syntax Module Level 3: <https://drafts.csswg.org/css-syntax-3/>
35//! - Spec source (Markdown): `D:\CSSWG\css-syntax-3\Overview.md`
36
37pub mod algorithms;
38pub mod entry_points;
39pub mod grammar;
40pub mod token_stream;
41pub mod types;
42
43// Re-export from muskitty-css-tokenizer for downstream convenience.
44// Downstream crates that depend only on `muskitty-css-parser` get the
45// full tokenizer + parser stack through this single dependency.
46pub use muskitty_css_tokenizer::{CssTokenizer, HashType, Numeric, State, Token, Tokenizer};
47
48// Re-export parser data structures and algorithms at crate root.
49pub use algorithms::{
50 consume_a_block, consume_a_blocks_contents, consume_a_component_value, consume_a_declaration,
51 consume_a_function, consume_a_list_of_component_values, consume_a_qualified_rule,
52 consume_a_simple_block, consume_a_stylesheets_contents, consume_a_unicode_range_value,
53 consume_an_at_rule, consume_the_remnants_of_a_bad_declaration, BlockContents,
54};
55pub use entry_points::{
56 parse_a_blocks_contents, parse_a_comma_separated_list_of_component_values,
57 parse_a_component_value, parse_a_declaration, parse_a_list_of_component_values, parse_a_rule,
58 parse_a_stylesheet, parse_a_stylesheets_contents,
59};
60pub use grammar::{parse_a_comma_separated_list_with_grammar, parse_a_grammar, Grammar};
61pub use token_stream::TokenStream;
62pub use types::{
63 AtRule, BlockKind, ComponentValue, Declaration, Function, ParseError, QualifiedRule, Rule,
64 SimpleBlock, Stylesheet,
65};
66
67/// Tokenize a CSS input string into a vector of tokens.
68///
69/// Implements the tokenization stage of CSS Syntax §3.1: construct a
70/// tokenizer over `input` (after §5.3 input preprocessing, which the
71/// tokenizer applies internally), then drain all tokens up to and
72/// including `<EOF-token>`.
73///
74/// Returns the token stream without the trailing `<EOF-token>`. Parse
75/// errors are currently discarded; a future API will expose them.
76///
77/// # Examples
78///
79/// ```
80/// use muskitty_css_parser::tokenize;
81/// use muskitty_css_parser::Token;
82///
83/// let tokens = tokenize("color: red;");
84/// assert!(matches!(tokens[0], Token::Ident(_)));
85/// assert!(matches!(tokens[1], Token::Colon));
86/// assert!(matches!(tokens[2], Token::Whitespace));
87/// assert!(matches!(tokens[3], Token::Ident(_)));
88/// assert!(matches!(tokens[4], Token::Semicolon));
89/// ```
90pub fn tokenize(input: &str) -> Vec<Token> {
91 let mut tz = CssTokenizer::new(input);
92 let mut out = Vec::new();
93 while let Some(token) = tz.next_token() {
94 if matches!(token, Token::Eof) {
95 break;
96 }
97 out.push(token);
98 }
99 out
100}
101
102/// Parse a CSS string into a [`Stylesheet`] (§5.4.3).
103///
104/// Implements `parse a stylesheet` from CSS Syntax §5.4.3: tokenize
105/// the input (with §5.3 preprocessing), then `consume a stylesheet's
106/// contents` (§5.5.1) to produce the list of rules.
107///
108/// # Examples
109///
110/// ```
111/// use muskitty_css_parser::parse_stylesheet;
112///
113/// let ss = parse_stylesheet("a { color: red; }");
114/// assert_eq!(ss.rules.len(), 1);
115/// ```
116pub fn parse_stylesheet(input: &str) -> Stylesheet {
117 parse_a_stylesheet(input)
118}
119
120/// Parse a CSS string into a single [`Rule`] (§5.4.6).
121///
122/// Returns `None` for a syntax error (empty input or trailing garbage).
123///
124/// # Examples
125///
126/// ```
127/// use muskitty_css_parser::parse_rule;
128///
129/// assert!(parse_rule("@media print {}").is_some());
130/// assert!(parse_rule("").is_none());
131/// ```
132pub fn parse_rule(input: &str) -> Option<Rule> {
133 parse_a_rule(input)
134}
135
136/// Parse a CSS string into a single [`Declaration`] (§5.4.7).
137///
138/// Returns `None` for a syntax error (malformed declaration).
139///
140/// # Examples
141///
142/// ```
143/// use muskitty_css_parser::parse_declaration;
144///
145/// let decl = parse_declaration("color: red").unwrap();
146/// assert_eq!(decl.name, "color");
147/// ```
148pub fn parse_declaration(input: &str) -> Option<Declaration> {
149 parse_a_declaration(input)
150}
151
152/// Parse a CSS string into a single [`ComponentValue`] (§5.4.8).
153///
154/// Returns `None` for a syntax error (empty input or trailing
155/// garbage after the component value).
156///
157/// # Examples
158///
159/// ```
160/// use muskitty_css_parser::parse_component_value;
161/// use muskitty_css_parser::ComponentValue;
162/// use muskitty_css_parser::Token;
163///
164/// let cv = parse_component_value("red").unwrap();
165/// assert!(matches!(cv, ComponentValue::PreservedToken(Token::Ident(_))));
166/// ```
167pub fn parse_component_value(input: &str) -> Option<ComponentValue> {
168 parse_a_component_value(input)
169}
170
171/// Parse a CSS string into a list of [`ComponentValue`] (§5.4.9).
172///
173/// # Examples
174///
175/// ```
176/// use muskitty_css_parser::parse_list_of_component_values;
177///
178/// // "a b c" → 5 component values: a, ws, b, ws, c.
179/// let list = parse_list_of_component_values("a b c");
180/// assert_eq!(list.len(), 5);
181/// ```
182pub fn parse_list_of_component_values(input: &str) -> Vec<ComponentValue> {
183 parse_a_list_of_component_values(input)
184}
185
186/// Parse a CSS string into a comma-separated list of [`ComponentValue`]
187/// (§5.4.10).
188///
189/// # Examples
190///
191/// ```
192/// use muskitty_css_parser::parse_comma_separated_list_of_component_values;
193///
194/// // "a, b, c" → 3 groups. Per §5.4.10, the algorithm does not
195/// // discard leading whitespace between commas, so groups after the
196/// // first carry a leading whitespace token.
197/// let groups = parse_comma_separated_list_of_component_values("a, b, c");
198/// assert_eq!(groups.len(), 3);
199/// ```
200pub fn parse_comma_separated_list_of_component_values(input: &str) -> Vec<Vec<ComponentValue>> {
201 parse_a_comma_separated_list_of_component_values(input)
202}