diff --git a/docs/v2/index.html b/docs/v2/index.html index ac134080..2d7a4155 100644 --- a/docs/v2/index.html +++ b/docs/v2/index.html @@ -607,6 +607,9 @@ textarea {
CoffeeScript 2 generates JavaScript that uses the latest ES2015+ features. It is your responsibility to ensure that your target JavaScript runtime(s) support all these features, or that you pass the output through another transpiler like Babel, Rollup or Traceur Compiler. In general, CoffeeScript 2’s output is fully supported by Node.js 7+, although async functions require the --harmony
or --harmony-async-await
flags; and ES2015 modules require an additional transpiler. Output JavaScript intended for browsers generally requires additional transpilation.
If you’re looking for a single tool that takes CoffeeScript input and generates JavaScript output that runs in any JavaScript runtime, assuming you opt out of certain newer features, stick to the CoffeeScript 1.x branch. CoffeeScript 2 breaks compatibility with certain CoffeeScript 1.x features in order to conform with the ES2015+ specifications, and generate more idiomatic output (a CoffeeScript =>
becomes an ES =>
; a CoffeeScript class
becomes an ES class
; and so on).
CoffeeScript introduced many new features to the JavaScript world, such as =>
and destructuring and 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 a cleaner, terser syntax that uses less punctuation and enforces indentation, to make code easier to read and reason about. Increased clarity leads to increased quality, and fewer bugs. This benefit of CoffeeScript remains, even in an ES2015+ world.
+CoffeeScript 2 supports many of the latest ES2015+ features, output using ES2015+ syntax. If you’re looking for a single tool that takes CoffeeScript input and generates JavaScript output that runs in any JavaScript runtime, assuming you opt out of certain newer features, stick to the CoffeeScript 1.x branch. CoffeeScript 2 breaks compatibility with certain CoffeeScript 1.x features in order to conform with the ES2015+ specifications, and generate more idiomatic output (a CoffeeScript =>
becomes an ES =>
; a CoffeeScript class
becomes an ES class
; and so on).
Since the CoffeeScript 2 compiler outputs ES2015+ syntax, it is your responsibility to either ensure that your target JavaScript runtime(s) support all these features, or that you pass the output through another transpiler like Babel, Rollup or Traceur Compiler. In general, CoffeeScript 2’s output is supported as is by Node.js 7.6+, except for modules which require transpilation.
+There are many great task runners for setting up JavaScript build chains, such as Gulp, Webpack, Grunt and Broccoli. If you’re looking for a very minimal solution to get started, you can use babel-preset-env and the command line:
++npm install --global coffeescript@next +npm install --save-dev coffeescript@next babel-cli babel-preset-env +coffee -p *.coffee | babel --presets env > app.js
There are a few ECMAScript features that CoffeeScript intentionally doesn’t support.
+let
and const
: Block-Scoped and Reassignment-Protected VariablesWhen CoffeeScript was designed, var
was intentionally omitted. This was to spare developers the mental housekeeping of needing to worry about variable declaration (var foo
) as opposed to variable assignment (foo = 1
). The CoffeeScript compiler automatically takes care of declaration for you, by generating var
statements at the top of every function scope. This makes it impossible to accidentally declare a global variable.
let
and const
add a useful ability to JavaScript in that you can use them to declare variables within a block scope, for example within an if
statement body or a for
loop body, whereas var
always declares variables in the scope of an entire function. When CoffeeScript 2 was designed, there was much discussion of whether this functionality was useful enough to outweigh the simplicity offered by never needing to consider variable declaration in CoffeeScript. In the end, it was decided that the simplicity was more valued. In CoffeeScript there remains only one type of variable.
Keep in mind that const
only protects you from reassigning a variable; it doesn’t prevent the variable’s value from changing, the way constants usually do in other languages:
++const obj = {foo: 'bar'}; +obj.foo = 'baz'; // Allowed! +obj = {}; // Throws error
get
and set
Keyword Shorthand Syntaxget
and set
, as keywords preceding functions or class methods, are intentionally unimplemented in CoffeeScript.
This is to avoid grammatical ambiguity, since in CoffeeScript such a construct looks identical to a function call (e.g. get(function foo() {})
); and because there is an alternate syntax that is slightly more verbose but just as effective:
CoffeeScript 2 aims to output as much idiomatic ES2015+ syntax as possible with as few breaking changes from CoffeeScript 1.x as possible. Some breaking changes, unfortunately, were unavoidable.
Per the ES2015 spec regarding default parameters, default values are only applied when a parameter value is missing or undefined
. In CoffeeScript 1.x, the default value would be applied in those cases but also if the parameter value was null
.
Contributions are welcome! Feel free to fork the repo and submit a pull request.
+Some features of ECMAScript are intentionally unsupported. Please review both the open and closed issues on GitHub to see if the feature you’re looking for has already been discussed. As a general rule, we don’t support ECMAScript syntax for features that aren’t yet finalized (at Stage 4 in the proposal approval process).
+For more resources on adding to CoffeeScript, please see the Wiki, especially How The Parser Works.
+There are several things you can do to increase your odds of having your pull request accepted:
+Of course, it’s entirely possible that you have a great addition, but it doesn’t fit within these constraints. Feel free to roll your own solution; you will have plenty of company.
+