Repository navigation
CSS
parsec-html-css (crates/parsec-css, crate parsec_css) is the CSS module's first part: CSS Syntax Level 3 as the current editor's draft has it, nesting included. It turns CSS text into tokens, then into rules, declarations and component values, each with its place in the source, and writes them back out as CSS. I wrote it from the spec, with no dependency but encoding_rs, which only the bytes-in function uses.
What it doesn't do yet is know any properties. color: red comes back as a declaration named color whose value is the ident red; what red means is #29, and the cascade is #30. Both build on this crate.
On this page: Using it · Entry points · The tree · Positions · Nesting and block contents · Tokens · An+B and unicode ranges · Serialization · Bytes in · Conformance · What fails, and why · Speed · Fuzzing · Next to Lexbor
It isn't on crates.io yet. From git:
[dependencies]
parsec-html-css = { git = "https://github.com/parsec-html/parsec" }use parsec_css::{Item, LineIndex, Rule};
let css = "a { color: red; &:hover { color: blue } }";
let sheet = parsec_css::parse_stylesheet(css);
let Rule::Qualified(rule) = &sheet.rules[0] else { unreachable!() };
assert_eq!(parsec_css::to_css(&rule.prelude), "a ");
let contents = rule.block.clone().contents(css);
let Item::Declaration(color) = &contents.items[0] else { unreachable!() };
assert_eq!(&*color.name, "color");
assert_eq!(color.span.text(css), "color: red");
assert_eq!(LineIndex::new(css).line_column(css, color.span.start), (1, 5));One function per entry point in the spec, plus two the 2021 draft had that are still useful.
| Function | Spec | Returns |
|---|---|---|
parse_stylesheet(css) |
parse a stylesheet, and a stylesheet's contents |
Stylesheet: rules and errors. <!-- and --> between rules are skipped. |
parse_rule_list(css) |
the 2021 draft's "parse a list of rules" | The same, with <!-- and --> kept as tokens. |
parse_block_contents(css) |
consume a block's contents |
BlockContents: declarations and rules, in order, and errors. What a style rule's {} holds. |
parse_declaration_list(css) |
parse a list of declarations |
BlockContents with declarations, plus any at-rules, which the spec drops and I keep as Item::Rule for you to drop. For style="". |
parse_rule(css) |
parse a rule |
Result<Rule, ParseError>: exactly one, or Empty, InvalidRule or ExtraInput. |
parse_declaration(css) |
parse a declaration |
Result<Declaration, ParseError>, as @supports (…) needs. |
parse_component_value(css) |
parse a component value | Result<ComponentValue, ParseError> |
parse_component_values(css) |
parse a list of component values |
Vec<ComponentValue>: the whole input, as a selector or a media query list is read. |
parse_comma_separated(css) |
parse a comma-separated list of component values |
Vec<Vec<ComponentValue>>, split at commas outside any block. |
parse_unicode_range_value(css) |
consume the value of a unicode-range descriptor | Component values with <unicode-range-token>s. |
SimpleBlock::contents(self, src) |
consume a block | The block's declarations and rules: parse_block_contents for a block you already have. |
Nothing panics on any input, and nothing is thrown away silently: whatever a parse drops goes into errors, with a kind and the span it covered.
Every type borrows the text it was parsed from ('a), and every one has a span.
| Type | What it holds |
|---|---|
Stylesheet |
rules: Vec<Rule>, errors: Vec<ParseError>
|
Rule |
At(AtRule) or Qualified(QualifiedRule); span()
|
AtRule |
name, prelude: Vec<ComponentValue>, block: Option<SimpleBlock>, span
|
QualifiedRule |
prelude, block: SimpleBlock, span. A style rule when the prelude is a selector. |
Declaration |
name, value: Vec<ComponentValue> without the whitespace at either end or the !important, important: bool, span; original_text(src) gives the value as written, which custom properties keep. |
BlockContents |
items: Vec<Item>, errors
|
Item |
Declaration(Declaration) or Rule(Rule)
|
ComponentValue |
Token(Token, Span), Function(Function) or Block(SimpleBlock); span(), token(), is_whitespace()
|
Function |
name, arguments, span
|
SimpleBlock |
bracket (Paren, Square or Curly), contents, span
|
ParseError |
kind (Empty, ExtraInput, InvalidDeclaration, InvalidRule) and span; Display and Error
|
Names and values are Cow<str>: borrowed from your text unless an escape or a NUL changed them, so a\62 c is the owned string abc and abc is a slice of the input. Number tokens keep the text they were written as too (repr), so +.5e3 serializes as +.5e3.
A ), ] or } with nothing to close stays in the tree as a token, as the spec keeps it, so a media query parser can do its own error recovery.
A span is two byte offsets into the text you parsed, start..end; span.text(css) gives the text back. They're free to keep, so everything has one: each token, function, block, rule and declaration. A declaration's span runs from its name to the end of its value or its important, without the ;. A rule's runs from its first token to the } or ; that ends it.
Lines and columns are counted only when you ask. LineIndex::new(css) finds where each line starts, once, and line_column(css, offset) gives the 1-based line and column of an offset by binary search. CR LF, CR, LF and form feed each end one line, as CSS counts them, and columns count code points.
This is what lexbor#374 asked Lexbor for: positions on every rule and declaration.
Since CSS Nesting, a style rule's block holds declarations and rules mixed: color: red; &:hover { color: blue }. The draft parses each item as a declaration first and, if that fails, again as a rule, so a:hover {…} inside a block is a nested rule and color: red is a declaration. parse_block_contents and SimpleBlock::contents do exactly that, including its edge cases: a {} block is only allowed as the whole of a property's value, and --x:hover {…} is always a custom property gone wrong, never a rule.
parse_stylesheet keeps each rule's {} block as it was parsed, as component values, and parses its contents when you call contents. That's because what a block holds depends on the rule: @media holds rules, @font-face holds descriptors, an at-rule nobody knows holds whatever it likes. The result is the same either way; cargo test checks that parsing a block later gives what parsing it at once does.
Tokenizer::new(css) is an iterator of (Token, Span), comments skipped. Every token type in the spec is there: Ident, Function, AtKeyword, Hash { value, id }, String, BadString, Url, BadUrl, Delim, Number, Percentage, Dimension { number, unit }, UnicodeRange { start, end }, Whitespace, Cdo, Cdc, Colon, Semicolon, Comma and the six brackets. A Number has value: f64, integer (the type flag), repr, sign() and int().
The spec's preprocessing (CR LF, CR and FF to LF, NUL to U+FFFD) isn't a copy of the input here. Copying a stylesheet would cost more than tokenizing it, so every newline test accepts all four forms and a NUL counts as the U+FFFD it stands for. Positions are therefore offsets into your text, not into a filtered copy.
Two choices worth knowing about:
-
The non-ASCII ident code points are the 2024 set, the code points HTML allows in custom element names. Before that every code point from U+0080 up counted, so
\u{80}was an ident and is now a delim. -
url( "x"): the spec has the function token swallow all but one of the spaces afterurl(. I give them all to the whitespace token after it instead, which makes the same tokens withurl(as the function's text.
parse_anb(css) reads An+B, the microsyntax in :nth-child(), from text, and anb(&values) from component values you already have. Both return Some((a, b)) or None; values past i32 saturate. serialize_anb(a, b) writes it back the way the spec serializes it: 2n+1, -n, 5.
parse_unicode_ranges(css) reads a unicode-range descriptor: one Option<UnicodeRange> per comma-separated range, None where it isn't exactly one range, or the range is backwards or goes past U+10FFFF. A declaration named unicode-range gets its value tokenized this way automatically, as the spec says: U+0-7F is one range token there, and an ident and two numbers anywhere else.
to_css(&values) and write_values(&mut out, &values) write component values; Display writes a Stylesheet, BlockContents, Rule, AtRule, QualifiedRule, Declaration, SimpleBlock or ComponentValue. write_identifier and write_string are CSSOM's "serialize an identifier" and "serialize a string".
The spec only asks that what's written parses back to the same thing, runs of whitespace aside, and that's what this promises. It writes each token in its plainest form: strings in double quotes, url() unquoted with escapes, numbers as you wrote them. Where two tokens would run together it puts /**/ between them, from the spec's table plus two pairs the table misses: the ident -- before >, and < before !, which would otherwise read back as --> and <!--. The fuzzer found the first one.
cargo test serializes every input in the suite below, as values, as a stylesheet and as block contents, parses the output and checks it comes back the same. The fuzz target does the same for whatever it generates.
decode_stylesheet(bytes, protocol, environment) decodes a stylesheet the way CSS Syntax §3.2 says: a byte order mark wins; then the charset label HTTP gave, if encoding_rs knows it; then an @charset "…"; written exactly so in the first 1,024 bytes (UTF-16 there means UTF-8); then the encoding of the document that linked it; then UTF-8. It returns the text and the encoding used. fallback_encoding gives the encoding alone.
let (text, encoding) = parsec_css::decode_stylesheet(b"@charset \"iso-8859-5\"; @\xe9", None, None);
assert_eq!((&*text, encoding.name()), ("@charset \"iso-8859-5\"; @щ", "ISO-8859-5"));Three suites, all in cargo test, all pinned in crates/parsec-css/tests with their commit and licence beside them, and all in each CI run's conformance summary.
| Suite | Data | Passed | Failed | Skipped |
|---|---|---|---|---|
| css-parsing-tests |
tests/css-parsing-tests, at 203ce36
|
293 | 12 | 8,061 |
its <urange> cases, from rust-cssparser's copy |
tests/urange, at 4765111
|
12 | 0 | 0 |
| css-tokenizer-tests |
tests/css-tokenizer-tests, at 0db1d12
|
287 | 0 | 0 |
css-parsing-tests: 293 passed, 12 failed, 8061 skipped (CSS Color)
urange: 12 passed, 0 failed
css-tokenizer-tests: 287 passed, 0 failed
css-parsing-tests is the implementation-independent suite Simon Sapin started for Servo and tinycss2. SimonSapin's repository now points to CourtBouillon's, where the tinycss2 maintainers keep it, so that's the copy pinned here, at its latest commit. Every file runs. The 8,061 skipped are the color_* files, which test CSS Color, not CSS Syntax; they wait for typed values (#29). Of the 305 syntax cases, 293 pass, and the other 12 are on the list below.
The suite was written against older drafts than the one followed here, so the runner allows for four differences of form, not of parsing, and says so in its header:
- two delims written side by side, like
~then=, count as the one~=token the 2013 draft had; - the
eof-in-stringandeof-in-urlerrors tinycss2 puts into its trees are left out, since the spec doesn't put parse errors in the tree; - whitespace at the two ends of a declaration's value isn't compared, because the spec trims it and the suite's parsers keep it;
- errors and results are put in source order by their spans, since
errorsis a list of its own here.
The <urange> cases come from rust-cssparser's copy of the suite, the only one that has them, since <urange> changed after the original was written. All 12 pass.
css-tokenizer-tests is Romain Menke's corpus for CSS tokenizers: 287 stylesheets, each with every token's type, text, start, end and value. Every field a case gives is compared, so this checks positions as well as tokens. Its positions are UTF-16 indexes, as JavaScript counts, and the runner converts. Its three community stylesheets (Bootstrap, Open Props and Tailwind, 53 MB with their token lists) aren't pinned, for size; I ran them once and every token matched.
To run them with the counts showing:
cargo test -p parsec-html-css -- --nocaptureAll 12 failures are cases where the current draft parses differently from the draft the suite was written for. Each is listed in KNOWN_FAILURES in tests/css_parsing_tests.rs with its reason, and the run fails if any other case fails or a listed one starts to pass.
| Cases | File | Why |
|---|---|---|
9, every input with u+ in it |
component_value_list.json |
The suite expects a <unicode-range-token> wherever u+ could start one. The current draft makes that token only inside a unicode-range descriptor, and everywhere else u+1f is an ident and a number. The same ranges pass in the <urange> suite. |
1, the one ending \u{7f}\u{80}\u{81}
|
component_value_list.json |
The suite has U+0080 and U+0081 as ident code points. Since 2024 they aren't, so they're two delims. |
2, foo:; and foo:;bar:;
|
one_declaration.json |
In the 2021 draft "parse a declaration" took the rest of the input as the value, ; and all. Since nesting it stops at the ;, and what follows is extra input. |
Timed against Lexbor 3.0.1's CSS module, in the same process, and Servo's cssparser 0.38, on ten real stylesheets, 1.87 MB in all: the <style> elements of the five benchmark pages with more than a kilobyte of them, and Bootstrap 5.3.3 (plain and minified), Bulma 1.0.2, Font Awesome 6.6.0 and normalize.css 8.0.1. Benchmarks has the method.
| All ten, MB/s | Parsec | Lexbor | cssparser | Parsec vs Lexbor | Parsec vs cssparser |
|---|---|---|---|---|---|
| Tokenizing | 378 | 217 | 291 | 1.75× | 1.30× |
| Parsing | 148 | 115 | 196 | 1.29× | 0.76× |
Parsec tokenizes faster than both on every sheet, 1.2 to 2.7 times Lexbor's speed. It parses faster than Lexbor on every sheet too, by 1.1 to 1.65 times, though Lexbor's parse also reads selectors and the values of the 105 properties it knows, so the two aren't doing quite the same work. cssparser parses a third faster than Parsec. It builds nothing of its own, so the benchmark gives it the least a caller would build (each prelude and value kept as its tokens), while Parsec keeps every block as a tree with spans and then parses its contents from that. Closing that gap, by parsing a block's contents straight from the tokenizer when you want them at once, is the next thing to try.
crates/parsec-css/fuzz has a cargo-fuzz target, parse, in the nightly fuzz run beside the HTML parser's. It sends any input through the tokenizer and every entry point, parses every block's contents, decodes the bytes, checks every span lies inside the input, and checks that the values serialize to text that parses back to the same values. Locally:
cd crates/parsec-css
cargo +nightly fuzz run parse -- -max_len=4096Lexbor's css module has a CSS Syntax tokenizer and parser, and its README claims full conformance with CSS Syntax. Its tests are its own: 17 files in its own format under test/files/lexbor/css/syntax, not an outside suite, and it publishes no count. It parses stylesheets straight into typed rules for the properties it knows, and keeps no positions on rules or declarations (lexbor#374).
| Lexbor 3.0.1 | Parsec | |
|---|---|---|
| CSS Syntax tokenizer and parser | Yes | Yes, the current draft, nesting included |
| Outside suite run | No | css-parsing-tests, its <urange> cases and css-tokenizer-tests, in cargo test
|
| Positions on rules and declarations | No | Byte spans on everything, lines and columns on request |
| Serialization | Yes, lxb_css_rule_serialize
|
Yes, checked to round-trip on every suite input and by the fuzzer |
| Typed properties | 105 | Not yet (#29) |
var(), media queries, computed values |
No | Not yet (#29, #30) |
- Conformance, for every suite Parsec runs.
- Benchmarks, for the method behind the speed numbers.
- Selectors, for the selector engine, which has its own parser for now.
Parsec is Apache-2.0 and not yet released; these pages describe main. Found something wrong here? Open an issue or ask in Discussions.
Repository · Issues · Discussions · Roadmap · Security policy · Licence