Skip to content

Latest commit

 

History

History
168 lines (121 loc) · 8.31 KB

README.md

File metadata and controls

168 lines (121 loc) · 8.31 KB
Raw

babylon

Babylon is a JavaScript parser used in Babel.

NPM Version Travis Status Codecov Status

  • The latest ECMAScript version enabled by default (ES2017).
  • Comment attachment.
  • Support for JSX, Flow, Typescript.
  • Support for experimental language proposals (accepting PRs for anything at least stage-0).

Contributing

Check out contributing.md

Credits

Heavily based on acorn and acorn-jsx, thanks to the awesome work of @RReverser and @marijnh.

API

babylon.parse(code, [options])

babylon.parseExpression(code, [options])

parse() parses the provided code as an entire ECMAScript program, while parseExpression() tries to parse a single Expression with performance in mind. When in doubt, use .parse().

Options

  • allowImportExportEverywhere: By default, import and export declarations can only appear at a program's top level. Setting this option to true allows them anywhere where a statement is allowed.

  • allowReturnOutsideFunction: By default, a return statement at the top level raises an error. Set this to true to accept such code.

  • allowSuperOutsideMethod: TODO

  • sourceType: Indicate the mode the code should be parsed in. Can be either "script" or "module".

  • sourceFilename: Correlate output AST nodes with their source filename. Useful when generating code and source maps from the ASTs of multiple input files.

  • 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.

  • plugins: Array containing the plugins that you want to enable.

  • strictMode: TODO

  • ranges: Adds a ranges property to each node: [node.start, node.end]

  • tokens: Adds all parsed tokens to a tokens property on the File node

Output

Babylon generates AST according to Babel AST format. It is based on ESTree spec with the following deviations:

There is now an estree plugin which reverts these deviations

AST for JSX code is based on Facebook JSX AST with the addition of one node type:

  • JSXText

Semver

Babylon follows semver in most situations. The only thing to note is that some spec-compliancy bug fixes may be released under patch versions.

For example: We push a fix to early error on something like #107 - multiple default exports per file. That would be considered a bug fix even though it would cause a build to fail.

Example

require("babylon").parse("code", {
  // parse in strict mode and allow module declarations
  sourceType: "module",

  plugins: [
    // enable jsx and flow syntax
    "jsx",
    "flow"
  ]
});

Plugins

Name Code Example
estree (repo) n/a
jsx (repo) <a attr="b">{s}</a>
flow (repo) var a: string = "";
typescript (repo) var a: string = "";
doExpressions var a = do { if (true) { 'hi'; } };
objectRestSpread (proposal) var a = { b, ...c };
decorators (Stage 1) and decorators2 (Stage 2 proposal) @a class A {}
classProperties (proposal) class A { b = 1; }
classPrivateProperties (proposal) class A { #b = 1; }
exportExtensions (proposal 1), (proposal 2) Proposal 1: export v from "mod" Proposal 2: export * as ns from "mod"
asyncGenerators (proposal) async function*() {}, for await (let a of b) {}
functionBind (proposal) a::b, ::console.log
functionSent function.sent
dynamicImport (proposal) import('./guy').then(a)
numericSeparator (proposal) 1_000_000
optionalChaining (proposal) a?.b
importMeta (proposal) import.meta.url
bigInt (proposal) 100n

FAQ

Will Babylon support a plugin system?

Previous issues: babel/babel#1351, #500.

We currently aren't willing to commit to supporting the API for plugins or the resulting ecosystem (there is already enough work maintaining Babel's own plugin system). It's not clear how to make that API effective, and it would limit out ability to refactor and optimize the codebase.

Our current recommendation for those that want to create their own custom syntax is for users to fork Babylon.

To consume your custom parser, you can add to your .babelrc via its npm package name or require it if using JavaScript,

{
  "parserOpts": {
    "parser": "custom-fork-of-babylon-on-npm-here"
  }
}