1 | <p align="center">
|
2 | <img alt="babylon" src="https://raw.githubusercontent.com/babel/logo/master/babylon.png" width="700">
|
3 | </p>
|
4 |
|
5 | <p align="center">
|
6 | Babylon is a JavaScript parser used in <a href="https://github.com/babel/babel">Babel</a>.
|
7 | </p>
|
8 |
|
9 | <p align="center">
|
10 | <a href="https://travis-ci.org/babel/babylon"><img alt="Travis Status" src="https://img.shields.io/travis/babel/babylon/master.svg?style=flat&label=travis"></a>
|
11 | <a href="https://codecov.io/gh/babel/babylon"><img alt="Codecov Status" src="https://img.shields.io/codecov/c/github/babel/babylon/master.svg?style=flat"></a>
|
12 | </p>
|
13 |
|
14 | - The latest ECMAScript version enabled by default (ES2017).
|
15 | - Comment attachment.
|
16 | - Support for JSX and Flow.
|
17 | - Support for experimental language proposals (accepting PRs for anything at least [stage-0](https://github.com/tc39/proposals/blob/master/stage-0-proposals.md)).
|
18 |
|
19 | ## Credits
|
20 |
|
21 | Heavily based on [acorn](https://github.com/marijnh/acorn) and [acorn-jsx](https://github.com/RReverser/acorn-jsx),
|
22 | thanks to the awesome work of [@RReverser](https://github.com/RReverser) and [@marijnh](https://github.com/marijnh).
|
23 |
|
24 | Significant diversions are expected to occur in the future such as streaming, EBNF definitions, sweet.js integration, interspatial parsing and more.
|
25 |
|
26 | ## API
|
27 |
|
28 | ### `babylon.parse(code, [options])`
|
29 |
|
30 | ### `babylon.parseExpression(code, [options])`
|
31 |
|
32 | `parse()` parses the provided `code` as an entire ECMAScript program, while
|
33 | `parseExpression()` tries to parse a single Expression with performance in
|
34 | mind. When in doubt, use `.parse()`.
|
35 |
|
36 | ### Options
|
37 |
|
38 | - **allowImportExportEverywhere**: By default, `import` and `export`
|
39 | declarations can only appear at a program's top level. Setting this
|
40 | option to `true` allows them anywhere where a statement is allowed.
|
41 |
|
42 | - **allowReturnOutsideFunction**: By default, a return statement at
|
43 | the top level raises an error. Set this to `true` to accept such
|
44 | code.
|
45 |
|
46 | - **allowSuperOutsideMethod**: TODO
|
47 |
|
48 | - **sourceType**: Indicate the mode the code should be parsed in. Can be
|
49 | either `"script"` or `"module"`.
|
50 |
|
51 | - **sourceFilename**: Correlate output AST nodes with their source filename. Useful when generating code and source maps from the ASTs of multiple input files.
|
52 |
|
53 | - **startLine**: By default, the first line of code parsed is treated as line 1. You can provide a line number to alternatively start with. Useful for integration with other source tools.
|
54 |
|
55 | - **plugins**: Array containing the plugins that you want to enable.
|
56 |
|
57 | - **strictMode**: TODO
|
58 |
|
59 | ### Output
|
60 |
|
61 | Babylon generates AST according to [Babel AST format][].
|
62 | It is based on [ESTree spec][] with the following deviations:
|
63 |
|
64 | > There is now an `estree` plugin which reverts these deviations
|
65 |
|
66 | - [Literal][] token is replaced with [StringLiteral][], [NumericLiteral][], [BooleanLiteral][], [NullLiteral][], [RegExpLiteral][]
|
67 | - [Property][] token is replaced with [ObjectProperty][] and [ObjectMethod][]
|
68 | - [MethodDefinition][] is replaced with [ClassMethod][]
|
69 | - [Program][] and [BlockStatement][] contain additional `directives` field with [Directive][] and [DirectiveLiteral][]
|
70 | - [ClassMethod][], [ObjectProperty][], and [ObjectMethod][] value property's properties in [FunctionExpression][] is coerced/brought into the main method node.
|
71 |
|
72 | AST for JSX code is based on [Facebook JSX AST][] with the addition of one node type:
|
73 |
|
74 | - `JSXText`
|
75 |
|
76 | [Babel AST format]: https://github.com/babel/babylon/blob/master/ast/spec.md
|
77 | [ESTree spec]: https://github.com/estree/estree
|
78 |
|
79 | [Literal]: https://github.com/estree/estree/blob/master/es5.md#literal
|
80 | [Property]: https://github.com/estree/estree/blob/master/es5.md#property
|
81 | [MethodDefinition]: https://github.com/estree/estree/blob/master/es2015.md#methoddefinition
|
82 |
|
83 | [StringLiteral]: https://github.com/babel/babylon/blob/master/ast/spec.md#stringliteral
|
84 | [NumericLiteral]: https://github.com/babel/babylon/blob/master/ast/spec.md#numericliteral
|
85 | [BooleanLiteral]: https://github.com/babel/babylon/blob/master/ast/spec.md#booleanliteral
|
86 | [NullLiteral]: https://github.com/babel/babylon/blob/master/ast/spec.md#nullliteral
|
87 | [RegExpLiteral]: https://github.com/babel/babylon/blob/master/ast/spec.md#regexpliteral
|
88 | [ObjectProperty]: https://github.com/babel/babylon/blob/master/ast/spec.md#objectproperty
|
89 | [ObjectMethod]: https://github.com/babel/babylon/blob/master/ast/spec.md#objectmethod
|
90 | [ClassMethod]: https://github.com/babel/babylon/blob/master/ast/spec.md#classmethod
|
91 | [Program]: https://github.com/babel/babylon/blob/master/ast/spec.md#programs
|
92 | [BlockStatement]: https://github.com/babel/babylon/blob/master/ast/spec.md#blockstatement
|
93 | [Directive]: https://github.com/babel/babylon/blob/master/ast/spec.md#directive
|
94 | [DirectiveLiteral]: https://github.com/babel/babylon/blob/master/ast/spec.md#directiveliteral
|
95 | [FunctionExpression]: https://github.com/babel/babylon/blob/master/ast/spec.md#functionexpression
|
96 |
|
97 | [Facebook JSX AST]: https://github.com/facebook/jsx/blob/master/AST.md
|
98 |
|
99 | ### Semver
|
100 |
|
101 | Babylon follows semver in most situations. The only thing to note is that some spec-compliancy bug fixes may be released under patch versions.
|
102 |
|
103 | For example: We push a fix to early error on something like [#107](https://github.com/babel/babylon/pull/107) - multiple default exports per file. That would be considered a bug fix even though it would cause a build to fail.
|
104 |
|
105 | ### Example
|
106 |
|
107 | ```javascript
|
108 | require("babylon").parse("code", {
|
109 | // parse in strict mode and allow module declarations
|
110 | sourceType: "module",
|
111 |
|
112 | plugins: [
|
113 | // enable jsx and flow syntax
|
114 | "jsx",
|
115 | "flow"
|
116 | ]
|
117 | });
|
118 | ```
|
119 |
|
120 | ### Plugins
|
121 |
|
122 | - `estree`
|
123 | - `jsx`
|
124 | - `flow`
|
125 | - `doExpressions`
|
126 | - `objectRestSpread`
|
127 | - `decorators` (Based on an outdated version of the Decorators proposal. Will be removed in a future version of `Babylon`)
|
128 | - `classProperties`
|
129 | - `exportExtensions`
|
130 | - `asyncGenerators`
|
131 | - `functionBind`
|
132 | - `functionSent`
|
133 | - `dynamicImport`
|
134 | - `templateInvalidEscapes`
|