Crate oxc_css_parser 

oxc-css-parser is a parser that can parse CSS, SCSS, Sass (indented syntax) and Less.

Basic Usage

This crate provides a simple API to get started.

First, create a parser, give it the source code and specify the syntax, then call the parse method:

use oxc_css_parser::{Allocator, Parser, Syntax, ast::Stylesheet};

let allocator = Allocator::default();
let mut parser = Parser::new(&allocator, "a {}", Syntax::Css); // syntax can also be `Scss`, `Sass` or `Less`
let result = parser.parse::<Stylesheet>();
match result {
    Ok(ast) => {
        // parsed successfully
        println!("{:#?}", ast);
    }
    Err(error) => {
        // it failed, error message and position can be accessed via `error`
        println!("{:#?}", error);
    }
}

Advanced Usage

Creating Parser with Builder

If you need to control parser with additional features, you can use ParserBuilder.

For example, to collect comments:

use oxc_css_parser::{Allocator, ParserBuilder, ast::Stylesheet};

let allocator = Allocator::default();
let builder = ParserBuilder::new(&allocator, "/* comment */ a {}").comments();
let mut parser = builder.build();
parser.parse::<Stylesheet>().unwrap();
let comments = parser.comments();

By default, syntax is CSS when using parser builder. You can customize it:

use oxc_css_parser::{Allocator, ParserBuilder, Syntax};

let allocator = Allocator::default();
let builder = ParserBuilder::new(&allocator, "a {}").syntax(Syntax::Scss);

Parser Options

try_parsing_value_in_custom_property

By default, value of custom property whose name starts with -- will be parsed as tokens. If you want to parse it as normal declaration value, you can enable this option. Even though this option is enabled, parser will fallback to parse as tokens if there’re syntax errors.

use oxc_css_parser::{Allocator, ParserBuilder, ParserOptions, ast::*};

let allocator = Allocator::default();
let options = ParserOptions {
    try_parsing_value_in_custom_property: true,
    ..Default::default()
};
let builder = ParserBuilder::new(&allocator, "--foo: calc(var(--bar) + 1px)").options(options);
let mut parser = builder.build();

let declaration = parser.parse::<Declaration>().unwrap();
assert!(matches!(declaration.value[0], ComponentValue::Function(..)));

template_placeholder

By default, a backtick is a syntax error outside Less. Setting this option makes the parser recognize a backtick-delimited token of the shape `<prefix><decimal index>` as an atomic Placeholder node (in value, selector, and statement positions) carrying the parsed index. The token terminates at the closing backtick, so a following identifier re-lexes separately. This is designed for downstream formatters that substitute template interpolations (e.g. CSS-in-JS ${expr}) with such placeholders before parsing. It MUST be used with Syntax::Scss (backtick is Less’s inline-JS delimiter).

use oxc_css_parser::{Allocator, ParserBuilder, ParserOptions, Syntax, TemplatePlaceholder, ast::*};

let allocator = Allocator::default();
let options = ParserOptions {
    template_placeholder: Some(TemplatePlaceholder {
        prefix: "PLACEHOLDER-",
    }),
    ..Default::default()
};
let builder = ParserBuilder::new(&allocator, "a { width: `PLACEHOLDER-0`; }")
    .syntax(Syntax::Scss)
    .options(options);
let mut parser = builder.build();

assert!(parser.parse::<Stylesheet>().is_ok());

Parse Partial Structure

Sometimes you don’t want to parse a full stylesheet. Say you only need to parse a qualified rule or even a single declaration. All you need to do is to update the generics of the parse method.

use oxc_css_parser::{Allocator, Parser, Syntax, ast::QualifiedRule};

let allocator = Allocator::default();
let mut parser = Parser::new(&allocator, "a {}", Syntax::Css);
parser.parse::<QualifiedRule>();

and

use oxc_css_parser::{Allocator, Parser, Syntax, ast::Declaration};

let allocator = Allocator::default();
let mut parser = Parser::new(&allocator, "color: green", Syntax::Css);
parser.parse::<Declaration>();

Not all AST nodes support the usage above; technically, those nodes that implement Parse trait are supported.

Retrieve Recoverable Errors

There may be some recoverable errors which doesn’t affect on producing AST. To retrieve those errors, use recoverable_errors.

use oxc_css_parser::{Allocator, Parser, Syntax, ast::Stylesheet};

let allocator = Allocator::default();
let mut parser = Parser::new(&allocator, "@keyframes kf { invalid {} }", Syntax::Css);
let result = parser.parse::<Stylesheet>();
assert!(result.is_ok());
println!("{:?}", parser.recoverable_errors());

Serialization

Produced AST can be serialized by Serde, but this feature is disabled by default. You need to enable feature serialize manually:

oxc-css-parser = { version = "*", features = ["serialize"] }

Then you can pass AST to Serde.

Note that oxc-css-parser only supports serialization. Deserialization isn’t supported.

Re-exports

pub use pos::Span;

Modules

ast

All kinds of AST nodes are here.

error

Error management.

pos

token

All supported tokens, and with comments.

Structs

Allocator

A bump-allocated memory arena.

Parser

Create a parser with some source code, then parse it.

ParserBuilder

Parser builder is for building a parser while allowing us to control advanced behaviors.

ParserOptions

Parser options for customizing parser behaviors.

TemplatePlaceholder

Configuration for a backtick-delimited template placeholder.

Enums

Syntax

Supported syntax.

Traits

Parse