cerxes/babel
3
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Add new documentation

Browse Source
This commit is contained in:
James Kyle
2015-01-05 23:27:46 -08:00
parent 92366dfc7b
commit 46f9ed7d74
24 changed files with 2198 additions and 1018 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
doc/usage/api.md Normal file
View File

@@ -0,0 +1,59 @@
---
layout: docs
title: API
description: How to use the Node.js API.
permalink: /docs/usage/api/
---
```javascript
var to5 = require('6to5');
```
## to5.transform
Transforms the passed in `code`.
```
to5.transform(code, [options])
```
**Example**
```js
var result = to5.transform('code();', options);
result.code;
result.map;
result.ast;
```
## to5.transformFile
Asynchronously transforms the entire contents of a file.
```js
to5.transformFile(filename, [options], callback)
```
**Example**
```js
to5.transformFile('filename.js', options, function (err, result) {
result.code;
});
```
## to5.transformFileSync
Synchronous version of `to5.transformFile`. Returns the transformed contents of
the `filename`.
```js
to5.transformFileSync(filename, [options])
```
**Example**
```js
to5.transformFileSync('filename.js', options).code;
```

59
doc/usage/browser.md Normal file
View File

@@ -0,0 +1,59 @@
---
layout: docs
title: Browser
description: How to transpile in the browser.
permalink: /docs/usage/browser/
redirect_from: /browser.html
---
<p class="lead">
A browser version of 6to5 is available from `browser.js` inside the 6to5
directory in an npm release.
</p>
<blockquote class="to5-callout to5-callout-warning">
<h4>Not intended for serious use</h4>
<p>
Compiling in the browser has a fairly limited use case, so if you are
working on a production site you should be precompiling your scripts
server-side. See <a href="../setup/#build-systems">setup build systems</a>
for more information.
</p>
</blockquote>
## Script tags
When the `browser.js` file is included all scripts with the type
`text/ecmascript-6` and `text/6to5` are automatically compiled and ran.
```html
<script src="node_modules/6to5/browser.js"></script>
<script type="text/6to5">
class Test {
test() {
return 'test';
}
}
var test = new Test;
test.test(); // "test"
</script>
```
## API
Programmatically transpile and execute strings of ES6 code.
See [options](#options) for additional documentation.
### `to5.transform(code, [opts])`
```js
to5.transform('class Test {}').code;
```
### `to5.run(code, [opts])`
````js
to5.run('class Test {}');
````

99
doc/usage/cli.md Normal file
View File

@@ -0,0 +1,99 @@
---
layout: docs
title: CLI
description: How to use the CLI tools.
permalink: /docs/usage/cli/
redirect_from: /usage.html
---
<p class="lead">
6to5 comes with a built-in CLI which can be used to compile files from the
command line.
</p>
## Install
Using [npm](https://www.npmjs.com/) you can install 6to5 globally, making it
available from the command line.
```sh
$ npm install --global 6to5
```
## 6to5
#### Compile Files
Compile the file `script.js` and **output to stdout**.
```sh
$ 6to5 script.js
# output...
```
If you would like to **output to a file** you may use `--out-file` or `-o`.
```sh
$ 6to5 script.js --out-file script-compiled.js
```
### Compile with Source Maps
If you would then like to add a **source map file** you can use
`--source-maps` or `-s`. [Learn more about source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/).
```sh
$ 6to5 script.js --out-file script-compiled.js --source-maps
```
If you would rather have **inline source maps**, you may use
`--source-maps-inline` or `-t`.
```sh
$ 6to5 script.js --out-file script-compiled.js --source-maps-inline
```
### Compile Directories
Compile the entire `src` directory and output it to the `lib` directory.
```sh
$ 6to5 src --out-dir lib
```
Compile the entire `src` directory and output it to the one concatenated file.
```sh
$ 6to5 src --out-file script-compiled.js
```
### Piping Files
Pipe a file in via stdin and output it to `script-compiled.js`
```sh
$ 6to5 --out-file script-compiled.js < script.js
```
## 6to5-node
6to5 comes with a second CLI which works exactly the same as Node.js's CLI, only
it will compile ES6 code before running it.
Launch a REPL (Read-Eval-Print-Loop).
```sh
$ 6to5-node
```
Evaluate code.
```sh
$ 6to5-node -e "class Test { }"
```
Compile and run `test.js`.
```sh
$ 6to5-node test
```

28
doc/usage/experimental.md Normal file
View File

@@ -0,0 +1,28 @@
---
layout: docs
title: Experimental
description: How to use experimental ES7 features.
permalink: /docs/usage/experimental/
redirect_from: /experimental.html
---
> 6to5 also has experimental support for ES7 proposals.
<blockquote class="to5-callout to5-callout-danger">
<h4>Subject to change</h4>
<p>
These proposals are subject to change so <strong><em>use with extreme
caution</em></strong>. 6to5 may update without warning in order to track spec
changes. Please do not use them in production applications.
</p>
</blockquote>
#### Usage
```js
$ 6to5 --experimental
```
```js
to5.transform('code', { experimental: true });
```

22
doc/usage/jsx.md Normal file
View File

@@ -0,0 +1,22 @@
---
layout: docs
title: JSX
description: How to use JSX.
permalink: /docs/usage/jsx/
---
<p class="lead">
6to5 has built-in support for React v0.12. Tags are automatically transformed
to their equivalent <code>React.createElement(...)</code> and
<code>displayName</code> is automatically inferred and added to all
<code>React.createClass</code> calls.
</p>
## Blacklist
To disable this behaviour add react to your blacklist:
````js
to5.transform("code", { blacklist: ["react"] });
$ 6to5 --blacklist react
```

260
doc/usage/modules.md Normal file
View File

@@ -0,0 +1,260 @@
---
layout: docs
title: Modules
description: How to use module formatters.
permalink: /docs/usage/modules/
redirect_from: /modules.html
---
<p class="lead">
6to5 has the ability to transpile ES6 modules to the module system of your
choice. You can even easily create your own.
</p>
## Usage
```sh
$ 6to5 --modules common script.js
```
```js
to5.transform('import "foo";', { modules: "common" });
```
## Formats
### Common (Default)
**Usage**
```sh
$ 6to5 --modules common
```
**Example**
```js
export default test;
export {test};
export var test = 5;
import "foo";
import foo from "foo";
import * as foo from "foo";
import {bar} from "foo";
import {foo as bar} from "foo";
```
```js
"use strict";
var _interopRequire = function (obj) {
return obj && (obj["default"] || obj);
};
exports = module.exports = test;
exports.test = test;
var test = exports.test = 5;
require("foo");
var foo = _interopRequire(require("foo"));
var foo = require("foo");
var bar = require("foo").bar;
var bar = require("foo").foo;
```
### AMD
**Usage**
```sh
$ 6to5 --modules amd
```
**Example**
```js
import foo from "foo";
export function bar() {
return foo("foobar");
}
```
```js
define(["exports", "foo"], function (exports, _foo) {
"use strict";
var _interopRequire = function (obj) {
return obj && (obj["default"] || obj);
};
exports.bar = bar;
var foo = _interopRequire(_foo);
function bar() {
return foo("foobar");
}
});
```
You can optionally specify to include the module id (using the `--amd-module-id`
argument):
```js
define("filename", ["exports", "foo"], function (exports, _foo) {})
```
### System
**Usage**
```sh
$ 6to5 --modules system
```
**Example**
```js
import foo from "foo";
export function bar() {
return foo("foobar");
}
```
```js
System.register("bar", ["foo"], function (_export) {
"use strict";
var __moduleName = "bar";
var foo;
function bar() {
return foo("foobar");
}
return {
setters: [function (m) {
foo = m.default;
}],
execute: function () {
_export("bar", bar);
}
};
});
```
### UMD
**Usage**
```sh
$ 6to5 --modules umd
```
**Example**
```js
import foo from "foo";
export function bar() {
return foo("foobar");
}
```
```js
(function (factory) {
if (typeof define === "function" && define.amd) {
define(["exports", "foo"], factory);
} else if (typeof exports !== "undefined") {
factory(exports, require("foo"));
}
})(function (exports, _foo) {
"use strict";
var _interopRequire = function (obj) {
return obj && (obj["default"] || obj);
};
exports.bar = bar;
var foo = _interopRequire(_foo);
function bar() {
return foo("foobar");
}
});
```
### Ignore
**Usage**
```sh
$ 6to5 --modules ignore
```
**Example**
```js
import foo from "foo";
export function bar() {
return foo("foobar");
}
```
```js
function bar() {
return foo("foobar");
}
```
### Custom
You can alternatively specify module names instead of one of the built-in types.
**Usage**
```js
$ 6to5 --modules custom-module-formatter
```
**Example**
**`node_modules/custom-module-formatter/index.js`**
```js
module.exports = ModuleFormatter;
function ModuleFormatter() {}
ModuleFormatter.prototype.transform = function (ast) {
// this is ran after all transformers have had their turn at modifying the ast
// feel free to modify this however
};
ModuleFormatter.prototype.importDeclaration = function (node, nodes) {
// node is an ImportDeclaration
};
ModuleFormatter.prototype.importSpecifier = function (specifier, node, nodes) {
// specifier is an ImportSpecifier
// node is an ImportDeclaration
};
ModuleFormatter.prototype.exportDeclaration = function (node, nodes) {
// node is an ExportDeclaration
};
ModuleFormatter.prototype.exportSpecifier = function (specifier, node, nodes) {
// specifier is an ExportSpecifier
// node is an ExportDeclaration
};
```

35
doc/usage/options.md Normal file
View File

@@ -0,0 +1,35 @@
---
layout: docs
title: Options
description: Options for 6to5 transpiling.
permalink: /docs/usage/options/
---
## Usage
```js
to5.transform(code, options);
```
```sh
$ 6to5 --name=value
```
## Options
| Option | Default | Description |
| ------------------ | -------------------- | ------------------------------- |
| `filename` | `"unknown"` | Filename for use in errors etc. |
| `fileNameRelative` | `(filename)` | Filename relative to `sourceRoot`. |
| `blacklist` | `[]` | Array of transformers to **exclude**. Run `6to5 --help` to see a full list of transformers. |
| `whitelist` | `[]` | Array of transformers to **only** use. Run `6to5 --help` to see a full list of transformers. |
| `modules` | `"common"` | Which module formatter to use. Run `6to5 --help` to see a full list of module formatters. |
| `sourceMap` | `false` | If truthy, adds a `map` property to returned output. If set to `"inline"`, a comment with a sourceMappingURL directive is added to the bottom of the returned code. |
| `sourceMapName` | `(filenameRelative)` | Set `file` on returned source map. |
| `sourceFileName` | `(filenameRelative)` | Set `sources[0]` on returned source map. |
| `sourceRoot` | `(moduleRoot)` | The root from which all sources are relative. |
| `moduleRoot` | `(sourceRoot)` | Optional prefix for the AMD module formatter that will be prepend to the filename on module definitions. |
| `amdModuleIds` | `false` | If truthy, insert an explicit id for each defined AMD module. By default, AMD modules are anonymous. |
| `runtime` | `false` | Optionally replace all 6to5 helper declarations with a referenece to this variable. If set to `true` then the default namespace is used `to5Runtime`. |
| `comments` | `true` | Output comments in generated output. |
| `experimental` | `false` | Enable support for experimental ES7 features. |

173
doc/usage/playground.md Normal file
View File

@@ -0,0 +1,173 @@
---
layout: docs
title: Playground
description: How to use the playground.
permalink: /docs/usage/playground/
redirect_from: /playground.html
---
> Playground is a proving ground for language ideas.
<blockquote class="to5-callout to5-callout-danger">
<h4>Unofficial</h4>
<p>
These features are in no way endorsed by Ecma International and are not a
part of any ECMAScript standard, nor are they necessarily on track to become
part of any standard. <strong><em>Use with extreme caution</em></strong>.
</p>
</blockquote>
<blockquote class="to5-callout to5-callout-info">
<h4>Proposal Authors</h4>
<p>
If you are actively working on an
<a href="https://github.com/tc39/ecma262">ECMAScript proposal</a>, this is a
good place to get your ideas implemented with so that they may be tested
with all of the latest language and API features.
</p>
<p>
Please feel free to <a href="https://github.com/6to5/6to5/issues/new">open
an issue</a> on the 6to5 repository with your WIP spec, and we can discuss
getting it implemented. Be sure to include as much information as possible.
</p>
</blockquote>
## Usage
```js
$ 6to5 --playground
```
```js
to5.transform('code', { playground: true });
```
<blockquote class="to5-callout to5-callout-info">
<h4>Enables experimental</h4>
<p>
Enabling playground also enables experimental support.
</p>
</blockquote>
## Features
### Memoization assignment operator
The memoization assignment operator allows you to lazily set an object property.
It checks whether there's a property defined on the object and if there isn't
then the right hand value is set.
This means that `obj.x` in the following `var x = { x: undefined }; obj.x ?= 2;``
will still be `undefined` because it's already been defined on the object.
**Uses**
```js
var obj = {};
obj.x ?= 2;
obj.x; // 2
obj = { x: 1 };
obj.x ?= 2;
obj.x; // 1
obj = { x: undefined }
obj.x ?= 2;
obj.x; // undefined
```
**Example**
```js
var obj = {};
obj.x ?= 2;
```
is equivalent to
```js
var obj = {};
if (!Object.prototype.hasOwnProperty.call(obj, 'x')) obj.x = 2;
```
### Method binding
```javascript
var fn = obj#method;
var fn = obj#method("foob");
```
is equivalent to
```javascript
var fn = obj.method.bind(obj);
var fn = obj.method.bind(obj, "foob");
```
### Method binding function shorthand
```javascript
["foo", "bar"].map(#toUpperCase); // ["FOO", "BAR"]
[1.1234, 23.53245, 3].map(#toFixed(2)); // ["1.12", "23.53", "3.00"]
```
equivalent to
```javascript
["foo", "bar"].map(function (val) { return val.toUpperCase(); });
[1.1234, 23.53245, 3].map(function (val) { return val.toFixed(2); });
```
### Object getter memoization
```js
var foo = {
memo bar() {
return complex();
}
};
class Foo {
memo bar() {
return complex();
}
}
```
is equivalent to
```js
var foo = {
get bar() {
return Object.defineProperty(this, "bar", {
value: complex(),
enumerable: true,
configurable: true,
writable: true
}).bar;
}
};
class Foo {
get bar() {
return Object.defineProperty(this, "bar", {
value: complex(),
enumerable: true,
configurable: true,
writable: true
}).bar;
}
}
```
### This shorthand
```js
@foo
```
is equivalent to
```
this.foo
```

56
doc/usage/polyfill.md Normal file
View File

@@ -0,0 +1,56 @@
---
layout: docs
title: Polyfill
description: How to use the Polyfill.
permalink: /docs/usage/polyfill/
---
<p class="lead">
6to5 includes a polyfill that includes a custom
<a href="https://github.com/facebook/regenerator/blob/master/runtime.js">regenerator runtime</a>
and <a href="https://github.com/zloirock/core-js">core.js</a>.
</p>
This will emulate a full ES6 environment. This polyfill is automatically loaded
when using `6to5-node` and `6to5/register`.
## Usage in Node/Browserify
You need to include the polyfill require at the top the **entry point** to
your application.
```js
require('6to5/polyfill');
```
Fortunately, this is automatically loaded when using:
```js
require('6to5/register');
```
## Usage in Browser
Available from the `browser-polyfill.js` file within the 6to5 directory of an
npm release. This needs to be included **before** all your compiled 6to5 code.
You can either prepend it to your compiled code or include it in a `<script>`
before it.
**NOTE:** Do not `require` this via browserify etc, use `6to5/polyfill`.
<blockquote class="to5-callout to5-callout-warning">
<h4>Polyfills are not perfect</h4>
<p>
Due to limitations in various ES5 environments not every polyfill will work
in every environment.
</p>
</blockquote>
<blockquote class="to5-callout to5-callout-warning">
<h4>Certain polyfills not included</h4>
<p>
Certain polyfills are too large/complex for their implemented features to
justify including them for all builds. You may have to include additional
polyfills for a subset of ES6 features.
</p>
</blockquote>

55
doc/usage/require.md Normal file
View File

@@ -0,0 +1,55 @@
---
layout: docs
title: Require Hook
description: How to use the require hook.
permalink: /docs/usage/require/
---
## Install
```sh
$ npm install 6to5
```
## Usage
```js
require('6to5/register');
```
All subsequent files required by node with the extensions `.es6`, `.es`, and
`.js` will be transformed by 6to5. The polyfill specified in Polyfill is also
required.
**NOTE:** By default all requires to `node_modules` will be ignored. You can
override this by passing an ignore regex via:
```js
require('6to5/register')({
// This will override `node_modules` ignoring - you can alternatively pass
// a regex
ignore: false
});
```
## Register Options
```javascript
require('6to5/register')({
// Optional ignore regex - if any filenames **do** match this regex then they
// aren't compiled
ignore: /regex/,
// Optional only regex - if any filenames **don't** match this regex then they
// aren't compiled
only: /my_es6_folder/,
// See options above for usage
whitelist: [],
blacklist: [],
// This will remove the currently hooked extensions of .es6 and .js so you'll
// have to add them back if you want them to be used again.
extensions: ['.js', '.es6']
});
```

56
doc/usage/runtime.md Normal file
View File

@@ -0,0 +1,56 @@
---
layout: docs
title: Optional Runtime
description: How to use the optional runtime.
permalink: /docs/usage/runtime/
---
## Details
6to5 has a few helper functions that'll be placed at the top of the generated
code if needed so it's not inlined multiple times throughout that file. This may
become an issue if you have multiple files, especially when you're sending them
to the browser. gzip alleviates most of this concern but it's still not ideal.
You can tell 6to5 to not place any declarations at the top of your files and
instead just point them to a reference contained within the runtime.
## Usage
```js
$ 6to5 --runtime
```
```js
to5.transform('code', { runtime: true });
```
### Getting the runtime
```sh
$ 6to5-runtime
```
or
```js
require('6to5').runtime();
```
or from an npm release in `runtime.js` from the 6to5 directory.
### Customising namespace
You can also customise the runtime namespace by passing an optional namespace
argument:
```sh
$ 6to5-runtime myCustomNamespace
```
```js
require("6to5").runtime('myCustomNamespace');
```
See [Options - runtime](../options) for documentation on changing the reference in
generated code.