cssparser

Each .json file in the test suite corresponds to a specific CSS parsing function. The files are UTF-8 encoded and follow a specific structure:

• The file contains a single JSON array.
• The array contains an even number of items.
• Items are organized in pairs: [input, expected_result].

Common Test Files

Special Input Formats

For stylesheet_bytes.json, the input is a JSON object containing:

• css_bytes: The input byte string (U+0000 to U+00FF represent raw bytes).
• protocol_encoding (optional): A string label or null.
• environment_encoding (optional): A string label or null.
• comment (optional): Ignored.

The rust-cssparser library implements the CSS Syntax Module Level 3 through a multi-step process, though it combines some steps for efficiency:

1. Encoding/Decoding: The library currently assumes UTF-8 input. It does not handle character encoding detection (e.g., via @charset or Content-Type headers) automatically.
2. Tokenization & Component Value Construction: Instead of producing a flat stream of raw tokens, the library performs tokenization and the construction of a tree of component values simultaneously. This means raw tokens are not materialized; you interact directly with component values which can be:
   • Preserved tokens
   • Blocks/Functions (e.g., { ... }, [ ... ], ( ... ), or foo( ... )) containing nested component values.
3. Rule/Declaration Parsing: Component values can be organized into generic rules or declarations. At this stage, the header, body, and declaration values are still represented as lists of component values (see the Token enum in src/tokenizer.rs).

Note on Selectors and Properties: rust-cssparser does not perform the final step of parsing component values into specific CSS Selectors or specific CSS properties. This is by design to allow consumers to define their own logic for property and selector support. However, it provides helpers for specific types like CSS colors and An+B (used in :nth-child() selectors).

When implementing custom parsing functions for use with cssparser, follow these rules:

1. Signature: Functions should take at least a &mut cssparser::Parser parameter and return Result<_, ()>.
2. Success (Ok): On success, the function must have consumed exactly the amount of input representing the parsed value.
3. Failure (Err): On failure, any amount of input may have been consumed.

Error Handling and Parser::try

Because an error might leave the Parser in an indeterminate position, you have two choices when calling a parsing function:

• Propagate Errors: Use the ? operator to propagate Err(()) immediately. This is standard for tail calls or when the error is fatal to the current context.
• Use Parser::try: If you want to attempt a parse without permanently advancing the parser position on failure, wrap the call in input.try_parse(|input| { ... }). The try method saves the current position and restores it if the provided closure returns Err.

// Example: Using try_parse to attempt an optional parse without advancing on error
fn parse_border_spacing(_context: &ParserContext, input: &mut Parser) 
    -> Result<(LengthOrPercentage, LengthOrPercentage), ()> 
{
    let first = LengthOrPercentage::parse?; 
    // If LengthOrPercentage::parse fails inside try_parse, 'input' position is restored
    let second = input.try_parse(LengthOrPercentage::parse).unwrap_or(first);
    (first, second)
}

The test suite represents parsed AST nodes using compact JSON arrays. Use these schemas to validate your parser's output against the expected results.

Rules and Declarations

Component Values

To parse CSS declarations (e.g., color: red;), implement the DeclarationParser trait. This trait allows you to define how specific property names are handled and how their values are parsed.

When implementing parse_value, the input is a delimited parser that ends at the next semicolon or the end of the current block. If the property supports !important, you should call input.try_parse(parse_important).is_ok() at the end of your implementation.

Note: Declaration name matching should be case-insensitive in the ASCII range.

impl<'i> DeclarationParser<'i> for MyParser {
    type Declaration = MyValue;
    type Error = MyError;

    fn parse_value<'t>(
        &mut self,
        name: CowRcStr<'i>,
        input: &mut Parser<'i, 't>,
        _declaration_start: &ParserState,
    ) -> Result<Self::Declaration, ParseError<'i, Self::Error>> {
        // Implementation logic here
        // Example: check for !important
        // input.try_parse(parse_important).is_ok();
        todo!()
    }
}