{
  "author": {
    "name": "Ben Newman",
    "email": "bn@cs.stanford.edu"
  },
  "name": "recast",
  "description": "JavaScript syntax tree transformer, conservative pretty-printer, and automatic source map generator",
  "keywords": [
    "ast",
    "rewriting",
    "refactoring",
    "codegen",
    "syntax",
    "transformation",
    "parsing",
    "pretty-printing"
  ],
  "version": "0.5.17",
  "homepage": "http://github.com/benjamn/recast",
  "repository": {
    "type": "git",
    "url": "git://github.com/benjamn/recast.git"
  },
  "main": "main.js",
  "scripts": {
    "test": "node ./node_modules/mocha/bin/mocha --reporter spec"
  },
  "dependencies": {
    "esprima": "~1.1.1",
    "source-map": "0.1.32",
    "private": "~0.1.3",
    "cls": "~0.1.3",
    "ast-types": "~0.3.27"
  },
  "devDependencies": {
    "mocha": "~1.18.2"
  },
  "engines": {
    "node": ">= 0.8"
  },
  "readme": "# recast, _v_. [![Build Status](https://travis-ci.org/benjamn/recast.png?branch=master)](https://travis-ci.org/benjamn/recast)\n1. to give (a metal object) a different form by melting it down and reshaping it.\n1. to form, fashion, or arrange again.\n1. to remodel or reconstruct (a literary work, document, sentence, etc.).\n1. to supply (a theater or opera work) with a new cast.\n\nInstallation\n---\n\nFrom NPM:\n\n    npm install recast\n    \nFrom GitHub:\n\n    cd path/to/node_modules\n    git clone git://github.com/benjamn/recast.git\n    cd recast\n    npm install .\n\nUsage\n---\n\nIn less poetic terms, Recast exposes two essential interfaces, one for parsing JavaScript code (`require(\"recast\").parse`) and the other for reprinting modified syntax trees (`require(\"recast\").print`).\n\nHere's a simple but non-trivial example of how you might use `.parse` and `.print`:\n```js\nvar recast = require(\"recast\");\n\n// Let's turn this function declaration into a variable declaration.\nvar code = [\n    \"function add(a, b) {\",\n    \"  return a +\",\n    \"    // Weird formatting, huh?\",\n    \"    b;\",\n    \"}\"\n].join(\"\\n\");\n\n// Parse the code using an interface similar to require(\"esprima\").parse.\nvar ast = recast.parse(code);\n```\nNow do *whatever* you want to `ast`. Really, anything at all!\n```js\n// Grab a reference to the function declaration we just parsed.\nvar add = ast.program.body[0];\n\n// Make sure it's a FunctionDeclaration (optional).\nvar n = recast.types.namedTypes;\nn.FunctionDeclaration.assert(add);\n\n// If you choose to use recast.builders to construct new AST nodes, all builder\n// arguments will be dynamically type-checked against the Mozilla Parser API.\nvar b = recast.types.builders;\n\n// This kind of manipulation should seem familiar if you've used Esprima or the\n// Mozilla Parser API before.\nast.program.body[0] = b.variableDeclaration(\"var\", [\n    b.variableDeclarator(add.id, b.functionExpression(\n        null, // Anonymize the function expression.\n        add.params,\n        add.body\n    ))\n]);\n\n// Just for fun, because addition is commutative:\nadd.params.push(add.params.shift());\n```\nWhen you finish manipulating the AST, let `recast.print` work its magic:\n```js\nvar output = recast.print(ast).code;\n```\nThe `output` string now looks exactly like this, weird formatting and all:\n```js\nvar add = function(b, a) {\n  return a +\n    // Weird formatting, huh?\n    b;\n}\n```\nThe 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:\n```js\nrecast.print(recast.parse(source)).code === source\n```\nWhenever Recast cannot reprint a modified node using the orginal 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.\n\nIf you really don't care about preserving the original formatting, you can access the pretty printer directly:\n```js\nvar output = recast.prettyPrint(ast, { tabWidth: 2 }).code;\n```\nAnd here's the exact `output`:\n```js\nvar add = function(b, a) {\n  return a + b;\n}\n```\nNote that the weird formatting was discarded, yet the behavior and abstract structure of the code remain the same.\n\nSource maps\n---\n\nOne 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!\n\nWith 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.\n\nAll 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:\n```js\nvar result = recast.print(transform(recast.parse(source, {\n  sourceFileName: \"source.js\"\n})), {\n  sourceMapName: \"map.json\"\n});\n    \nconsole.log(result.code); // Resulting string of code.\nconsole.log(result.map); // JSON source map.\n\nvar SourceMapConsumer = require(\"source-map\").SourceMapConsumer;\nvar smc = new SourceMapConsumer(result.map);\nconsole.log(smc.originalPositionFor({\n  line: 3,\n  column: 15\n})); // { source: 'source.js',\n     //   line: 2,\n     //   column: 10,\n     //   name: null }\n```\n\nNote 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.\n\nNote 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.\n\nMotivation\n---\n\nThe 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.\n\nIs 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.\n\nWhat 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.\n\nAnd 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?\n",
  "readmeFilename": "README.md",
  "bugs": {
    "url": "https://github.com/benjamn/recast/issues"
  },
  "_id": "recast@0.5.17",
  "_shasum": "12b0a8c76b4d9064dc455a0076a73301acfa652b",
  "_from": "recast@~0.5.12",
  "_resolved": "https://registry.npmjs.org/recast/-/recast-0.5.17.tgz"
}
