kotovalexarian-likes-github/jashkenas--coffeescript
1
0
Fork 0
mirror of https://github.com/jashkenas/coffeescript.git synced 2022-11-09 12:23:24 -05:00
Code Releases Activity

Update transpilation docs (#4700)

Browse source
This commit is contained in:
Geoffrey Booth 2017-09-16 09:32:48 -07:00 committed by GitHub
parent f51c1a150b
commit 659f1b3c4c
10 changed files with 73 additions and 47 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
docs/v2/index.html
View file

@ -527,7 +527,11 @@ div.CodeMirror-cursor {
<a href="#try" class="nav-link d-md-none" data-action="sidebar-nav" data-toggle="try">Try CoffeeScript</a>
<a href="#top" class="nav-link" data-action="sidebar-nav">Overview</a>
<a href="#coffeescript-2" class="nav-link" data-action="sidebar-nav">CoffeeScript 2</a>
<a href="#compatibility" class="nav-link" data-action="sidebar-nav">Compatibility</a>
<nav class="nav flex-column">
<a href="#whats-new-in-coffeescript-2" class="nav-link" data-action="sidebar-nav">What’s New in CoffeeScript 2</a>
<a href="#why-coffeescript" class="nav-link" data-action="sidebar-nav">Why CoffeeScript When There’s ES6?</a>
<a href="#compatibility" class="nav-link" data-action="sidebar-nav">Compatibility</a>
</nav>
<a href="#installation" class="nav-link" data-action="sidebar-nav">Installation</a>
<a href="#usage" class="nav-link" data-action="sidebar-nav">Usage</a>
<nav class="nav flex-column">
@ -802,19 +806,25 @@ cubes = (function() {
</section>
<section id="coffeescript-2">
<h2>CoffeeScript 2</h2>
<h3>What’s New In CoffeeScript 2?</h3>
<section id="whats-new-in-coffeescript-2">
<h3>What’s New In CoffeeScript 2?</h3>
<p>The biggest change in CoffeeScript 2 is that now the CoffeeScript compiler produces modern JavaScript syntax (ES6, or ES2015 and later). A CoffeeScript <code>=&gt;</code> becomes a JS <code>=&gt;</code>, a CoffeeScript <code>class</code> becomes a JS <code>class</code> and so on. Major new features in CoffeeScript 2 include <a href="#async-functions">async functions</a> and <a href="#jsx">JSX</a>. You can read more in the <a href="#changelog">changelog</a>.</p>
<p>There are very few <a href="#breaking-changes">breaking changes from CoffeeScript 1.x to 2</a>; we hope the upgrade process is smooth for most projects.</p>
<h3>Why CoffeeScript When There’s ES6?</h3>
</section>
<section id="why-coffeescript">
<h3>Why CoffeeScript When There’s ES6?</h3>
<p>CoffeeScript introduced many new features to the JavaScript world, such as <a href="#fat-arrow"><code>=&gt;</code></a> and <a href="#destructuring">destructuring</a> and <a href="#classes">classes</a>. We are happy that ECMA has seen their utility and adopted them into ECMAScript.</p>
<p>CoffeeScript’s intent, however, was never to be a superset of JavaScript. One of the guiding principles of CoffeeScript has been <em>simplicity:</em> not just removing JavaScript’s “bad parts,” but providing an elegant, concise syntax that eschews unnecessary punctuation whenever possible, to make code easier to read and reason about. This benefit of CoffeeScript remains, even in an ES2015+ world.</p>
</section>
<section id="compatibility">
<h2>Compatibility</h2>
<p>With the exception of <a href="#modules">modules</a> (<code>import</code> and <code>export</code> statements) and <a href="#jsx">JSX</a>, all the modern JavaScript features that CoffeeScript supports can run natively in Node 7.6+, meaning that Node can run CoffeeScript’s output without any further processing required. You can <a href="http://coffeescript.org/v2/test.html">run the tests in your browser</a> to see if your browser can do the same. For older browsers or older versions of Node, <a href="#transpilation">transpilation</a> is required.</p>
</section>
<section id="compatibility">
<h3>Compatibility</h3>
<p>With the exception of <a href="#modules">modules</a> (<code>import</code> and <code>export</code> statements) and <a href="#jsx">JSX</a>, all the modern JavaScript features that CoffeeScript supports can run natively in Node 7.6+, meaning that Node can run CoffeeScript’s output without any further processing required. You can <a href="http://coffeescript.org/v2/test.html">run the tests in your browser</a> to see if your browser can do the same. For older browsers or older versions of Node, however, <a href="#transpilation">transpilation</a> is required.</p>
<p>Support for modern JavaScript syntax is important to ensure compatibility with frameworks that assume modern features. Now that CoffeeScript compiles classes to the <code>class</code> keyword, it’s possible to <code>extend</code> a JavaScript class; that wasn’t possible in CoffeeScript 1. Parity in how language features work is also important on its own; CoffeeScript “is just JavaScript,” and so things like <a href="#breaking-changes-default-values">function parameter default values</a> should behave the same in CoffeeScript as in JavaScript. Some such features behave slightly differently in JavaScript than they did in CoffeeScript 1; in such cases we are conforming with the JavaScript spec, and we’ve documented the differences as <a href="#breaking-changes">breaking changes</a>.</p>
</section>
</section>
<section id="installation">
<h2>Installation</h2>
@ -956,7 +966,14 @@ eval CoffeeScript.compile <span class="string">'console.log "Mmmmm, I could real
</section>
<section id="transpilation">
<h3>Transpilation</h3>
<p>CoffeeScript 2 generates JavaScript that uses the latest, modern syntax (a.k.a. ES6, or ES2015, or ES2016 or ES2017 etc.). In general, <a href="http://node.green/">CoffeeScript 2’s output is supported as is by Node.js 7.6+</a>, except for <a href="#modules">modules</a> and <a href="#jsx">JSX</a>. Evergreen browsers such as the latest versions of Chrome and Safari have similar robust support. But if you want to support older browsers, or if you want to use modules or JSX, you must transpile CoffeeScript’s output.</p>
<p>CoffeeScript 2 generates JavaScript that uses the latest, modern syntax. Your runtime <a href="#compatibility">might not support all of that syntax</a>. If so, you need to <em>transpile</em> the JavaScript. To make things a little easier, CoffeeScript has built-in support for the popular <a href="http://babeljs.io/">Babel</a> transpiler.</p>
<h4>Quickstart</h4>
<p>From the root of your project:</p>
<blockquote class="uneditable-code-block"><pre><code class="language-bash">npm install --save-dev babel-core babel-preset-env
<span class="built_in">echo</span> <span class="string">'{ "presets": ["env"] }'</span> &gt; .babelrc
coffee --compile --transpile --inline-map some-file.coffee
</code></pre>
</blockquote><h4>About Transpilation</h4>
<p>Transpilation is the conversion of source code into equivalent but different source code. In our case, we want to convert modern JavaScript into older JavaScript that will run in older versions of Node or older browsers; for example, <code>{ a } = obj</code> into <code>a = obj.a</code>. This is done via transpilers like <a href="http://babeljs.io/">Babel</a>, <a href="https://buble.surge.sh/">Bublé</a> or <a href="https://github.com/google/traceur-compiler">Traceur Compiler</a>.</p>
<p>CoffeeScript includes a <code>--transpile</code> option when used via the <code>coffee</code> command, or a <code>transpile</code> option when used via Node. To use either, <a href="http://babeljs.io/">Babel</a> must be installed in your project:</p>
<blockquote class="uneditable-code-block"><pre><code class="language-bash">npm install --save-dev babel-core
@ -967,12 +984,8 @@ eval CoffeeScript.compile <span class="string">'console.log "Mmmmm, I could real
</code></pre>
</blockquote><p>See <a href="https://babeljs.io/docs/plugins/">Babel’s website to learn about presets and plugins</a> and the multitude of options you have.</p>
<p>Simply installing <code>babel-preset-env</code> isn’t enough. You also need to define the configuration options that you want Babel to use. You can do this by creating a <a href="https://babeljs.io/docs/usage/babelrc/"><code>.babelrc</code> file</a> in the folder containing the files you’re compiling, or in any parent folder up the path above those files. So if your project is in <code>~/app</code> and your files are in <code>~/app/src</code>, you can put <code>.babelrc</code> in either <code>~/app</code> or in <code>~/app/src</code>. You can also define the Babel options via a <code>babel</code> key in the <code>package.json</code> file for your project. A minimal <code>.babelrc</code> file (or <code>package.json</code> <code>babel</code> key) for use with <code>babel-preset-env</code> would be just <code>{ &quot;presets&quot;: [&quot;env&quot;] }</code>.</p>
<p>So to put it all together, from the root of your project:</p>
<blockquote class="uneditable-code-block"><pre><code class="language-bash">npm install --save-dev babel-core babel-preset-env
<span class="built_in">echo</span> <span class="string">'{ "presets": ["env"] }'</span> &gt; .babelrc
</code></pre>
</blockquote><p>And then you can use <code>coffee --transpile</code> and it will pipe CoffeeScript’s output through Babel using the options in this <code>.babelrc</code> file.</p>
<p>If you’re using CoffeeScript via the <a href="nodejs_usage">Node API</a>, where you call <code>CoffeeScript.compile</code> with a string to be compiled and an options object, the <code>transpile</code> key of the <code>options</code> object should be the Babel options:</p>
<p>Once you have <code>babel-core</code> and <code>babel-preset-env</code> (or other presets or plugins) installed, and a <code>.babelrc</code> file (or <code>package.json</code> <code>babel</code> key) in place, you can use <code>coffee --transpile</code> to pipe CoffeeScript’s output through Babel using the options you’ve saved.</p>
<p>If you’re using CoffeeScript via the <a href="nodejs_usage">Node API</a>, where you call <code>CoffeeScript.compile</code> with a string to be compiled and an <code>options</code> object, the <code>transpile</code> key of the <code>options</code> object should be the Babel options:</p>
<blockquote class="uneditable-code-block"><pre><code class="language-js">CoffeeScript.compile(code, {<span class="attr">transpile</span>: {<span class="attr">presets</span>: [<span class="string">'env'</span>]}})
</code></pre>
</blockquote><p>You can also transpile CoffeeScript’s output without using the <code>transpile</code> option, for example as part of a build chain. This lets you use transpilers other than Babel, and it gives you greater control over the process. There are many great task runners for setting up JavaScript build chains, such as <a href="http://gulpjs.com/">Gulp</a>, <a href="https://webpack.github.io/">Webpack</a>, <a href="https://gruntjs.com/">Grunt</a> and <a href="http://broccolijs.com/">Broccoli</a>.</p>

12
documentation/sections/coffeescript_2.md
View file

@ -1,13 +1 @@
## CoffeeScript 2
### What’s New In CoffeeScript 2?
The biggest change in CoffeeScript 2 is that now the CoffeeScript compiler produces modern JavaScript syntax (ES6, or ES2015 and later). A CoffeeScript `=>` becomes a JS `=>`, a CoffeeScript `class` becomes a JS `class` and so on. Major new features in CoffeeScript 2 include [async functions](#async-functions) and [JSX](#jsx). You can read more in the [changelog](#changelog).
There are very few [breaking changes from CoffeeScript 1.x to 2](#breaking-changes); we hope the upgrade process is smooth for most projects.
### Why CoffeeScript When There’s ES6?
CoffeeScript introduced many new features to the JavaScript world, such as [`=>`](#fat-arrow) and [destructuring](#destructuring) and [classes](#classes). We are happy that ECMA has seen their utility and adopted them into ECMAScript.
CoffeeScript’s intent, however, was never to be a superset of JavaScript. One of the guiding principles of CoffeeScript has been _simplicity:_ not just removing JavaScript’s “bad parts,” but providing an elegant, concise syntax that eschews unnecessary punctuation whenever possible, to make code easier to read and reason about. This benefit of CoffeeScript remains, even in an ES2015+ world.

6
documentation/sections/compatibility.md
View file

@ -1,5 +1,5 @@
## Compatibility
### Compatibility
With the exception of [modules](#modules) (`import` and `export` statements) and [JSX](#jsx), all the modern JavaScript features that CoffeeScript supports can run natively in Node 7.6+, meaning that Node can run CoffeeScript’s output without any further processing required. You can [run the tests in your browser](http://coffeescript.org/v<%= majorVersion %>/test.html) to see if your browser can do the same. For older browsers or older versions of Node, [transpilation](#transpilation) is required.
With the exception of [modules](#modules) (`import` and `export` statements) and [JSX](#jsx), all the modern JavaScript features that CoffeeScript supports can run natively in Node 7.6+, meaning that Node can run CoffeeScript’s output without any further processing required. You can [run the tests in your browser](http://coffeescript.org/v<%= majorVersion %>/test.html) to see if your browser can do the same. For older browsers or older versions of Node, however, [transpilation](#transpilation) is required.
Support for modern JavaScript syntax is important to ensure compatibility with frameworks that assume modern features. Now that CoffeeScript compiles classes to the `class` keyword, it’s possible to `extend` a JavaScript class; that wasn’t possible in CoffeeScript 1. Parity in how language features work is also important on its own; CoffeeScript “is just JavaScript,” and so things like [function parameter default values](#breaking-changes-default-values) should behave the same in CoffeeScript as in JavaScript. Some such features behave slightly differently in JavaScript than they did in CoffeeScript 1; in such cases we are conforming with the JavaScript spec, and we’ve documented the differences as [breaking changes](#breaking-changes).
Support for modern JavaScript syntax is important to ensure compatibility with frameworks that assume modern features. Now that CoffeeScript compiles classes to the `class` keyword, it’s possible to `extend` a JavaScript class; that wasn’t possible in CoffeeScript 1. Parity in how language features work is also important on its own; CoffeeScript “is just JavaScript,” and so things like [function parameter default values](#breaking-changes-default-values) should behave the same in CoffeeScript as in JavaScript. Some such features behave slightly differently in JavaScript than they did in CoffeeScript 1; in such cases we are conforming with the JavaScript spec, and we’ve documented the differences as [breaking changes](#breaking-changes).

25
documentation/sections/transpilation.md
View file

@ -1,6 +1,18 @@
### Transpilation
CoffeeScript 2 generates JavaScript that uses the latest, modern syntax (a.k.a. ES6, or ES2015, or ES2016 or ES2017 etc.). In general, [CoffeeScript 2’s output is supported as is by Node.js 7.6+](http://node.green/), except for [modules](#modules) and [JSX](#jsx). Evergreen browsers such as the latest versions of Chrome and Safari have similar robust support. But if you want to support older browsers, or if you want to use modules or JSX, you must transpile CoffeeScript’s output.
CoffeeScript 2 generates JavaScript that uses the latest, modern syntax. Your runtime [might not support all of that syntax](#compatibility). If so, you need to _transpile_ the JavaScript. To make things a little easier, CoffeeScript has built-in support for the popular [Babel](http://babeljs.io/) transpiler.
#### Quickstart
From the root of your project:
```bash
npm install --save-dev babel-core babel-preset-env
echo '{ "presets": ["env"] }' > .babelrc
coffee --compile --transpile --inline-map some-file.coffee
```
#### About Transpilation
Transpilation is the conversion of source code into equivalent but different source code. In our case, we want to convert modern JavaScript into older JavaScript that will run in older versions of Node or older browsers; for example, `{ a } = obj` into `a = obj.a`. This is done via transpilers like [Babel](http://babeljs.io/), [Bublé](https://buble.surge.sh/) or [Traceur Compiler](https://github.com/google/traceur-compiler).
@ -22,16 +34,9 @@ See [Babel’s website to learn about presets and plugins](https://babeljs.io/do
Simply installing `babel-preset-env` isn’t enough. You also need to define the configuration options that you want Babel to use. You can do this by creating a [`.babelrc` file](https://babeljs.io/docs/usage/babelrc/) in the folder containing the files you’re compiling, or in any parent folder up the path above those files. So if your project is in `~/app` and your files are in `~/app/src`, you can put `.babelrc` in either `~/app` or in `~/app/src`. You can also define the Babel options via a `babel` key in the `package.json` file for your project. A minimal `.babelrc` file (or `package.json` `babel` key) for use with `babel-preset-env` would be just `{ "presets": ["env"] }`.
So to put it all together, from the root of your project:
Once you have `babel-core` and `babel-preset-env` (or other presets or plugins) installed, and a `.babelrc` file (or `package.json` `babel` key) in place, you can use `coffee --transpile` to pipe CoffeeScript’s output through Babel using the options you’ve saved.
```bash
npm install --save-dev babel-core babel-preset-env
echo '{ "presets": ["env"] }' > .babelrc
```
And then you can use `coffee --transpile` and it will pipe CoffeeScript’s output through Babel using the options in this `.babelrc` file.
If you’re using CoffeeScript via the [Node API](nodejs_usage), where you call `CoffeeScript.compile` with a string to be compiled and an options object, the `transpile` key of the `options` object should be the Babel options:
If you’re using CoffeeScript via the [Node API](nodejs_usage), where you call `CoffeeScript.compile` with a string to be compiled and an `options` object, the `transpile` key of the `options` object should be the Babel options:
```js
CoffeeScript.compile(code, {transpile: {presets: ['env']}})

5
documentation/sections/whats_new_in_coffeescript_2.md Normal file
View file

@ -0,0 +1,5 @@
### What’s New In CoffeeScript 2?
The biggest change in CoffeeScript 2 is that now the CoffeeScript compiler produces modern JavaScript syntax (ES6, or ES2015 and later). A CoffeeScript `=>` becomes a JS `=>`, a CoffeeScript `class` becomes a JS `class` and so on. Major new features in CoffeeScript 2 include [async functions](#async-functions) and [JSX](#jsx). You can read more in the [changelog](#changelog).
There are very few [breaking changes from CoffeeScript 1.x to 2](#breaking-changes); we hope the upgrade process is smooth for most projects.

5
documentation/sections/why_coffeescript.md Normal file
View file

@ -0,0 +1,5 @@
### Why CoffeeScript When There’s ES6?
CoffeeScript introduced many new features to the JavaScript world, such as [`=>`](#fat-arrow) and [destructuring](#destructuring) and [classes](#classes). We are happy that ECMA has seen their utility and adopted them into ECMAScript.
CoffeeScript’s intent, however, was never to be a superset of JavaScript. One of the guiding principles of CoffeeScript has been _simplicity:_ not just removing JavaScript’s “bad parts,” but providing an elegant, concise syntax that eschews unnecessary punctuation whenever possible, to make code easier to read and reason about. This benefit of CoffeeScript remains, even in an ES2015+ world.

12
documentation/v2/body.html
View file

@ -17,9 +17,15 @@
</section>
<section id="coffeescript-2">
<%= htmlFor('coffeescript_2') %>
</section>
<section id="compatibility">
<%= htmlFor('compatibility') %>
<section id="whats-new-in-coffeescript-2">
<%= htmlFor('whats_new_in_coffeescript_2') %>
</section>
<section id="why-coffeescript">
<%= htmlFor('why_coffeescript') %>
</section>
<section id="compatibility">
<%= htmlFor('compatibility') %>
</section>
</section>
<section id="installation">
<%= htmlFor('installation') %>

6
documentation/v2/sidebar.html
View file

@ -3,7 +3,11 @@
<a href="#try" class="nav-link d-md-none" data-action="sidebar-nav" data-toggle="try">Try CoffeeScript</a>
<a href="#top" class="nav-link" data-action="sidebar-nav">Overview</a>
<a href="#coffeescript-2" class="nav-link" data-action="sidebar-nav">CoffeeScript 2</a>
<a href="#compatibility" class="nav-link" data-action="sidebar-nav">Compatibility</a>
<nav class="nav flex-column">
<a href="#whats-new-in-coffeescript-2" class="nav-link" data-action="sidebar-nav">What’s New in CoffeeScript 2</a>
<a href="#why-coffeescript" class="nav-link" data-action="sidebar-nav">Why CoffeeScript When There’s ES6?</a>
<a href="#compatibility" class="nav-link" data-action="sidebar-nav">Compatibility</a>
</nav>
<a href="#installation" class="nav-link" data-action="sidebar-nav">Installation</a>
<a href="#usage" class="nav-link" data-action="sidebar-nav">Usage</a>
<nav class="nav flex-column">

4
lib/coffeescript/command.js
View file

@ -613,7 +613,7 @@
// https://docs.npmjs.com/files/package.json#optionaldependencies.
require('babel-core');
} catch (error) {
console.error('To use --transpile, you must have Babel installed and configured.\nSee http://coffeescript.org/#usage');
console.error('To use --transpile, you must have Babel installed and configured.\nSee http://coffeescript.org/#transpilation');
process.exit(1);
}
// We’re giving Babel only a string, not a filename or path to a file, so
@ -623,7 +623,7 @@
if (typeof opts.transpile !== 'object') {
// Find the options based on the path to the file being compiled.
cantFindOptions = function() {
console.error('To use the transpile option, there must be a .babelrc file\n(or a package.json file with a "babel" key) in the path of the file\nto be compiled, or in the path of the current working directory.\nIf you are compiling a string via the Node API, the transpile option\nmust be an object with the options to pass to Babel.\nSee http://coffeescript.org/#usage');
console.error('To use the transpile option, there must be a .babelrc file\n(or a package.json file with a "babel" key) in the path of the file\nto be compiled, or in the path of the current working directory.\nIf you are compiling a string via the Node API, the transpile option\nmust be an object with the options to pass to Babel.\nSee http://coffeescript.org/#transpilation');
return process.exit(1);
};
checkPath = filename ? path.dirname(filename) : base ? base : typeof process !== "undefined" && process !== null ? process.cwd() : cantFindOptions();

4
src/command.coffee
View file

@ -451,7 +451,7 @@ compileOptions = (filename, base) ->
catch
console.error '''
To use --transpile, you must have Babel installed and configured.
See http://coffeescript.org/#usage
See http://coffeescript.org/#transpilation
'''
process.exit 1
@ -468,7 +468,7 @@ compileOptions = (filename, base) ->
to be compiled, or in the path of the current working directory.
If you are compiling a string via the Node API, the transpile option
must be an object with the options to pass to Babel.
See http://coffeescript.org/#usage
See http://coffeescript.org/#transpilation
'''
process.exit 1