From 46f9ed7d7471e7cbf3bfcfee418d7c39f44d2488 Mon Sep 17 00:00:00 2001 From: James Kyle Date: Mon, 5 Jan 2015 23:27:46 -0800 Subject: [PATCH] Add new documentation --- doc/browser.md | 65 -- doc/caveats.md | 16 +- doc/{differences.md => compare.md} | 20 +- doc/experimental.md | 8 - doc/features.md | 283 ------- doc/index.md | 62 -- doc/playground.md | 140 ---- doc/plugins.md | 33 - doc/polyfill.md | 34 - doc/react.md | 17 - doc/setup.md | 708 ++++++++++++++++ doc/tour.md | 771 ++++++++++++++++++ doc/usage.md | 259 ------ doc/usage/api.md | 59 ++ doc/usage/browser.md | 59 ++ doc/usage/cli.md | 99 +++ doc/usage/experimental.md | 28 + doc/usage/jsx.md | 22 + doc/{ => usage}/modules.md | 167 ++-- doc/usage/options.md | 35 + doc/usage/playground.md | 173 ++++ doc/usage/polyfill.md | 56 ++ doc/usage/require.md | 55 ++ doc/{optional-runtime.md => usage/runtime.md} | 47 +- 24 files changed, 2198 insertions(+), 1018 deletions(-) delete mode 100644 doc/browser.md rename doc/{differences.md => compare.md} (95%) delete mode 100644 doc/experimental.md delete mode 100644 doc/features.md delete mode 100644 doc/index.md delete mode 100644 doc/playground.md delete mode 100644 doc/plugins.md delete mode 100644 doc/polyfill.md delete mode 100644 doc/react.md create mode 100644 doc/setup.md create mode 100644 doc/tour.md delete mode 100644 doc/usage.md create mode 100644 doc/usage/api.md create mode 100644 doc/usage/browser.md create mode 100644 doc/usage/cli.md create mode 100644 doc/usage/experimental.md create mode 100644 doc/usage/jsx.md rename doc/{ => usage}/modules.md (83%) create mode 100644 doc/usage/options.md create mode 100644 doc/usage/playground.md create mode 100644 doc/usage/polyfill.md create mode 100644 doc/usage/require.md rename doc/{optional-runtime.md => usage/runtime.md} (57%) diff --git a/doc/browser.md b/doc/browser.md deleted file mode 100644 index 408ddd77d0..0000000000 --- a/doc/browser.md +++ /dev/null @@ -1,65 +0,0 @@ -# Browser - -A browser version of 6to5 is available from `browser.js` inside the 6to5 -directory in an npm release. - -## 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 - - -``` - -## Build - -You can build a browser version of the compiler by running the following in the -6to5 directory: - -```sh -$ make build -``` - -This will output the files `dist/6to5.js` and `dist/6to5.min.js`. - -## Test - -To test 6to5 in your browser run: - -```sh -$ make test-browser -``` - -And open `test/browser.html` in your browser if it doesn't open automatically. - -## API - -### to5.transform(code, [opts]) - -See [options](usage.md#options) for additional documentation. - -```javascript -to5.transform("class Test {}").code; -``` - -### to5.run(code, [opts]) - -See [options](usage.md#options) for additional documentation. - -```javascript -to5.run("class Test {}"); -``` diff --git a/doc/caveats.md b/doc/caveats.md index 4e953bd9d1..9c56bd744f 100644 --- a/doc/caveats.md +++ b/doc/caveats.md @@ -1,4 +1,12 @@ -# Caveats +--- +layout: docs +title: Caveats +description: Just some things to keep in mind when using 6to5. +permalink: /docs/caveats/ +redirect_from: /caveats.html +--- + +## Polyfills In order for certain features to work they require certain polyfills. You can satisfy **all** 6to5 feature requirements by using the included @@ -35,10 +43,10 @@ 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 in IE <= 10 so static properties +**NOTE:** `__proto__` is not supported on IE <= 10 so static properties **will not** be inherited. A possible workaround is to use `super();`: -```javascript +```js class Foo { static foo() { @@ -52,7 +60,7 @@ class Bar extends Foo { } ``` -## Getters/setters (8 and below) +### Getters/setters (8 and below) In IE8 `Object.defineProperty` can only be used on DOM objects. This is unfortunate as it's required to set getters and setters. Due to this if diff --git a/doc/differences.md b/doc/compare.md similarity index 95% rename from doc/differences.md rename to doc/compare.md index e90b2ea907..a04e9b9f55 100644 --- a/doc/differences.md +++ b/doc/compare.md @@ -1,6 +1,12 @@ -# Differences +--- +layout: docs +title: Compare +description: Differences between 6to5 and other ES6 transpilers. +permalink: /docs/compare/ +redirect_from: /differences.html +--- -There are three main points that separate 6to5 from all other transpilers. +## Differences ### Readable code @@ -12,13 +18,13 @@ is concerned with making sure it works **and** is readable at the same time. For example, given the following array comprehension: -```javascript +```js var seattlers = [for (c of customers) if (c.city == "Seattle") { name: c.name, age: c.age }]; ``` is generated to the following with 6to5: -```javascript +```js var seattlers = Array.from(customers).filter(function (c) { return c.city == "Seattle"; }).map(function (c) { @@ -31,7 +37,7 @@ var seattlers = Array.from(customers).filter(function (c) { The following is what Traceur generates: -```javascript +```js var seattlers = (function() { var c; var $__20 = 0, @@ -49,8 +55,8 @@ var seattlers = (function() { }()); ``` -As you can tell, it's not very pretty. Instead of mapping directly to a -runtime, like other transpilers, 6to5 maps directly to the equivalent ES5. +As you can tell, it's not very pretty. Instead of mapping directly to a runtime, +like other transpilers, 6to5 maps directly to the equivalent ES5. Sometimes there are little inline functions that 6to5 needs. These are placed at the top of your file much like coffee-script does. If these diff --git a/doc/experimental.md b/doc/experimental.md deleted file mode 100644 index 3546d0cb82..0000000000 --- a/doc/experimental.md +++ /dev/null @@ -1,8 +0,0 @@ -## Experimental - -6to5 also has experimental support for ES7 proposals. You can enable this with -the `experimental: true` option when using the [Node API](#node) or -`--experimental` when using the [CLI](#cli). - -**WARNING:** These proposals are subject to change so use with -**extreme caution**. diff --git a/doc/features.md b/doc/features.md deleted file mode 100644 index a5c55fda81..0000000000 --- a/doc/features.md +++ /dev/null @@ -1,283 +0,0 @@ -# Features - -## Abstract references ([experimental](experimental.md)) ([spec](https://github.com/zenparsing/es-abstract-refs)) - -```javascript -foo::bar; -foo::bar = baz; -delete foo::bar; -``` - -## Array comprehensions ([experimental](experimental.md)) - -```javascript -var results = [for (c of customers) if (c.city == "Seattle") { name: c.name, age: c.age }] -``` - -## Arrow functions - -```javascript -// Expression bodies -var odds = evens.map(v => v + 1); -var nums = evens.map((v, i) => v + i); - -// Statement bodies -nums.forEach(v => { - if (v % 5 === 0) - fives.push(v); -}); - -// Lexical this -var bob = { - _name: "Bob", - _friends: [], - printFriends() { - this._friends.forEach(f => { - console.log(this._name + " knows " + f); - }); - } -}; -``` - -## Async functions ([experimental](experimental.md)) ([spec](https://github.com/lukehoban/ecmascript-asyncawait)) - -```javascript -async function chainAnimationsAsync(elem, animations) { - for (var anim of animations) { - await anim(elem); - } -} -``` - -## Async generator functions ([experimental](experimental.md)) ([spec](https://github.com/jhusain/asyncgenerator)) - -```javascript - -``` - -## Classes - -```javascript -class SkinnedMesh extends THREE.Mesh { - constructor(geometry, materials) { - super(geometry, materials); - - this.idMatrix = SkinnedMesh.defaultMatrix(); - this.bones = []; - this.boneMatrices = []; - //... - } - - update(camera) { - //... - super.update(); - } - - static defaultMatrix() { - return new THREE.Matrix4(); - } -} -``` - -## 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 f(x, y = 12) { - // y is 12 if not passed (or passed as undefined) - return x + y; -} -f(3) == 15 -``` - -## Destructuring - -```javascript -// list matching -var [a, , b] = [1,2,3]; - -// object matching -var { op: a, lhs: { op: b }, rhs: c } = getASTNode(); - -// object matching shorthand -// binds `op`, `lhs` and `rhs` in scope -var { op, lhs, rhs } = getASTNode(); - -// Can be used in parameter position -function g({ name: x }) { - console.log(x); -} -g({ name: 5 }); - -// Fail-soft destructuring -var [a] = []; -a === undefined; -``` - -## Exponentiation operator ([experimental](experimental.md)) ([spec](https://github.com/rwaldron/exponentiation-operator)) - -```javascript -var a = 2; -a **= 2; - -var squared = 2 ** 2; -``` - -## For-of - -```javascript -for (var i of [1, 2, 3]) { - console.log(i * i); -} -``` - -## Generators - -```javascript -function* fibonacci() { - var pre = 0, cur = 1; - for (;;) { - var temp = pre; - pre = cur; - cur += temp; - yield cur; - } -} - -for (var n of fibonacci()) { - // truncate the sequence at 1000 - if (n > 1000) break; - console.log(n); -} -``` - -## Generator comprehensions ([experimental](experimental.md)) - -```javascript -var nums = [1, 2, 3, 4, 5, 6]; -var multiples = (for (i of nums) if (i % 2) i * i); -assert.equal(multiples.next().value, 1); -assert.equal(multiples.next().value, 9); -assert.equal(multiples.next().value, 25); -``` - -## Let scoping - -```javascript -for (let i in arr) { - let v = arr[i]; -} -``` - -## Modules - -```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 function test() {} - -export default test; -``` - -## Numeric literals - -```javascript -0b111110111 === 503; // true -0o767 === 503; // true -``` - -## Object spread/rest ([experimental](experimental.md)) ([spec](https://github.com/sebmarkbage/ecmascript-rest-spread)) - -```javascript -var n = { x, y, ...z }; -var { x, y, ...z } = { x: 1, y: 2, a: 3, b: 4 }; -``` - -## 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 f(x, ...y) { - // y is an Array - return x * y.length; -} -f(3, "hello", true) == 6 -``` - -## Spread - -```javascript -function f(x, y, z) { - return x + y + z; -} -// Pass each elem of array as argument -f(...[1,2,3]) == 6 -``` - -## 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]); -``` diff --git a/doc/index.md b/doc/index.md deleted file mode 100644 index d37e7d8eaf..0000000000 --- a/doc/index.md +++ /dev/null @@ -1,62 +0,0 @@ -**6to5** turns ES6+ code into vanilla ES5, so you can use next generation 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). - -## Installation - -It's as easy as: - - $ npm install -g 6to5 - -## Usage - -Once you've installed 6to5, there are multiple paths you can take depending on -how you want to use it. - -6to5 will simply compile your ES6+ script to ES5 if you pass it as an argument -to the command-line tool `6to5`: - -```sh -$ 6to5 script.js -``` - -If you have a file written using ES6+ and you just want to run it, `6to5-node` -has you covered: - -```sh -$ 6to5-node script.js -``` - -And it doesn't end here! To see all the ways you can use 6to5, check out the -[Usage](http://6to5.github.io/usage.html) page. - -## [Features](features.md) - - - [Abstract references](features.md#abstract-references) ([experimental](experimental.md)) - - [Array comprehension](features.md#array-comprehension) ([experimental](experimental.md)) - - [Async functions](features.md#async-functions) ([experimental](experimental.md)) - - [Async generator functions](features.md#async-generator-functions) ([experimental](experimental.md)) - - [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) - - [Exponentiation operator](features.md#exponentiation-operator) ([experimental](experimental.md)) - - [For-of](features.md#for-of) - - [Generators](features.md#generators) - - [Generator comprehension](features.md#generator-comprehension) ([experimental](experimental.md)) - - [Let scoping](features.md#let-scoping) - - [Modules](features.md#modules) - - [Numeric literals](features.md#numeric-literals) - - [Object rest/spread](features.md#object-rest-spread) ([experimental](experimental.md)) - - [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) diff --git a/doc/playground.md b/doc/playground.md deleted file mode 100644 index 985bc5409d..0000000000 --- a/doc/playground.md +++ /dev/null @@ -1,140 +0,0 @@ -# Playground - -Playground is a proving ground for **possible** ES7 proposals. - -**NOTE: These features are in no way endorsed by Ecma International and are not a part of ES6. They might become a part of ECMAScript in the future.** - -## Usage - - $ 6to5 --playground - -```javascript -to5.transform("code", { playground: true }); -``` - -**NOTE:** Enabling `playground` also enables [experimental support](experimental.md). - -## Features - - * [Memoization operator](#memoization-operator) - * [Method binding](#method-binding) - * [Method binding function shorthand](#method-binding-function-shorthand) - * [Object getter memoization](#object-getter-memoization) - * [This shorthand](#this-shorthand) - -### 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. - -```javascript -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 -``` - -```javascript -var obj = {}; -obj.x ?= 2; -``` - -equivalent to - -```javascript -var obj = {}; -if (!Object.prototype.hasOwnProperty.call(obj, "x")) obj.x = 2; -``` - -### Method binding - -```javascript -var fn = obj#method; -var fn = obj#method("foob"); -``` - -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 - -```javascript -var foo = { - memo bar() { - return complex(); - } -}; - -class Foo { - memo bar() { - return complex(); - } -} -``` - -equivalent to - -```javascript -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 - -```javascript -@foo -``` - -equivalent to - -```javascirpt -this.foo -``` diff --git a/doc/plugins.md b/doc/plugins.md deleted file mode 100644 index 3785d31575..0000000000 --- a/doc/plugins.md +++ /dev/null @@ -1,33 +0,0 @@ -# Plugins - -## Build systems - - - [Broccoli](https://github.com/6to5/broccoli-6to5-transpiler) - - [Browserify](https://github.com/6to5/6to5ify) - - [Brunch](https://github.com/6to5/6to5-brunch) - - [Duo](https://github.com/6to5/duo6to5) - - [Gobble](https://github.com/6to5/gobble-6to5) - - [Gulp](https://github.com/6to5/gulp-6to5) - - [Grunt](https://github.com/6to5/grunt-6to5) - - [Sprockets](https://github.com/josh/sprockets-es6) or via [Browserify](https://github.com/6to5/6to5-rails) - - [webpack](https://github.com/6to5/6to5-loader) - -## Integrations - - - [Isparta](https://github.com/douglasduteil/isparta) - Code coverage with `karma` and `instanbul` using 6to5 - - [JSXHint](https://github.com/STRML/JSXHint) - A wrapper around JSHint to allow linting of JSX files - -## Bridges - - - [Ruby](https://github.com/6to5/6to5-ruby) - -## Testing - - - [Jest](https://github.com/6to5/6to5-jest) - - [Karma](https://github.com/6to5/karma-6to5-preprocessor) - - [Mocha](https://github.com/6to5/6to5-mocha) - -## Misc - - - [Connect](https://github.com/6to5/6to5-connect) - - [Jade](https://github.com/6to5/jade-6to5) diff --git a/doc/polyfill.md b/doc/polyfill.md deleted file mode 100644 index a97e334fb7..0000000000 --- a/doc/polyfill.md +++ /dev/null @@ -1,34 +0,0 @@ -# Polyfill - -6to5 includes a polyfill that includes a custom -[regenerator runtime](https://github.com/facebook/regenerator/blob/master/runtime.js) and -[core.js](https://github.com/zloirock/core-js). - -This will emulate a full ES6 environment. This polyfill is automatically loaded -when using [6to5-node](usage.md#node) and [6to5/register](usage.md#register-hook). - -## Usage - -### Node/Browserify - -You need to include the polyfill require at the top the **entry point** to your -application. - -```javascript -require("6to5/polyfill"); -``` - -Fortunately, this is automatically loaded when using: - -```javascript -require("6to5/register"); -``` - -### 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 ` + +``` + +## 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 {}'); +```` diff --git a/doc/usage/cli.md b/doc/usage/cli.md new file mode 100644 index 0000000000..6e71a7c145 --- /dev/null +++ b/doc/usage/cli.md @@ -0,0 +1,99 @@ +--- +layout: docs +title: CLI +description: How to use the CLI tools. +permalink: /docs/usage/cli/ +redirect_from: /usage.html +--- + +

+ 6to5 comes with a built-in CLI which can be used to compile files from the + command line. +

+ +## 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 +``` diff --git a/doc/usage/experimental.md b/doc/usage/experimental.md new file mode 100644 index 0000000000..4386404504 --- /dev/null +++ b/doc/usage/experimental.md @@ -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. + +
+

Subject to change

+

+ These proposals are subject to change so use with extreme + caution. 6to5 may update without warning in order to track spec + changes. Please do not use them in production applications. +

+
+ +#### Usage + +```js +$ 6to5 --experimental +``` + +```js +to5.transform('code', { experimental: true }); +``` diff --git a/doc/usage/jsx.md b/doc/usage/jsx.md new file mode 100644 index 0000000000..3a4283cabd --- /dev/null +++ b/doc/usage/jsx.md @@ -0,0 +1,22 @@ +--- +layout: docs +title: JSX +description: How to use JSX. +permalink: /docs/usage/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: + +````js +to5.transform("code", { blacklist: ["react"] }); +$ 6to5 --blacklist react +``` diff --git a/doc/modules.md b/doc/usage/modules.md similarity index 83% rename from doc/modules.md rename to doc/usage/modules.md index f58c68416f..7ebbcadb0b 100644 --- a/doc/modules.md +++ b/doc/usage/modules.md @@ -1,37 +1,39 @@ -# Modules +--- +layout: docs +title: Modules +description: How to use module formatters. +permalink: /docs/usage/modules/ +redirect_from: /modules.html +--- + +

+ 6to5 has the ability to transpile ES6 modules to the module system of your + choice. You can even easily create your own. +

## Usage -### CLI - ```sh $ 6to5 --modules common script.js ``` -### Node - -```javascript -var to5 = require("6to5"); +```js to5.transform('import "foo";', { modules: "common" }); ``` ## Formats - * [AMD](#amd) - * [Common (Default)](#common-default) - * [Ignore](#ignore) - * [System](#system) - * [UMD](#umd) +### Common (Default) -### Common +**Usage** ```sh $ 6to5 --modules common ``` -**In** +**Example** -```javascript +```js export default test; export {test}; @@ -46,9 +48,7 @@ import {bar} from "foo"; import {foo as bar} from "foo"; ``` -**Out** - -```javascript +```js "use strict"; var _interopRequire = function (obj) { @@ -72,13 +72,15 @@ var bar = require("foo").foo; ### AMD +**Usage** + ```sh $ 6to5 --modules amd ``` -**In** +**Example** -```javascript +```js import foo from "foo"; export function bar() { @@ -86,9 +88,7 @@ export function bar() { } ``` -**Out** - -```javascript +```js define(["exports", "foo"], function (exports, _foo) { "use strict"; @@ -105,21 +105,24 @@ define(["exports", "foo"], function (exports, _foo) { }); ``` -You can optionally specify to include the module id (using the `--amd-module-id` argument): +You can optionally specify to include the module id (using the `--amd-module-id` +argument): -```javascript +```js define("filename", ["exports", "foo"], function (exports, _foo) {}) ``` -### UMD +### System + +**Usage** ```sh -$ 6to5 --modules umd +$ 6to5 --modules system ``` -**In** +**Example** -```javascript +```js import foo from "foo"; export function bar() { @@ -127,9 +130,46 @@ export function bar() { } ``` -**Out** +```js +System.register("bar", ["foo"], function (_export) { + "use strict"; -```javascript + 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); @@ -154,13 +194,15 @@ export function bar() { ### Ignore +**Usage** + ```sh $ 6to5 --modules ignore ``` -**In** +**Example** -```javascript +```js import foo from "foo"; export function bar() { @@ -168,69 +210,30 @@ export function bar() { } ``` -**Out** - -```javascript +```js function bar() { return foo("foobar"); } ``` -### System - -```sh -$ 6to5 --modules system -``` - -**In** - -```javascript -import foo from "foo"; - -export function bar() { - return foo("foobar"); -} -``` - -**Out** - -```javascript -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); - } - }; -}); -``` - -## Custom +### Custom You can alternatively specify module names instead of one of the built-in types. -```sh +**Usage** + +```js $ 6to5 --modules custom-module-formatter ``` -**node_modules/custom-module-formatter/index.js** +**Example** -```javascript +**`node_modules/custom-module-formatter/index.js`** + +```js module.exports = ModuleFormatter; -function ModuleFormatter() { - -} +function ModuleFormatter() {} ModuleFormatter.prototype.transform = function (ast) { // this is ran after all transformers have had their turn at modifying the ast diff --git a/doc/usage/options.md b/doc/usage/options.md new file mode 100644 index 0000000000..398381c2a0 --- /dev/null +++ b/doc/usage/options.md @@ -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. | diff --git a/doc/usage/playground.md b/doc/usage/playground.md new file mode 100644 index 0000000000..3e7fb582bf --- /dev/null +++ b/doc/usage/playground.md @@ -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. + +
+

Unofficial

+

+ 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. Use with extreme caution. +

+
+ +
+

Proposal Authors

+

+ If you are actively working on an + ECMAScript proposal, 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. +

+

+ Please feel free to open + an issue on the 6to5 repository with your WIP spec, and we can discuss + getting it implemented. Be sure to include as much information as possible. +

+
+ +## Usage + +```js +$ 6to5 --playground +``` + +```js +to5.transform('code', { playground: true }); +``` + +
+

Enables experimental

+

+ Enabling playground also enables experimental support. +

+
+ +## 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 +``` diff --git a/doc/usage/polyfill.md b/doc/usage/polyfill.md new file mode 100644 index 0000000000..137cde5fa2 --- /dev/null +++ b/doc/usage/polyfill.md @@ -0,0 +1,56 @@ +--- +layout: docs +title: Polyfill +description: How to use the Polyfill. +permalink: /docs/usage/polyfill/ +--- + +

+ 6to5 includes a polyfill that includes a custom + regenerator runtime + and core.js. +

+ +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 `