edit intro/babel

Author: ruanyf

docs/intro.md

@@ -121,74 +121,238 @@ input.map(function (item) {
 
 上面的原始代码用了箭头函数，这个特性还没有得到广泛支持，Babel将其转为普通函数，就能在现有的JavaScript环境执行了。
 
-### 命令行环境
+### 配置文件`.babelrc`
 
-命令行下，Babel的安装命令如下。
+Babel的配置文件是`.babelrc`，存放在项目的根目录下。使用Babel的第一步，就是配置这个文件。
+
+该文件用来设置转码规则和插件，基本格式如下。
+
+```javascript
+{
+  "presets": [],
+  "plugins": []
+}
+```
+
+`preset`字段设定转码规则，官方提供以下的规则集，你可以根据需要安装。
+
+```bash
+# ES2015转码规则
+$ npm install --save-dev babel-preset-es2015
+
+# react转码规则
+$ npm install --save-dev babel-preset-react
+
+# ES7不同阶段语法提案的转码规则（共有4个阶段），选装一个
+$ npm install --save-dev babel-preset-stage-0
+$ npm install --save-dev babel-preset-stage-1
+$ npm install --save-dev babel-preset-stage-2
+$ npm install --save-dev babel-preset-stage-3
+```
+
+然后，将这些规则加入`.babelrc`。
+
+```javascript
+  {
+    "presets": [
+      "es2015",
+      "react",
+      "stage-2"
+    ],
+    "plugins": []
+  }
+```
+
+注意，以下所有Babel工具和模块的使用，都必须先写好`.babelrc`。
+
+### 命令行转码`babel-cli`
+
+Babel提供`babel-cli`工具，用于命令行转码。
+
+它的安装命令如下。
 
 ```bash
 $ npm install --global babel-cli
-$ npm install --save babel-preset-es2015
 ```
 
-然后在当前目录下，新建一个配置文件`.babelrc`。
+它的命令行基本用法如下。
+
+```bash
+# 转码结果输出到标准输出
+$ babel example.js
+
+# 转码结果写入一个文件
+$ babel example.js --out-file compiled.js
+# 或者
+$ babel example.js -o compiled.js
+
+# 整个目录转码
+# --out-dir 或 -d 参数指定输出目录
+$ babel src --out-dir lib
+# 或者
+$ babel src -d lib
+
+# -s 参数生成source map文件
+$ babel src -d lib -s
+```
+
+上面代码是在全局环境下，进行Babel转码。但这意味着，如果项目要运行，全局环境必须有Babel，这就让项目产生了对环境的依赖，也无法支持不同项目使用不同版本的Babel。
+
+一个解决办法是将`babel-cli`安装在项目之中。
+
+```bash
+# 安装
+$ npm install --save-dev babel-cli
+```
+
+然后，改写`package.json`。
 
 ```javascript
-// .babelrc
 {
-  "presets": ['es2015']
+  // ...
+  "devDependencies": {
+    "babel-cli": "^6.0.0"
+  },
+  "scripts": {
+    "build": "babel src -d lib"
+  },
 }
 ```
 
-Babel自带一个`babel-node`命令，提供支持ES6的REPL环境。它支持Node的REPL环境的所有功能，而且可以直接运行ES6代码。
+转码的时候，就执行下面的命令。
+
+```javascript
+$ npm run build
+```
+
+### babel-node
+
+`babel-cli`工具自带一个`babel-node`命令，提供一个支持ES6的REPL环境。它支持Node的REPL环境的所有功能，而且可以直接运行ES6代码。
+
+它不用单独安装，而是随`babel-cli`一起安装。然后，执行`babel-node`就进入PEPL环境。
 
 ```bash
 $ babel-node
->
-> console.log([1,2,3].map(x => x * x))
-    [ 1, 4, 9 ]
->
+> (x => x * 2)(1)
+2
 ```
 
 `babel-node`命令也可以直接运行ES6脚本。假定将上面的代码放入脚本文件`es6.js`。
 
 ```bash
 $ babel-node es6.js
-[1, 4, 9]
+2
 ```
 
-`babel`命令可以将ES6代码转为ES5代码。
+`babel-node`也可以安装在项目中。
 
 ```bash
-$ babel es6.js
-"use strict";
+# 安装
+$ npm install --save-dev babel-cli
+```
 
-console.log([1, 2, 3].map(function (x) {
-  return x * x;
-}));
+然后，改写`package.json`。
+
+```javascript
+{
+  "scripts": {
+    "script-name": "babel-node script.js"
+  }
+}
 ```
 
-`-o`参数将转换后的代码，从标准输出导入文件。
+上面代码中，使用`babel-node`替代`node`，这样`script.js`本身就不用做任何改变。
+
+### babel-register
+
+`babel-register`模块改写`require`命令，为它加上一个钩子。每当使用`require`加载某个文件，就会先用Babel进行转码。
 
 ```bash
-$ babel es6.js -o es5.js
-# 或者
-$ babel es6.js --out-file es5.js
+$ npm install --save-dev babel-register
+```
+
+使用时，必须首先加载`babel-register`。
+
+```bash
+require("babel-register");
+require("./index.js");
 ```
 
-`-d`参数用于转换整个目录。
+然后，就不需要手动对`index.js`转码了。
+
+需要注意的是，`babel-register`只会对`require`命令加载的文件转码，而不会对当前文件转码。另外，由于它是实时转码，所以只适合在开发环境使用。
+
+### babel-core
+
+如果某些代码需要调用API进行转码，就要使用`babel-core`模块。
+
+安装命令如下。
 
 ```bash
-$ babel -d build-dir source-dir
+$ npm install babel-core
+```
+
+然后，在项目中就可以调用`babel-core`。
+
+```javascript
+var babel = require("babel-core");
+
+// 字符串转码
+babel.transform("code();", options);
+// => { code, map, ast }
+
+// 文件转码（异步）
+babel.transformFile("filename.js", options, function(err, result) {
+  result; // => { code, map, ast }
+});
+
+// 文件转码（同步）
+babel.transformFileSync("filename.js", options);
+// => { code, map, ast }
+
+// Babel AST转码
+babel.transformFromAst(ast, code, options);
+// => { code, map, ast }
+```
+
+配置对象`options`，可以参看官方文档[http://babeljs.io/docs/usage/options/](http://babeljs.io/docs/usage/options/)。
+
+下面是一个例子。
+
+```javascript
+var es5Code = 'let x = n => n + 1';
+var es6Code = require('babel-core')
+  .transform(es5Code, {
+    presets: ['es2015']
+  })
+  .code;
+// '"use strict";\n\nvar x = function x(n) {\n  return n + 1;\n};'
 ```
 
-注意，`-d`参数后面跟的是输出目录。
+上面代码中，`transform`方法的第一个参数是一个字符串，表示需要转换的ES5代码，第二个参数是转换的配置对象。
+
+### babel-polyfill
 
-如果希望生成source map文件，则要加上`-s`参数。
+Babel默认只转换新的JavaScript句法（syntax），而不转换新的API，比如Iterator、Generator、Set、Maps、Proxy、Reflect、Symbol、Promise等全局对象，以及一些定义在全局对象上的方法（比如`Object.assign`）。
+
+举例来说，ES6在`Array`对象上新增了`Array.from`方法。Babel就不会转换这个方法。如果想让这个方法运行，必须使用`babel-polyfill`。
+
+安装命令如下。
 
 ```bash
-$ babel -d build-dir source-dir -s
+$ npm install --save babel-polyfill
 ```
 
+然后，在脚本头部，加入如下一行代码。
+
+```javascript
+import 'babel-polyfill';
+// 或者
+require('babel-polyfill');
+```
+
+Babel默认不转码的API非常多，详细清单可以查看`babel-plugin-transform-runtime`模块的[`definitions.js`](https://github.com/babel/babel/blob/master/packages/babel-plugin-transform-runtime/src/definitions.js)文件。
+
 ### 浏览器环境
 
 Babel也可以用于浏览器。但是，从Babel 6.0开始，不再直接提供浏览器版本，而是要用构建工具构建出来。如果你没有或不想使用构建工具，只有通过安装5.x版本的`babel-core`模块获取。
@@ -237,70 +401,53 @@ $  browserify script.js -o bundle.js \
 }
 ```
 
-### Node环境
-
-Node脚本之中，需要转换ES6脚本，可以像下面这样写。
-
-先安装`babel-core`和`babel-preset-es2015`。
+### 在线转换
 
-```javascript
-$ npm install --save-dev babel-core babel-preset-es2015
-```
+Babel提供一个[REPL在线编译器](https://babeljs.io/repl/)，可以在线将ES6代码转为ES5代码。转换后的代码，可以直接作为ES5代码插入网页运行。
 
-然后，在项目根目录下新建一个`.babelrc`文件。
+### 与其他工具的配合
 
-```javascript
-{
-  "presets": ["es2015"]
-}
-```
+许多工具需要Babel进行前置转码，这里举两个例子：ESLint和Mocha。
 
-然后在脚本中，调用`babel-core`的`transform`方法。
+ESLint用于静态检查代码的语法和风格，安装命令如下。
 
-```javascript
-var es5Code = 'let x = n => n + 1';
-var es6Code = require('babel-core')
-  .transform(es5Code, {presets: ['es2015']})
-  .code;
-// '"use strict";\n\nvar x = function x(n) {\n  return n + 1;\n};'
+```bash
+$ npm install --save-dev eslint babel-eslint
 ```
 
-上面代码中，`transform`方法的第一个参数是一个字符串，表示需要转换的ES5代码，第二个参数是转换的配置对象。
-
-Node脚本还有一种特殊的`babel`用法，即把`babel`加载为`require`命令的一个钩子。安装`babel-core`和`babel-preset-es2015`以后，先在项目的根目录下面，设置一个配置文件`.babelrc`。
+然后，在项目根目录下，新建一个配置文件`.eslint`，在其中加入`parser`字段。
 
 ```javascript
-// .babelrc
 {
-  "presets": ["es2015"]
+  "parser": "babel-eslint",
+  "rules": {
+    ...
+  }
 }
 ```
 
-然后，在你的应用的入口脚本（entry script）头部，加入下面的语句。
+再在`package.json`之中，加入相应的`scripts`脚本。
 
 ```javascript
-require("babel-core/register");
-```
-
-有了上面这行语句，后面所有通过`require`命令加载的后缀名为`.es6`、`.es`、`.jsx`和`.js`的脚本，都会先通过`babel`转码后再加载。
-
-需要注意的是，Babel默认不会转换Iterator、Generator、Set、Maps、Proxy、Reflect、Symbol、Promise等全局对象，以及一些定义在全局对象上的方法（比如`Object.assign`）。如果你用到了这些功能，当前的运行环境又不支持。就需要安装`babel-polyfill`模块。
-
-```bash
-$ npm install babel-polyfill --save
+  {
+    "name": "my-module",
+    "scripts": {
+      "lint": "eslint my-files.js"
+    },
+    "devDependencies": {
+      "babel-eslint": "...",
+      "eslint": "..."
+    }
+  }
 ```
 
-然后，在所有脚本头部加上一行。
+Mocha则是一个测试框架，如果需要执行使用ES6语法的测试脚本，可以修改`package.json`的`scripts.test`脚本如下。
 
 ```javascript
-require('babel-polyfill');
-// 或者
-import 'babel-polyfill';
+  "test": "mocha --ui qunit --compilers js:babel-core/register"
 ```
 
-### 在线转换
-
-Babel提供一个[REPL在线编译器](https://babeljs.io/repl/)，可以在线将ES6代码转为ES5代码。转换后的代码，可以直接作为ES5代码插入网页运行
+上面命令中，`--compilers`参数指定脚本的转码器，意为后缀名为`js`的文件，都需要使用`babel-core/register`先转码。
 
 ## Traceur转码器