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() {}".into(),
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
128pub use swc_common::input::{Input, StringInput};
129use swc_common::{comments::Comments, input::SourceFileInput, SourceFile};
130use swc_ecma_ast::*;
131use swc_ecma_lexer::error::Error;
132
133pub use self::parser::*;
134
135#[macro_use]
136mod macros;
137use swc_ecma_lexer::Lexer;
138pub use swc_ecma_lexer::{error, lexer, token, Context, EsSyntax, Syntax, TsSyntax};
139
140mod parser;
141
142#[cfg(test)]
143fn with_test_sess<F, Ret>(src: &str, f: F) -> Result<Ret, ::testing::StdErr>
144where
145    F: FnOnce(&swc_common::errors::Handler, StringInput<'_>) -> Result<Ret, ()>,
146{
147    use swc_common::FileName;
148
149    ::testing::run_test(false, |cm, handler| {
150        let fm = cm.new_source_file(FileName::Real("testing".into()).into(), src.into());
151
152        f(handler, (&*fm).into())
153    })
154}
155
156pub fn with_file_parser<T>(
157    fm: &SourceFile,
158    syntax: Syntax,
159    target: EsVersion,
160    comments: Option<&dyn Comments>,
161    recovered_errors: &mut Vec<Error>,
162    op: impl for<'aa> FnOnce(&mut Parser<Lexer>) -> PResult<T>,
163) -> PResult<T> {
164    let lexer = Lexer::new(syntax, target, SourceFileInput::from(fm), comments);
165    let mut p = Parser::new_from(lexer);
166    let ret = op(&mut p);
167
168    recovered_errors.append(&mut p.take_errors());
169
170    ret
171}
172
173macro_rules! expose {
174    (
175        $name:ident,
176        $T:ty,
177        $($t:tt)*
178    ) => {
179        /// Note: This is recommended way to parse a file.
180        ///
181        /// This is an alias for [Parser], [Lexer] and [SourceFileInput], but
182        /// instantiation of generics occur in `swc_ecma_parser` crate.
183        pub fn $name(
184            fm: &SourceFile,
185            syntax: Syntax,
186            target: EsVersion,
187            comments: Option<&dyn Comments>,
188            recovered_errors: &mut Vec<Error>,
189        ) -> PResult<$T> {
190            with_file_parser(fm, syntax, target, comments, recovered_errors, $($t)*)
191        }
192    };
193}
194
195expose!(parse_file_as_expr, Box<Expr>, |p| {
196    // This allow to parse `import.meta`
197    p.input().ctx.insert(Context::CanBeModule);
198    p.parse_expr()
199});
200expose!(parse_file_as_module, Module, |p| { p.parse_module() });
201expose!(parse_file_as_script, Script, |p| { p.parse_script() });
202expose!(parse_file_as_program, Program, |p| { p.parse_program() });
203
204#[inline(always)]
205#[cfg(any(
206    target_arch = "wasm32",
207    target_arch = "arm",
208    not(feature = "stacker"),
209    // miri does not work with stacker
210    miri
211))]
212fn maybe_grow<R, F: FnOnce() -> R>(_red_zone: usize, _stack_size: usize, callback: F) -> R {
213    callback()
214}
215
216#[inline(always)]
217#[cfg(all(
218    not(any(target_arch = "wasm32", target_arch = "arm", miri)),
219    feature = "stacker"
220))]
221fn maybe_grow<R, F: FnOnce() -> R>(red_zone: usize, stack_size: usize, callback: F) -> R {
222    stacker::maybe_grow(red_zone, stack_size, callback)
223}
swc_ecma_parser/lib.rs

swc_ecma_parser/
lib.rs
