1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
//! §5.4.1 / §5.4.2 grammar-based parse entry points.
//!
//! Two generic entry points defined by CSS Syntax Module Level 3:
//!
//! - §5.4.1 (L1895-1944) `parse something according to a CSS grammar`
//! (aka [=CSS/parse=]): normalize → `parse a list of component
//! values` → match the resulting component-value list against a
//! grammar. Returns the grammar-specific output or failure.
//!
//! - §5.4.2 (L1949-2001) `parse a comma-separated list according to a
//! CSS grammar` (aka [=CSS/parse a list=]): normalize → if input is
//! whitespace-only return an empty list; otherwise `parse a
//! comma-separated list of component values`, then match each group
//! against the grammar. Returns a `Vec` of `Result`s preserving
//! per-group failures.
//!
//! # Why a `Grammar` trait?
//!
//! The CSS Syntax spec leaves the actual grammar-matching to the spec
//! that defines the grammar (e.g. Selectors, Values & Units). We model
//! this as a trait so any crate can plug in its own grammar by
//! implementing [`Grammar`]:
//!
//! ```text
//! pub trait Grammar {
//! type Output;
//! fn parse(&self, input: &[ComponentValue]) -> Result<Self::Output, ParseError>;
//! }
//! ```
//!
//! # Spec references
//!
//! Source: `D:\CSSWG\css-syntax-3\Overview.md`, §5.4.1 L1895-1944,
//! §5.4.2 L1949-2001.
use crateconsume_a_list_of_component_values;
use cratenormalize_from_string;
use crateTokenStream;
use crate;
use Token;
/// §5.4.1: A CSS grammar production.
///
/// Implementors receive the component-value list produced by
/// [`parse_a_grammar`] / [`parse_a_comma_separated_list_with_grammar`]
/// and decide whether it matches the grammar. Returning `Ok` yields
/// the grammar-specific output; returning `Err` signals failure per
/// §5.4.1 L1944 ("otherwise, return failure").
/// §5.4.1 (L1895-1944): Parse something according to a CSS grammar.
///
/// Algorithm (spec verbatim):
///
/// 1. Normalize `input`, and set `input` to the result.
/// 2. Parse a list of component values from `input`, and let `result`
/// be the return value.
/// 3. Attempt to match `result` against `grammar`. If this is
/// successful, return the matched result; otherwise, return
/// failure.
///
/// # Examples
///
/// ```ignore
/// use muskitty_css_parser::{Grammar, parse_a_grammar, ComponentValue, ParseError};
///
/// struct CountingGrammar;
/// impl Grammar for CountingGrammar {
/// type Output = usize;
/// fn parse(&self, input: &[ComponentValue]) -> Result<usize, ParseError> {
/// Ok(input.len())
/// }
/// }
///
/// assert_eq!(parse_a_grammar("a b c", &CountingGrammar).unwrap(), 5);
/// // 5 = 3 idents + 2 whitespace tokens.
/// ```
/// §5.4.2 (L1949-2001): Parse a comma-separated list according to a
/// CSS grammar.
///
/// Algorithm (spec verbatim):
///
/// 1. Normalize `input`, and set `input` to the result.
/// 2. If `input` contains only whitespace tokens, return an empty
/// list.
/// 3. Parse a comma-separated list of component values from `input`,
/// and let `list` be the return value.
/// 4. For each `item` of `list`, replace `item` with the result of
/// [=CSS/parsing=] `item` with `grammar`.
/// 5. Return `list`.
///
/// Each `item` is itself a `Vec<ComponentValue>` (one comma-group of
/// the comma-separated parse). The grammar is applied to each group
/// independently; failures are preserved per-group rather than
/// failing the entire call, per §5.4.2 L1956-1967.
/// §5.4.2 step 3 helper: Parse a comma-separated list of component
/// values from a token stream.
///
/// This is the same algorithm as
/// [`crate::entry_points::parse_a_comma_separated_list_of_component_values`]
/// but operating on an already-normalized `TokenStream` rather than a
/// raw `&str` (so the caller can normalize once and reuse the stream).