From 9d0518b715872385759f71e914f36898e389e11f Mon Sep 17 00:00:00 2001 From: Henry Zhu Date: Tue, 22 Nov 2016 14:17:17 -0500 Subject: [PATCH] Readme updates from babel.github.io [skip ci] (#4884) --- .../README.md | 17 ++++- .../README.md | 22 ++++++ .../README.md | 10 ++- .../README.md | 72 +++++++++++++++++++ .../README.md | 68 ++++++++++++++++++ 5 files changed, 187 insertions(+), 2 deletions(-) diff --git a/packages/babel-plugin-syntax-async-functions/README.md b/packages/babel-plugin-syntax-async-functions/README.md index a2c13f519d..32f1385368 100644 --- a/packages/babel-plugin-syntax-async-functions/README.md +++ b/packages/babel-plugin-syntax-async-functions/README.md @@ -1,6 +1,17 @@ # babel-plugin-syntax-async-functions -Allow parsing of async functions. +This plugin allows Babel to parse async functions. + +## Example + +**Syntax** + +```javascript +(async function() { + await loadStory(); + console.log("Yey, story successfully loaded!"); +}()); +``` ## Installation @@ -33,3 +44,7 @@ require("babel-core").transform("code", { plugins: ["syntax-async-functions"] }); ``` + +## References + +* [Proposal: Async Functions for ECMAScript](https://github.com/tc39/ecmascript-asyncawait) diff --git a/packages/babel-plugin-syntax-async-generators/README.md b/packages/babel-plugin-syntax-async-generators/README.md index 330f8e2079..bbb0d5e910 100644 --- a/packages/babel-plugin-syntax-async-generators/README.md +++ b/packages/babel-plugin-syntax-async-generators/README.md @@ -2,6 +2,24 @@ Allow parsing of async generator functions. +## Example + +**Syntax** + +```javascript +async function* agf() { + await 1; +} +``` + +```js +async function f() { + for await (let x of y) { + g(x); + } +} +``` + ## Installation ```sh @@ -33,3 +51,7 @@ require("babel-core").transform("code", { plugins: ["syntax-async-generators"] }); ``` + +## References + +* [Proposal: Asynchronous iteration for ECMAScript](https://github.com/tc39/proposal-async-iteration) diff --git a/packages/babel-plugin-syntax-class-constructor-call/README.md b/packages/babel-plugin-syntax-class-constructor-call/README.md index 174c8d555d..ecb4ee252f 100644 --- a/packages/babel-plugin-syntax-class-constructor-call/README.md +++ b/packages/babel-plugin-syntax-class-constructor-call/README.md @@ -1,6 +1,8 @@ # babel-plugin-syntax-class-constructor-call (deprecated) -Allow parsing of do expressions. +> Proposal Withdrawn: can be solved with decorators. + +Allow parsing of call constructors. ## Installation @@ -33,3 +35,9 @@ require("babel-core").transform("code", { plugins: ["syntax-class-constructor-call"] }); ``` + +## References + +* [Inactive Proposals](https://github.com/tc39/proposals/blob/master/inactive-proposals.md) +* [Proposal: Call Constructor](https://github.com/tc39/ecma262/blob/master/workingdocs/callconstructor.md) +* [Blog post: ECMAScript proposal: function-callable classes](http://www.2ality.com/2015/10/call-constructor-esprop.html) diff --git a/packages/babel-plugin-transform-async-generator-functions/README.md b/packages/babel-plugin-transform-async-generator-functions/README.md index 33cbd52888..b6c20c4be9 100644 --- a/packages/babel-plugin-transform-async-generator-functions/README.md +++ b/packages/babel-plugin-transform-async-generator-functions/README.md @@ -2,6 +2,74 @@ Turn async generator functions and for-await statements to ES2015 generators +## Example + +**In** + +```javascript +async function* agf() { + await 1; + yield 2; +} +``` + +**Out** + +```javascript +var _asyncGenerator = ... + +let agf = (() => { + var _ref = _asyncGenerator.wrap(function* () { + yield _asyncGenerator.await(1); + yield 2; + }); + + return function agf() { + return _ref.apply(this, arguments); + }; +})(); +``` + +For await example + +```js +async function f() { + for await (let x of y) { + g(x); + } +} +``` + +**Example Usage** + +```js +async function* genAnswers() { + var stream = [ Promise.resolve(4), Promise.resolve(9), Promise.resolve(12) ]; + var total = 0; + for await (let val of stream) { + total += await val; + yield total; + } +} + +function forEach(ai, fn) { + return ai.next().then(function (r) { + if (!r.done) { + fn(r); + return forEach(ai, fn); + } + }); +} + +var output = 0; +forEach(genAnswers(), function(val) { output += val.value }) +.then(function () { + console.log(output); // 42 +}); +``` + +[Try it Out in the REPL](https://babeljs.io/repl/#?babili=false&evaluate=true&lineWrap=false&presets=stage-3&code=async%20function*%20genAnswers()%20%7B%0A%20%20var%20stream%20%3D%20%5B%20Promise.resolve(4)%2C%20Promise.resolve(9)%2C%20Promise.resolve(12)%20%5D%3B%0A%20%20var%20total%20%3D%200%3B%0A%20%20for%20await%20(let%20val%20of%20stream)%20%7B%0A%20%20%20%20total%20%2B%3D%20await%20val%3B%0A%20%20%20%20yield%20total%3B%0A%20%20%7D%0A%7D%0A%0Afunction%20forEach(ai%2C%20fn)%20%7B%0A%20%20return%20ai.next().then(function%20(r)%20%7B%0A%20%20%20%20if%20(!r.done)%20%7B%0A%20%20%20%20%20%20fn(r)%3B%0A%20%20%20%20%20%20return%20forEach(ai%2C%20fn)%3B%0A%20%20%20%20%7D%0A%20%20%7D)%3B%0A%7D%0A%0Avar%20output%20%3D%200%3B%0AforEach(genAnswers()%2C%20function(val)%20%7B%20output%20%2B%3D%20val.value%20%7D)%0A.then(function%20()%20%7B%0A%20%20console.log(output)%3B%20%2F%2F%2042%0A%7D)%3B&experimental=true&loose=false&spec=false&playground=true&stage=0) + ## Installation ```sh @@ -33,3 +101,7 @@ require("babel-core").transform("code", { plugins: ["transform-async-generator-functions"] }); ``` + +## References + +* [Proposal: Asynchronous iteration for ECMAScript](https://github.com/tc39/proposal-async-iteration) diff --git a/packages/babel-plugin-transform-class-constructor-call/README.md b/packages/babel-plugin-transform-class-constructor-call/README.md index b06dab710f..fcadd5a3da 100644 --- a/packages/babel-plugin-transform-class-constructor-call/README.md +++ b/packages/babel-plugin-transform-class-constructor-call/README.md @@ -1,5 +1,67 @@ # babel-plugin-transform-class-constructor-call (deprecated) +> Proposal Withdrawn: can be solved with decorators. + +This plugin allows Babel to transform class constructors. + +It basically allows to use the [new.target](http://mdn.io/new.target) feature on ES2015 classes: + +```js +class Point { + + constructor(x, y) { + this.x = x; + this.y = y; + } + + call constructor(x, y) { + return new Point(x, y); + } + +} + +let p1 = new Point(1, 2); // OK +let p2 = Point(3, 4); // OK +``` +[Try in REPL](/repl/#?evaluate=true&presets=es2015%2Cstage-0&code=class%20Point%20%7B%0A%0A%20%20constructor(x%2C%20y)%20%7B%0A%20%20%20%20this.x%20%3D%20x%3B%0A%20%20%20%20this.y%20%3D%20y%3B%0A%20%20%7D%0A%0A%20%20call%20constructor(x%2C%20y)%20%7B%0A%20%20%20%20return%20new%20Point(x%2C%20y)%3B%0A%20%20%7D%0A%0A%7D%0A%0Alet%20p1%20%3D%20new%20Point(1%2C%202)%3B%20%2F%2F%20OK%0Alet%20p2%20%3D%20Point(3%2C%204)%3B%20%2F%2F%20OK) + +## Example + +### Date example +The javascript [Date](http://mdn.io/date) works this way: + +```js +// You can get a Date instance using the new keyword +let now = new Date(); +console.log(now.getMonth()); // Prints '3' +console.log(now.toString()); // Prints 'Mon Apr 11 2016 13:26:07 GMT+0100 (BST)' + +// You can get a string of the current date using Date as a function: +let nowStr = Date(); +console.log(nowStr); // Prints 'Mon Apr 11 2016 13:26:07 GMT+0100 (BST)' +``` + +It is currently possible to implement something like that using [new.target](http://mdn.io/new.target) (see [example in proposal](https://github.com/tc39/ecma262/blob/master/workingdocs/callconstructor.md#motivating-example)) and this new feature makes it available for ES2015 classes. + +A date implementation could be: + +```js +class Date { + constructor() { + // ... + } + + call constructor() { + let date = new Date(); + return date.toString(); + } +} + +let now = new Date(); // Get a Date instance +let nowStr = Date(); // Use the 'call constructor()' part to get a string value of the current date +``` +[Try in REPL](/repl/#?evaluate=true&presets=es2015%2Cstage-0&code=class%20Date%20%7B%0A%20%20constructor()%20%7B%0A%20%20%20%20%2F%2F%20...%0A%20%20%7D%0A%0A%20%20call%20constructor()%20%7B%0A%20%20%20%20let%20date%20%3D%20new%20Date()%3B%0A%20%20%20%20return%20date.toString()%3B%0A%20%20%7D%0A%7D%0A%0Alet%20now%20%3D%20new%20Date()%3B%20%2F%2F%20Get%20a%20Date%20instance%0Alet%20nowStr%20%3D%20Date()%3B%20%2F%2F%20Use%20the%20'call%20constructor()'%20part%20to%20get%20a%20string%20value%20of%20the%20current%20date) + ## Installation ```sh @@ -31,3 +93,9 @@ require("babel-core").transform("code", { plugins: ["transform-class-constructor-call"] }); ``` + +## References + +* [Inactive Proposals](https://github.com/tc39/proposals/blob/master/inactive-proposals.md) +* [Proposal: Call Constructor](https://github.com/tc39/ecma262/blob/master/workingdocs/callconstructor.md) +* [Blog post: ECMAScript proposal: function-callable classes](http://www.2ality.com/2015/10/call-constructor-esprop.html)