swc_ecma_parser/
lib.rs

1//! EcmaScript/TypeScript parser for the rust programming language.
2//!
3//! # Features
4//!
5//! ## Heavily tested
6//!
7//! Passes almost all tests from [tc39/test262][].
8//!
9//! ## Error reporting
10//!
11//! ```sh
12//! error: 'implements', 'interface', 'let', 'package', 'private', 'protected',  'public', 'static', or 'yield' cannot be used as an identifier in strict mode
13//!  --> invalid.js:3:10
14//!   |
15//! 3 | function yield() {
16//!   |          ^^^^^
17//! ```
18//!
19//! ## Error recovery
20//!
21//! The parser can recover from some parsing errors. For example, parser returns
22//! `Ok(Module)` for the code below, while emitting error to handler.
23//!
24//! ```ts
25//! const CONST = 9000 % 2;
26//! const enum D {
27//!     // Comma is required, but parser can recover because of the newline.
28//!     d = 10
29//!     g = CONST
30//! }
31//! ```
32//!
33//! # Example (lexer)
34//!
35//! See `lexer.rs` in examples directory.
36//!
37//! # Example (parser)
38//!
39//! ```
40//! #[macro_use]
41//! extern crate swc_common;
42//! extern crate swc_ecma_parser;
43//! use swc_common::sync::Lrc;
44//! use swc_common::{
45//!     errors::{ColorConfig, Handler},
46//!     FileName, FilePathMapping, SourceMap,
47//! };
48//! use swc_ecma_parser::{lexer::Lexer, Parser, StringInput, Syntax};
49//!
50//! fn main() {
51//!     let cm: Lrc<SourceMap> = Default::default();
52//!     let handler =
53//!         Handler::with_tty_emitter(ColorConfig::Auto, true, false,
54//!         Some(cm.clone()));
55//!
56//!     // Real usage
57//!     // let fm = cm
58//!     //     .load_file(Path::new("test.js"))
59//!     //     .expect("failed to load test.js");
60//!     let fm = cm.new_source_file(
61//!         FileName::Custom("test.js".into()).into(),
62//!         "function foo() {}",
63//!     );
64//!     let lexer = Lexer::new(
65//!         // We want to parse ecmascript
66//!         Syntax::Es(Default::default()),
67//!         // EsVersion defaults to es5
68//!         Default::default(),
69//!         StringInput::from(&*fm),
70//!         None,
71//!     );
72//!
73//!     let mut parser = Parser::new_from(lexer);
74//!
75//!     for e in parser.take_errors() {
76//!         e.into_diagnostic(&handler).emit();
77//!     }
78//!
79//!     let _module = parser
80//!         .parse_module()
81//!         .map_err(|mut e| {
82//!             // Unrecoverable fatal error occurred
83//!             e.into_diagnostic(&handler).emit()
84//!         })
85//!         .expect("failed to parser module");
86//! }
87//! ```
88//!
89//! ## Cargo features
90//!
91//! ### `typescript`
92//!
93//! Enables typescript parser.
94//!
95//! ### `verify`
96//!
97//! Verify more errors, using `swc_ecma_visit`.
98//!
99//! ## Known issues
100//!
101//! ### Null character after `\`
102//!
103//! Because [String] of rust should only contain valid utf-8 characters while
104//! javascript allows non-utf8 characters, the parser stores invalid utf8
105//! characters in escaped form.
106//!
107//! As a result, swc needs a way to distinguish invalid-utf8 code points and
108//! input specified by the user. The parser stores a null character right after
109//! `\\` for non-utf8 code points. Note that other parts of swc is aware of this
110//! fact.
111//!
112//! Note that this can be changed at anytime with a breaking change.
113//!
114//! [tc39/test262]:https://github.com/tc39/test262
115
116#![cfg_attr(docsrs, feature(doc_cfg))]
117#![cfg_attr(test, feature(test))]
118#![deny(clippy::all)]
119#![deny(unused)]
120#![allow(unexpected_cfgs)]
121#![allow(clippy::nonminimal_bool)]
122#![allow(clippy::too_many_arguments)]
123#![allow(clippy::unnecessary_unwrap)]
124#![allow(clippy::vec_box)]
125#![allow(clippy::wrong_self_convention)]
126#![allow(clippy::match_like_matches_macro)]
127
128#[cfg(feature = "unstable")]
129pub mod unstable {
130    //! This module expose tokens related to the `swc_ecma_parser::lexer`.
131    //!
132    //! Unlike the tokens re-exported from `swc_ecma_lexer`, the token kinds
133    //! defined in the `swc_ecma_parser` here are non-strict for higher
134    //! performance.
135    //!
136    //! Although it's marked as unstable, we can ensure that we will not
137    //! introduce too many breaking changes. And we also encourage the
138    //! applications to migrate to the lexer and tokens in terms of
139    //! the performance.
140    //!
141    //! Also see the dicussion https://github.com/swc-project/swc/discussions/10683
142    pub use swc_ecma_lexer::common::lexer::token::TokenFactory;
143
144    pub use crate::lexer::{
145        capturing::Capturing,
146        token::{NextTokenAndSpan, Token, TokenAndSpan, TokenValue},
147    };
148}
149
150pub mod lexer;
151mod parser;
152
153pub use lexer::Lexer;
154pub use swc_common::input::{Input, StringInput};
155use swc_common::{comments::Comments, input::SourceFileInput, SourceFile};
156use swc_ecma_ast::*;
157use swc_ecma_lexer::{common::parser::Parser as ParserTrait, error::Error};
158pub use swc_ecma_lexer::{
159    common::{
160        context::Context,
161        syntax::{EsSyntax, Syntax, TsSyntax},
162    },
163    error, token,
164};
165
166pub use self::parser::*;
167
168#[cfg(test)]
169fn with_test_sess<F, Ret>(src: &str, f: F) -> Result<Ret, ::testing::StdErr>
170where
171    F: FnOnce(&swc_common::errors::Handler, StringInput<'_>) -> Result<Ret, ()>,
172{
173    use swc_common::FileName;
174
175    ::testing::run_test(false, |cm, handler| {
176        let fm = cm.new_source_file(FileName::Real("testing".into()).into(), src.to_string());
177
178        f(handler, (&*fm).into())
179    })
180}
181
182pub fn with_file_parser<T>(
183    fm: &SourceFile,
184    syntax: Syntax,
185    target: EsVersion,
186    comments: Option<&dyn Comments>,
187    recovered_errors: &mut Vec<Error>,
188    op: impl for<'aa> FnOnce(&mut Parser<self::Lexer>) -> PResult<T>,
189) -> PResult<T> {
190    let lexer = self::Lexer::new(syntax, target, SourceFileInput::from(fm), comments);
191    let mut p = Parser::new_from(lexer);
192    let ret = op(&mut p);
193
194    recovered_errors.append(&mut p.take_errors());
195
196    ret
197}
198
199macro_rules! expose {
200    (
201        $name:ident,
202        $T:ty,
203        $($t:tt)*
204    ) => {
205        /// Note: This is recommended way to parse a file.
206        ///
207        /// This is an alias for [Parser], [Lexer] and [SourceFileInput], but
208        /// instantiation of generics occur in `swc_ecma_parser` crate.
209        pub fn $name(
210            fm: &SourceFile,
211            syntax: Syntax,
212            target: EsVersion,
213            comments: Option<&dyn Comments>,
214            recovered_errors: &mut Vec<Error>,
215        ) -> PResult<$T> {
216            with_file_parser(fm, syntax, target, comments, recovered_errors, $($t)*)
217        }
218    };
219}
220
221expose!(parse_file_as_expr, Box<Expr>, |p| {
222    // This allow to parse `import.meta`
223    let ctx = p.ctx();
224    p.set_ctx(ctx.union(Context::CanBeModule));
225    p.parse_expr()
226});
227expose!(parse_file_as_module, Module, |p| { p.parse_module() });
228expose!(parse_file_as_script, Script, |p| { p.parse_script() });
229expose!(parse_file_as_commonjs, Script, |p| { p.parse_commonjs() });
230expose!(parse_file_as_program, Program, |p| { p.parse_program() });
swc_ecma_parser/lib.rs

swc_ecma_parser/
lib.rs
