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}