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
21Heavily based on [acorn](https://github.com/marijnh/acorn) and [acorn-jsx](https://github.com/RReverser/acorn-jsx),
22thanks to the awesome work of [@RReverser](https://github.com/RReverser) and [@marijnh](https://github.com/marijnh).
23
24Significant 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
34mind. 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
61Babylon generates AST according to [Babel AST format][].
62It 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
72AST 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
101Babylon follows semver in most situations. The only thing to note is that some spec-compliancy bug fixes may be released under patch versions.
102
103For 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
108require("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`
135