## 1. Project Overview & Quickstart (benjamn/recast) # recast, _v_. [](https://gitter.im/benjamn/recast?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) 1. to give (a metal object) a different form by melting it down and reshaping it. 1. to form, fashion, or arrange again. 1. to remodel or reconstruct (a literary work, document, sentence, etc.). 1. to supply (a theater or opera work) with a new cast. ## Installation From npm: npm install recast From GitHub: cd path/to/node_modules git clone git://github.com/benjamn/recast.git cd recast npm install . ## Import style Recast is designed to be imported using **named** imports: ```js import { parse, print } from "recast"; console.log(print(parse(source)).code); import * as recast from "recast"; console.log(recast.print(recast.parse(source)).code); ``` If you're using CommonJS: ```js const { parse, print } = require("recast"); console.log(print(parse(source)).code); const recast = require("recast"); console.log(recast.print(recast.parse(source)).code); ``` ## Usage Recast exposes two essential interfaces, one for parsing JavaScript code (`require("recast").parse`) and the other for reprinting modified syntax trees (`require("recast").print`). Here's a simple but non-trivial example of how you might use `.parse` and `.print`: ```js import * as recast from "recast"; // Let's turn this function declaration into a variable declaration. const code = [ "function add(a, b) {", " return a +", " // Weird formatting, huh?", " b;", "}" ].join("\n"); // Parse the code using an interface similar to require("esprima").parse. const ast = recast.parse(code); ``` Now do _whatever_ you want to `ast`. Really, anything at all! See [ast-types](https://github.com/benjamn/ast-types) (especially the [def/core.ts](https://github.com/benjamn/ast-types/blob/master/src/def/core.ts)) module for a thorough overview of the `ast` API. ```js // Grab a reference to the function declaration we just parsed. const add = ast.program.body[0]; // Make sure it's a FunctionDeclaration (optional). const n = recast.types.namedTypes; n.FunctionDeclaration.assert(add); // If you choose to use recast.builders to construct new AST nodes, all builder // arguments will be dynamically type-checked against the Mozilla Parser API. const b = recast.types.builders; // This kind of manipulation should seem familiar if you've used Esprima or the // Mozilla Parser API before. ast.program.body[0] = b.variableDeclaration("var", [ b.variableDeclarator(add.id, b.functionExpression( null, // Anonymize the function expression. add.params, add.body )) ]); // Just for fun, because addition is commutative: add.params.push(add.params.shift()); ``` When you finish manipulating the AST, let `recast.print` work its magic: ```js const output = recast.print(ast).code; ``` The `output` string now looks exactly like this, weird formatting and all: ```js var add = function(b, a) { return a + // Weird formatting, huh? b; } ``` The magic of Recast is that it reprints only those parts of the syntax tree that you modify. In other words, the following identity is guaranteed: ```js recast.print(recast.parse(source)).code === source ``` Whenever Recast cannot reprint a modified node using the original source code, it falls back to using a generic pretty printer. So the worst that can happen is that your changes trigger some harmless reformatting of your code. If you really don't care about preserving the original formatting, you can access the pretty printer directly: ```js var output = recast.prettyPrint(ast, { tabWidth: 2 }).code; ``` And here's the exact `output`: ```js var add = function(b, a) { return a + b; } ``` Note that the weird formatting was discarded, yet the behavior and abstract structure of the code remain the same. ## Using a different parser By default, Recast uses the [Esprima JavaScript parser](https://www.npmjs.com/package/esprima) when you call `recast.parse(code)`. While Esprima supports almost all modern ECMAScript syntax, you may want to use a different parser to enable TypeScript or Flow syntax, or just because you want to match other compilation tools you might be using. In order to get any benefits from Recast's conservative pretty-printing, **it is very important that you continue to call `recast.parse`** (rather than parsing the AST yourself using a different parser), and simply instruct `recast.parse` to use a different parser: ```js const acornAst = recast.parse(source, { parser: require("acorn") }); ``` Why is this so important? When you call `recast.parse`, it makes a shadow copy of the AST before returning it to you, giving every copied AST node a reference back to the original through a special `.original` property. This information is what enables `recast.print` to detect where the AST has been modified, so that it can preserve formatting for parts of the AST that were not modified. Any `parser` object that supports a `parser.parse(source)` method will work here; however, if your parser requires additional options, you can always implement your own `parse` method that invokes your parser with custom options: ```js const acornAst = recast.parse(source, { parser: { parse(source) { return require("acorn").parse(source, { // additional options }); } } }); ``` To take some of the guesswork out of configuring common parsers, Recast provides [several preconfigured parsers](https://github.com/benjamn/recast/tree/master/parsers), so you can parse TypeScript (for example) without worrying about the configuration details: ```js const tsAst = recast.parse(source, { parser: require("recast/parsers/typescript") }); ``` **Note:** Some of these parsers import npm packages that Recast does not directly depend upon, so please be aware you may have to run `npm install @babel/parser` to use the `typescript`, `flow`, or `babel` parsers, or `npm install acorn` to use the `acorn` parser. Only Esprima is installed by default when Recast is installed. After calling `recast.parse`, if you're going to transform the AST, make sure that the `.original` property is preserved. With Babel, for instance, if you call `transformFromAST`, you must pass `cloneInputAst: false` in its options. ([More detail](https://github.com/babel/babel/issues/12882)). ## Source maps One of the coolest consequences of tracking and reusing original source code during reprinting is that it's pretty easy to generate a high-resolution mapping between the original code and the generated code—completely automatically! With every `slice`, `join`, and re-`indent`-ation, the reprinting process maintains exact knowledge of which character sequences are original, and where in the original source they came from. All you have to think about is how to manipulate the syntax tree, and Recast will give you a [source map](https://github.com/mozilla/source-map) in exchange for specifying the names of your source file(s) and the desired name of the map: ```js var result = recast.print(transform(recast.parse(source, { sourceFileName: "source.js" })), { sourceMapName: "source.min.js" }); console.log(result.code); // Resulting string of code. console.log(result.map); // JSON source map. var SourceMapConsumer = require("source-map").SourceMapConsumer; var smc = new SourceMapConsumer(result.map); console.log(smc.originalPositionFor({ line: 3, column: 15 })); // { source: 'source.js', // line: 2, // column: 10, // name: null } ``` Note that you are free to mix and match syntax trees parsed from different source files, and the resulting source map will automatically keep track of the separate file origins for you. Note also that the source maps generated by Recast are character-by-character maps, so meaningful identifier names are not recorded at this time. This approach leads to higher-resolution debugging in modern browsers, at the expense of somewhat larger map sizes. Striking the perfect balance here is an area for future exploration, but such improvements will not require any breaking changes to the interface demonstrated above. ## Options All Recast API functions take second parameter with configuration options, documented in [options.ts](https://github.com/benjamn/recast/blob/master/lib/options.ts) ## Motivation The more code you have, the harder it becomes to make big, sweeping changes quickly and confidently. Even if you trust yourself not to make too many mistakes, and no matter how proficient you are with your text editor, changing tens of thousands of lines of code takes precious, non-refundable time. Is there a better way? Not always! When a task requires you to alter the semantics of many different pieces of code in subtly different ways, your brain inevitably becomes the bottleneck, and there is little hope of completely automating the process. Your best bet is to plan carefully, buckle down, and get it right the first time. Love it or loathe it, that's the way programming goes sometimes. What I hope to eliminate are the brain-wasting tasks, the tasks that are bottlenecked by keystrokes, the tasks that can be expressed as operations on the _syntactic structure_ of your code. Specifically, my goal is to make it possible for you to run your code through a parser, manipulate the abstract syntax tree directly, subject only to the constraints of your imagination, and then automatically translate those modifications back into source code, without upsetting the formatting of unmodified code. And here's the best part: when you're done running a Recast script, if you're not completely satisfied with the results, blow them away with `git reset --hard`, tweak the script, and just run it again. Change your mind as many times as you like. Instead of typing yourself into a nasty case of [RSI](http://en.wikipedia.org/wiki/Repetitive_strain_injury), gaze upon your new wells of free time and ask yourself: what next? ## 2. Official Technical Reference & Guides (benjamn/website) ## File: README.md # [babel/website](https://babeljs.io) This is the source for the [babeljs.io](https://babeljs.io) website; feel free to suggest changes to our docs! - Current: `master` branch is deployed to https://babeljs.io - Old: `old-site` branch is deployed to https://old.babeljs.io ### Setup ```bash $ git clone git@github.com:babel/website.git $ cd website $ yarn && yarn bootstrap ``` - Just run `yarn start` next time (check the package.json for scripts). ### Contributing to the website To keep documentation in sync across all of Babel's packages, the docs are now directly located in this repository. The READMEs in [`babel/babel`](https://github.com/babel/babel) are [auto generated](https://github.com/babel/babel/blob/master/scripts/generators/readmes.js) and point to this documentation. You might want to make yourself familiar with [docusaurus](https://docusaurus.io/docs/en/installation) to make significant changes to the website. If you only want to make content changes you just need to know about versioned docs. #### Versioned docs - `/docs` - the files in here are responsible for the "next" version at https://babeljs.io/docs/en/next. - `/website/versioned_docs/version-*` - these are the docs for the past versions, the latest one being the currently published version at https://babeljs.io/docs/en After making your changes to the markdown files in the `/docs` folder, a git hook script will suggest files from the past versions folders that you might also need to apply your changes to. #### Looking for support? For questions and support on contributing please join our [Slack community](https://slack.babeljs.io/), channel `#website` or directly [here](https://babeljs.slack.com/messages/website). --- ## File: docs/index.md --- id: index title: What is Babel? --- ## Babel is a JavaScript compiler Babel is a toolchain that is mainly used to convert ECMAScript 2015+ code into a backwards compatible version of JavaScript in current and older browsers or environments. Here are the main things Babel can do for you: - Transform syntax - Polyfill features that are missing in your target environment (through [@babel/polyfill](polyfill.md)) - Source code transformations (codemods) - And more! (check out these [videos](/videos.html) for inspiration) ```js // Babel Input: ES2015 arrow function [1, 2, 3].map((n) => n + 1); // Babel Output: ES5 equivalent [1, 2, 3].map(function(n) { return n + 1; }); ``` > For an awesome tutorial on compilers, check out [the-super-tiny-compiler](https://github.com/thejameskyle/the-super-tiny-compiler), which also explains how Babel itself works on a high level. ## ES2015 and beyond Babel has support for the latest version of JavaScript through syntax transformers. These [plugins](plugins.md) allow you to use new syntax, **right now** without waiting for browser support. Check out our [usage guide](usage.md) to get started. ## JSX and React Babel can convert JSX syntax! Check out our [React preset](preset-react.md) to get started. Use it together with the [babel-sublime](https://github.com/babel/babel-sublime) package to bring syntax highlighting to a whole new level. You can install this preset with ```shell npm install --save-dev @babel/preset-react ``` and add `@babel/preset-react` to your Babel configuration. ```jsx export default React.createClass({ getInitialState() { return { num: this.getRandomNumber() }; }, getRandomNumber() { return Math.ceil(Math.random() * 6); }, render() { return Your dice roll: {this.state.num} ; } }); ``` > Learn more about [JSX](https://facebook.github.io/jsx/) ## Type Annotations (Flow and TypeScript) Babel can strip out type annotations! Check out either our [Flow preset](preset-flow.md) or [TypeScript preset](preset-typescript.md) to get started. Keep in mind that **Babel doesn't do type checking**; you'll still have to install and use Flow or TypeScript to check types. You can install the flow preset with ```shell npm install --save-dev @babel/preset-flow ``` ```js // @flow function square(n: number): number { return n * n; } ``` or the typescript preset with ```shell npm install --save-dev @babel/preset-typescript ``` ```js function Greeter(greeting: string) { this.greeting = greeting; } ``` > Learn more about [Flow](http://flowtype.org/) and [TypeScript](https://www.typescriptlang.org/) Pluggable --------- Babel is built out of plugins. Compose your own transformation pipeline using existing plugins or write your own. Easily use a set of plugins by using or creating a [preset](plugins.md#presets). [Learn more →](plugins.md) Create a plugin on the fly with [astexplorer.net](https://astexplorer.net/#/KJ8AjD6maa) or use [generator-babel-plugin](https://github.com/babel/generator-babel-plugin) to generate a plugin template. ```javascript // A plugin is just a function export default function ({types: t}) { return { visitor: { Identifier(path) { let name = path.node.name; // reverse the name: JavaScript -> tpircSavaJ path.node.name = name.split('').reverse().join(''); } } }; } ``` Debuggable ---------- **Source map** support so you can debug your compiled code with ease. Spec Compliant -------- Babel tries to stay true to the ECMAScript standard, as much as reasonably possible. It may also have specific options to be more spec compliant as a tradeoff to performance. Compact -------- Babel tries using the least amount of code possible with no dependence on a bulky runtime. This may be difficult to do in cases, and there are "loose" options for specific transforms that may tradeoff spec compliancy for readability, file size, and speed.