oxc_css_parser/
lib.rs

1//! oxc-css-parser is a parser that can parse CSS, SCSS, Sass (indented syntax) and Less.
2//!
3//! ## Basic Usage
4//!
5//! This crate provides a simple API to get started.
6//!
7//! First, create a parser, give it the source code and specify the syntax,
8//! then call the [`parse`](Parser::parse) method:
9//!
10//! ```rust
11//! use oxc_css_parser::{Allocator, Parser, Syntax, ast::Stylesheet};
12//!
13//! let allocator = Allocator::default();
14//! let mut parser = Parser::new(&allocator, "a {}", Syntax::Css); // syntax can also be `Scss`, `Sass` or `Less`
15//! let result = parser.parse::<Stylesheet>();
16//! match result {
17//!     Ok(ast) => {
18//!         // parsed successfully
19//!         println!("{:#?}", ast);
20//!     }
21//!     Err(error) => {
22//!         // it failed, error message and position can be accessed via `error`
23//!         println!("{:#?}", error);
24//!     }
25//! }
26//! ```
27//!
28//! ## Advanced Usage
29//!
30//! ### Creating Parser with Builder
31//!
32//! If you need to control parser with additional features, you can use [`ParserBuilder`].
33//!
34//! For example, to collect comments:
35//!
36//! ```rust
37//! use oxc_css_parser::{Allocator, ParserBuilder, ast::Stylesheet};
38//!
39//! let allocator = Allocator::default();
40//! let builder = ParserBuilder::new(&allocator, "/* comment */ a {}").comments();
41//! let mut parser = builder.build();
42//! parser.parse::<Stylesheet>().unwrap();
43//! let comments = parser.comments();
44//! ```
45//!
46//! By default, syntax is CSS when using parser builder. You can customize it:
47//!
48//! ```rust
49//! use oxc_css_parser::{Allocator, ParserBuilder, Syntax};
50//!
51//! let allocator = Allocator::default();
52//! let builder = ParserBuilder::new(&allocator, "a {}").syntax(Syntax::Scss);
53//! ```
54//!
55//! ### Parser option: `template_placeholder`
56//!
57//! By default, a backtick is a syntax error outside Less. Setting this option
58//! makes the parser recognize a backtick-delimited token of the shape
59//! `` `<prefix><decimal index>` `` as an atomic
60//! [`Placeholder`](crate::ast::Placeholder) node (in value, selector, and
61//! statement positions) carrying the parsed index. The token terminates at the
62//! closing backtick, so a following identifier re-lexes separately. This is
63//! designed for downstream formatters that substitute template interpolations
64//! (e.g. CSS-in-JS `${expr}`) with such placeholders before parsing. It MUST be
65//! used with [`Syntax::Scss`] (backtick is Less's inline-JS delimiter).
66//!
67//! ```rust
68//! use oxc_css_parser::{Allocator, ParserBuilder, ParserOptions, Syntax, TemplatePlaceholder, ast::*};
69//!
70//! let allocator = Allocator::default();
71//! let options = ParserOptions {
72//!     template_placeholder: Some(TemplatePlaceholder {
73//!         prefix: "PLACEHOLDER-",
74//!     }),
75//!     ..Default::default()
76//! };
77//! let builder = ParserBuilder::new(&allocator, "a { width: `PLACEHOLDER-0`; }")
78//!     .syntax(Syntax::Scss)
79//!     .options(options);
80//! let mut parser = builder.build();
81//!
82//! assert!(parser.parse::<Stylesheet>().is_ok());
83//! ```
84//!
85//! ### Parse Partial Structure
86//!
87//! Sometimes you don't want to parse a full stylesheet.
88//! Say you only need to parse a qualified rule or even a single declaration.
89//! All you need to do is to update the generics of the [`parse`](Parser::parse) method.
90//!
91//! ```rust
92//! use oxc_css_parser::{Allocator, Parser, Syntax, ast::QualifiedRule};
93//!
94//! let allocator = Allocator::default();
95//! let mut parser = Parser::new(&allocator, "a {}", Syntax::Css);
96//! parser.parse::<QualifiedRule>();
97//! ```
98//!
99//! and
100//!
101//! ```rust
102//! use oxc_css_parser::{Allocator, Parser, Syntax, ast::Declaration};
103//!
104//! let allocator = Allocator::default();
105//! let mut parser = Parser::new(&allocator, "color: green", Syntax::Css);
106//! parser.parse::<Declaration>();
107//! ```
108//!
109//! Not all AST nodes support the usage above;
110//! technically, those nodes that implement [`Parse`] trait are supported.
111//!
112//! ### Retrieve Recoverable Errors
113//!
114//! There may be some recoverable errors which doesn't affect on producing AST.
115//! To retrieve those errors, use [`recoverable_errors`](Parser::recoverable_errors).
116//!
117//! ```rust
118//! use oxc_css_parser::{Allocator, Parser, Syntax, ast::Stylesheet};
119//!
120//! let allocator = Allocator::default();
121//! let mut parser = Parser::new(&allocator, "@keyframes kf { invalid {} }", Syntax::Css);
122//! let result = parser.parse::<Stylesheet>();
123//! assert!(result.is_ok());
124//! println!("{:?}", parser.recoverable_errors());
125//! ```
126//!
127//! ## Serialization
128//!
129//! Produced AST can be serialized by Serde, but this feature is disabled by default.
130//! You need to enable feature `serialize` manually:
131//!
132//! ```toml
133//! oxc-css-parser = { version = "*", features = ["serialize"] }
134//! ```
135//!
136//! Then you can pass AST to Serde.
137//!
138//! Note that oxc-css-parser only supports serialization. Deserialization isn't supported.
139
140pub use config::{ParserOptions, Syntax, TemplatePlaceholder};
141pub use oxc_allocator::Allocator;
142pub use parser::{Parse, Parser, ParserBuilder};
143pub use pos::Span;
144pub use tokenizer::token;
145
146pub mod ast;
147mod ast_generated;
148mod config;
149pub mod error;
150mod parser;
151pub mod pos;
152mod tokenizer;
153mod util;
oxc_css_parser/lib.rs

oxc_css_parser/
lib.rs
