Expand description
Implementation of CSS Syntax Module Level 3 for Rust.
Input
Everything is based on Parser
objects, which borrow a &str
input.
If you have bytes (from a file, the network, or something)
and want to support character encodings other than UTF-8,
see the stylesheet_encoding
function,
which can be used together with rust-encoding or encoding-rs.
Conventions for parsing functions
- Take (at least) a
input: &mut cssparser::Parser
parameter - Return
Result<_, ()>
- When returning
Ok(_)
, the function must have consumed exactly the amount of input that represents the parsed value. - When returning
Err(())
, any amount of input may have been consumed.
As a consequence, when calling another parsing function, either:
- Any
Err(())
return value must be propagated. This happens by definition for tail calls, and can otherwise be done with thetry!
macro. - Or the call must be wrapped in a
Parser::try
call.try
takes a closure that takes aParser
and returns aResult
, calls it once, and returns itself that same result. If the result isErr
, it restores the position inside the input to the one saved before calling the closure.
Examples:
ⓘ
// 'none' | <image>
fn parse_background_image(context: &ParserContext, input: &mut Parser)
-> Result<Option<Image>, ()> {
if input.try(|input| input.expect_ident_matching("none")).is_ok() {
Ok(None)
} else {
Image::parse(context, input).map(Some) // tail call
}
}
ⓘ
// [ <length> | <percentage> ] [ <length> | <percentage> ]?
fn parse_border_spacing(_context: &ParserContext, input: &mut Parser)
-> Result<(LengthOrPercentage, LengthOrPercentage), ()> {
let first = try!(LengthOrPercentage::parse);
let second = input.try(LengthOrPercentage::parse).unwrap_or(first);
(first, second)
}
Modules
Delimiters
constants.Macros
Define a function
$name(&str) -> Option<&'static $ValueType>
Expands to a
match
expression with string patterns,
matching case-insensitively in the ASCII range.Structs
The funamental parsing errors that can be triggered by built-in parsing routines.
A string that is either shared (heap-allocated and reference-counted) or borrowed.
A
fmt::Write
adapter that escapes text for writing as a double-quoted CSS string.
Quotes are not included.Provides an iterator for declaration list parsing.
A set of characters, to be used with the
Parser::parse_until*
methods.Extensible parse errors that can be encountered by client parsing implementations.
A CSS parser that borrows its
&str
input,
yields Token
s,
and keeps track of nested blocks and functions.The owned input for a parser.
A capture of the internal state of a
Parser
(including the position within the input),
obtained from the Parser::position
method.A color with red, green, blue, and alpha components, in a byte each.
Provides an iterator for rule list parsing.
The line and column number for a given position within the input.
A position from the start of the input, counted in UTF-8 bytes.
A category of token. See the
needs_separator_when_before
method.One contiguous range of code points.
Enums
Either an angle or a number.
The return value for
AtRuleParser::parse_prelude
.
Indicates whether the at-rule is expected to have a { /* ... */ }
block
or end with a ;
semicolon.Details about a
BasicParseError
A value.
Either a number or a percentage.
Details of a
ParseError
One of the pieces the CSS input is broken into.
Traits
A trait to provide various parsing of at-rules.
A trait that can be used to hook into how
cssparser
parses color
components, with the intention of implementing more complicated behavior.A trait to provide various parsing of declaration values.
Abstraction for avoiding a dependency from cssparser to an encoding library
A trait to provide various parsing of qualified rules.
Trait for things the can serialize themselves in CSS syntax.
Functions
Return the named color with the given name.
Parse
!important
.Parse the An+B notation, as found in the
:nth-child()
selector.
The input is typically the arguments of a function,
in which case the caller needs to check if the arguments’ parser is exhausted.
Return Ok((A, B))
, or Err(())
for a syntax error.Parse a single declaration, such as an
( /* ... */ )
parenthesis in an @supports
prelude.Parse a single rule, such as for CSSOM’s
CSSStyleSheet.insertRule
.Write a CSS identifier, escaping characters as necessary.
Write a CSS name, like a custom property name.
Write a double-quoted CSS string token, escaping content as necessary.
Determine the character encoding of a CSS stylesheet.
Derive Macros
Input: the arms of a
match
expression.Input: string literals with no separator
Input: parsed as token trees. The first TT is a type. (Can be wrapped in parens.)
following TTs are grouped in pairs, each pair being a key as a string literal
and the corresponding value as a const expression.