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

move docs to folder

Browse Source
This commit is contained in:
Sebastian McKenzie
2014-11-13 01:13:48 +11:00
parent fd63650d6a
commit 297f103ddb
13 changed files with 477 additions and 495 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
doc/browser.md Normal file
View File

@@ -0,0 +1,49 @@
# Browser
A browser version of 6to5 is available from `browser.js` inside the 6to5
directory in an npm release.
## API
```javascript
to5.transform("class Test {}").code;
```
## Scripts
While it's not recommended for serious use, when the browser version is included
all scripts with the type `text/ecmascript-6` and `text/6to5` are automatically
compiled and ran.
For example:
```html
<script src="node_modules/6to5/browser.js"></script>
<script type="text/6to5">
class Test {
test() {
return "test";
}
}
var test = new Test;
test.test();
</script>
```
## Build
You can build a browser version of the compiler by running the following in the
6to5 directory:
$ make build
This will output the files `dist/6to5.js` and `dist/6to5.min.js`.
## Test
To test 6to5 in your browser run:
$ make test-browser
And open `test/browser.html` in your browser if it doesn't open automatically.

43
doc/caveats.md Normal file
View File

@@ -0,0 +1,43 @@
# Caveats
## Classes
Built-in classes such as `Date`, `Array` and `DOM` cannot be subclassed due to
limitations in ES5 implementations.
If you're inheriting from a class then static properties are inherited from it
via [\_\_proto\_\_](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto),
this is widely supported but you may run into problems with much older browsers.
**NOTE:** `__proto__` is not supported on IE <= 9 so static properties
**will not** be inherited. A possible workaround is to use `super();`:
```javascript
class Foo {
static foo() {
}
}
class Bar extends Foo {
static foo() {
super();
}
}
```
## For-of
A polyfill is required for for-of functionality that implements `Symbol` and
adds `prototype[Symbol.iterator]` behaviour to built-ins. Using the polyfills
specified in [polyfill](polyfill.md) suffices.
## Generators
The [regenerator runtime](https://github.com/facebook/regenerator/blob/master/runtime.js)
and an [ES6 polyfill](polyfill.md) are required in order for generators to work.
## Spread
An [ES6 polyfill](polyfill.md) is required in order for spread to work. More
specifically a polyfill for `Array.from`.

99
doc/differences.md Normal file
View File

@@ -0,0 +1,99 @@
# Differences
## Philosophy
The fundamental concept behind 6to5 is that the generated code must be close as
possible to the original, retaining all the same formatting and readability.
Many other transpilers are just concerned with making the code work while 6to5
is concerned with making sure it works **and** is readable at the same time.
For example, given the following array comprehension:
```javascript
var seattlers = [for (c of customers) if (c.city == "Seattle") { name: c.name, age: c.age }];
```
is generated to the following with 6to5:
```javascript
var seattlers = customers.filter(function (c) {
return c.city == "Seattle";
}).map(function (c) {
return {
name: c.name,
age: c.age
};
});
```
The following is what Traceur generates:
```javascript
var seattlers = (function() {
var c;
var $__20 = 0,
$__21 = [];
for (var $__22 = customers[$traceurRuntime.toProperty(Symbol.iterator)](),
$__23; !($__23 = $__22.next()).done; ) {
c = $__23.value;
if (c.city == "Seattle")
$traceurRuntime.setProperty($__21, $__20++, {
name: c.name,
age: c.age
});
}
return $__21;
}());
```
As you can tell, it's not very pretty, unreadable even. Instead of mapping
directly to a runtime, like other transpilers, 6to5 maps directly to the
equivalent ES5.
I'm not saying 6to5 is for everyone or even suited for everything. Traceur is
better suited if you'd like a full ES6 environment with polyfills and all.
## Comparison to other transpilers
| | 6to5 | Traceur | esnext | es6now | es6-transpiler | jstransform |
| ---------------------------- | ---- | ------- | ------ | ------ | -------------- | ----------- |
| No runtime | ✓ | | | | ✓ | ✓ |
| Source maps | ✓ | ✓ | ✓ | | ✓ | ✓ |
| No compiler global pollution | ✓ | | ✓ | | ✓ | ✓ |
| Arrow functions | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Classes | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Computed property names | ✓ | ✓ | ✓ | ✓ | ✓ | |
| Constants | ✓ | ✓ | | | ✓ | |
| Default parameters | ✓ | ✓ | ✓ | ✓ | ✓ | |
| Destructuring | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| For-of | ✓ | ✓ | ✓ | ✓ | ✓ | |
| Generators | ✓ | ✓ | ✓ | | | |
| Let scoping | ✓ | ✓ | | | ✓ | |
| Modules | ✓ | ✓ | | ✓ | | |
| Property method assignment | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Property name shorthand | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Rest parameters | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Spread | ✓ | ✓ | ✓ | ✓ | ✓ | |
| Template literals | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Unicode regex | ✓ | ✓ | | | ✓ | |
### [Traceur](https://github.com/google/traceur-compiler)
Traceur requires quite a bulky runtime (~75KB) and produces quite verbose code.
While this can be trimmed down by selectively building the runtime, it's an
unneccesary step when a runtime can be eliminated entirely.
### [es6now](https://github.com/zenparsing/es6now)
es6now doesn't output sourcemaps. This is cited as a positive as line-to-line
mapping is the goal. This however obviously doesn't retain column mapping
resulting in the output code not being very pleasant.
### [es6-transpiler](https://github.com/termi/es6-transpiler)
The es6-transpiler compiler requires shims to operate which pollutes the global
scope resulting in possible collisions.
es6-transpiler maps line-by-line, just like es6now, this results in the same
issues such as lack of column information and unpleasant code output.

177
doc/features.md Normal file
View File

@@ -0,0 +1,177 @@
# Features
## Array comprehension
```javascript
[for (i of [1, 2, 3]) i * i]; // [1, 4, 9]
```
## Async functions
```javascript
async function chainAnimationsAsync(elem, animations) {
for (var anim of animations) {
await anim(elem);
}
}
```
## Arrow functions
```javascript
arr.map(x => x * x);
```
## Let scoping
```javascript
for (let i in arr) {
let v = arr[i];
}
```
## Classes
```javascript
class Foo extends Bar {
constructor() { }
foo() { }
get bar() { }
set bar() { }
}
```
## Computed property names
```javascript
var foo = "foo";
var bar = "bar";
var obj = {
["foo" + bar]: "heh",
["bar" + foo]: "noo",
foo: "foo",
bar: "bar"
};
```
## Constants
```javascript
const MULTIPLIER = 5;
console.log(2 * MULTIPLIER);
MULTIPLIER = 6; // error
var MULTIPLIER; // error
```
## Default parameters
```javascript
function foo(bar = "foo") {
return bar + "bar";
}
```
## Destructuring
```javascript
var [a, [b], c, d] = ["hello", [", ", "junk"], ["world"]];
console.log(a + b + c); // hello, world
```
## For-of
```javascript
for (var i of [1, 2, 3]) {
console.log(i * i);
}
```
## Generators
```javascript
```
## Generator comprehension
```javascript
```
## Modules
```javascript
```
## Numeric literals
```javascript
0b111110111 === 503; // true
0o767 === 503; // true
```
## Property method assignment
```javascript
var obj = {
foo() {
return "foobar";
},
get bar() {
return this._bar;
},
set bar(val) {
this._bar = val;
}
};
```
## Property name shorthand
```javascript
function f(x, y) {
return { x, y };
}
```
## Rest parameters
```javascript
function printList(name, ...items) {
console.log("list %s has the following items", name);
items.forEach(function (item) {
console.log(item);
});
}
```
## Spread
```javascript
function add(x, y) {
return x + y;
}
var numbers = [5, 10];
add(...numbers); // 15
```
## Template literals
```javascript
var x = 5;
var y = 10;
console.log(`${x} + ${y} = ${x + y}`); // "5 + 10 = 15"
```
## Unicode regex
```javascript
var string = 'foo💩bar';
var match = string.match(/foo(.)bar/u);
console.log(match[1]);
```

36
doc/index.md Normal file
View File

@@ -0,0 +1,36 @@
**6to5** turns ES6 code into vanilla ES5, so you can use ES6 features **today.**
- **Readable** - formatting is retained if possible so your generated code is as similar as possible.
- **Extensible** - with a large range of [plugins](plugins.md) and **browser support**.
- **Lossless** - **source map support** so you can debug your compiled code with ease.
- **Compact** - maps directly to the equivalent ES5 with **no runtime**[\*](caveats.md#generators).
## Installation
It's as easy as:
$ npm install -g 6to5
## [Features](features.md)
- [Array comprehension](features.md#array-comprehension)
- [Async functions](features.md#async-functions) via [regenerator](https://github.com/facebook/regenerator)
- [Arrow functions](features.md#arrow-functions)
- [Classes](features.md#classes)
- [Computed property names](features.md#computed-property-names)
- [Constants](features.md#constants)
- [Default parameters](features.md#default-parameters)
- [Destructuring](features.md#destructuring)
- [For-of](features.md#for-of)
- [Generators](features.md#generators) via [regenerator](https://github.com/facebook/regenerator)
- [Generator comprehension](features.md#generator-comprehension)
- [Let scoping](features.md#let-scoping)
- [Modules](features.md#modules)
- [Numeric literals](features.md#numeric-literals)
- [Property method assignment](features.md#property-method-assignment)
- [Property name shorthand](features.md#property-name-shorthand)
- [React/JSX](react.md)
- [Rest parameters](features.md#rest-parameters)
- [Spread](features.md#spread)
- [Template literals](features.md#template-literals)
- [Unicode regex](features.md#unicode-regex)

170
doc/modules.md Normal file
View File

@@ -0,0 +1,170 @@
# Modules
## Usage
### CLI
$ 6to5 --modules common script.js
### Node
```javascript
var to5 = require("6to5");
to5.transform('import "foo";', { modules: "common" });
```
## Formats
### Common (Default)
**In**
```javascript
import "foo";
import foo from "foo";
import * as foo from "foo";
import {bar} from "foo";
import {foo as bar} from "foo";
export {test};
export var test = 5;
export default test;
```
**Out**
```javascript
require("foo");
var foo = require("foo").default;
var foo = require("foo");
var bar = require("foo").bar;
var bar = require("foo").foo;
exports.test = test;
var test = 5; exports.test = test;
exports.default = test;
```
### AMD
**In**
```javascript
import foo from "foo";
export function bar() {
return foo("foobar");
}
```
**Out**
```javascript
define(["exports", "foo"], function (exports, _foo) {
exports.bar = bar;
var foo = _foo.default;
function bar() {
return foo("foobar");
}
});
```
### UMD
**In**
```javascript
import foo from "foo";
export function bar() {
return foo("foobar");
}
```
**Out**
```javascript
(function (factory) {
if (typeof define === "function" && define.amd) {
define(["exports", "foo"], factory);
} else if (typeof exports !== "undefined") {
factory(exports, require("foo"));
}
})(function (exports) {
exports.bar = bar;
var foo = _foo.default;
function bar() {
return foo("foobar");
}
});
```
### Ignore
**In**
```javascript
import foo from "foo";
export function bar() {
return foo("foobar");
}
```
**Out**
```javascript
function bar() {
return foo("foobar");
}
```
## Custom
You can alternatively specify module names instead of one of the built-in types.
$ 6to5 --modules custom-module-formatter
**node_modules/custom-module-formatter/index.js**
```javascript
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.import = function (node, nodes) {
// node is an ImportDeclaration
};
ModuleFormatter.prototype.importSpecifier = function (specifier, node, nodes) {
// specifier is an ImportSpecifier
// node is an ImportDeclaration
};
ModuleFormatter.prototype.export = function (node, nodes) {
// node is an ExportDeclaration
};
ModuleFormatter.prototype.exportSpecifier = function (specifier, node, nodes) {
// specifier is an ExportSpecifier
// node is an ExportDeclaration
};
```

51
doc/optional-runtime.md Normal file
View File

@@ -0,0 +1,51 @@
# Optional runtime
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.
Simply use the following option if you're using the [Node API](usage.md#node):
```javascript
{
runtime: true
}
```
or the following flag if you're using the [CLI](usage.md#cli):
$ 6to5 --runtime
Then just include the runtime before your generated code.
## Getting the runtime
You can get the runtime via either:
$ 6to5-runtime
or
```javascript
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:
```javascript
require("6to5").runtime("myCustomNamespace");
```
$ 6to5-runtime myCustomNamespace
See [Options - runtime](usage.md#options) for documentation on changing the
reference in generated code.

15
doc/plugins.md Normal file
View File

@@ -0,0 +1,15 @@
# Plugins
- [Broccoli](https://github.com/very-geek/broccoli-6to5-transpiler)
- [Browserify](https://github.com/6to5/6to5-browserify)
- [Brunch](https://github.com/es128/6to5-brunch)
- [Duo](https://github.com/bdo-labs/duo6to5)
- [Connect](https://github.com/6to5/6to5-connect)
- [Gulp](https://github.com/sindresorhus/gulp-6to5)
- [Grunt](https://github.com/sindresorhus/grunt-6to5)
- [Jade](https://github.com/Apoxx/jade-6to5)
- [Jest](https://github.com/6to5/6to5-jest)
- [Karma](https://github.com/shuhei/karma-6to5-preprocessor)
- [Mocha](https://github.com/6to5/6to5-mocha)
- [Rails](https://github.com/6to5/6to5-rails)
- [webpack](https://github.com/Couto/6to5-loader)

17
doc/polyfill.md Normal file
View File

@@ -0,0 +1,17 @@
# Polyfill
6to5 includes a polyfill that includes the
[regenerator runtime](https://github.com/facebook/regenerator/blob/master/runtime.js) and the
[es6-shim](https://github.com/paulmillr/es6-shim) and
[es6-symbol](https://github.com/medikoo/es6-symbol) polyfills.
## Node
```javascript
require("6to5/polyfill");
```
## Browser
Available from the `browser-polyfill.js` file within the 6to5 directory of an
npm release.

16
doc/react.md Normal file
View File

@@ -0,0 +1,16 @@
# React/JSX
6to5 has built-in support for React v0.12. Tags are automatically transformed to
their equivalent `React.createElement(...)` and `displayName` is automatically
inferred and added to all `React.createClass` calls.
## Blacklist
To disable this behaviour add `react` to your blacklist:
```javascript
to5.transform("code", { blacklist: ["react"] });
```
$ 6to5 --blacklist react

149
doc/usage.md Normal file
View File

@@ -0,0 +1,149 @@
# Usage
## CLI
Compile the file `script.js` and output it to stdout.
$ 6to5 script.js
Compile the file `script.js` and output it to `script-compiled.js`.
$ 6to5 script.js --out-file script-compiled.js
Compile the file `script.js` and output it to `script-compiled.js` and save a
source map to `script-compiled.js.map`.
$ 6to5 script.js --source-maps --out-file script-compiled.js
Compile the file `script.js` and output it to `script-compiled.js` with a source
map embedded in a comment at the bottom.
$ 6to5 script.js --source-maps-inline --out-file script-compiled.js
Compile the entire `src` directory and output it to the `lib` directory.
$ 6to5 src --out-dir lib
Compile the entire `src` directory and output it to the one concatenated file.
$ 6to5 src --out-file script-compiled.js
Pipe a file in via stdin and output it to `script-compiled.js`
$ 6to5 --out-file script-compiled.js < script.js
### Node
Launch a repl.
$ 6to5-node
Evaluate code.
$ 6to5-node -e "class Test { }"
Compile and run `test.js`.
$ 6to5-node test
## Node
```javascript
var to5 = require("6to5");
var result = to5.transform("code();", options);
result.code;
result.map;
result.ast;
to5.transformFileSync("filename.js", options).code;
to5.transformFile("filename.js", options, function (err, result) {
});
```
#### Options
```javascript
{
// Filename for use in errors etc.
// Default: "unknown"
filename: "filename",
// List of transformers to EXCLUDE.
// Run `6to5 --help` to see a full list of transformers.
blacklist: [],
// List of transformers to ONLY use.
// Run `6to5 --help` to see a full list of transformers.
whitelist: [],
// Module formatter to use
// Run `6to5 --help` to see a full list of module formatters.
// Default: "common"
modules: "common",
// 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.
// Default: false
sourceMap: true,
// Set `file` on returned source map.
// Default: `filename` option.
sourceMapName: "filename",
// Set `sources[0]` on returned source map.
// Default: `filename` option.
sourceFileName: "filename",
// Optionally replace all 6to5 helper declarations with a referenece to this
// variable. If set to `true` then the default namespace is used "to5Runtime".
// Default: false
runtime: true
}
```
### Require hook
All subsequent files required by node with the extensions `.es6` and `.js` will
be transformed by 6to5. The polyfill specified in [Polyfill](polyfill.md) is
also required.
```javascript
require("6to5/register");
```
**NOTE:** By default all requires to `node_modules` will be ignored. You can
override this by passing an ignore regex via:
```javascript
require("6to5/register")({
// This will override `node_modules` ignoring - you can alternatively pass
// a regex
ignore: false
});
```
#### 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"]
});
```