2.0.0-beta4 (#4628)

* 2.0.0-beta4 changelog

* Recompile parser, update browser compiler

* Updated annotated source and browser tests

* Bump version to 2.0.0-beta4

.gitignore

@@ -8,3 +8,4 @@ test/*.js
 parser.output
 /node_modules
 npm-debug.log*
+yarn.lock

CONTRIBUTING.md

@@ -4,6 +4,6 @@
 
 * Before sending a pull request for a feature, be sure to have [tests](https://github.com/jashkenas/coffeescript/tree/master/test).
 
-* Use the same coding style as the rest of the [codebase](https://github.com/jashkenas/coffeescript/tree/master/src). If you're just getting started with CoffeeScript, there's a nice [style guide](https://github.com/polarmobile/coffeescript-style-guide).
+* Use the same coding style as the rest of the [codebase](https://github.com/jashkenas/coffeescript/tree/master/src). If you’re just getting started with CoffeeScript, there’s a nice [style guide](https://github.com/polarmobile/coffeescript-style-guide).
 
-* In your pull request, do not add documentation to `index.html` or re-build the minified `coffee-script.js` file. We'll do those things before cutting a new release.
+* In your pull request, do not add documentation to `index.html` or re-build the minified `coffeescript.js` file. We’ll do those things before cutting a new release. You _should,_ however, commit the updated compiled JavaScript files in `lib`.

Cakefile

@@ -1,17 +1,19 @@
 fs                        = require 'fs'
+os                        = require 'os'
 path                      = require 'path'
 _                         = require 'underscore'
 { spawn, exec, execSync } = require 'child_process'
-CoffeeScript              = require './lib/coffee-script'
-helpers                   = require './lib/coffee-script/helpers'
+CoffeeScript              = require './lib/coffeescript'
+helpers                   = require './lib/coffeescript/helpers'
 
 # ANSI Terminal Colors.
-bold = red = green = reset = ''
+bold = red = green = yellow = reset = ''
 unless process.env.NODE_DISABLE_COLORS
-  bold  = '\x1B[0;1m'
-  red   = '\x1B[0;31m'
-  green = '\x1B[0;32m'
-  reset = '\x1B[0m'
+  bold   = '\x1B[0;1m'
+  red    = '\x1B[0;31m'
+  green  = '\x1B[0;32m'
+  yellow = '\x1B[0;33m'
+  reset  = '\x1B[0m'
 
 # Built file header.
 header = """
@@ -51,27 +53,21 @@ run = (args, callback) ->
 buildParser = ->
   helpers.extend global, require 'util'
   require 'jison'
-  parser = require('./lib/coffee-script/grammar').parser.generate()
-  # Patch Jison’s output, until https://github.com/zaach/jison/pull/339 is accepted,
-  # to ensure that require('fs') is only called where it exists.
-  parser = parser.replace "var source = require('fs')", """
-      var source = '';
-          var fs = require('fs');
-          if (typeof fs !== 'undefined' && fs !== null)
-              source = fs"""
-  fs.writeFileSync 'lib/coffee-script/parser.js', parser
+  # We don't need `moduleMain`, since the parser is unlikely to be run standalone.
+  parser = require('./lib/coffeescript/grammar').parser.generate(moduleMain: ->)
+  fs.writeFileSync 'lib/coffeescript/parser.js', parser
 
 buildExceptParser = (callback) ->
   files = fs.readdirSync 'src'
   files = ('src/' + file for file in files when file.match(/\.(lit)?coffee$/))
-  run ['-c', '-o', 'lib/coffee-script'].concat(files), callback
+  run ['-c', '-o', 'lib/coffeescript'].concat(files), callback
 
 build = (callback) ->
   buildParser()
   buildExceptParser callback
 
 testBuiltCode = (watch = no) ->
-  csPath = './lib/coffee-script'
+  csPath = './lib/coffeescript'
   csDir  = path.dirname require.resolve csPath
 
   for mod of require.cache when csDir is mod[0 ... csDir.length]
@@ -122,11 +118,11 @@ task 'build:browser', 'merge the built scripts into a single file for use in a b
     return #{fs.readFileSync "./package.json"};
   })();
   """
-  for name in ['helpers', 'rewriter', 'lexer', 'parser', 'scope', 'nodes', 'sourcemap', 'coffee-script', 'browser']
+  for name in ['helpers', 'rewriter', 'lexer', 'parser', 'scope', 'nodes', 'sourcemap', 'coffeescript', 'browser']
     code += """
       require['./#{name}'] = (function() {
         var exports = {}, module = {exports: exports};
-        #{fs.readFileSync "lib/coffee-script/#{name}.js"}
+        #{fs.readFileSync "lib/coffeescript/#{name}.js"}
         return module.exports;
       })();
     """
@@ -135,7 +131,7 @@ task 'build:browser', 'merge the built scripts into a single file for use in a b
       var CoffeeScript = function() {
         function require(path){ return require[path]; }
         #{code}
-        return require['./coffee-script'];
+        return require['./browser'];
       }();
 
       if (typeof define === 'function' && define.amd) {
@@ -145,15 +141,27 @@ task 'build:browser', 'merge the built scripts into a single file for use in a b
       }
     }(this));
   """
-  unless process.env.MINIFY is 'false'
-    {compiledCode: code} = require('google-closure-compiler-js').compile
-      jsCode: [
-        src: code
-        languageOut: if majorVersion is 1 then 'ES5' else 'ES6'
-      ]
+  babel = require 'babel-core'
+  presets = []
+  # Exclude the `modules` plugin in order to not break the `}(this));`
+  # at the end of the above code block.
+  presets.push ['env', {modules: no}] unless process.env.TRANSFORM is 'false'
+  babelOptions =
+    presets: presets
+    sourceType: 'script'
+  { code } = babel.transform code, babelOptions unless presets.length is 0
+  # Running Babel twice due to https://github.com/babel/babili/issues/614.
+  # Once that issue is fixed, move the `babili` preset back up into the
+  # `presets` array and run Babel once with both presets together.
+  presets = if process.env.MINIFY is 'false' then [] else ['babili']
+  babelOptions =
+    compact: process.env.MINIFY isnt 'false'
+    presets: presets
+    sourceType: 'script'
+  { code } = babel.transform code, babelOptions unless presets.length is 0
   outputFolder = "docs/v#{majorVersion}/browser-compiler"
   fs.mkdirSync outputFolder unless fs.existsSync outputFolder
-  fs.writeFileSync "#{outputFolder}/coffee-script.js", header + '\n' + code
+  fs.writeFileSync "#{outputFolder}/coffeescript.js", header + '\n' + code
 
 task 'build:browser:full', 'merge the built scripts into a single file for use in a browser, and test it', ->
   invoke 'build:browser'
@@ -194,9 +202,19 @@ buildDocs = (watch = no) ->
   codeFor = require "./documentation/v#{majorVersion}/code.coffee"
 
   htmlFor = ->
+    hljs = require 'highlight.js'
+    hljs.configure classPrefix: ''
     markdownRenderer = require('markdown-it')
       html: yes
       typographer: yes
+      highlight: (str, lang) ->
+        # From https://github.com/markdown-it/markdown-it#syntax-highlighting
+        if lang and hljs.getLanguage(lang)
+          try
+            return hljs.highlight(lang, str).value
+          catch ex
+        return '' # No syntax highlighting
+
 
     # Add some custom overrides to Markdown-It’s rendering, per
     # https://github.com/markdown-it/markdown-it/blob/master/docs/architecture.md#renderer
@@ -330,8 +348,8 @@ task 'release', 'build and test the CoffeeScript source, and build the documenta
   invoke 'doc:source'
 
 task 'bench', 'quick benchmark of compilation time', ->
-  {Rewriter} = require './lib/coffee-script/rewriter'
-  sources = ['coffee-script', 'grammar', 'helpers', 'lexer', 'nodes', 'rewriter']
+  {Rewriter} = require './lib/coffeescript/rewriter'
+  sources = ['coffeescript', 'grammar', 'helpers', 'lexer', 'nodes', 'rewriter']
   coffee  = sources.map((name) -> fs.readFileSync "src/#{name}.coffee").join '\n'
   litcoffee = fs.readFileSync("src/scope.litcoffee").toString()
   fmt    = (ms) -> " #{bold}#{ "   #{ms}".slice -4 }#{reset} ms"
@@ -353,17 +371,26 @@ task 'bench', 'quick benchmark of compilation time', ->
 
 # Run the CoffeeScript test suite.
 runTests = (CoffeeScript) ->
-  CoffeeScript.register()
-  startTime   = Date.now()
-  currentFile = null
-  passedTests = 0
-  failures    = []
+  CoffeeScript.register() unless global.testingBrowser
+  startTime = Date.now()
+
+  # These are attached to `global` so that they’re accessible from within
+  # `test/async.coffee`, which has an async-capable version of
+  # `global.test`.
+  global.currentFile = null
+  global.passedTests = 0
+  global.failures    = []
 
   global[name] = func for name, func of require 'assert'
 
   # Convenience aliases.
   global.CoffeeScript = CoffeeScript
-  global.Repl = require './lib/coffee-script/repl'
+  global.Repl   = require './lib/coffeescript/repl'
+  global.bold   = bold
+  global.red    = red
+  global.green  = green
+  global.yellow = yellow
+  global.reset  = reset
 
   # Our test helper function for delimiting different test cases.
   global.test = (description, fn) ->
@@ -415,9 +442,35 @@ task 'test', 'run the CoffeeScript language test suite', ->
 
 
 task 'test:browser', 'run the test suite against the merged browser script', ->
-  source = fs.readFileSync "docs/v#{majorVersion}/browser-compiler/coffee-script.js", 'utf-8'
+  source = fs.readFileSync "docs/v#{majorVersion}/browser-compiler/coffeescript.js", 'utf-8'
   result = {}
   global.testingBrowser = yes
   (-> eval source).call result
   testResults = runTests result.CoffeeScript
   process.exit 1 unless testResults
+
+task 'test:integrations', 'test the module integrated with other libraries and environments', ->
+  # Tools like Webpack and Browserify generate builds intended for a browser
+  # environment where Node modules are not available. We want to ensure that
+  # the CoffeeScript module as presented by the `browser` key in `package.json`
+  # can be built by such tools; if such a build succeeds, it verifies that no
+  # Node modules are required as part of the compiler (as opposed to the tests)
+  # and that therefore the compiler will run in a browser environment.
+  tmpdir = os.tmpdir()
+  try
+    buildLog = execSync "./node_modules/webpack/bin/webpack.js
+      --entry=./
+      --output-library=CoffeeScript
+      --output-library-target=commonjs2
+      --output-path=#{tmpdir}
+      --output-filename=coffeescript.js"
+  catch exception
+    console.error buildLog.toString()
+    throw exception
+
+  builtCompiler = path.join tmpdir, 'coffeescript.js'
+  CoffeeScript = require builtCompiler
+  global.testingBrowser = yes
+  testResults = runTests CoffeeScript
+  fs.unlinkSync builtCompiler
+  process.exit 1 unless testResults

bin/cake

@@ -7,7 +7,7 @@ var potentialPaths = [
   path.join(process.cwd(), 'node_modules/coffeescript/lib/coffeescript'),
   path.join(process.cwd(), 'node_modules/coffeescript/lib/coffee-script'),
   path.join(process.cwd(), 'node_modules/coffee-script/lib/coffee-script'),
-  path.join(__dirname, '../lib/coffee-script')
+  path.join(__dirname, '../lib/coffeescript')
 ];
 
 for (var i = 0, len = potentialPaths.length; i < len; i++) {

bin/coffee

@@ -7,7 +7,7 @@ var potentialPaths = [
   path.join(process.cwd(), 'node_modules/coffeescript/lib/coffeescript'),
   path.join(process.cwd(), 'node_modules/coffeescript/lib/coffee-script'),
   path.join(process.cwd(), 'node_modules/coffee-script/lib/coffee-script'),
-  path.join(__dirname, '../lib/coffee-script')
+  path.join(__dirname, '../lib/coffeescript')
 ];
 
 for (var i = 0, len = potentialPaths.length; i < len; i++) {

bower.json

@@ -1,7 +1,7 @@
 {
-  "name": "coffee-script",
+  "name": "coffeescript",
   "main": [
-    "lib/coffee-script/coffee-script.js"
+    "lib/coffeescript/browser.js"
   ],
   "description": "Unfancy JavaScript",
   "keywords": [

docs/v2/annotated-source/coffeescript.html

@@ -315,6 +315,8 @@ we need to recompile it to get a source map for <code>prepareStackTrace</code>.<
             <div class="content"><div class='highlight'><pre>  generateSourceMap = options.sourceMap <span class="hljs-keyword">or</span> options.inlineMap <span class="hljs-keyword">or</span> <span class="hljs-keyword">not</span> options.filename?
   filename = options.filename <span class="hljs-keyword">or</span> <span class="hljs-string">'&lt;anonymous&gt;'</span>
 
+  checkShebangLine filename, code
+
   sources[filename] = code
   map = <span class="hljs-keyword">new</span> SourceMap <span class="hljs-keyword">if</span> generateSourceMap
 
@@ -540,13 +542,11 @@ directly as a “Jison lexer”.</p>
       @yylineno = @yylloc.first_line
     <span class="hljs-keyword">else</span>
       tag = <span class="hljs-string">''</span>
-
     tag
   setInput: <span class="hljs-function"><span class="hljs-params">(tokens)</span> -&gt;</span>
     parser.tokens = tokens
     @pos = <span class="hljs-number">0</span>
-  upcomingInput: <span class="hljs-function">-&gt;</span>
-    <span class="hljs-string">""</span></pre></div></div>
+  upcomingInput: <span class="hljs-function">-&gt;</span> <span class="hljs-string">''</span></pre></div></div>
             
         </li>
         
@@ -757,7 +757,20 @@ positions.</p>
     <span class="hljs-keyword">break</span> <span class="hljs-keyword">if</span> frame.getFunction() <span class="hljs-keyword">is</span> exports.run
     <span class="hljs-string">"    at <span class="hljs-subst">#{formatSourcePosition frame, getSourceMapping}</span>"</span>
 
-  <span class="hljs-string">"<span class="hljs-subst">#{err.toString()}</span>\n<span class="hljs-subst">#{frames.join <span class="hljs-string">'\n'</span>}</span>\n"</span></pre></div></div>
+  <span class="hljs-string">"<span class="hljs-subst">#{err.toString()}</span>\n<span class="hljs-subst">#{frames.join <span class="hljs-string">'\n'</span>}</span>\n"</span>
+<span class="hljs-function">
+<span class="hljs-title">checkShebangLine</span> = <span class="hljs-params">(file, input)</span> -&gt;</span>
+  firstLine = input.split(<span class="hljs-regexp">/$/m</span>)[<span class="hljs-number">0</span>]
+  rest = firstLine?.match(<span class="hljs-regexp">/^#!\s*([^\s]+\s*)(.*)/</span>)
+  args = rest?[<span class="hljs-number">2</span>]?.split(<span class="hljs-regexp">/\s/</span>).filter (s) -&gt; s <span class="hljs-keyword">isnt</span> <span class="hljs-string">''</span>
+  <span class="hljs-keyword">if</span> args?.length &gt; <span class="hljs-number">1</span>
+    <span class="hljs-built_in">console</span>.error <span class="hljs-string">'''
+      The script to be run begins with a shebang line with more than one
+      argument. This script will fail on platforms such as Linux which only
+      allow a single argument.
+    '''</span>
+    <span class="hljs-built_in">console</span>.error <span class="hljs-string">"The shebang line was: '<span class="hljs-subst">#{firstLine}</span>' in file '<span class="hljs-subst">#{file}</span>'"</span>
+    <span class="hljs-built_in">console</span>.error <span class="hljs-string">"The arguments were: <span class="hljs-subst">#{JSON.stringify args}</span>"</span></pre></div></div>
             
         </li>
         

docs/v2/annotated-source/command.html

@@ -180,7 +180,7 @@ useWinPathSep  = path.sep <span class="hljs-keyword">is</span> <span class="hljs
             </div>
             
             <div class="content"><div class='highlight'><pre>BANNER = <span class="hljs-string">'''
-  Usage: coffee [options] path/to/script.coffee -- [args]
+  Usage: coffee [options] path/to/script.coffee [args]
 
   If called without options, `coffee` will run your script.
 '''</span></pre></div></div>
@@ -260,7 +260,21 @@ Many flags cause us to divert before compiling anything. Flags passed after
             
             <div class="content"><div class='highlight'><pre>exports.run = <span class="hljs-function">-&gt;</span>
   optionParser = buildCSOptionParser()
-  parseOptions()</pre></div></div>
+  <span class="hljs-keyword">try</span> parseOptions()
+  <span class="hljs-keyword">catch</span> err
+    <span class="hljs-built_in">console</span>.error <span class="hljs-string">"option parsing error: <span class="hljs-subst">#{err.message}</span>"</span>
+    process.exit <span class="hljs-number">1</span>
+
+  <span class="hljs-keyword">if</span> (<span class="hljs-keyword">not</span> opts.doubleDashed) <span class="hljs-keyword">and</span> (opts.arguments[<span class="hljs-number">1</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'--'</span>)
+    printWarn <span class="hljs-string">'''
+      coffee was invoked with '--' as the second positional argument, which is
+      now deprecated. To pass '--' as an argument to a script to run, put an
+      additional '--' before the path to your script.
+
+      '--' will be removed from the argument list.
+    '''</span>
+    printWarn <span class="hljs-string">"The positional arguments were: <span class="hljs-subst">#{JSON.stringify opts.arguments}</span>"</span>
+    opts.arguments = [opts.arguments[<span class="hljs-number">0</span>]].concat opts.arguments[<span class="hljs-number">2.</span>.]</pre></div></div>
             
         </li>
         
@@ -842,6 +856,9 @@ the <code>node</code> binary, preserving the other options.</p>
     cwd:        process.cwd()
     env:        process.env
     stdio:      [<span class="hljs-number">0</span>, <span class="hljs-number">1</span>, <span class="hljs-number">2</span>]
+  <span class="hljs-keyword">for</span> signal <span class="hljs-keyword">in</span> [<span class="hljs-string">'SIGINT'</span>, <span class="hljs-string">'SIGTERM'</span>]
+    process.<span class="hljs-literal">on</span> signal, <span class="hljs-keyword">do</span> (signal) -&gt;
+      -&gt; p.kill signal
   p.<span class="hljs-literal">on</span> <span class="hljs-string">'exit'</span>, <span class="hljs-function"><span class="hljs-params">(code)</span> -&gt;</span> process.exit code</pre></div></div>
             
         </li>

docs/v2/annotated-source/grammar.html

@@ -209,8 +209,8 @@ previous nonterminal.</p>
             <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">o</span> = <span class="hljs-params">(patternString, action, options)</span> -&gt;</span>
   patternString = patternString.replace <span class="hljs-regexp">/\s{2,}/g</span>, <span class="hljs-string">' '</span>
   patternCount = patternString.split(<span class="hljs-string">' '</span>).length
-  <span class="hljs-keyword">return</span> [patternString, <span class="hljs-string">'$$ = $1;'</span>, options] <span class="hljs-keyword">unless</span> action
-  action = <span class="hljs-keyword">if</span> match = unwrap.exec action <span class="hljs-keyword">then</span> match[<span class="hljs-number">1</span>] <span class="hljs-keyword">else</span> <span class="hljs-string">"(<span class="hljs-subst">#{action}</span>())"</span></pre></div></div>
+  <span class="hljs-keyword">if</span> action
+    action = <span class="hljs-keyword">if</span> match = unwrap.exec action <span class="hljs-keyword">then</span> match[<span class="hljs-number">1</span>] <span class="hljs-keyword">else</span> <span class="hljs-string">"(<span class="hljs-subst">#{action}</span>())"</span></pre></div></div>
             
         </li>
         
@@ -225,8 +225,8 @@ previous nonterminal.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>  action = action.replace <span class="hljs-regexp">/\bnew /g</span>, <span class="hljs-string">'$&amp;yy.'</span>
-  action = action.replace <span class="hljs-regexp">/\b(?:Block\.wrap|extend)\b/g</span>, <span class="hljs-string">'yy.$&amp;'</span></pre></div></div>
+            <div class="content"><div class='highlight'><pre>    action = action.replace <span class="hljs-regexp">/\bnew /g</span>, <span class="hljs-string">'$&amp;yy.'</span>
+    action = action.replace <span class="hljs-regexp">/\b(?:Block\.wrap|extend)\b/g</span>, <span class="hljs-string">'yy.$&amp;'</span></pre></div></div>
             
         </li>
         
@@ -237,22 +237,23 @@ previous nonterminal.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-8">&#182;</a>
               </div>
-              <p>Returns a function which adds location data to the first parameter passed
-in, and returns the parameter. If the parameter is not a node, it will
-just be passed through unaffected.</p>
+              <p>Returns strings of functions to add to <code>parser.js</code> which add extra data
+that nodes may have, such as comments or location data. Location data
+is added to the first parameter passed in, and the parameter is returned.
+If the parameter is not a node, it will just be passed through unaffected.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre><span class="hljs-function">  <span class="hljs-title">addLocationDataFn</span> = <span class="hljs-params">(first, last)</span> -&gt;</span>
-    <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> last
-      <span class="hljs-string">"yy.addLocationDataFn(@<span class="hljs-subst">#{first}</span>)"</span>
-    <span class="hljs-keyword">else</span>
-      <span class="hljs-string">"yy.addLocationDataFn(@<span class="hljs-subst">#{first}</span>, @<span class="hljs-subst">#{last}</span>)"</span>
+            <div class="content"><div class='highlight'><pre><span class="hljs-function">    <span class="hljs-title">getAddDataToNodeFunctionString</span> = <span class="hljs-params">(first, last)</span> -&gt;</span>
+      <span class="hljs-string">"yy.addDataToNode(yy, @<span class="hljs-subst">#{first}</span><span class="hljs-subst">#{<span class="hljs-keyword">if</span> last <span class="hljs-keyword">then</span> <span class="hljs-string">", @<span class="hljs-subst">#{last}</span>"</span> <span class="hljs-keyword">else</span> <span class="hljs-string">''</span>}</span>)"</span>
 
-  action = action.replace <span class="hljs-regexp">/LOC\(([0-9]*)\)/g</span>, addLocationDataFn(<span class="hljs-string">'$1'</span>)
-  action = action.replace <span class="hljs-regexp">/LOC\(([0-9]*),\s*([0-9]*)\)/g</span>, addLocationDataFn(<span class="hljs-string">'$1'</span>, <span class="hljs-string">'$2'</span>)
+    action = action.replace <span class="hljs-regexp">/LOC\(([0-9]*)\)/g</span>, getAddDataToNodeFunctionString(<span class="hljs-string">'$1'</span>)
+    action = action.replace <span class="hljs-regexp">/LOC\(([0-9]*),\s*([0-9]*)\)/g</span>, getAddDataToNodeFunctionString(<span class="hljs-string">'$1'</span>, <span class="hljs-string">'$2'</span>)
+    performActionFunctionString = <span class="hljs-string">"$$ = <span class="hljs-subst">#{getAddDataToNodeFunctionString(<span class="hljs-number">1</span>, patternCount)}</span>(<span class="hljs-subst">#{action}</span>);"</span>
+  <span class="hljs-keyword">else</span>
+    performActionFunctionString = <span class="hljs-string">'$$ = $1;'</span>
 
-  [patternString, <span class="hljs-string">"$$ = <span class="hljs-subst">#{addLocationDataFn(<span class="hljs-number">1</span>, patternCount)}</span>(<span class="hljs-subst">#{action}</span>);"</span>, options]</pre></div></div>
+  [patternString, performActionFunctionString, options]</pre></div></div>
             
         </li>
         
@@ -380,7 +381,6 @@ grammar.</p>
             
             <div class="content"><div class='highlight'><pre>  Statement: [
     o <span class="hljs-string">'Return'</span>
-    o <span class="hljs-string">'Comment'</span>
     o <span class="hljs-string">'STATEMENT'</span>,                              <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> StatementLiteral $<span class="hljs-number">1</span>
     o <span class="hljs-string">'Import'</span>
     o <span class="hljs-string">'Export'</span>
@@ -404,7 +404,6 @@ them somewhat circular.</p>
             
             <div class="content"><div class='highlight'><pre>  Expression: [
     o <span class="hljs-string">'Value'</span>
-    o <span class="hljs-string">'Invocation'</span>
     o <span class="hljs-string">'Code'</span>
     o <span class="hljs-string">'Operation'</span>
     o <span class="hljs-string">'Assign'</span>
@@ -500,11 +499,11 @@ through and printed to JavaScript.</p>
     o <span class="hljs-string">'AlphaNumeric'</span>
     o <span class="hljs-string">'JS'</span>,                                     <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> PassthroughLiteral $<span class="hljs-number">1</span>
     o <span class="hljs-string">'Regex'</span>
-    o <span class="hljs-string">'UNDEFINED'</span>,                              <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> UndefinedLiteral
-    o <span class="hljs-string">'NULL'</span>,                                   <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> NullLiteral
+    o <span class="hljs-string">'UNDEFINED'</span>,                              <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> UndefinedLiteral $<span class="hljs-number">1</span>
+    o <span class="hljs-string">'NULL'</span>,                                   <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> NullLiteral $<span class="hljs-number">1</span>
     o <span class="hljs-string">'BOOL'</span>,                                   <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> BooleanLiteral $<span class="hljs-number">1</span>
     o <span class="hljs-string">'INFINITY'</span>,                               <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> InfinityLiteral $<span class="hljs-number">1</span>
-    o <span class="hljs-string">'NAN'</span>,                                    <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> NaNLiteral
+    o <span class="hljs-string">'NAN'</span>,                                    <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> NaNLiteral $<span class="hljs-number">1</span>
   ]</pre></div></div>
             
         </li>
@@ -553,7 +552,6 @@ the ordinary <strong>Assign</strong> is that these allow numbers and strings as
     o <span class="hljs-string">'SimpleObjAssignable =
        INDENT Expression OUTDENT'</span>,              <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Assign LOC(<span class="hljs-number">1</span>)(<span class="hljs-keyword">new</span> Value $<span class="hljs-number">1</span>), $<span class="hljs-number">4</span>, <span class="hljs-literal">null</span>,
                                                               operatorToken: LOC(<span class="hljs-number">2</span>)(<span class="hljs-keyword">new</span> Literal $<span class="hljs-number">2</span>)
-    o <span class="hljs-string">'Comment'</span>
   ]
 
   SimpleObjAssignable: [
@@ -582,7 +580,9 @@ the ordinary <strong>Assign</strong> is that these allow numbers and strings as
             
             <div class="content"><div class='highlight'><pre>  ObjRestValue: [
     o <span class="hljs-string">'SimpleObjAssignable ...'</span>, <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Splat <span class="hljs-keyword">new</span> Value $<span class="hljs-number">1</span>
+    o <span class="hljs-string">'... SimpleObjAssignable'</span>, <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Splat <span class="hljs-keyword">new</span> Value $<span class="hljs-number">2</span>
     o <span class="hljs-string">'ObjSpreadExpr ...'</span>,       <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Splat $<span class="hljs-number">1</span>
+    o <span class="hljs-string">'... ObjSpreadExpr'</span>,       <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Splat $<span class="hljs-number">2</span>
   ]
 
   ObjSpreadExpr: [
@@ -591,14 +591,19 @@ the ordinary <strong>Assign</strong> is that these allow numbers and strings as
     o <span class="hljs-string">'Parenthetical'</span>
     o <span class="hljs-string">'Super'</span>
     o <span class="hljs-string">'This'</span>
-    o <span class="hljs-string">'SUPER Arguments'</span>,               <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> SuperCall LOC(<span class="hljs-number">1</span>)(<span class="hljs-keyword">new</span> Super), $<span class="hljs-number">2</span>
+    o <span class="hljs-string">'SUPER Arguments'</span>,               <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> SuperCall LOC(<span class="hljs-number">1</span>)(<span class="hljs-keyword">new</span> Super), $<span class="hljs-number">2</span>, <span class="hljs-literal">no</span>, $<span class="hljs-number">1</span>
     o <span class="hljs-string">'SimpleObjAssignable Arguments'</span>, <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Call (<span class="hljs-keyword">new</span> Value $<span class="hljs-number">1</span>), $<span class="hljs-number">2</span>
     o <span class="hljs-string">'ObjSpreadExpr Arguments'</span>,       <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Call $<span class="hljs-number">1</span>, $<span class="hljs-number">2</span>
   ]
 
   ObjSpreadIdentifier: [
-    o <span class="hljs-string">'SimpleObjAssignable . Property'</span>,                             <span class="hljs-function">-&gt;</span> (<span class="hljs-keyword">new</span> Value $<span class="hljs-number">1</span>).add(<span class="hljs-keyword">new</span> Access $<span class="hljs-number">3</span>)
-    o <span class="hljs-string">'SimpleObjAssignable INDEX_START IndexValue INDEX_END'</span>,       <span class="hljs-function">-&gt;</span> (<span class="hljs-keyword">new</span> Value $<span class="hljs-number">1</span>).add($<span class="hljs-number">3</span>)
+    o <span class="hljs-string">'SimpleObjAssignable ObjSpreadAccessor'</span>, <span class="hljs-function">-&gt;</span> (<span class="hljs-keyword">new</span> Value $<span class="hljs-number">1</span>).add $<span class="hljs-number">2</span>
+    o <span class="hljs-string">'ObjSpreadExpr ObjSpreadAccessor'</span>,       <span class="hljs-function">-&gt;</span> (<span class="hljs-keyword">new</span> Value $<span class="hljs-number">1</span>).add $<span class="hljs-number">2</span>
+  ]
+
+  ObjSpreadAccessor: [
+    o <span class="hljs-string">'. Property'</span>,                             <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Access $<span class="hljs-number">2</span>
+    o <span class="hljs-string">'INDEX_START IndexValue INDEX_END'</span>,       <span class="hljs-function">-&gt;</span> $<span class="hljs-number">2</span>
   ]</pre></div></div>
             
         </li>
@@ -616,6 +621,7 @@ the ordinary <strong>Assign</strong> is that these allow numbers and strings as
             
             <div class="content"><div class='highlight'><pre>  Return: [
     o <span class="hljs-string">'RETURN Expression'</span>,                      <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Return $<span class="hljs-number">2</span>
+    o <span class="hljs-string">'RETURN INDENT Object OUTDENT'</span>,           <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Return <span class="hljs-keyword">new</span> Value $<span class="hljs-number">3</span>
     o <span class="hljs-string">'RETURN'</span>,                                 <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Return
   ]
 
@@ -638,23 +644,6 @@ the ordinary <strong>Assign</strong> is that these allow numbers and strings as
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-24">&#182;</a>
               </div>
-              <p>A block comment.</p>
-
-            </div>
-            
-            <div class="content"><div class='highlight'><pre>  Comment: [
-    o <span class="hljs-string">'HERECOMMENT'</span>,                            <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Comment $<span class="hljs-number">1</span>
-  ]</pre></div></div>
-            
-        </li>
-        
-        
-        <li id="section-25">
-            <div class="annotation">
-              
-              <div class="pilwrap ">
-                <a class="pilcrow" href="#section-25">&#182;</a>
-              </div>
               <p>The <strong>Code</strong> node is the function literal. It’s defined by an indented block
 of <strong>Block</strong> preceded by a function arrow, with an optional parameter list.</p>
 
@@ -668,11 +657,11 @@ of <strong>Block</strong> preceded by a function arrow, with an optional paramet
         </li>
         
         
-        <li id="section-26">
+        <li id="section-25">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-26">&#182;</a>
+                <a class="pilcrow" href="#section-25">&#182;</a>
               </div>
               <p>CoffeeScript has two different symbols for functions. <code>-&gt;</code> is for ordinary
 functions, and <code>=&gt;</code> is for functions bound to the current value of <em>this</em>.</p>
@@ -680,18 +669,18 @@ functions, and <code>=&gt;</code> is for functions bound to the current value of
             </div>
             
             <div class="content"><div class='highlight'><pre>  FuncGlyph: [
-    o <span class="hljs-string">'-&gt;'</span>,                                     <span class="hljs-function">-&gt;</span> <span class="hljs-string">'func'</span>
-    o <span class="hljs-string">'=&gt;'</span>,                                     <span class="hljs-function">-&gt;</span> <span class="hljs-string">'boundfunc'</span>
+    o <span class="hljs-string">'-&gt;'</span>,                                     <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> FuncGlyph $<span class="hljs-number">1</span>
+    o <span class="hljs-string">'=&gt;'</span>,                                     <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> FuncGlyph $<span class="hljs-number">1</span>
   ]</pre></div></div>
             
         </li>
         
         
-        <li id="section-27">
+        <li id="section-26">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-27">&#182;</a>
+                <a class="pilcrow" href="#section-26">&#182;</a>
               </div>
               <p>An optional, trailing comma.</p>
 
@@ -705,11 +694,11 @@ functions, and <code>=&gt;</code> is for functions bound to the current value of
         </li>
         
         
-        <li id="section-28">
+        <li id="section-27">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-28">&#182;</a>
+                <a class="pilcrow" href="#section-27">&#182;</a>
               </div>
               <p>The list of parameters that a function accepts can be of any length.</p>
 
@@ -726,11 +715,11 @@ functions, and <code>=&gt;</code> is for functions bound to the current value of
         </li>
         
         
-        <li id="section-29">
+        <li id="section-28">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-29">&#182;</a>
+                <a class="pilcrow" href="#section-28">&#182;</a>
               </div>
               <p>A single parameter in a function definition can be ordinary, or a splat
 that hoovers up the remaining arguments.</p>
@@ -740,6 +729,7 @@ that hoovers up the remaining arguments.</p>
             <div class="content"><div class='highlight'><pre>  Param: [
     o <span class="hljs-string">'ParamVar'</span>,                               <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Param $<span class="hljs-number">1</span>
     o <span class="hljs-string">'ParamVar ...'</span>,                           <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Param $<span class="hljs-number">1</span>, <span class="hljs-literal">null</span>, <span class="hljs-literal">on</span>
+    o <span class="hljs-string">'... ParamVar'</span>,                           <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Param $<span class="hljs-number">2</span>, <span class="hljs-literal">null</span>, <span class="hljs-literal">on</span>
     o <span class="hljs-string">'ParamVar = Expression'</span>,                  <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Param $<span class="hljs-number">1</span>, $<span class="hljs-number">3</span>
     o <span class="hljs-string">'...'</span>,                                    <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Expansion
   ]</pre></div></div>
@@ -747,11 +737,11 @@ that hoovers up the remaining arguments.</p>
         </li>
         
         
-        <li id="section-30">
+        <li id="section-29">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-30">&#182;</a>
+                <a class="pilcrow" href="#section-29">&#182;</a>
               </div>
               <p>Function Parameters</p>
 
@@ -767,11 +757,11 @@ that hoovers up the remaining arguments.</p>
         </li>
         
         
-        <li id="section-31">
+        <li id="section-30">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-31">&#182;</a>
+                <a class="pilcrow" href="#section-30">&#182;</a>
               </div>
               <p>A splat that occurs outside of a parameter list.</p>
 
@@ -779,6 +769,26 @@ that hoovers up the remaining arguments.</p>
             
             <div class="content"><div class='highlight'><pre>  Splat: [
     o <span class="hljs-string">'Expression ...'</span>,                         <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Splat $<span class="hljs-number">1</span>
+    o <span class="hljs-string">'... Expression'</span>,                         <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Splat $<span class="hljs-number">2</span>
+  ]</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-31">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-31">&#182;</a>
+              </div>
+              <p>Variables and properties that can be assigned to.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>  SimpleAssignable: [
+    o <span class="hljs-string">'Identifier'</span>,                             <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Value $<span class="hljs-number">1</span>
+    o <span class="hljs-string">'Value Accessor'</span>,                         <span class="hljs-function">-&gt;</span> $<span class="hljs-number">1.</span>add $<span class="hljs-number">2</span>
+    o <span class="hljs-string">'ThisProperty'</span>
   ]</pre></div></div>
             
         </li>
@@ -790,26 +800,6 @@ that hoovers up the remaining arguments.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-32">&#182;</a>
               </div>
-              <p>Variables and properties that can be assigned to.</p>
-
-            </div>
-            
-            <div class="content"><div class='highlight'><pre>  SimpleAssignable: [
-    o <span class="hljs-string">'Identifier'</span>,                             <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Value $<span class="hljs-number">1</span>
-    o <span class="hljs-string">'Value Accessor'</span>,                         <span class="hljs-function">-&gt;</span> $<span class="hljs-number">1.</span>add $<span class="hljs-number">2</span>
-    o <span class="hljs-string">'Invocation Accessor'</span>,                    <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Value $<span class="hljs-number">1</span>, [].concat $<span class="hljs-number">2</span>
-    o <span class="hljs-string">'ThisProperty'</span>
-  ]</pre></div></div>
-            
-        </li>
-        
-        
-        <li id="section-33">
-            <div class="annotation">
-              
-              <div class="pilwrap ">
-                <a class="pilcrow" href="#section-33">&#182;</a>
-              </div>
               <p>Everything that can be assigned to.</p>
 
             </div>
@@ -823,11 +813,11 @@ that hoovers up the remaining arguments.</p>
         </li>
         
         
-        <li id="section-34">
+        <li id="section-33">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-34">&#182;</a>
+                <a class="pilcrow" href="#section-33">&#182;</a>
               </div>
               <p>The types of things that can be treated as values – assigned to, invoked
 as functions, indexed into, named as a class, etc.</p>
@@ -839,8 +829,27 @@ as functions, indexed into, named as a class, etc.</p>
     o <span class="hljs-string">'Literal'</span>,                                <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Value $<span class="hljs-number">1</span>
     o <span class="hljs-string">'Parenthetical'</span>,                          <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Value $<span class="hljs-number">1</span>
     o <span class="hljs-string">'Range'</span>,                                  <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Value $<span class="hljs-number">1</span>
+    o <span class="hljs-string">'Invocation'</span>,                             <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Value $<span class="hljs-number">1</span>
     o <span class="hljs-string">'This'</span>
-    o <span class="hljs-string">'Super'</span>
+    o <span class="hljs-string">'Super'</span>,                                  <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Value $<span class="hljs-number">1</span>
+  ]</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-34">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-34">&#182;</a>
+              </div>
+              <p>A <code>super</code>-based expression that can be used as a value.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>  Super: [
+    o <span class="hljs-string">'SUPER . Property'</span>,                       <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Super LOC(<span class="hljs-number">3</span>)(<span class="hljs-keyword">new</span> Access $<span class="hljs-number">3</span>), [], <span class="hljs-literal">no</span>, $<span class="hljs-number">1</span>
+    o <span class="hljs-string">'SUPER INDEX_START Expression INDEX_END'</span>, <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Super LOC(<span class="hljs-number">3</span>)(<span class="hljs-keyword">new</span> Index $<span class="hljs-number">3</span>),  [], <span class="hljs-literal">no</span>, $<span class="hljs-number">1</span>
   ]</pre></div></div>
             
         </li>
@@ -852,24 +861,6 @@ as functions, indexed into, named as a class, etc.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-35">&#182;</a>
               </div>
-              <p>A <code>super</code>-based expression that can be used as a value.</p>
-
-            </div>
-            
-            <div class="content"><div class='highlight'><pre>  Super: [
-    o <span class="hljs-string">'SUPER . Property'</span>,                       <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Super LOC(<span class="hljs-number">3</span>) <span class="hljs-keyword">new</span> Access $<span class="hljs-number">3</span>
-    o <span class="hljs-string">'SUPER INDEX_START Expression INDEX_END'</span>, <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Super LOC(<span class="hljs-number">3</span>) <span class="hljs-keyword">new</span> Index $<span class="hljs-number">3</span>
-  ]</pre></div></div>
-            
-        </li>
-        
-        
-        <li id="section-36">
-            <div class="annotation">
-              
-              <div class="pilwrap ">
-                <a class="pilcrow" href="#section-36">&#182;</a>
-              </div>
               <p>The general group of accessors into an object, by property, by prototype
 or by array index or slice.</p>
 
@@ -887,11 +878,11 @@ or by array index or slice.</p>
         </li>
         
         
-        <li id="section-37">
+        <li id="section-36">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-37">&#182;</a>
+                <a class="pilcrow" href="#section-36">&#182;</a>
               </div>
               <p>Indexing into an object or array using bracket notation.</p>
 
@@ -899,7 +890,7 @@ or by array index or slice.</p>
             
             <div class="content"><div class='highlight'><pre>  Index: [
     o <span class="hljs-string">'INDEX_START IndexValue INDEX_END'</span>,       <span class="hljs-function">-&gt;</span> $<span class="hljs-number">2</span>
-    o <span class="hljs-string">'INDEX_SOAK  Index'</span>,                      <span class="hljs-function">-&gt;</span> extend $<span class="hljs-number">2</span>, soak : <span class="hljs-literal">yes</span>
+    o <span class="hljs-string">'INDEX_SOAK  Index'</span>,                      <span class="hljs-function">-&gt;</span> extend $<span class="hljs-number">2</span>, soak: <span class="hljs-literal">yes</span>
   ]
 
   IndexValue: [
@@ -910,11 +901,11 @@ or by array index or slice.</p>
         </li>
         
         
-        <li id="section-38">
+        <li id="section-37">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-38">&#182;</a>
+                <a class="pilcrow" href="#section-37">&#182;</a>
               </div>
               <p>In CoffeeScript, an object literal is simply a list of assignments.</p>
 
@@ -927,11 +918,11 @@ or by array index or slice.</p>
         </li>
         
         
-        <li id="section-39">
+        <li id="section-38">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-39">&#182;</a>
+                <a class="pilcrow" href="#section-38">&#182;</a>
               </div>
               <p>Assignment of properties within an object literal can be separated by
 comma, as in JavaScript, or simply by newline.</p>
@@ -949,11 +940,11 @@ comma, as in JavaScript, or simply by newline.</p>
         </li>
         
         
-        <li id="section-40">
+        <li id="section-39">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-40">&#182;</a>
+                <a class="pilcrow" href="#section-39">&#182;</a>
               </div>
               <p>Class definitions have optional bodies of prototype property assignments,
 and optional references to the superclass.</p>
@@ -1038,11 +1029,11 @@ and optional references to the superclass.</p>
         </li>
         
         
-        <li id="section-41">
+        <li id="section-40">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-41">&#182;</a>
+                <a class="pilcrow" href="#section-40">&#182;</a>
               </div>
               <p>Ordinary function invocation, or a chained series of calls.</p>
 
@@ -1051,18 +1042,17 @@ and optional references to the superclass.</p>
             <div class="content"><div class='highlight'><pre>  Invocation: [
     o <span class="hljs-string">'Value OptFuncExist String'</span>,              <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> TaggedTemplateCall $<span class="hljs-number">1</span>, $<span class="hljs-number">3</span>, $<span class="hljs-number">2</span>
     o <span class="hljs-string">'Value OptFuncExist Arguments'</span>,           <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Call $<span class="hljs-number">1</span>, $<span class="hljs-number">3</span>, $<span class="hljs-number">2</span>
-    o <span class="hljs-string">'Invocation OptFuncExist Arguments'</span>,      <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Call $<span class="hljs-number">1</span>, $<span class="hljs-number">3</span>, $<span class="hljs-number">2</span>
-    o <span class="hljs-string">'SUPER OptFuncExist Arguments'</span>,           <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> SuperCall LOC(<span class="hljs-number">1</span>)(<span class="hljs-keyword">new</span> Super), $<span class="hljs-number">3</span>, $<span class="hljs-number">2</span>
+    o <span class="hljs-string">'SUPER OptFuncExist Arguments'</span>,           <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> SuperCall LOC(<span class="hljs-number">1</span>)(<span class="hljs-keyword">new</span> Super), $<span class="hljs-number">3</span>, $<span class="hljs-number">2</span>, $<span class="hljs-number">1</span>
   ]</pre></div></div>
             
         </li>
         
         
-        <li id="section-42">
+        <li id="section-41">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-42">&#182;</a>
+                <a class="pilcrow" href="#section-41">&#182;</a>
               </div>
               <p>An optional existence check on a function.</p>
 
@@ -1076,11 +1066,11 @@ and optional references to the superclass.</p>
         </li>
         
         
-        <li id="section-43">
+        <li id="section-42">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-43">&#182;</a>
+                <a class="pilcrow" href="#section-42">&#182;</a>
               </div>
               <p>The list of arguments to a function call.</p>
 
@@ -1094,19 +1084,36 @@ and optional references to the superclass.</p>
         </li>
         
         
-        <li id="section-44">
+        <li id="section-43">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-44">&#182;</a>
+                <a class="pilcrow" href="#section-43">&#182;</a>
               </div>
               <p>A reference to the <em>this</em> current object.</p>
 
             </div>
             
             <div class="content"><div class='highlight'><pre>  This: [
-    o <span class="hljs-string">'THIS'</span>,                                   <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Value <span class="hljs-keyword">new</span> ThisLiteral
-    o <span class="hljs-string">'@'</span>,                                      <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Value <span class="hljs-keyword">new</span> ThisLiteral
+    o <span class="hljs-string">'THIS'</span>,                                   <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Value <span class="hljs-keyword">new</span> ThisLiteral $<span class="hljs-number">1</span>
+    o <span class="hljs-string">'@'</span>,                                      <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Value <span class="hljs-keyword">new</span> ThisLiteral $<span class="hljs-number">1</span>
+  ]</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-44">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-44">&#182;</a>
+              </div>
+              <p>A reference to a property on <em>this</em>.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>  ThisProperty: [
+    o <span class="hljs-string">'@ Property'</span>,                             <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Value LOC(<span class="hljs-number">1</span>)(<span class="hljs-keyword">new</span> ThisLiteral $<span class="hljs-number">1</span>), [LOC(<span class="hljs-number">2</span>)(<span class="hljs-keyword">new</span> Access($<span class="hljs-number">2</span>))], <span class="hljs-string">'this'</span>
   ]</pre></div></div>
             
         </li>
@@ -1118,23 +1125,6 @@ and optional references to the superclass.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-45">&#182;</a>
               </div>
-              <p>A reference to a property on <em>this</em>.</p>
-
-            </div>
-            
-            <div class="content"><div class='highlight'><pre>  ThisProperty: [
-    o <span class="hljs-string">'@ Property'</span>,                             <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Value LOC(<span class="hljs-number">1</span>)(<span class="hljs-keyword">new</span> ThisLiteral), [LOC(<span class="hljs-number">2</span>)(<span class="hljs-keyword">new</span> Access($<span class="hljs-number">2</span>))], <span class="hljs-string">'this'</span>
-  ]</pre></div></div>
-            
-        </li>
-        
-        
-        <li id="section-46">
-            <div class="annotation">
-              
-              <div class="pilwrap ">
-                <a class="pilcrow" href="#section-46">&#182;</a>
-              </div>
               <p>The array literal.</p>
 
             </div>
@@ -1147,11 +1137,11 @@ and optional references to the superclass.</p>
         </li>
         
         
-        <li id="section-47">
+        <li id="section-46">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-47">&#182;</a>
+                <a class="pilcrow" href="#section-46">&#182;</a>
               </div>
               <p>Inclusive and exclusive range dots.</p>
 
@@ -1165,11 +1155,11 @@ and optional references to the superclass.</p>
         </li>
         
         
-        <li id="section-48">
+        <li id="section-47">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-48">&#182;</a>
+                <a class="pilcrow" href="#section-47">&#182;</a>
               </div>
               <p>The CoffeeScript range literal.</p>
 
@@ -1182,11 +1172,11 @@ and optional references to the superclass.</p>
         </li>
         
         
-        <li id="section-49">
+        <li id="section-48">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-49">&#182;</a>
+                <a class="pilcrow" href="#section-48">&#182;</a>
               </div>
               <p>Array slice literals.</p>
 
@@ -1202,11 +1192,11 @@ and optional references to the superclass.</p>
         </li>
         
         
-        <li id="section-50">
+        <li id="section-49">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-50">&#182;</a>
+                <a class="pilcrow" href="#section-49">&#182;</a>
               </div>
               <p>The <strong>ArgList</strong> is both the list of objects passed into a function call,
 as well as the contents of an array literal
@@ -1225,11 +1215,11 @@ as well as the contents of an array literal
         </li>
         
         
-        <li id="section-51">
+        <li id="section-50">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-51">&#182;</a>
+                <a class="pilcrow" href="#section-50">&#182;</a>
               </div>
               <p>Valid arguments are Blocks or Splats.</p>
 
@@ -1244,11 +1234,11 @@ as well as the contents of an array literal
         </li>
         
         
-        <li id="section-52">
+        <li id="section-51">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-52">&#182;</a>
+                <a class="pilcrow" href="#section-51">&#182;</a>
               </div>
               <p>Just simple, comma-separated, required arguments (no fancy syntax). We need
 this to be separate from the <strong>ArgList</strong> for use in <strong>Switch</strong> blocks, where
@@ -1264,11 +1254,11 @@ having the newlines wouldn’t make sense.</p>
         </li>
         
         
-        <li id="section-53">
+        <li id="section-52">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-53">&#182;</a>
+                <a class="pilcrow" href="#section-52">&#182;</a>
               </div>
               <p>The variants of <em>try/catch/finally</em> exception handling blocks.</p>
 
@@ -1284,11 +1274,11 @@ having the newlines wouldn’t make sense.</p>
         </li>
         
         
-        <li id="section-54">
+        <li id="section-53">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-54">&#182;</a>
+                <a class="pilcrow" href="#section-53">&#182;</a>
               </div>
               <p>A catch clause names its error and runs a block of code.</p>
 
@@ -1303,11 +1293,11 @@ having the newlines wouldn’t make sense.</p>
         </li>
         
         
-        <li id="section-55">
+        <li id="section-54">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-55">&#182;</a>
+                <a class="pilcrow" href="#section-54">&#182;</a>
               </div>
               <p>Throw an exception object.</p>
 
@@ -1315,16 +1305,17 @@ having the newlines wouldn’t make sense.</p>
             
             <div class="content"><div class='highlight'><pre>  Throw: [
     o <span class="hljs-string">'THROW Expression'</span>,                       <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Throw $<span class="hljs-number">2</span>
+    o <span class="hljs-string">'THROW INDENT Object OUTDENT'</span>,            <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Throw <span class="hljs-keyword">new</span> Value $<span class="hljs-number">3</span>
   ]</pre></div></div>
             
         </li>
         
         
-        <li id="section-56">
+        <li id="section-55">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-56">&#182;</a>
+                <a class="pilcrow" href="#section-55">&#182;</a>
               </div>
               <p>Parenthetical expressions. Note that the <strong>Parenthetical</strong> is a <strong>Value</strong>,
 not an <strong>Expression</strong>, so if you need to use an expression in a place
@@ -1341,11 +1332,11 @@ the trick.</p>
         </li>
         
         
-        <li id="section-57">
+        <li id="section-56">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-57">&#182;</a>
+                <a class="pilcrow" href="#section-56">&#182;</a>
               </div>
               <p>The condition portion of a while loop.</p>
 
@@ -1361,11 +1352,11 @@ the trick.</p>
         </li>
         
         
-        <li id="section-58">
+        <li id="section-57">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-58">&#182;</a>
+                <a class="pilcrow" href="#section-57">&#182;</a>
               </div>
               <p>The while loop can either be normal, with a block of expressions to execute,
 or postfix, with a single expression. There is no do..while.</p>
@@ -1387,11 +1378,11 @@ or postfix, with a single expression. There is no do..while.</p>
         </li>
         
         
-        <li id="section-59">
+        <li id="section-58">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-59">&#182;</a>
+                <a class="pilcrow" href="#section-58">&#182;</a>
               </div>
               <p>Array, object, and range comprehensions, at the most generic level.
 Comprehensions can either be normal, with a block of expressions to execute,
@@ -1419,11 +1410,11 @@ or postfix, with a single expression.</p>
         </li>
         
         
-        <li id="section-60">
+        <li id="section-59">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-60">&#182;</a>
+                <a class="pilcrow" href="#section-59">&#182;</a>
               </div>
               <p>An array of all accepted values for a variable inside the loop.
 This enables support for pattern matching.</p>
@@ -1440,11 +1431,11 @@ This enables support for pattern matching.</p>
         </li>
         
         
-        <li id="section-61">
+        <li id="section-60">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-61">&#182;</a>
+                <a class="pilcrow" href="#section-60">&#182;</a>
               </div>
               <p>An array or range comprehension has variables for the current element
 and (optional) reference to the current index. Or, <em>key, value</em>, in the case
@@ -1460,11 +1451,11 @@ of object comprehensions.</p>
         </li>
         
         
-        <li id="section-62">
+        <li id="section-61">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-62">&#182;</a>
+                <a class="pilcrow" href="#section-61">&#182;</a>
               </div>
               <p>The source of a comprehension is an array or object with an optional guard
 clause. If it’s an array comprehension, you can also choose to step through
@@ -1499,11 +1490,11 @@ in fixed-size increments.</p>
         </li>
         
         
-        <li id="section-63">
+        <li id="section-62">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-63">&#182;</a>
+                <a class="pilcrow" href="#section-62">&#182;</a>
               </div>
               <p>An individual <strong>When</strong> clause, with action.</p>
 
@@ -1517,11 +1508,11 @@ in fixed-size increments.</p>
         </li>
         
         
-        <li id="section-64">
+        <li id="section-63">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-64">&#182;</a>
+                <a class="pilcrow" href="#section-63">&#182;</a>
               </div>
               <p>The most basic form of <em>if</em> is a condition and an action. The following
 if-related rules are broken up along these lines in order to avoid
@@ -1537,11 +1528,11 @@ ambiguity.</p>
         </li>
         
         
-        <li id="section-65">
+        <li id="section-64">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-65">&#182;</a>
+                <a class="pilcrow" href="#section-64">&#182;</a>
               </div>
               <p>The full complement of <em>if</em> expressions, including postfix one-liner
 <em>if</em> and <em>unless</em>.</p>
@@ -1558,11 +1549,11 @@ ambiguity.</p>
         </li>
         
         
-        <li id="section-66">
+        <li id="section-65">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-66">&#182;</a>
+                <a class="pilcrow" href="#section-65">&#182;</a>
               </div>
               <p>Arithmetic and logical operators, working on one or more operands.
 Here they are grouped by order of precedence. The actual precedence rules
@@ -1589,11 +1580,11 @@ rules are necessary.</p>
         </li>
         
         
-        <li id="section-67">
+        <li id="section-66">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-67">&#182;</a>
+                <a class="pilcrow" href="#section-66">&#182;</a>
               </div>
               <p><a href="http://coffeescript.org/#existential-operator">The existential operator</a>.</p>
 
@@ -1631,14 +1622,26 @@ rules are necessary.</p>
         </li>
         
         
+        <li id="section-67">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-67">&#182;</a>
+              </div>
+              <h2 id="precedence">Precedence</h2>
+
+            </div>
+            
+        </li>
+        
+        
         <li id="section-68">
             <div class="annotation">
               
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-68">&#182;</a>
               </div>
-              <h2 id="precedence">Precedence</h2>
-
+              
             </div>
             
         </li>
@@ -1650,18 +1653,6 @@ rules are necessary.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-69">&#182;</a>
               </div>
-              
-            </div>
-            
-        </li>
-        
-        
-        <li id="section-70">
-            <div class="annotation">
-              
-              <div class="pilwrap ">
-                <a class="pilcrow" href="#section-70">&#182;</a>
-              </div>
               <p>Operators at the top of this list have higher precedence than the ones lower
 down. Following these rules is what makes <code>2 + 3 * 4</code> parse as:</p>
 <pre><code><span class="hljs-number">2</span> + (<span class="hljs-number">3</span> * <span class="hljs-number">4</span>)
@@ -1701,14 +1692,26 @@ down. Following these rules is what makes <code>2 + 3 * 4</code> parse as:</p>
         </li>
         
         
+        <li id="section-70">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-70">&#182;</a>
+              </div>
+              <h2 id="wrapping-up">Wrapping Up</h2>
+
+            </div>
+            
+        </li>
+        
+        
         <li id="section-71">
             <div class="annotation">
               
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-71">&#182;</a>
               </div>
-              <h2 id="wrapping-up">Wrapping Up</h2>
-
+              
             </div>
             
         </li>
@@ -1720,18 +1723,6 @@ down. Following these rules is what makes <code>2 + 3 * 4</code> parse as:</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-72">&#182;</a>
               </div>
-              
-            </div>
-            
-        </li>
-        
-        
-        <li id="section-73">
-            <div class="annotation">
-              
-              <div class="pilwrap ">
-                <a class="pilcrow" href="#section-73">&#182;</a>
-              </div>
               <p>Finally, now that we have our <strong>grammar</strong> and our <strong>operators</strong>, we can create
 our <strong>Jison.Parser</strong>. We do this by processing all of our rules, recording all
 terminals (every symbol which does not appear as the name of a rule above)
@@ -1750,11 +1741,11 @@ as “tokens”.</p>
         </li>
         
         
-        <li id="section-74">
+        <li id="section-73">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-74">&#182;</a>
+                <a class="pilcrow" href="#section-73">&#182;</a>
               </div>
               <p>Initialize the <strong>Parser</strong> with our list of terminal <strong>tokens</strong>, our <strong>grammar</strong>
 rules, and the name of the root. Reverse the operators because Jison orders

docs/v2/annotated-source/helpers.html

@@ -382,7 +382,10 @@ If <code>last</code> is not provided, this will simply return <code>first</code>
     first_line: first.first_line
     first_column: first.first_column
     last_line: last.last_line
-    last_column: last.last_column</pre></div></div>
+    last_column: last.last_column
+<span class="hljs-function">
+<span class="hljs-title">buildLocationHash</span> = <span class="hljs-params">(loc)</span> -&gt;</span>
+  <span class="hljs-string">"<span class="hljs-subst">#{loc.first_line}</span>x<span class="hljs-subst">#{loc.first_column}</span>-<span class="hljs-subst">#{loc.last_line}</span>x<span class="hljs-subst">#{loc.last_column}</span>"</span></pre></div></div>
             
         </li>
         
@@ -399,12 +402,8 @@ The object is returned either way.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>exports.addLocationDataFn = <span class="hljs-function"><span class="hljs-params">(first, last)</span> -&gt;</span>
-  (obj) -&gt;
-    <span class="hljs-keyword">if</span> ((<span class="hljs-keyword">typeof</span> obj) <span class="hljs-keyword">is</span> <span class="hljs-string">'object'</span>) <span class="hljs-keyword">and</span> (!!obj[<span class="hljs-string">'updateLocationDataIfMissing'</span>])
-      obj.updateLocationDataIfMissing buildLocationData(first, last)
-
-    <span class="hljs-keyword">return</span> obj</pre></div></div>
+            <div class="content"><div class='highlight'><pre>exports.addDataToNode = <span class="hljs-function"><span class="hljs-params">(parserState, first, last)</span> -&gt;</span>
+  (obj) -&gt;</pre></div></div>
             
         </li>
         
@@ -415,6 +414,56 @@ The object is returned either way.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-16">&#182;</a>
               </div>
+              <p>Add location data</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>    <span class="hljs-keyword">if</span> obj?.updateLocationDataIfMissing? <span class="hljs-keyword">and</span> first?
+      obj.updateLocationDataIfMissing buildLocationData(first, last)</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-17">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-17">&#182;</a>
+              </div>
+              <p>Add comments data</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>    <span class="hljs-keyword">unless</span> parserState.tokenComments
+      parserState.tokenComments = {}
+      <span class="hljs-keyword">for</span> token <span class="hljs-keyword">in</span> parserState.parser.tokens <span class="hljs-keyword">when</span> token.comments
+        tokenHash = buildLocationHash token[<span class="hljs-number">2</span>]
+        <span class="hljs-keyword">unless</span> parserState.tokenComments[tokenHash]?
+          parserState.tokenComments[tokenHash] = token.comments
+        <span class="hljs-keyword">else</span>
+          parserState.tokenComments[tokenHash].push token.comments...
+
+    <span class="hljs-keyword">if</span> obj.locationData?
+      objHash = buildLocationHash obj.locationData
+      <span class="hljs-keyword">if</span> parserState.tokenComments[objHash]?
+        attachCommentsToNode parserState.tokenComments[objHash], obj
+
+    obj
+
+exports.attachCommentsToNode = attachCommentsToNode = <span class="hljs-function"><span class="hljs-params">(comments, node)</span> -&gt;</span>
+  <span class="hljs-keyword">return</span> <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> comments? <span class="hljs-keyword">or</span> comments.length <span class="hljs-keyword">is</span> <span class="hljs-number">0</span>
+  node.comments ?= []
+  node.comments.push comments...</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-18">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-18">&#182;</a>
+              </div>
               <p>Convert jison location data to a string.
 <code>obj</code> can be a token, or a locationData.</p>
 
@@ -433,11 +482,11 @@ The object is returned either way.</p>
         </li>
         
         
-        <li id="section-17">
+        <li id="section-19">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-17">&#182;</a>
+                <a class="pilcrow" href="#section-19">&#182;</a>
               </div>
               <p>A <code>.coffee.md</code> compatible version of <code>basename</code>, that returns the file sans-extension.</p>
 
@@ -456,11 +505,11 @@ The object is returned either way.</p>
         </li>
         
         
-        <li id="section-18">
+        <li id="section-20">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-18">&#182;</a>
+                <a class="pilcrow" href="#section-20">&#182;</a>
               </div>
               <p>Determine if a filename represents a CoffeeScript file.</p>
 
@@ -471,11 +520,11 @@ The object is returned either way.</p>
         </li>
         
         
-        <li id="section-19">
+        <li id="section-21">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-19">&#182;</a>
+                <a class="pilcrow" href="#section-21">&#182;</a>
               </div>
               <p>Determine if a filename represents a Literate CoffeeScript file.</p>
 
@@ -486,11 +535,11 @@ The object is returned either way.</p>
         </li>
         
         
-        <li id="section-20">
+        <li id="section-22">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-20">&#182;</a>
+                <a class="pilcrow" href="#section-22">&#182;</a>
               </div>
               <p>Throws a SyntaxError from a given location.
 The error’s <code>toString</code> will return an error message following the “standard”
@@ -507,11 +556,11 @@ marker showing where the error is.</p>
         </li>
         
         
-        <li id="section-21">
+        <li id="section-23">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-21">&#182;</a>
+                <a class="pilcrow" href="#section-23">&#182;</a>
               </div>
               <p>Instead of showing the compiler’s stacktrace, show our custom error message
 (this is useful when the error bubbles up in Node.js applications that
@@ -526,11 +575,11 @@ compile CoffeeScript for example).</p>
         </li>
         
         
-        <li id="section-22">
+        <li id="section-24">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-22">&#182;</a>
+                <a class="pilcrow" href="#section-24">&#182;</a>
               </div>
               <p>Update a compiler SyntaxError with source code information if it didn’t have
 it already.</p>
@@ -542,11 +591,11 @@ it already.</p>
         </li>
         
         
-        <li id="section-23">
+        <li id="section-25">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-23">&#182;</a>
+                <a class="pilcrow" href="#section-25">&#182;</a>
               </div>
               <p>Avoid screwing up the <code>stack</code> property of other errors (i.e. possible bugs).</p>
 
@@ -572,11 +621,11 @@ it already.</p>
         </li>
         
         
-        <li id="section-24">
+        <li id="section-26">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-24">&#182;</a>
+                <a class="pilcrow" href="#section-26">&#182;</a>
               </div>
               <p>Show only the first line on multi-line errors.</p>
 
@@ -588,11 +637,11 @@ it already.</p>
         </li>
         
         
-        <li id="section-25">
+        <li id="section-27">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-25">&#182;</a>
+                <a class="pilcrow" href="#section-27">&#182;</a>
               </div>
               <p>Check to see if we’re running on a color-enabled TTY.</p>
 

docs/v2/annotated-source/optparse.html

@@ -157,8 +157,8 @@ command-line arguments in <code>src/command.coffee</code>.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>  constructor: <span class="hljs-function"><span class="hljs-params">(rules, @banner)</span> -&gt;</span>
-    @rules = buildRules rules</pre></div></div>
+            <div class="content"><div class='highlight'><pre>  constructor: <span class="hljs-function"><span class="hljs-params">(ruleDeclarations, @banner)</span> -&gt;</span>
+    @rules = buildRules ruleDeclarations</pre></div></div>
             
         </li>
         
@@ -178,20 +178,7 @@ you’re responsible for interpreting the options object.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>  parse: <span class="hljs-function"><span class="hljs-params">(args)</span> -&gt;</span>
-    options = arguments: []
-    skippingArgument = <span class="hljs-literal">no</span>
-    originalArgs = args
-    args = normalizeArguments args
-    <span class="hljs-keyword">for</span> arg, i <span class="hljs-keyword">in</span> args
-      <span class="hljs-keyword">if</span> skippingArgument
-        skippingArgument = <span class="hljs-literal">no</span>
-        <span class="hljs-keyword">continue</span>
-      <span class="hljs-keyword">if</span> arg <span class="hljs-keyword">is</span> <span class="hljs-string">'--'</span>
-        pos = originalArgs.indexOf <span class="hljs-string">'--'</span>
-        options.arguments = options.arguments.concat originalArgs[(pos + <span class="hljs-number">1</span>)..]
-        <span class="hljs-keyword">break</span>
-      isOption = !!(arg.match(LONG_FLAG) <span class="hljs-keyword">or</span> arg.match(SHORT_FLAG))</pre></div></div>
+            <div class="content"><div class='highlight'><pre>  parse: <span class="hljs-function"><span class="hljs-params">(args)</span> -&gt;</span></pre></div></div>
             
         </li>
         
@@ -202,27 +189,18 @@ you’re responsible for interpreting the options object.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-5">&#182;</a>
               </div>
-              <p>the CS option parser is a little odd; options after the first
-non-option argument are treated as non-option arguments themselves</p>
+              <p>The CoffeeScript option parser is a little odd; options after the first
+non-option argument are treated as non-option arguments themselves.
+Optional arguments are normalized by expanding merged flags into multiple
+flags. This allows you to have <code>-wl</code> be the same as <code>--watch --lint</code>.
+Note that executable scripts with a shebang (<code>#!</code>) line should use the
+line <code>#!/usr/bin/env coffee</code>, or <code>#!/absolute/path/to/coffee</code>, without a
+<code>--</code> argument after, because that will fail on Linux (see #3946).</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>      seenNonOptionArg = options.arguments.length &gt; <span class="hljs-number">0</span>
-      <span class="hljs-keyword">unless</span> seenNonOptionArg
-        matchedRule = <span class="hljs-literal">no</span>
-        <span class="hljs-keyword">for</span> rule <span class="hljs-keyword">in</span> @rules
-          <span class="hljs-keyword">if</span> rule.shortFlag <span class="hljs-keyword">is</span> arg <span class="hljs-keyword">or</span> rule.longFlag <span class="hljs-keyword">is</span> arg
-            value = <span class="hljs-literal">true</span>
-            <span class="hljs-keyword">if</span> rule.hasArgument
-              skippingArgument = <span class="hljs-literal">yes</span>
-              value = args[i + <span class="hljs-number">1</span>]
-            options[rule.name] = <span class="hljs-keyword">if</span> rule.isList <span class="hljs-keyword">then</span> (options[rule.name] <span class="hljs-keyword">or</span> []).concat value <span class="hljs-keyword">else</span> value
-            matchedRule = <span class="hljs-literal">yes</span>
-            <span class="hljs-keyword">break</span>
-        <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> Error <span class="hljs-string">"unrecognized option: <span class="hljs-subst">#{arg}</span>"</span> <span class="hljs-keyword">if</span> isOption <span class="hljs-keyword">and</span> <span class="hljs-keyword">not</span> matchedRule
-      <span class="hljs-keyword">if</span> seenNonOptionArg <span class="hljs-keyword">or</span> <span class="hljs-keyword">not</span> isOption
-        options.arguments.push arg
-    options</pre></div></div>
+            <div class="content"><div class='highlight'><pre>    {rules, positional} = normalizeArguments args, @rules.flagDict
+    options = {}</pre></div></div>
             
         </li>
         
@@ -233,20 +211,27 @@ non-option argument are treated as non-option arguments themselves</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-6">&#182;</a>
               </div>
-              <p>Return the help text for this <strong>OptionParser</strong>, listing and describing all
-of the valid options, for <code>--help</code> and such.</p>
+              <p>The <code>argument</code> field is added to the rule instance non-destructively by
+<code>normalizeArguments</code>.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>  help: <span class="hljs-function">-&gt;</span>
-    lines = []
-    lines.unshift <span class="hljs-string">"<span class="hljs-subst">#{@banner}</span>\n"</span> <span class="hljs-keyword">if</span> @banner
-    <span class="hljs-keyword">for</span> rule <span class="hljs-keyword">in</span> @rules
-      spaces  = <span class="hljs-number">15</span> - rule.longFlag.length
-      spaces  = <span class="hljs-keyword">if</span> spaces &gt; <span class="hljs-number">0</span> <span class="hljs-keyword">then</span> repeat <span class="hljs-string">' '</span>, spaces <span class="hljs-keyword">else</span> <span class="hljs-string">''</span>
-      letPart = <span class="hljs-keyword">if</span> rule.shortFlag <span class="hljs-keyword">then</span> rule.shortFlag + <span class="hljs-string">', '</span> <span class="hljs-keyword">else</span> <span class="hljs-string">'    '</span>
-      lines.push <span class="hljs-string">'  '</span> + letPart + rule.longFlag + spaces + rule.description
-    <span class="hljs-string">"\n<span class="hljs-subst">#{ lines.join(<span class="hljs-string">'\n'</span>) }</span>\n"</span></pre></div></div>
+            <div class="content"><div class='highlight'><pre>    <span class="hljs-keyword">for</span> {hasArgument, argument, isList, name} <span class="hljs-keyword">in</span> rules
+      <span class="hljs-keyword">if</span> hasArgument
+        <span class="hljs-keyword">if</span> isList
+          options[name] ?= []
+          options[name].push argument
+        <span class="hljs-keyword">else</span>
+          options[name] = argument
+      <span class="hljs-keyword">else</span>
+        options[name] = <span class="hljs-literal">true</span>
+
+    <span class="hljs-keyword">if</span> positional[<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'--'</span>
+      options.doubleDashed = <span class="hljs-literal">yes</span>
+      positional = positional[<span class="hljs-number">1.</span>.]
+
+    options.arguments = positional
+    options</pre></div></div>
             
         </li>
         
@@ -257,10 +242,21 @@ of the valid options, for <code>--help</code> and such.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-7">&#182;</a>
               </div>
-              <h2 id="helpers">Helpers</h2>
+              <p>Return the help text for this <strong>OptionParser</strong>, listing and describing all
+of the valid options, for <code>--help</code> and such.</p>
 
             </div>
             
+            <div class="content"><div class='highlight'><pre>  help: <span class="hljs-function">-&gt;</span>
+    lines = []
+    lines.unshift <span class="hljs-string">"<span class="hljs-subst">#{@banner}</span>\n"</span> <span class="hljs-keyword">if</span> @banner
+    <span class="hljs-keyword">for</span> rule <span class="hljs-keyword">in</span> @rules.ruleList
+      spaces  = <span class="hljs-number">15</span> - rule.longFlag.length
+      spaces  = <span class="hljs-keyword">if</span> spaces &gt; <span class="hljs-number">0</span> <span class="hljs-keyword">then</span> repeat <span class="hljs-string">' '</span>, spaces <span class="hljs-keyword">else</span> <span class="hljs-string">''</span>
+      letPart = <span class="hljs-keyword">if</span> rule.shortFlag <span class="hljs-keyword">then</span> rule.shortFlag + <span class="hljs-string">', '</span> <span class="hljs-keyword">else</span> <span class="hljs-string">'    '</span>
+      lines.push <span class="hljs-string">'  '</span> + letPart + rule.longFlag + spaces + rule.description
+    <span class="hljs-string">"\n<span class="hljs-subst">#{ lines.join(<span class="hljs-string">'\n'</span>) }</span>\n"</span></pre></div></div>
+            
         </li>
         
         
@@ -270,7 +266,8 @@ of the valid options, for <code>--help</code> and such.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-8">&#182;</a>
               </div>
-              
+              <h2 id="helpers">Helpers</h2>
+
             </div>
             
         </li>
@@ -282,15 +279,9 @@ of the valid options, for <code>--help</code> and such.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-9">&#182;</a>
               </div>
-              <p>Regex matchers for option flags.</p>
-
+              
             </div>
             
-            <div class="content"><div class='highlight'><pre>LONG_FLAG  = <span class="hljs-regexp">/^(--\w[\w\-]*)/</span>
-SHORT_FLAG = <span class="hljs-regexp">/^(-\w)$/</span>
-MULTI_FLAG = <span class="hljs-regexp">/^-(\w{2,})/</span>
-OPTIONAL   = <span class="hljs-regexp">/\[(\w+(\*?))\]/</span></pre></div></div>
-            
         </li>
         
         
@@ -300,15 +291,13 @@ OPTIONAL   = <span class="hljs-regexp">/\[(\w+(\*?))\]/</span></pre></div></div>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-10">&#182;</a>
               </div>
-              <p>Build and return the list of option rules. If the optional <em>short-flag</em> is
-unspecified, leave it out by padding with <code>null</code>.</p>
+              <p>Regex matchers for option flags on the command line and their rules.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">buildRules</span> = <span class="hljs-params">(rules)</span> -&gt;</span>
-  <span class="hljs-keyword">for</span> tuple <span class="hljs-keyword">in</span> rules
-    tuple.unshift <span class="hljs-literal">null</span> <span class="hljs-keyword">if</span> tuple.length &lt; <span class="hljs-number">3</span>
-    buildRule tuple...</pre></div></div>
+            <div class="content"><div class='highlight'><pre>LONG_FLAG  = <span class="hljs-regexp">/^(--\w[\w\-]*)/</span>
+SHORT_FLAG = <span class="hljs-regexp">/^(-\w)$/</span>
+MULTI_FLAG = <span class="hljs-regexp">/^-(\w{2,})/</span></pre></div></div>
             
         </li>
         
@@ -319,22 +308,12 @@ unspecified, leave it out by padding with <code>null</code>.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-11">&#182;</a>
               </div>
-              <p>Build a rule from a <code>-o</code> short flag, a <code>--output [DIR]</code> long flag, and the
-description of what the option does.</p>
+              <p>Matches the long flag part of a rule for an option with an argument. Not
+applied to anything in process.argv.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">buildRule</span> = <span class="hljs-params">(shortFlag, longFlag, description, options = {})</span> -&gt;</span>
-  match     = longFlag.match(OPTIONAL)
-  longFlag  = longFlag.match(LONG_FLAG)[<span class="hljs-number">1</span>]
-  {
-    name:         longFlag.substr <span class="hljs-number">2</span>
-    shortFlag:    shortFlag
-    longFlag:     longFlag
-    description:  description
-    hasArgument:  !!(match <span class="hljs-keyword">and</span> match[<span class="hljs-number">1</span>])
-    isList:       !!(match <span class="hljs-keyword">and</span> match[<span class="hljs-number">2</span>])
-  }</pre></div></div>
+            <div class="content"><div class='highlight'><pre>OPTIONAL   = <span class="hljs-regexp">/\[(\w+(\*?))\]/</span></pre></div></div>
             
         </li>
         
@@ -345,20 +324,156 @@ description of what the option does.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-12">&#182;</a>
               </div>
-              <p>Normalize arguments by expanding merged flags into multiple flags. This allows
-you to have <code>-wl</code> be the same as <code>--watch --lint</code>.</p>
+              <p>Build and return the list of option rules. If the optional <em>short-flag</em> is
+unspecified, leave it out by padding with <code>null</code>.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">normalizeArguments</span> = <span class="hljs-params">(args)</span> -&gt;</span>
-  args = args[..]
-  result = []
-  <span class="hljs-keyword">for</span> arg <span class="hljs-keyword">in</span> args
-    <span class="hljs-keyword">if</span> match = arg.match MULTI_FLAG
-      result.push <span class="hljs-string">'-'</span> + l <span class="hljs-keyword">for</span> l <span class="hljs-keyword">in</span> match[<span class="hljs-number">1</span>].split <span class="hljs-string">''</span>
-    <span class="hljs-keyword">else</span>
-      result.push arg
-  result</pre></div></div>
+            <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">buildRules</span> = <span class="hljs-params">(ruleDeclarations)</span> -&gt;</span>
+  ruleList = <span class="hljs-keyword">for</span> tuple <span class="hljs-keyword">in</span> ruleDeclarations
+    tuple.unshift <span class="hljs-literal">null</span> <span class="hljs-keyword">if</span> tuple.length &lt; <span class="hljs-number">3</span>
+    buildRule tuple...
+  flagDict = {}
+  <span class="hljs-keyword">for</span> rule <span class="hljs-keyword">in</span> ruleList</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-13">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-13">&#182;</a>
+              </div>
+              <p><code>shortFlag</code> is null if not provided in the rule.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>    <span class="hljs-keyword">for</span> flag <span class="hljs-keyword">in</span> [rule.shortFlag, rule.longFlag] <span class="hljs-keyword">when</span> flag?
+      <span class="hljs-keyword">if</span> flagDict[flag]?
+        <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> Error <span class="hljs-string">"flag <span class="hljs-subst">#{flag}</span> for switch <span class="hljs-subst">#{rule.name}</span>
+          was already declared for switch <span class="hljs-subst">#{flagDict[flag].name}</span>"</span>
+      flagDict[flag] = rule
+
+  {ruleList, flagDict}</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-14">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-14">&#182;</a>
+              </div>
+              <p>Build a rule from a <code>-o</code> short flag, a <code>--output [DIR]</code> long flag, and the
+description of what the option does.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">buildRule</span> = <span class="hljs-params">(shortFlag, longFlag, description)</span> -&gt;</span>
+  match     = longFlag.match(OPTIONAL)
+  shortFlag = shortFlag?.match(SHORT_FLAG)[<span class="hljs-number">1</span>]
+  longFlag  = longFlag.match(LONG_FLAG)[<span class="hljs-number">1</span>]
+  {
+    name:         longFlag.replace <span class="hljs-regexp">/^--/</span>, <span class="hljs-string">''</span>
+    shortFlag:    shortFlag
+    longFlag:     longFlag
+    description:  description
+    hasArgument:  !!(match <span class="hljs-keyword">and</span> match[<span class="hljs-number">1</span>])
+    isList:       !!(match <span class="hljs-keyword">and</span> match[<span class="hljs-number">2</span>])
+  }
+<span class="hljs-function">
+<span class="hljs-title">normalizeArguments</span> = <span class="hljs-params">(args, flagDict)</span> -&gt;</span>
+  rules = []
+  positional = []
+  needsArgOpt = <span class="hljs-literal">null</span>
+  <span class="hljs-keyword">for</span> arg, argIndex <span class="hljs-keyword">in</span> args</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-15">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-15">&#182;</a>
+              </div>
+              <p>If the previous argument given to the script was an option that uses the
+next command-line argument as its argument, create copy of the option’s
+rule with an <code>argument</code> field.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>    <span class="hljs-keyword">if</span> needsArgOpt?
+      withArg = Object.assign {}, needsArgOpt.rule, {argument: arg}
+      rules.push withArg
+      needsArgOpt = <span class="hljs-literal">null</span>
+      <span class="hljs-keyword">continue</span>
+
+    multiFlags = arg.match(MULTI_FLAG)?[<span class="hljs-number">1</span>]
+      .split(<span class="hljs-string">''</span>)
+      .map (flagName) -&gt; <span class="hljs-string">"-<span class="hljs-subst">#{flagName}</span>"</span>
+    <span class="hljs-keyword">if</span> multiFlags?
+      multiOpts = multiFlags.map (flag) -&gt;
+        rule = flagDict[flag]
+        <span class="hljs-keyword">unless</span> rule?
+          <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> Error <span class="hljs-string">"unrecognized option <span class="hljs-subst">#{flag}</span> in multi-flag <span class="hljs-subst">#{arg}</span>"</span>
+        {rule, flag}</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-16">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-16">&#182;</a>
+              </div>
+              <p>Only the last flag in a multi-flag may have an argument.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>      [innerOpts..., lastOpt] = multiOpts
+      <span class="hljs-keyword">for</span> {rule, flag} <span class="hljs-keyword">in</span> innerOpts
+        <span class="hljs-keyword">if</span> rule.hasArgument
+          <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> Error <span class="hljs-string">"cannot use option <span class="hljs-subst">#{flag}</span> in multi-flag <span class="hljs-subst">#{arg}</span> except
+          as the last option, because it needs an argument"</span>
+        rules.push rule
+      <span class="hljs-keyword">if</span> lastOpt.rule.hasArgument
+        needsArgOpt = lastOpt
+      <span class="hljs-keyword">else</span>
+        rules.push lastOpt.rule
+    <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> ([LONG_FLAG, SHORT_FLAG].some (pat) -&gt; arg.match(pat)?)
+      singleRule = flagDict[arg]
+      <span class="hljs-keyword">unless</span> singleRule?
+        <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> Error <span class="hljs-string">"unrecognized option <span class="hljs-subst">#{arg}</span>"</span>
+      <span class="hljs-keyword">if</span> singleRule.hasArgument
+        needsArgOpt = {rule: singleRule, flag: arg}
+      <span class="hljs-keyword">else</span>
+        rules.push singleRule
+    <span class="hljs-keyword">else</span></pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-17">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-17">&#182;</a>
+              </div>
+              <p>This is a positional argument.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>      positional = args[argIndex..]
+      <span class="hljs-keyword">break</span>
+
+  <span class="hljs-keyword">if</span> needsArgOpt?
+    <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> Error <span class="hljs-string">"value required for <span class="hljs-subst">#{needsArgOpt.flag}</span>, but it was the last
+    argument provided"</span>
+  {rules, positional}</pre></div></div>
             
         </li>
         

docs/v2/annotated-source/repl.html

@@ -125,6 +125,8 @@ nodeREPL = <span class="hljs-built_in">require</span> <span class="hljs-string">
 CoffeeScript = <span class="hljs-built_in">require</span> <span class="hljs-string">'./'</span>
 {merge, updateSyntaxError} = <span class="hljs-built_in">require</span> <span class="hljs-string">'./helpers'</span>
 
+sawSIGINT = <span class="hljs-literal">no</span>
+
 replDefaults =
   prompt: <span class="hljs-string">'coffee&gt; '</span>,
   historyFile: <span class="hljs-keyword">do</span> -&gt;
@@ -193,7 +195,7 @@ Unwrap that too.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>    {Block, Assign, Value, Literal} = <span class="hljs-built_in">require</span> <span class="hljs-string">'./nodes'</span>
+            <div class="content"><div class='highlight'><pre>    {Block, Assign, Value, Literal, Call, Code} = <span class="hljs-built_in">require</span> <span class="hljs-string">'./nodes'</span>
 
     <span class="hljs-keyword">try</span></pre></div></div>
             
@@ -225,9 +227,7 @@ Unwrap that too.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>      referencedVars = (
-        token[<span class="hljs-number">1</span>] <span class="hljs-keyword">for</span> token <span class="hljs-keyword">in</span> tokens <span class="hljs-keyword">when</span> token[<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'IDENTIFIER'</span>
-      )</pre></div></div>
+            <div class="content"><div class='highlight'><pre>      referencedVars = (token[<span class="hljs-number">1</span>] <span class="hljs-keyword">for</span> token <span class="hljs-keyword">in</span> tokens <span class="hljs-keyword">when</span> token[<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'IDENTIFIER'</span>)</pre></div></div>
             
         </li>
         
@@ -253,16 +253,11 @@ Unwrap that too.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-9">&#182;</a>
               </div>
-              <p>Add assignment to <code>_</code> variable to force the input to be an expression.</p>
+              <p>Add assignment to <code>__</code> variable to force the input to be an expression.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>      ast = <span class="hljs-keyword">new</span> Block [
-        <span class="hljs-keyword">new</span> Assign (<span class="hljs-keyword">new</span> Value <span class="hljs-keyword">new</span> Literal <span class="hljs-string">'__'</span>), ast, <span class="hljs-string">'='</span>
-      ]
-      js = ast.compile {bare: <span class="hljs-literal">yes</span>, locals: Object.keys(context), referencedVars}
-      cb <span class="hljs-literal">null</span>, runInContext js, context, filename
-    <span class="hljs-keyword">catch</span> err</pre></div></div>
+            <div class="content"><div class='highlight'><pre>      ast = <span class="hljs-keyword">new</span> Block [<span class="hljs-keyword">new</span> Assign (<span class="hljs-keyword">new</span> Value <span class="hljs-keyword">new</span> Literal <span class="hljs-string">'__'</span>), ast, <span class="hljs-string">'='</span>]</pre></div></div>
             
         </li>
         
@@ -273,6 +268,60 @@ Unwrap that too.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-10">&#182;</a>
               </div>
+              <p>Wrap the expression in a closure to support top-level <code>await</code></p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>      ast     = <span class="hljs-keyword">new</span> Code [], ast
+      isAsync = ast.isAsync</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-11">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-11">&#182;</a>
+              </div>
+              <p>Invoke the wrapping closure</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>      ast    = <span class="hljs-keyword">new</span> Block [<span class="hljs-keyword">new</span> Call ast]
+      js     = ast.compile {bare: <span class="hljs-literal">yes</span>, locals: Object.keys(context), referencedVars, sharedScope: <span class="hljs-literal">yes</span>}
+      result = runInContext js, context, filename</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-12">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-12">&#182;</a>
+              </div>
+              <p>Await an async result, if necessary</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>      <span class="hljs-keyword">if</span> isAsync
+        result = <span class="hljs-keyword">await</span> result
+        cb <span class="hljs-literal">null</span>, result <span class="hljs-keyword">unless</span> sawSIGINT
+        sawSIGINT = <span class="hljs-literal">false</span>
+      <span class="hljs-keyword">else</span>
+        cb <span class="hljs-literal">null</span>, result
+    <span class="hljs-keyword">catch</span> err</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-13">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-13">&#182;</a>
+              </div>
               <p>AST’s <code>compile</code> does not add source code information to syntax errors.</p>
 
             </div>
@@ -292,11 +341,11 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-11">
+        <li id="section-14">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-11">&#182;</a>
+                <a class="pilcrow" href="#section-14">&#182;</a>
               </div>
               <p>Node 0.11.12 changed API, prompt is now _prompt.</p>
 
@@ -313,11 +362,11 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-12">
+        <li id="section-15">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-12">&#182;</a>
+                <a class="pilcrow" href="#section-15">&#182;</a>
               </div>
               <p>Proxy node’s line listener</p>
 
@@ -338,11 +387,11 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-13">
+        <li id="section-16">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-13">&#182;</a>
+                <a class="pilcrow" href="#section-16">&#182;</a>
               </div>
               <p>Handle Ctrl-v</p>
 
@@ -355,11 +404,11 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-14">
+        <li id="section-17">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-14">&#182;</a>
+                <a class="pilcrow" href="#section-17">&#182;</a>
               </div>
               <p>allow arbitrarily switching between modes any time before multiple lines are entered</p>
 
@@ -374,11 +423,11 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-15">
+        <li id="section-18">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-15">&#182;</a>
+                <a class="pilcrow" href="#section-18">&#182;</a>
               </div>
               <p>no-op unless the current line is empty</p>
 
@@ -389,11 +438,11 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-16">
+        <li id="section-19">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-16">&#182;</a>
+                <a class="pilcrow" href="#section-19">&#182;</a>
               </div>
               <p>eval, print, loop</p>
 
@@ -408,11 +457,11 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-17">
+        <li id="section-20">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-17">&#182;</a>
+                <a class="pilcrow" href="#section-20">&#182;</a>
               </div>
               <p>XXX: multiline hack</p>
 
@@ -430,11 +479,11 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-18">
+        <li id="section-21">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-18">&#182;</a>
+                <a class="pilcrow" href="#section-21">&#182;</a>
               </div>
               <p>Store and load command history from a file</p>
 
@@ -447,11 +496,11 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-19">
+        <li id="section-22">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-19">&#182;</a>
+                <a class="pilcrow" href="#section-22">&#182;</a>
               </div>
               <p>Get file info and at most maxSize of command history</p>
 
@@ -463,11 +512,11 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-20">
+        <li id="section-23">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-20">&#182;</a>
+                <a class="pilcrow" href="#section-23">&#182;</a>
               </div>
               <p>Read last <code>size</code> bytes from the file</p>
 
@@ -481,11 +530,11 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-21">
+        <li id="section-24">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-21">&#182;</a>
+                <a class="pilcrow" href="#section-24">&#182;</a>
               </div>
               <p>Set the history on the interpreter</p>
 
@@ -496,11 +545,11 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-22">
+        <li id="section-25">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-22">&#182;</a>
+                <a class="pilcrow" href="#section-25">&#182;</a>
               </div>
               <p>If the history file was truncated we should pop off a potential partial line</p>
 
@@ -511,11 +560,11 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-23">
+        <li id="section-26">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-23">&#182;</a>
+                <a class="pilcrow" href="#section-26">&#182;</a>
               </div>
               <p>Shift off the final blank newline</p>
 
@@ -533,29 +582,43 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-24">
+        <li id="section-27">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-24">&#182;</a>
+                <a class="pilcrow" href="#section-27">&#182;</a>
               </div>
               <p>Save the latest command in the file</p>
 
             </div>
             
             <div class="content"><div class='highlight'><pre>      fs.writeSync fd, <span class="hljs-string">"<span class="hljs-subst">#{code}</span>\n"</span>
-      lastLine = code
+      lastLine = code</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-28">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-28">&#182;</a>
+              </div>
+              <p>XXX: The SIGINT event from REPLServer is undocumented, so this is a bit fragile</p>
 
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>  repl.<span class="hljs-literal">on</span> <span class="hljs-string">'SIGINT'</span>, <span class="hljs-function">-&gt;</span> sawSIGINT = <span class="hljs-literal">yes</span>
   repl.<span class="hljs-literal">on</span> <span class="hljs-string">'exit'</span>, <span class="hljs-function">-&gt;</span> fs.closeSync fd</pre></div></div>
             
         </li>
         
         
-        <li id="section-25">
+        <li id="section-29">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-25">&#182;</a>
+                <a class="pilcrow" href="#section-29">&#182;</a>
               </div>
               <p>Add a command to show the history stack</p>
 
@@ -572,11 +635,11 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-26">
+        <li id="section-30">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-26">&#182;</a>
+                <a class="pilcrow" href="#section-30">&#182;</a>
               </div>
               <p>Node 0.11 changed API, a command such as ‘.help’ is now stored as ‘help’</p>
 
@@ -605,11 +668,11 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-27">
+        <li id="section-31">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-27">&#182;</a>
+                <a class="pilcrow" href="#section-31">&#182;</a>
               </div>
               <p>Adapt help inherited from the node REPL</p>
 

docs/v2/index.html

@@ -306,7 +306,7 @@ td code {
   white-space: nowrap;
 }
 
-h2, h3 {
+h2, h3, h4 {
   margin-top: 1.3em;
   margin-bottom: 0.6em;
   font-family: 'Alegreya Sans';
@@ -314,7 +314,7 @@ h2, h3 {
 h2 {
   font-weight: 800;
 }
-h3, h2 time {
+h3, h4, h2 time {
   font-weight: 400;
 }
 
@@ -574,6 +574,17 @@ textarea {
     </li>
     <li class="nav-item">
       <a href="#usage" class="nav-link" data-action="sidebar-nav">Usage</a>
+      <ul class="nav">
+        <li class="nav-item">
+          <a href="#cli" class="nav-link" data-action="sidebar-nav">Command Line</a>
+        </li>
+        <li class="nav-item">
+          <a href="#es2015plus-output" class="nav-link" data-action="sidebar-nav">ES2015+ Output</a>
+        </li>
+        <li class="nav-item">
+          <a href="#nodejs-usage" class="nav-link" data-action="sidebar-nav">Node.js</a>
+        </li>
+      </ul>
     </li>
     <li class="nav-item">
       <a href="#language" class="nav-link" data-action="sidebar-nav">Language Reference</a>
@@ -658,6 +669,9 @@ textarea {
         </li>
       </ul>
     </li>
+    <li class="nav-item">
+      <a href="#type-annotations" class="nav-link" data-action="sidebar-nav">Type Annotations</a>
+    </li>
     <li class="nav-item">
       <a href="#literate" class="nav-link" data-action="sidebar-nav">Literate CoffeeScript</a>
     </li>
@@ -734,6 +748,9 @@ textarea {
         <li class="nav-item">
           <a href="#breaking-changes-literate-coffeescript" class="nav-link" data-action="sidebar-nav">Literate CoffeeScript Parsing</a>
         </li>
+        <li class="nav-item">
+          <a href="#breaking-changes-argument-parsing-and-shebang-lines" class="nav-link" data-action="sidebar-nav">Argument Parsing and <code>#!</code> Lines</a>
+        </li>
       </ul>
     </li>
     <li class="nav-item">
@@ -761,7 +778,7 @@ textarea {
       <section id="overview">
         <p><strong>CoffeeScript is a little language that compiles into JavaScript.</strong> Underneath that awkward Java-esque patina, JavaScript has always had a gorgeous heart. CoffeeScript is an attempt to expose the good parts of JavaScript in a simple way.</p>
 <p>The golden rule of CoffeeScript is: <em>“It’s just JavaScript.”</em> The code compiles one-to-one into the equivalent JS, and there is no interpretation at runtime. You can use any existing JavaScript library seamlessly from CoffeeScript (and vice-versa). The compiled output is readable, pretty-printed, and tends to run as fast or faster than the equivalent handwritten JavaScript.</p>
-<p><strong>Latest Version:</strong> <a href="https://github.com/jashkenas/coffeescript/tarball/2.0.0-beta3">2.0.0-beta3</a></p>
+<p><strong>Latest Version:</strong> <a href="https://github.com/jashkenas/coffeescript/tarball/2.0.0-beta4">2.0.0-beta4</a></p>
 <blockquote class="uneditable-code-block"><pre><code class="language-bash">npm install -g coffeescript@next
 </code></pre>
 </blockquote>
@@ -801,22 +818,27 @@ cubes = (math.cube num for num in list)
 </textarea>
     </div>
     <div class="col-md-6 javascript-output-column">
-      <textarea class="javascript-output" id="overview-js">var cubes, list, math, num, number, opposite, race, square;
+      <textarea class="javascript-output" id="overview-js">// Assignment:
+var cubes, list, math, num, number, opposite, race, square;
 
 number = 42;
 
 opposite = true;
 
 if (opposite) {
+  // Conditions:
   number = -42;
 }
 
+// Functions:
 square = function(x) {
   return x * x;
 };
 
+// Arrays:
 list = [1, 2, 3, 4, 5];
 
+// Objects:
 math = {
   root: Math.sqrt,
   square: square,
@@ -825,14 +847,17 @@ math = {
   }
 };
 
+// Splats:
 race = function(winner, ...runners) {
   return print(winner, runners);
 };
 
 if (typeof elvis !== "undefined" && elvis !== null) {
+  // Existence:
   alert("I knew it!");
 }
 
+// Array comprehensions:
 cubes = (function() {
   var i, len, results;
   results = [];
@@ -858,7 +883,7 @@ cubes = (function() {
       <section id="coffeescript-2">
         <h2>CoffeeScript 2</h2>
 <h3>What’s New In CoffeeScript 2?</h3>
-<p>The biggest change in CoffeeScript 2 is that now the CoffeeScript compiler produces modern, ES2015+ JavaScript. A CoffeeScript <code>=&gt;</code> becomes an ES <code>=&gt;</code>, a CoffeeScript <code>class</code> becomes an ES <code>class</code> and so on. With the exception of modules (<code>import</code> and <code>export</code> statements), all the ES2015+ 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; Chrome has supported all features since version 55.</p>
+<p>The biggest change in CoffeeScript 2 is that now the CoffeeScript compiler produces modern, ES2015+ JavaScript. A CoffeeScript <code>=&gt;</code> becomes an ES <code>=&gt;</code>, a CoffeeScript <code>class</code> becomes an ES <code>class</code> and so on. 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 ES2015+ 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; Chrome has supported all features since version 55.</p>
 <p>Support for ES2015+ syntax is important to ensure compatibility with frameworks that assume ES2015. Now that CoffeeScript compiles classes to the ES <code>class</code> keyword, it’s possible to <code>extend</code> an ES 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.</p>
 <p>Many ES2015+ features have been backported to CoffeeScript 1.11 and 1.12, including <a href="#modules">modules</a>, <a href="#generator-iteration"><code>for…of</code></a>, and <a href="#tagged-template-literals">tagged template literals</a>. Major new features unique to CoffeeScript 2 are support for ES2017’s <a href="#async-functions">async functions</a> and for <a href="#jsx">JSX</a>. More details are 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>
@@ -882,6 +907,9 @@ cubes = (function() {
       </section>
       <section id="usage">
         <h2>Usage</h2>
+
+        <section id="cli">
+          <h3>Command Line</h3>
 <p>Once installed, you should have access to the <code>coffee</code> command, which can execute scripts, compile <code>.coffee</code> files into <code>.js</code>, and provide an interactive REPL. The <code>coffee</code> command takes the following options:</p>
 <table>
 <thead>
@@ -957,7 +985,7 @@ cubes = (function() {
 </tr>
 </tbody>
 </table>
-<h3>Examples:</h3>
+<h4>Examples:</h4>
 <ul>
 <li>Compile a directory tree of <code>.coffee</code> files in <code>src</code> into a parallel tree of <code>.js</code> files in <code>lib</code>:<br>
 <code>coffee --compile --output lib/ src/</code></li>
@@ -972,15 +1000,21 @@ cubes = (function() {
 <li>Start the CoffeeScript REPL (<code>Ctrl-D</code> to exit, <code>Ctrl-V</code>for multi-line):<br>
 <code>coffee</code></li>
 </ul>
-<h3>ES2015+ Output</h3>
+
+        </section>
+        <section id="es2015plus-output">
+          <h3>ES2015+ Output</h3>
 <p>CoffeeScript 2 outputs the latest 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 <a href="/v1/">CoffeeScript 1.x</a>. CoffeeScript 2 <a href="#breaking-changes">breaks compatibility</a> with certain CoffeeScript 1.x features in order to conform with the ES2015+ specifications, and generate more idiomatic output (a CoffeeScript <code>=&gt;</code> becomes an ES <code>=&gt;</code>; a CoffeeScript <code>class</code> becomes an ES <code>class</code>; and so on).</p>
 <p>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 <a href="http://babeljs.io/">Babel</a>, <a href="https://github.com/rollup/rollup">Rollup</a> or <a href="https://github.com/google/traceur-compiler">Traceur Compiler</a>. In general, <a href="http://node.green/">CoffeeScript 2’s output is supported as is by Node.js 7.6+</a>, except for modules and JSX which require transpilation.</p>
 <p>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>. If you’re looking for a very minimal solution to get started, you can use <a href="https://babeljs.io/docs/plugins/preset-env/">babel-preset-env</a> and the command line:</p>
 <blockquote class="uneditable-code-block"><pre><code class="language-bash">npm install --global coffeescript@next
 npm install --save-dev coffeescript@next babel-cli babel-preset-env
-coffee --print *.coffee | babel --presets env &gt; app.js
+coffee --<span class="built_in">print</span> *.coffee | babel --presets env &gt; app.js
 </code></pre>
-</blockquote><h3>Node.js</h3>
+</blockquote>
+        </section>
+        <section id="nodejs-usage">
+          <h3>Node.js</h3>
 <p>If you’d like to use Node.js’ CommonJS to <code>require</code> CoffeeScript files, e.g. <code>require './app.coffee'</code>, you must first “register” CoffeeScript as an extension:</p>
 <blockquote class="uneditable-code-block"><pre><code class="language-coffee"><span class="built_in">require</span> <span class="string">'coffeescript/register'</span>
 
@@ -1000,6 +1034,7 @@ eval CoffeeScript.compile <span class="string">'console.log "Mmmmm, I could real
 <li><code>options.header</code>, boolean: if true, output the <code>Generated by CoffeeScript</code> header.</li>
 </ul>
 
+        </section>
       </section>
       <section id="language">
         <h2>Language Reference</h2>
@@ -1264,44 +1299,35 @@ output = `${turtle.name} wears an ${turtle.mask} mask. Watch out for his ${turtl
         </section>
         <section id="comments">
           <h2>Comments</h2>
-<p>In CoffeeScript, comments are denoted by the <code>#</code> character. Everything from a <code>#</code> to the end of the line is ignored by the compiler, and will be excluded from the JavaScript output.</p>
+<p>In CoffeeScript, comments are denoted by the <code>#</code> character to the end of a line, or from <code>###</code> to the next appearance of <code>###</code>. Comments are ignored by the compiler, though the compiler makes its best effort at reinserting your comments into the output JavaScript after compilation.</p>
 <aside class="code-example container-fluid bg-ribbed-dark" data-example="comment">
   <div class="row">
     <div class="col-md-6 coffeescript-input-column">
-      <textarea class="coffeescript-input" id="comment-coffee">code = 2 * 617 # The code is 1234
-</textarea>
-    </div>
-    <div class="col-md-6 javascript-output-column">
-      <textarea class="javascript-output" id="comment-js">var code;
-
-code = 2 * 617;
-</textarea>
-    </div>
-  </div>
-  
-</aside>
-<p>Sometimes you’d like to pass a block comment through to the generated JavaScript. For example, when you need to embed a licensing header at the top of a file. Block comments, which mirror the syntax for block strings, are preserved in the generated output.</p>
-<aside class="code-example container-fluid bg-ribbed-dark" data-example="block_comment">
-  <div class="row">
-    <div class="col-md-6 coffeescript-input-column">
-      <textarea class="coffeescript-input" id="block_comment-coffee">###
-SkinnyMochaHalfCaffScript Compiler v1.0
+      <textarea class="coffeescript-input" id="comment-coffee">###
+Fortune Cookie Reader v1.0
 Released under the MIT License
 ###
+
+sayFortune = (fortune) ->
+	console.log fortune # in bed!
 </textarea>
     </div>
     <div class="col-md-6 javascript-output-column">
-      <textarea class="javascript-output" id="block_comment-js">
-/*
-SkinnyMochaHalfCaffScript Compiler v1.0
+      <textarea class="javascript-output" id="comment-js">/*
+Fortune Cookie Reader v1.0
 Released under the MIT License
- */
+*/
+var sayFortune;
 
+sayFortune = function(fortune) {
+  return console.log(fortune); // in bed!
+};
 </textarea>
     </div>
   </div>
   
 </aside>
+<p>Inline <code>###</code> comments make <a href="#type-annotations">type annotations</a> possible.</p>
 
         </section>
         <section id="lexical-scope">
@@ -1535,7 +1561,8 @@ eat food for food in foods when food isnt 'chocolate'
 </textarea>
     </div>
     <div class="col-md-6 javascript-output-column">
-      <textarea class="javascript-output" id="array_comprehensions-js">var courses, dish, food, foods, i, j, k, l, len, len1, len2, ref;
+      <textarea class="javascript-output" id="array_comprehensions-js">// Eat lunch.
+var courses, dish, food, foods, i, j, k, l, len, len1, len2, ref;
 
 ref = ['toast', 'cheese', 'wine'];
 for (j = 0, len = ref.length; j < len; j++) {
@@ -1543,6 +1570,7 @@ for (j = 0, len = ref.length; j < len; j++) {
   eat(food);
 }
 
+// Fine five course dining.
 courses = ['greens', 'caviar', 'truffles', 'roast', 'cake'];
 
 for (i = k = 0, len1 = courses.length; k < len1; i = ++k) {
@@ -1550,6 +1578,7 @@ for (i = k = 0, len1 = courses.length; k < len1; i = ++k) {
   menu(i + 1, dish);
 }
 
+// Health conscious meal.
 foods = ['broccoli', 'spinach', 'chocolate'];
 
 for (l = 0, len2 = foods.length; l < len2; l++) {
@@ -1657,7 +1686,8 @@ lyrics = while num -= 1
 </textarea>
     </div>
     <div class="col-md-6 javascript-output-column">
-      <textarea class="javascript-output" id="while-js">var lyrics, num;
+      <textarea class="javascript-output" id="while-js">// Econ 101
+var lyrics, num;
 
 if (this.studyingEconomics) {
   while (supply > demand) {
@@ -1668,6 +1698,7 @@ if (this.studyingEconomics) {
   }
 }
 
+// Nursery Rhyme
 num = 6;
 
 lyrics = (function() {
@@ -1871,7 +1902,8 @@ globals = (name for name of window)[0...10]
 </textarea>
     </div>
     <div class="col-md-6 javascript-output-column">
-      <textarea class="javascript-output" id="expressions_comprehension-js">var globals, name;
+      <textarea class="javascript-output" id="expressions_comprehension-js">// The first ten global properties.
+var globals, name;
 
 globals = ((function() {
   var results;
@@ -1953,9 +1985,9 @@ tabs.selectTabAtIndex((tabs.currentIndex - count) %% tabs.length)
     <div class="col-md-6 javascript-output-column">
       <textarea class="javascript-output" id="modulo-js">var modulo = function(a, b) { return (+a % (b = +b) + b) % b; };
 
--7 % 5 === -2;
+-7 % 5 === -2; // The remainder of 7 / 5
 
-modulo(-7, 5) === 3;
+modulo(-7, 5) === 3; // n %% 5 is always between 0 and 4
 
 tabs.selectTabAtIndex(modulo(tabs.currentIndex - count, tabs.length));
 </textarea>
@@ -2279,6 +2311,7 @@ theSwitch = 0;
       <textarea class="javascript-output" id="multiple_return_values-js">var city, forecast, temp, weatherReport;
 
 weatherReport = function(location) {
+  // Make an Ajax request to fetch the weather...
   return [location, 72, "Mostly Sunny"];
 };
 
@@ -2597,7 +2630,9 @@ countdown 3
 </textarea>
     </div>
     <div class="col-md-6 javascript-output-column">
-      <textarea class="javascript-output" id="async-js">var countdown, say, sleep;
+      <textarea class="javascript-output" id="async-js">// Your browser must support async/await and speech synthesis
+// to run this example.
+var countdown, say, sleep;
 
 sleep = function(ms) {
   return new Promise(function(resolve) {
@@ -2614,7 +2649,7 @@ countdown = async function(seconds) {
   var i, j, ref;
   for (i = j = ref = seconds; ref <= 1 ? j <= 1 : j >= 1; i = ref <= 1 ? ++j : --j) {
     say(i);
-    await sleep(1000);
+    await sleep(1000); // wait one second
   }
   return say("Blastoff!");
 };
@@ -2867,6 +2902,8 @@ grade = (function() {
       return 'A';
   }
 })();
+
+// grade == 'C'
 </textarea>
     </div>
   </div>
@@ -2944,21 +2981,21 @@ healthy = (200 > cholesterol && cholesterol > 60);
 <aside class="code-example container-fluid bg-ribbed-dark" data-example="heregexes">
   <div class="row">
     <div class="col-md-6 coffeescript-input-column">
-      <textarea class="coffeescript-input" id="heregexes-coffee">OPERATOR = /// ^ (
-  ?: [-=]>             # function
-   | [-+*/%<>&|^!?=]=  # compound assign / compare
-   | >>>=?             # zero-fill right shift
-   | ([-+:])\1         # doubles
-   | ([&|<>])\2=?      # logic / shift
-   | \?\.              # soak access
-   | \.{2,3}           # range or splat
-) ///
+      <textarea class="coffeescript-input" id="heregexes-coffee">NUMBER     = ///
+  ^ 0b[01]+    |              # binary
+  ^ 0o[0-7]+   |              # octal
+  ^ 0x[\da-f]+ |              # hex
+  ^ \d*\.?\d+ (?:e[+-]?\d+)?  # decimal
+///i
 </textarea>
     </div>
     <div class="col-md-6 javascript-output-column">
-      <textarea class="javascript-output" id="heregexes-js">var OPERATOR;
+      <textarea class="javascript-output" id="heregexes-js">var NUMBER;
 
-OPERATOR = /^(?:[-=]>|[-+*\/%<>&|^!?=]=|>>>=?|([-+:])\1|([&|<>])\2=?|\?\.|\.{2,3})/;
+NUMBER = /^0b[01]+|^0o[0-7]+|^0x[\da-f]+|^\d*\.?\d+(?:e[+-]?\d+)?/i; // binary
+// octal
+// hex
+// decimal
 </textarea>
     </div>
   </div>
@@ -3244,10 +3281,41 @@ renderStarRating = function({rating, maxStars}) {
   </div>
   
 </aside>
-<p>Older plugins or forks of CoffeeScript supported JSX syntax and referred to it as CSX or CJSX. They also often used a <code>.cjsx</code> file extension, but this is no longer necessary; regalar <code>.coffee</code> will do.</p>
+<p>Older plugins or forks of CoffeeScript supported JSX syntax and referred to it as CSX or CJSX. They also often used a <code>.cjsx</code> file extension, but this is no longer necessary; regular <code>.coffee</code> will do.</p>
 
         </section>
       </section>
+      <section id="type-annotations">
+        <h2>Type Annotations</h2>
+<p>Static type checking can be achieved in CoffeeScript by using <a href="https://flow.org/">Flow</a>’s <a href="https://flow.org/en/docs/types/comments/">Comment Types syntax</a>:</p>
+<aside class="code-example container-fluid bg-ribbed-dark" data-example="type_annotations">
+  <div class="row">
+    <div class="col-md-6 coffeescript-input-column">
+      <textarea class="coffeescript-input" id="type_annotations-coffee"># @flow
+
+fn = (str ###: string ###, num ###: number ###) ###: string ### ->
+  str + num
+</textarea>
+    </div>
+    <div class="col-md-6 javascript-output-column">
+      <textarea class="javascript-output" id="type_annotations-js">// @flow
+var fn;
+
+fn = function(str/*: string */, num/*: number */)/*: string */ {
+  return str + num;
+};
+</textarea>
+    </div>
+  </div>
+  
+</aside>
+<p>CoffeeScript does not do any type checking itself; the JavaScript output you see above needs to get passed to Flow for it to validate your code. We expect most people will use a <a href="#es2015plus-output">build tool</a> for this, but here’s how to do it the simplest way possible using the <a href="#cli">CoffeeScript</a> and <a href="https://flow.org/en/docs/usage/">Flow</a> command-line tools, assuming you’ve already <a href="https://flow.org/en/docs/install/">installed Flow</a> and the <a href="#installation">latest CoffeeScript</a> in your project folder:</p>
+<blockquote class="uneditable-code-block"><pre><code class="language-bash">coffee --bare --no-header --compile app.coffee &amp;&amp; npm run flow
+</code></pre>
+</blockquote><p><code>--bare</code> and <code>--no-header</code> are important because Flow requires the first line of the file to be the comment <code>// @flow</code>. If you configure your build chain to compile CoffeeScript and pass the result to Flow in-memory, you can get better performance than this example; and a proper build tool should be able to watch your CoffeeScript files and recompile and type-check them for you on save.</p>
+<p>If you know of another way to achieve static type checking with CoffeeScript, please <a href="https://github.com/jashkenas/coffeescript/issues/new">create an issue</a> and let us know.</p>
+
+      </section>
       <section id="literate">
         <h2>Literate CoffeeScript</h2>
 <p>Besides being used as an ordinary programming language, CoffeeScript may also be written in “literate” mode. If you name your file with a <code>.litcoffee</code> extension, you can write it as a Markdown document — a document that also happens to be executable CoffeeScript code. The compiler will treat any indented blocks (Markdown’s way of indicating source code) as executable code, and ignore the rest as comments. Code blocks must also be separated from comments by at least one blank line.</p>
@@ -3376,7 +3444,7 @@ The CoffeeScript logo is available in SVG for use in presentations.</li>
         </section>
         <section id="annotated-source">
           <h2>Annotated Source</h2>
-<p>You can browse the CoffeeScript 2.0.0-beta3 source in readable, annotated form <a href="http://coffeescript.org/v2/annotated-source/">here</a>. You can also jump directly to a particular source file:</p>
+<p>You can browse the CoffeeScript 2.0.0-beta4 source in readable, annotated form <a href="http://coffeescript.org/v2/annotated-source/">here</a>. You can also jump directly to a particular source file:</p>
 <ul>
 <li><a href="http://coffeescript.org/v2/annotated-source/grammar.html">Grammar Rules — src/grammar</a></li>
 <li><a href="http://coffeescript.org/v2/annotated-source/lexer.html">Lexing Tokens — src/lexer</a></li>
@@ -3506,7 +3574,7 @@ outer = function() {
   return inner();
 };
 
-outer(1, 2);
+outer(1, 2); // Returns '' in CoffeeScript 1.x, '1, 2' in CoffeeScript 2
 </textarea>
     </div>
   </div>
@@ -3538,7 +3606,7 @@ f = function(a = 1) {
   return a;
 };
 
-f(null);
+f(null); // Returns 1 in CoffeeScript 1.x, null in CoffeeScript 2
 </textarea>
     </div>
   </div>
@@ -3565,7 +3633,7 @@ a  # Equals 1 in CoffeeScript 1.x, null in CoffeeScript 2
   a: null
 });
 
-a;
+a; // Equals 1 in CoffeeScript 1.x, null in CoffeeScript 2
 </textarea>
     </div>
   </div>
@@ -3619,7 +3687,7 @@ f = function*() {
 <blockquote class="uneditable-code-block"><pre><code class="language-coffee"><span class="class"><span class="keyword">class</span> <span class="title">B</span> <span class="keyword">extends</span> <span class="title">A</span></span>
   constructor: <span class="function">-&gt;</span> <span class="keyword">this</span>  <span class="comment"># Throws a compiler error</span>
 </code></pre>
-</blockquote><p>ES2015 classes don’t allow bound (fat arrow) methods. The CoffeeScript compiler goes through some contortions to preserve support for them, but one thing that can’t be accomodated is calling a bound method before it is bound:</p>
+</blockquote><p>ES2015 classes don’t allow bound (fat arrow) methods. The CoffeeScript compiler goes through some contortions to preserve support for them, but one thing that can’t be accommodated is calling a bound method before it is bound:</p>
 <blockquote class="uneditable-code-block"><pre><code class="language-coffee"><span class="class"><span class="keyword">class</span> <span class="title">Base</span></span>
   constructor: <span class="function">-&gt;</span>
     @onClick()      <span class="comment"># This works</span>
@@ -3726,7 +3794,8 @@ B.prototype.foo = -> A::foo.apply this, arguments
 </textarea>
     </div>
     <div class="col-md-6 javascript-output-column">
-      <textarea class="javascript-output" id="breaking_change_super_in_non-class_methods_refactor_with_apply-js">var A, B, extend, hasProp;
+      <textarea class="javascript-output" id="breaking_change_super_in_non-class_methods_refactor_with_apply-js">// Helper functions
+var A, B, extend, hasProp;
 
 hasProp = {}.hasOwnProperty;
 
@@ -3787,7 +3856,7 @@ B = class B extends A {
 
         </section>
         <section id="breaking-changes-jsx-and-the-less-than-and-greater-than-operators">
-          <h3>JSX and the <code>&lt;</code> and <code>&gt;</code> Operators</h3>
+          <h3>JSX and the <code>&lt;</code> and <code>&gt;</code> operators</h3>
 <p>With the addition of <a href="#jsx">JSX</a>, the <code>&lt;</code> and <code>&gt;</code> characters serve as both the “less than” and “greater than” operators and as the delimiters for XML tags, like <code>&lt;div&gt;</code>. For best results, in general you should always wrap the operators in spaces to distinguish them from XML tags: <code>i &lt; len</code>, not <code>i&lt;len</code>. The compiler tries to be forgiving when it can be sure what you intend, but always putting spaces around the “less than” and “greater than” operators will remove ambiguity.</p>
 
         </section>
@@ -3797,10 +3866,59 @@ B = class B extends A {
 <p>Code blocks should also now maintain a consistent indentation level—so an indentation of one tab (or whatever you consider to be a tab stop, like 2 spaces or 4 spaces) should be treated as your code’s “left margin,” with all code in the file relative to that column.</p>
 <p>Code blocks that you want to be part of the commentary, and not executed, must have at least one line (ideally the first line of the block) completely unindented.</p>
 
+        </section>
+        <section id="breaking-changes-argument-parsing-and-shebang-lines">
+          <h3>Argument parsing and shebang (<code>#!</code>) lines</h3>
+<p>In CoffeeScript 1.x, <code>--</code> was required after the path and filename of the script to be run, but before any arguments passed to that script. This convention is now deprecated. So instead of:</p>
+<blockquote class="uneditable-code-block"><pre><code class="language-bash">coffee [options] path/to/script.coffee -- [args]
+</code></pre>
+</blockquote><p>Now you would just type:</p>
+<blockquote class="uneditable-code-block"><pre><code class="language-bash">coffee [options] path/to/script.coffee [args]
+</code></pre>
+</blockquote><p>The deprecated version will still work, but it will print a warning before running the script.</p>
+<p>On non-Windows platforms, a <code>.coffee</code> file can be made executable by adding a shebang (<code>#!</code>) line at the top of the file and marking the file as executable. For example:</p>
+<blockquote class="uneditable-code-block"><pre><code class="language-coffee"><span class="comment">#!/usr/bin/env coffee</span>
+
+x = <span class="number">2</span> + <span class="number">2</span>
+<span class="built_in">console</span>.log x
+</code></pre>
+</blockquote><p>If this were saved as <code>executable.coffee</code>, it could be made executable and run:</p>
+<blockquote class="uneditable-code-block"><pre><code class="language-bash">▶ chmod +x ./executable.coffee
+▶ ./executable.coffee
+4
+</code></pre>
+</blockquote><p>In CoffeeScript 1.x, this used to fail when trying to pass arguments to the script. Some users on OS X worked around the problem by using <code>#!/usr/bin/env coffee --</code> as the first line of the file. That didn’t work on Linux, however, which cannot parse shebang lines with more than a single argument. While such scripts will still run on OS X, CoffeeScript will now display a warning before compiling or evaluating files that begin with a too-long shebang line. Now that CoffeeScript 2 supports passing arguments without needing <code>--</code>, we recommend simply changing the shebang lines in such scripts to just <code>#!/usr/bin/env coffee</code>.</p>
+
         </section>
       </section>
       <section id="changelog">
         <h2>Changelog</h2>
+<div class="anchor" id="2.0.0-beta4"></div>
+<h2 class="header">
+  <a href="https://github.com/jashkenas/coffeescript/compare/2.0.0-beta3...2.0.0-beta4">2.0.0-beta4</a>
+  <span class="timestamp"> &mdash; <time datetime="2017-08-03">August 3, 2017</time></span>
+</h2><ul>
+<li>This release includes <a href="#1.12.7">all the changes from 1.12.6 to 1.12.7</a>.</li>
+<li><a href="#comments">Line comments</a> (starting with <code>#</code>) are now output in the generated JavaScript.</li>
+<li><a href="#comments">Block comments</a> (delimited by <code>###</code>) are now allowed anywhere, including inline where they previously weren’t possible. This provides support for <a href="#type-annotations">static type annotations</a> using Flow’s comments-based syntax.</li>
+<li>Spread syntax (<code>...</code> for objects) is now supported in JSX tags: <code>&lt;div {props...} /&gt;</code>.</li>
+<li>Argument parsing for scripts run via <code>coffee</code> is improved. See <a href="#breaking-changes-argument-parsing-and-shebang-lines">breaking changes</a>.</li>
+<li>CLI: Propagate <code>SIGINT</code> and <code>SIGTERM</code> signals when node is forked.</li>
+<li><code>await</code> in the REPL is now allowed without requiring a wrapper function.</li>
+<li><code>do super</code> is now allowed, and other accesses of <code>super</code> like <code>super.x.y</code> or <code>super['x'].y</code> now work.</li>
+<li>Splat/spread syntax triple dots are now allowed on either the left or the right (so <code>props...</code> or <code>...props</code> are both valid).</li>
+<li>Tagged template literals are recognized as callable functions.</li>
+<li>Bugfixes for object spread syntax in nested properties.</li>
+<li>Bugfixes for destructured function parameter default values.</li>
+</ul>
+<div class="anchor" id="1.12.7"></div>
+<h2 class="header">
+  <a href="https://github.com/jashkenas/coffeescript/compare/1.12.6...1.12.7">1.12.7</a>
+  <span class="timestamp"> &mdash; <time datetime="2017-07-16">July 16, 2017</time></span>
+</h2><ul>
+<li>Fix regressions in 1.12.6 related to chained function calls and indented <code>return</code> and <code>throw</code> arguments.</li>
+<li>The REPL no longer warns about assigning to <code>_</code>.</li>
+</ul>
 <div class="anchor" id="2.0.0-beta3"></div>
 <h2 class="header">
   <a href="https://github.com/jashkenas/coffeescript/compare/2.0.0-beta2...2.0.0-beta3">2.0.0-beta3</a>

documentation/examples/array_spread.coffee

@@ -0,0 +1,4 @@
+popular  = ['pepperoni', 'sausage', 'cheese']
+unwanted = ['anchovies', 'olives']
+
+all = [popular..., unwanted..., 'mushrooms']

documentation/examples/async.coffee

@@ -0,0 +1,18 @@
+# Your browser must support async/await and speech synthesis
+# to run this example.
+
+sleep = (ms) ->
+  new Promise (resolve) ->
+    window.setTimeout resolve, ms
+
+say = (text) ->
+  window.speechSynthesis.cancel()
+  window.speechSynthesis.speak new SpeechSynthesisUtterance text
+
+countdown = (seconds) ->
+  for i in [seconds..1]
+    say i
+    await sleep 1000 # wait one second
+  say "Blastoff!"
+
+countdown 3

documentation/examples/block_comment.coffee

@@ -1,4 +0,0 @@
-###
-SkinnyMochaHalfCaffScript Compiler v1.0
-Released under the MIT License
-###

documentation/examples/breaking_change_bound_generator_function.coffee

@@ -0,0 +1,2 @@
+self = this
+f = -> yield self

documentation/examples/breaking_change_destructuring_default_values.coffee

@@ -0,0 +1,3 @@
+{a = 1} = {a: null}
+
+a  # Equals 1 in CoffeeScript 1.x, null in CoffeeScript 2

documentation/examples/breaking_change_fat_arrow.coffee

@@ -0,0 +1,5 @@
+outer = ->
+  inner = => Array.from arguments
+  inner()
+
+outer(1, 2)  # Returns '' in CoffeeScript 1.x, '1, 2' in CoffeeScript 2

documentation/examples/breaking_change_function_parameter_default_values.coffee

@@ -0,0 +1,3 @@
+f = (a = 1) -> a
+
+f(null)  # Returns 1 in CoffeeScript 1.x, null in CoffeeScript 2

documentation/examples/breaking_change_super_in_non-class_methods_refactor_with_apply.coffee

@@ -0,0 +1,18 @@
+# Helper functions
+hasProp = {}.hasOwnProperty
+extend = (child, parent) ->
+  ctor = ->
+    @constructor = child
+    return
+  for key of parent
+    if hasProp.call(parent, key)
+      child[key] = parent[key]
+  ctor.prototype = parent.prototype
+  child.prototype = new ctor
+  child
+
+
+A = ->
+B = ->
+extend B, A
+B.prototype.foo = -> A::foo.apply this, arguments

documentation/examples/breaking_change_super_in_non-class_methods_refactor_with_class.coffee

@@ -0,0 +1,3 @@
+class A
+class B extends A
+  foo: -> super arguments...

documentation/examples/breaking_change_super_with_arguments.coffee

@@ -0,0 +1,2 @@
+class B extends A
+  foo: -> super arguments...

documentation/examples/breaking_change_super_without_arguments.coffee

@@ -0,0 +1,2 @@
+class B extends A
+  foo: -> super()

documentation/examples/comment.coffee

@@ -0,0 +1,7 @@
+###
+Fortune Cookie Reader v1.0
+Released under the MIT License
+###
+
+sayFortune = (fortune) ->
+	console.log fortune # in bed!

documentation/examples/do.coffee

@@ -1,4 +1,5 @@
 for filename in list
   do (filename) ->
-    fs.readFile filename, (err, contents) ->
-      compile filename, contents.toString()
+    if filename not in ['.DS_Store', 'Thumbs.db', 'ehthumbs.db']
+      fs.readFile filename, (err, contents) ->
+        compile filename, contents.toString()

documentation/examples/existence_declared.coffee

@@ -0,0 +1,4 @@
+major = 'Computer Science'
+
+unless major?
+  signUpForClass 'Introduction to Wines'

documentation/examples/existence_undeclared.coffee

@@ -0,0 +1,2 @@
+if window?
+  environment = 'browser (probably)'

documentation/examples/get_set.coffee

@@ -0,0 +1,9 @@
+screen =
+  width: 1200
+  ratio: 16/9
+
+Object.defineProperty screen, 'height',
+  get: ->
+    this.width / this.ratio
+  set: (val) ->
+    this.width = val / this.ratio

documentation/examples/heregexes.coffee

@@ -1,9 +1,6 @@
-OPERATOR = /// ^ (
-  ?: [-=]>             # function
-   | [-+*/%<>&|^!?=]=  # compound assign / compare
-   | >>>=?             # zero-fill right shift
-   | ([-+:])\1         # doubles
-   | ([&|<>])\2=?      # logic / shift
-   | \?\.              # soak access
-   | \.{2,3}           # range or splat
-) ///
+NUMBER     = ///
+  ^ 0b[01]+    |              # binary
+  ^ 0o[0-7]+   |              # octal
+  ^ 0x[\da-f]+ |              # hex
+  ^ \d*\.?\d+ (?:e[+-]?\d+)?  # decimal
+///i

documentation/examples/jsx.coffee

@@ -0,0 +1,9 @@
+renderStarRating = ({ rating, maxStars }) ->
+  <aside title={"Rating: #{rating} of #{maxStars} stars"}>
+    {for wholeStar in [0...Math.floor(rating)]
+      <Star className="wholeStar" key={wholeStar} />}
+    {if rating % 1 isnt 0
+      <Star className="halfStar" />}
+    {for emptyStar in [Math.ceil(rating)...maxStars]
+      <Star className="emptyStar" key={emptyStar} />}
+  </aside>

documentation/examples/object_spread.coffee

@@ -0,0 +1,5 @@
+user =
+  name: 'Werner Heisenberg'
+  occupation: 'theoretical physicist'
+
+currentUser = { user..., status: 'Uncertain' }

documentation/examples/objects_reserved.coffee

@@ -1,3 +1,3 @@
-$('.account').attr class: 'active'
+$('.account').prop class: 'active'
 
 log object.class

documentation/examples/splats.coffee

@@ -20,6 +20,8 @@ contenders = [
 
 awardMedals contenders...
 
-alert "Gold: " + gold
-alert "Silver: " + silver
-alert "The Field: " + rest
+alert """
+Gold: #{gold}
+Silver: #{silver}
+The Field: #{rest.join ', '}
+"""

documentation/examples/static.coffee

@@ -0,0 +1,9 @@
+class Teenager
+	@say: (speech) ->
+		words = speech.split ' '
+		fillers = ['uh', 'um', 'like', 'actually', 'so', 'maybe']
+		output = []
+		for word, index in words
+			output.push word
+			output.push fillers[Math.floor(Math.random() * fillers.length)] unless index is words.length - 1
+		output.join ', '

documentation/examples/type_annotations.coffee

@@ -0,0 +1,4 @@
+# @flow
+
+fn = (str ###: string ###, num ###: number ###) ###: string ### ->
+  str + num

documentation/sections/annotated_source.md

@@ -0,0 +1,16 @@
+## Annotated Source
+
+You can browse the CoffeeScript <%= fullVersion %> source in readable, annotated form [here](http://coffeescript.org/v<%= majorVersion %>/annotated-source/). You can also jump directly to a particular source file:
+
+- [Grammar Rules — src/grammar](http://coffeescript.org/v<%= majorVersion %>/annotated-source/grammar.html)
+- [Lexing Tokens — src/lexer](http://coffeescript.org/v<%= majorVersion %>/annotated-source/lexer.html)
+- [The Rewriter — src/rewriter](http://coffeescript.org/v<%= majorVersion %>/annotated-source/rewriter.html)
+- [The Syntax Tree — src/nodes](http://coffeescript.org/v<%= majorVersion %>/annotated-source/nodes.html)
+- [Lexical Scope — src/scope](http://coffeescript.org/v<%= majorVersion %>/annotated-source/scope.html)
+- [Helpers &amp; Utility Functions — src/helpers](http://coffeescript.org/v<%= majorVersion %>/annotated-source/helpers.html)
+- [The CoffeeScript Module — src/coffeescript](http://coffeescript.org/v<%= majorVersion %>/annotated-source/coffeescript.html)
+- [Cake &amp; Cakefiles — src/cake](http://coffeescript.org/v<%= majorVersion %>/annotated-source/cake.html)
+- [“coffee” Command-Line Utility — src/command](http://coffeescript.org/v<%= majorVersion %>/annotated-source/command.html)
+- [Option Parsing — src/optparse](http://coffeescript.org/v<%= majorVersion %>/annotated-source/optparse.html)
+- [Interactive REPL — src/repl](http://coffeescript.org/v<%= majorVersion %>/annotated-source/repl.html)
+- [Source Maps — src/sourcemap](http://coffeescript.org/v<%= majorVersion %>/annotated-source/sourcemap.html)

documentation/sections/async_functions.md

@@ -0,0 +1,9 @@
+## Async Functions
+
+ES2017’s [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) are supported through the `await` keyword. Like with generators, there's no need for an `async` keyword; an async function in CoffeeScript is simply a function that awaits.
+
+Similar to how `yield return` forces a generator, `await return` may be used to force a function to be async.
+
+```
+codeFor('async', true)
+```

documentation/sections/breaking_change_fat_arrow.md

@@ -0,0 +1,7 @@
+### Bound (fat arrow) functions
+
+In CoffeeScript 1.x, `=>` compiled to a regular `function` but with references to `this`/`@` rewritten to use the outer scope’s `this`, or with the inner function bound to the outer scope via `.bind` (hence the name “bound function”). In CoffeeScript 2, `=>` compiles to [ES2015’s `=>`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions), which behaves slightly differently. The largest difference is that in ES2015, `=>` functions lack an `arguments` object:
+
+```
+codeFor('breaking_change_fat_arrow', 'outer(1, 2)')
+```

documentation/sections/breaking_changes.md

@@ -0,0 +1,3 @@
+## Breaking Changes From CoffeeScript 1.x to 2
+
+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.

documentation/sections/breaking_changes_argument_parsing_and_shebang_lines.md

@@ -0,0 +1,34 @@
+### Argument parsing and shebang (`#!`) lines
+
+In CoffeeScript 1.x, `--` was required after the path and filename of the script to be run, but before any arguments passed to that script. This convention is now deprecated. So instead of:
+
+```bash
+coffee [options] path/to/script.coffee -- [args]
+```
+
+Now you would just type:
+
+```bash
+coffee [options] path/to/script.coffee [args]
+```
+
+The deprecated version will still work, but it will print a warning before running the script.
+
+On non-Windows platforms, a `.coffee` file can be made executable by adding a shebang (`#!`) line at the top of the file and marking the file as executable. For example:
+
+```coffee
+#!/usr/bin/env coffee
+
+x = 2 + 2
+console.log x
+```
+
+If this were saved as `executable.coffee`, it could be made executable and run:
+
+```bash
+▶ chmod +x ./executable.coffee
+▶ ./executable.coffee
+4
+```
+
+In CoffeeScript 1.x, this used to fail when trying to pass arguments to the script. Some users on OS X worked around the problem by using `#!/usr/bin/env coffee --` as the first line of the file. That didn’t work on Linux, however, which cannot parse shebang lines with more than a single argument. While such scripts will still run on OS X, CoffeeScript will now display a warning before compiling or evaluating files that begin with a too-long shebang line. Now that CoffeeScript 2 supports passing arguments without needing `--`, we recommend simply changing the shebang lines in such scripts to just `#!/usr/bin/env coffee`.

documentation/sections/breaking_changes_bound_generator_functions.md

@@ -0,0 +1,14 @@
+### Bound generator functions
+
+Bound generator functions, a.k.a. generator arrow functions, [aren’t allowed in ECMAScript](http://stackoverflow.com/questions/27661306/can-i-use-es6s-arrow-function-syntax-with-generators-arrow-notation). You can write `function*` or `=>`, but not both. Therefore, CoffeeScript code like this:
+
+```coffee
+f = => yield this
+# Throws a compiler error
+```
+
+Needs to be rewritten the old-fashioned way:
+
+```
+codeFor('breaking_change_bound_generator_function')
+```

documentation/sections/breaking_changes_classes.md

@@ -0,0 +1,48 @@
+### Classes are compiled to ES2015 classes
+
+ES2015 classes and their methods have some restrictions beyond those on regular functions.
+
+Class constructors can’t be invoked without `new`:
+
+```coffee
+(class)()
+# Throws a TypeError at runtime
+```
+
+Derived (extended) class `constructor`s cannot use `this` before calling `super`:
+
+```coffee
+class B extends A
+  constructor: -> this  # Throws a compiler error
+```
+
+ES2015 classes don’t allow bound (fat arrow) methods. The CoffeeScript compiler goes through some contortions to preserve support for them, but one thing that can’t be accommodated is calling a bound method before it is bound:
+
+```coffee
+class Base
+  constructor: ->
+    @onClick()      # This works
+    clickHandler = @onClick
+    clickHandler()  # This throws a runtime error
+
+class Component extends Base
+  onClick: =>
+    console.log 'Clicked!', @
+```
+
+Class methods can’t be used with `new` (uncommon):
+
+```coffee
+class Namespace
+  @Klass = ->
+new Namespace.Klass  # Throws a TypeError at runtime
+```
+
+Due to the hoisting required to compile to ES2015 classes, dynamic keys in class methods can’t use values from the executable class body unless the methods are assigned in prototype style.
+
+```coffee
+class A
+  name = 'method'
+  "#{name}": ->   # This method will be named 'undefined'
+  @::[name] = ->  # This will work; assigns to `A.prototype.method`
+```

documentation/sections/breaking_changes_default_values.md

@@ -0,0 +1,11 @@
+### Default values for function parameters and destructured elements
+
+Per the [ES2015 spec regarding function default parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters) and [destructuring default values](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment#Default_values), default values are only applied when a value is missing or `undefined`. In CoffeeScript 1.x, the default value would be applied in those cases but also if the  value was `null`.
+
+```
+codeFor('breaking_change_function_parameter_default_values', 'f(null)')
+```
+
+```
+codeFor('breaking_change_destructuring_default_values', 'a')
+```

documentation/sections/breaking_changes_jsx_and_the_less_than_and_greater_than_operators.md

@@ -0,0 +1,3 @@
+### JSX and the `<` and `>` operators
+
+With the addition of [JSX](#jsx), the `<` and `>` characters serve as both the “less than” and “greater than” operators and as the delimiters for XML tags, like `<div>`. For best results, in general you should always wrap the operators in spaces to distinguish them from XML tags: `i < len`, not `i<len`. The compiler tries to be forgiving when it can be sure what you intend, but always putting spaces around the “less than” and “greater than” operators will remove ambiguity.

documentation/sections/breaking_changes_literate_coffeescript.md

@@ -0,0 +1,7 @@
+### Literate CoffeeScript parsing
+
+CoffeeScript 2’s parsing of Literate CoffeeScript has been refactored to now be more careful about not treating indented lists as code blocks; but this means that all code blocks (unless they are to be interpreted as comments) must be separated by at least one blank line from lists.
+
+Code blocks should also now maintain a consistent indentation level—so an indentation of one tab (or whatever you consider to be a tab stop, like 2 spaces or 4 spaces) should be treated as your code’s “left margin,” with all code in the file relative to that column.
+
+Code blocks that you want to be part of the commentary, and not executed, must have at least one line (ideally the first line of the block) completely unindented.

documentation/sections/breaking_changes_super_extends.md

@@ -0,0 +1,43 @@
+### `super` and `extends`
+
+Due to a syntax clash with `super` with accessors, “bare” `super` (the keyword `super` without parentheses) no longer compiles to a super call forwarding all arguments.
+
+```coffee
+class B extends A
+  foo: -> super
+  # Throws a compiler error
+```
+
+Arguments can be forwarded explicitly using splats:
+
+```
+codeFor('breaking_change_super_with_arguments')
+```
+
+Or if you know that the parent function doesn’t require arguments, just call `super()`:
+
+```
+codeFor('breaking_change_super_without_arguments')
+```
+
+CoffeeScript 1.x allowed the `extends` keyword to set up prototypal inheritance between functions, and `super` could be used manually prototype-assigned functions:
+
+```coffee
+A = ->
+B = ->
+B extends A
+B.prototype.foo = -> super arguments...
+# Last two lines each throw compiler errors in CoffeeScript 2
+```
+
+Due to the switch to ES2015 `extends` and `super`, using these keywords for prototypal functions are no longer supported. The above case could be refactored to:
+
+```
+codeFor('breaking_change_super_in_non-class_methods_refactor_with_apply')
+```
+
+or
+
+```
+codeFor('breaking_change_super_in_non-class_methods_refactor_with_class')
+```

documentation/sections/chaining.md

@@ -0,0 +1,7 @@
+## Chaining Function Calls
+
+Leading `.` closes all open calls, allowing for simpler chaining syntax.
+
+```
+codeFor('chaining')
+```

documentation/sections/changelog.md

@@ -1,4 +1,21 @@
-## Change Log
+## Changelog
+
+```
+releaseHeader('2017-08-03', '2.0.0-beta4', '2.0.0-beta3')
+```
+
+*   This release includes [all the changes from 1.12.6 to 1.12.7](#1.12.7).
+*   [Line comments](#comments) (starting with `#`) are now output in the generated JavaScript.
+*   [Block comments](#comments) (delimited by `###`) are now allowed anywhere, including inline where they previously weren’t possible. This provides support for [static type annotations](#type-annotations) using Flow’s comments-based syntax.
+*   Spread syntax (`...` for objects) is now supported in JSX tags: `<div {props...} />`.
+*   Argument parsing for scripts run via `coffee` is improved. See [breaking changes](#breaking-changes-argument-parsing-and-shebang-lines).
+*   CLI: Propagate `SIGINT` and `SIGTERM` signals when node is forked.
+*   `await` in the REPL is now allowed without requiring a wrapper function.
+*   `do super` is now allowed, and other accesses of `super` like `super.x.y` or `super['x'].y` now work.
+*   Splat/spread syntax triple dots are now allowed on either the left or the right (so `props...` or `...props` are both valid).
+*   Tagged template literals are recognized as callable functions.
+*   Bugfixes for object spread syntax in nested properties.
+*   Bugfixes for destructured function parameter default values.
 
 ```
 releaseHeader('2017-07-16', '1.12.7', '1.12.6')
@@ -7,6 +24,33 @@ releaseHeader('2017-07-16', '1.12.7', '1.12.6')
 *   Fix regressions in 1.12.6 related to chained function calls and indented `return` and `throw` arguments.
 *   The REPL no longer warns about assigning to `_`.
 
+```
+releaseHeader('2017-06-30', '2.0.0-beta3', '2.0.0-beta2')
+```
+
+*   [JSX](#jsx) is now supported.
+*   [Object rest/spread properties](#object-spread) are now supported.
+*   Bound (fat arrow) methods are once again supported in classes; though an error will be thrown if you attempt to call the method before it is bound. See [breaking changes for classes](#breaking-changes-classes).
+*   The REPL no longer warns about assigning to `_`.
+*   Bugfixes for destructured nested default values and issues related to chaining or continuing expressions across multiple lines.
+
+
+```
+releaseHeader('2017-05-16', '2.0.0-beta2', '2.0.0-beta1')
+```
+
+*   This release includes [all the changes from 1.12.5 to 1.12.6](#1.12.6).
+*   Bound (fat arrow) methods in classes must be declared in the class constructor, after `super()` if the class is extending a parent class. See [breaking changes for classes](#breaking-changes-classes).
+*   All unnecessary utility helper functions have been removed, including the polyfills for `indexOf` and `bind`.
+*   The `extends` keyword now only works in the context of classes; it cannot be used to extend a function prototype. See [breaking changes for `extends`](#breaking-changes-super-extends).
+*   Literate CoffeeScript is now parsed entirely based on indentation, similar to the 1.x implementation; there is no longer a dependency for parsing Markdown. See [breaking changes for Literate CoffeeScript parsing](#breaking-changes-literate-coffeescript).
+*   JavaScript reserved words used as properties are no longer wrapped in quotes.
+*   `require('coffeescript')` should now work in non-Node environments such as the builds created by Webpack or Browserify. This provides a more convenient way to include the browser compiler in builds intending to run in a browser environment.
+*   Unreachable `break` statements are no longer added after `switch` cases that `throw` exceptions.
+*   The browser compiler is now compiled using Babili and transpiled down to Babel’s `env` preset (should be safe for use in all browsers in current use, not just evergreen versions).
+*   Calling functions `@get` or `@set` no longer throws an error about required parentheses. (Bare `get` or `set`, not attached to an object or `@`, [still intentionally throws a compiler error](#unsupported-get-set).)
+*   If `$XDG_CACHE_HOME` is set, the REPL `.coffee_history` file is saved there.
+
 ```
 releaseHeader('2017-05-15', '1.12.6', '1.12.5')
 ```
@@ -18,6 +62,16 @@ releaseHeader('2017-05-15', '1.12.6', '1.12.5')
 *   Bugfixes for incorrect code generated by the `?` operator within a termary `if` statement.
 *   Fixed some tests, and failing tests now result in a nonzero exit code.
 
+```
+releaseHeader('2017-04-14', '2.0.0-beta1', '2.0.0-alpha1')
+```
+
+*   Initial beta release of CoffeeScript 2. No further breaking changes are anticipated.
+*   Destructured objects and arrays now output using ES2015+ syntax whenever possible.
+*   Literate CoffeeScript now has much better support for parsing Markdown, thanks to using [Markdown-It](https://github.com/markdown-it/markdown-it) to detect Markdown sections rather than just looking at indentation.
+*   Calling a function named `get` or `set` now requires parentheses, to disambiguate from the `get` or `set` keywords (which are [disallowed](#unsupported-get-set)).
+*   The compiler now requires Node 7.6+, the first version of Node to support asynchronous functions without requiring a flag.
+
 ```
 releaseHeader('2017-04-10', '1.12.5', '1.12.4')
 ```
@@ -25,6 +79,24 @@ releaseHeader('2017-04-10', '1.12.5', '1.12.4')
 *   Better handling of `default`, `from`, `as` and `*` within `import` and `export` statements. You can now import or export a member named `default` and the compiler won’t interpret it as the `default` keyword.
 *   Fixed a bug where invalid octal escape sequences weren’t throwing errors in the compiler.
 
+
+```
+releaseHeader('2017-02-21', '2.0.0-alpha1', '1.12.4')
+```
+
+*   Initial alpha release of CoffeeScript 2. The CoffeeScript compiler now outputs ES2015+ syntax whenever possible. See [breaking changes](#breaking-changes).
+*   Classes are output using ES2015 `class` and `extends` keywords.
+*   Added support for `async`/`await`.
+*   Bound (arrow) functions now output as `=>` functions.
+*   Function parameters with default values now use ES2015 default values syntax.
+*   Splat function parameters now use ES2015 spread syntax.
+*   Computed properties now use ES2015 syntax.
+*   Interpolated strings (template literals) now use ES2015 backtick syntax.
+*   Improved support for recognizing Markdown in Literate CoffeeScript files.
+*   Mixing tabs and spaces in indentation is now disallowed.
+*   Browser compiler is now minified using the Google Closure Compiler (JavaScript version).
+*   Node 7+ required for CoffeeScript 2.
+
 ```
 releaseHeader('2017-02-18', '1.12.4', '1.12.3')
 ```
@@ -180,7 +252,7 @@ releaseHeader('2014-08-26', '1.8.0', '1.7.1')
 *   Fixed a slight formatting error in CoffeeScript’s source map-patched stack traces.
 *   The `%%` operator now coerces its right operand only once.
 *   It is now possible to require CoffeeScript files from Cakefiles without having to register the compiler first.
-*   The CoffeeScript REPL is now exported and can be required using `require 'coffee-script/repl'`.
+*   The CoffeeScript REPL is now exported and can be required using `require 'coffeescript/repl'`.
 *   Fixes for the REPL in Node 0.11.
 
 ```
@@ -193,14 +265,9 @@ releaseHeader('2014-01-29', '1.7.1', '1.7.0')
 releaseHeader('2014-01-28', '1.7.0', '1.6.3')
 ```
 
-*   When requiring CoffeeScript files in Node you must now explicitly register the compiler. This can be done with `require 'coffee-script/register'` or `CoffeeScript.register()`. Also for configuration such as Mocha’s, use **coffee-script/register**.
+*   When requiring CoffeeScript files in Node you must now explicitly register the compiler. This can be done with `require 'coffeescript/register'` or `CoffeeScript.register()`. Also for configuration such as Mocha’s, use **coffeescript/register**.
 *   Improved error messages, source maps and stack traces. Source maps now use the updated `//#` syntax.
 *   Leading `.` now closes all open calls, allowing for simpler chaining syntax.
-
-```
-codeFor('chaining')
-```
-
 *   Added `**`, `//` and `%%` operators and `...` expansion in parameter lists and destructuring expressions.
 *   Multiline strings are now joined by a single space and ignore all indentation. A backslash at the end of a line can denote the amount of whitespace between lines, in both strings and heredocs. Backslashes correctly escape whitespace in block regexes.
 *   Closing brackets can now be indented and therefore no longer cause unexpected error.
@@ -293,7 +360,7 @@ releaseHeader('2011-11-08', '1.1.3', '1.1.2')
 *   Ahh, whitespace. CoffeeScript’s compiled JS now tries to space things out and keep it readable, as you can see in the examples on this page.
 *   You can now call `super` in class level methods in class bodies, and bound class methods now preserve their correct context.
 *   JavaScript has always supported octal numbers `010 is 8`, and hexadecimal numbers `0xf is 15`, but CoffeeScript now also supports binary numbers: `0b10 is 2`.
-*   The CoffeeScript module has been nested under a subdirectory to make it easier to `require` individual components separately, without having to use **npm**. For example, after adding the CoffeeScript folder to your path: `require('coffee-script/lexer')`
+*   The CoffeeScript module has been nested under a subdirectory to make it easier to `require` individual components separately, without having to use **npm**. For example, after adding the CoffeeScript folder to your path: `require('coffeescript/lexer')`
 *   There’s a new “link” feature in Try CoffeeScript on this webpage. Use it to get a shareable permalink for your example script.
 *   The `coffee --watch` feature now only works on Node.js 0.6.0 and higher, but now also works properly on Windows.
 *   Lots of small bug fixes from **[@michaelficarra](https://github.com/michaelficarra)**, **[@geraldalewis](https://github.com/geraldalewis)**, **[@satyr](https://github.com/satyr)**, and **[@trevorburnham](https://github.com/trevorburnham)**.
@@ -412,7 +479,7 @@ Trailing commas are now allowed, a-la Python. Static properties may be assigned
 releaseHeader('2010-03-23', '0.5.6', '0.5.5')
 ```
 
-Interpolation can now be used within regular expressions and heredocs, as well as strings. Added the `<-` bind operator. Allowing assignment to half-expressions instead of special `||=`-style operators. The arguments object is no longer automatically converted into an array. After requiring `coffee-script`, Node.js can now directly load `.coffee` files, thanks to **registerExtension**. Multiple splats can now be used in function calls, arrays, and pattern matching.
+Interpolation can now be used within regular expressions and heredocs, as well as strings. Added the `<-` bind operator. Allowing assignment to half-expressions instead of special `||=`-style operators. The arguments object is no longer automatically converted into an array. After requiring `coffeescript`, Node.js can now directly load `.coffee` files, thanks to **registerExtension**. Multiple splats can now be used in function calls, arrays, and pattern matching.
 
 ```
 releaseHeader('2010-03-08', '0.5.5', '0.5.4')
@@ -437,7 +504,7 @@ releaseHeader('2010-02-25', '0.5.2', '0.5.1')
 ```
 
 Added a compressed version of the compiler for inclusion in web pages as
-`/v<%= majorVersion %>/browser-compiler/coffee-script.js`. It’ll automatically run any script tags with type `text/coffeescript` for you. Added a `--stdio` option to the `coffee` command, for piped-in compiles.
+`/v<%= majorVersion %>/browser-compiler/coffeescript.js`. It’ll automatically run any script tags with type `text/coffeescript` for you. Added a `--stdio` option to the `coffee` command, for piped-in compiles.
 
 ```
 releaseHeader('2010-02-24', '0.5.1', '0.5.0')
@@ -526,7 +593,7 @@ Bugfix for running `coffee --interactive` and `--run` from outside of the Coffee
 releaseHeader('2009-12-26', '0.1.5', '0.1.4')
 ```
 
-Array slice literals and array comprehensions can now both take Ruby-style ranges to specify the start and end. JavaScript variable declaration is now pushed up to the top of the scope, making all assignment statements into expressions. You can use `\` to escape newlines. The `coffee-script` command is now called `coffee`.
+Array slice literals and array comprehensions can now both take Ruby-style ranges to specify the start and end. JavaScript variable declaration is now pushed up to the top of the scope, making all assignment statements into expressions. You can use `\` to escape newlines. The `coffeescript` command is now called `coffee`.
 
 ```
 releaseHeader('2009-12-25', '0.1.4', '0.1.3')

documentation/sections/chat.md

@@ -1,5 +1,3 @@
 ## Web Chat (IRC)
 
-Quick help and advice can usually be found in the CoffeeScript IRC room. Join `#coffeescript` on `irc.freenode.net`, or click the button below to open a webchat session on this page.
-
-<button id="open_webchat">click to open #coffeescript</button>
+Quick help and advice can often be found in the CoffeeScript IRC room `#coffeescript` on `irc.freenode.net`, which you can [join via your web browser](http://webchat.freenode.net/?channels=coffeescript).

documentation/sections/classes.md

@@ -1,20 +1,15 @@
-## Classes, Inheritance, and Super
+## Classes
 
-JavaScript’s prototypal inheritance has always been a bit of a brain-bender, with a whole family tree of libraries that provide a cleaner syntax for classical inheritance on top of JavaScript’s prototypes: [Base2](https://code.google.com/p/base2/), [Prototype.js](http://prototypejs.org/), [JS.Class](http://jsclass.jcoglan.com/), etc. The libraries provide syntactic sugar, but the built-in inheritance would be completely usable if it weren’t for a couple of small exceptions: it’s awkward to call **super** (the prototype object’s implementation of the current function), and it’s awkward to correctly set the prototype chain.
-
-Instead of repetitively attaching functions to a prototype, CoffeeScript provides a basic `class` structure that allows you to name your class, set the superclass, assign prototypal properties, and define the constructor, in a single assignable expression.
-
-Constructor functions are named, to better support helpful stack traces. In the first class in the example below, `this.constructor.name is "Animal"`.
+CoffeeScript 1 provided the `class` and `extends` keywords as syntactic sugar for working with prototypal functions. With ES2015, JavaScript has adopted those keywords; so CoffeeScript 2 compiles its `class` and `extends` keywords to ES2015 classes.
 
 ```
 codeFor('classes', true)
 ```
 
-If structuring your prototypes classically isn’t your cup of tea, CoffeeScript provides a couple of lower-level conveniences. The `extends` operator helps with proper prototype setup, and can be used to create an inheritance chain between any pair of constructor functions; `::` gives you quick access to an object’s prototype; and `super()` is converted into a call against the immediate ancestor’s method of the same name.
+Static methods can be defined using `@` before the method name:
 
 ```
-codeFor('prototypes', '"one_two".dasherize()')
+codeFor('static', 'Teenager.say("Are we there yet?")')
 ```
 
-Finally, class definitions are blocks of executable code, which make for interesting metaprogramming possibilities. Because in the context of a class definition, `this` is the class object itself (the constructor function), you can assign static properties by using
-`@property: value`, and call functions defined in parent classes: `@attr 'title', type: 'text'`
+Finally, class definitions are blocks of executable code, which make for interesting metaprogramming possibilities. In the context of a class definition, `this` is the class object itself; therefore, you can assign static properties by using `@property: value`.

documentation/sections/coffeescript_2.md

@@ -0,0 +1,17 @@
+## CoffeeScript 2
+
+### What’s New In CoffeeScript 2?
+
+The biggest change in CoffeeScript 2 is that now the CoffeeScript compiler produces modern, ES2015+ JavaScript. A CoffeeScript `=>` becomes an ES `=>`, a CoffeeScript `class` becomes an ES `class` and so on. With the exception of [modules](#modules) (`import` and `export` statements) and [JSX](#jsx), all the ES2015+ 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; Chrome has supported all features since version 55.
+
+Support for ES2015+ syntax is important to ensure compatibility with frameworks that assume ES2015. Now that CoffeeScript compiles classes to the ES `class` keyword, it’s possible to `extend` an ES 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.
+
+Many ES2015+ features have been backported to CoffeeScript 1.11 and 1.12, including [modules](#modules), [`for…of`](#generator-iteration), and [tagged template literals](#tagged-template-literals). Major new features unique to CoffeeScript 2 are support for ES2017’s [async functions](#async-functions) and for [JSX](#jsx). More details are 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 ES2015?
+
+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.

documentation/sections/command_line_interface.md

@@ -0,0 +1,37 @@
+### Command Line
+
+Once installed, you should have access to the `coffee` command, which can execute scripts, compile `.coffee` files into `.js`, and provide an interactive REPL. The `coffee` command takes the following options:
+
+| Option | Description |
+| --- | --- |
+| `-c, --compile` | Compile a `.coffee` script into a `.js` JavaScript file of the same name. |
+| `-m, --map` | Generate source maps alongside the compiled JavaScript files. Adds `sourceMappingURL` directives to the JavaScript as well. |
+| `-M, --inline-map` | Just like `--map`, but include the source map directly in the compiled JavaScript files, rather than in a separate file. |
+| `-i, --interactive` | Launch an interactive CoffeeScript session to try short snippets. Identical to calling `coffee` with no arguments. |
+| `-o, --output [DIR]` | Write out all compiled JavaScript files into the specified directory. Use in conjunction with `--compile` or `--watch`. |
+| `-w, --watch` | Watch files for changes, rerunning the specified command when any file is updated. |
+| `-p, --print` | Instead of writing out the JavaScript as a file, print it directly to **stdout**. |
+| `-s, --stdio` | Pipe in CoffeeScript to STDIN and get back JavaScript over STDOUT. Good for use with processes written in other languages. An example:<br>`cat src/cake.coffee | coffee -sc` |
+| `-l, --literate` | Parses the code as Literate CoffeeScript. You only need to specify this when passing in code directly over **stdio**, or using some sort of extension-less file name. |
+| `-e, --eval` | Compile and print a little snippet of CoffeeScript directly from the command line. For example:<br>`coffee -e "console.log num for num in [10..1]"` |
+| `-r, --require [MODULE]`&emsp; | `require()` the given module before starting the REPL or evaluating the code given with the `--eval` flag. |
+| `-b, --bare` | Compile the JavaScript without the [top-level function safety wrapper](#lexical-scope). |
+| `-t, --tokens` | Instead of parsing the CoffeeScript, just lex it, and print out the token stream. Used for debugging the compiler. |
+| `-n, --nodes` | Instead of compiling the CoffeeScript, just lex and parse it, and print out the parse tree. Used for debugging the compiler. |
+| `--nodejs` | The `node` executable has some useful options you can set, such as `--debug`, `--debug-brk`, `--max-stack-size`, and `--expose-gc`. Use this flag to forward options directly to Node.js. To pass multiple flags, use `--nodejs` multiple times. |
+| `--no-header` | Suppress the “Generated by CoffeeScript” header. |
+
+#### Examples:
+
+*   Compile a directory tree of `.coffee` files in `src` into a parallel tree of `.js` files in `lib`:<br>
+    `coffee --compile --output lib/ src/`
+*   Watch a file for changes, and recompile it every time the file is saved:<br>
+    `coffee --watch --compile experimental.coffee`
+*   Concatenate a list of files into a single script:<br>
+    `coffee --join project.js --compile src/*.coffee`
+*   Print out the compiled JS from a one-liner:<br>
+    `coffee -bpe "alert i for i in [0..10]"`
+*   All together now, watch and recompile an entire project as you work on it:<br>
+    `coffee -o lib/ -cw src/`
+*   Start the CoffeeScript REPL (`Ctrl-D` to exit, `Ctrl-V`for multi-line):<br>
+    `coffee`

documentation/sections/comments.md

@@ -0,0 +1,9 @@
+## Comments
+
+In CoffeeScript, comments are denoted by the `#` character to the end of a line, or from `###` to the next appearance of `###`. Comments are ignored by the compiler, though the compiler makes its best effort at reinserting your comments into the output JavaScript after compilation.
+
+```
+codeFor('comment')
+```
+
+Inline `###` comments make [type annotations](#type-annotations) possible.

documentation/sections/conditionals.md

@@ -1,8 +1,8 @@
 ## If, Else, Unless, and Conditional Assignment
 
-**If/else** statements can be written without the use of parentheses and curly brackets. As with functions and other block expressions, multi-line conditionals are delimited by indentation. There’s also a handy postfix form, with the `if` or `unless` at the end.
+`if`/`else` statements can be written without the use of parentheses and curly brackets. As with functions and other block expressions, multi-line conditionals are delimited by indentation. There’s also a handy postfix form, with the `if` or `unless` at the end.
 
-CoffeeScript can compile **if** statements into JavaScript expressions, using the ternary operator when possible, and closure wrapping otherwise. There is no explicit ternary statement in CoffeeScript — you simply use a regular **if** statement on a single line.
+CoffeeScript can compile `if` statements into JavaScript expressions, using the ternary operator when possible, and closure wrapping otherwise. There is no explicit ternary statement in CoffeeScript — you simply use a regular `if` statement on a single line.
 
 ```
 codeFor('conditionals')

documentation/sections/contributing.md

@@ -0,0 +1,16 @@
+## Contributing
+
+Contributions are welcome! Feel free to fork [the repo](http://github.com/jashkenas/coffeescript) and submit a pull request.
+
+[Some features of ECMAScript are intentionally unsupported](#unsupported). Please review both the open and closed [issues on GitHub](http://github.com/jashkenas/coffeescript/issues) 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](https://github.com/jashkenas/coffeescript/wiki/%5BHowto%5D-Hacking-on-the-CoffeeScript-Compiler), especially [How The Parser Works](https://github.com/jashkenas/coffeescript/wiki/%5BHowTo%5D-How-parsing-works).
+
+There are several things you can do to increase your odds of having your pull request accepted:
+
+  * Create tests! Any pull request should probably include basic tests to verify you didn’t break anything, or future changes won’t break your code.
+  * Follow the style of the rest of the CoffeeScript codebase.
+  * Ensure any ECMAScript syntax is mature (at Stage 4), with no further potential changes.
+  * Add only features that have broad utility, rather than a feature aimed at a specific use case or framework.
+
+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](https://github.com/jashkenas/coffeescript/wiki/In-The-Wild).

documentation/sections/destructuring.md

@@ -36,4 +36,4 @@ Destructuring assignment is also useful when combined with class constructors to
 codeFor('constructor_destructuring', 'tim.age + " " + tim.height')
 ```
 
-The above example also demonstrates that if properties are missing in the destructured object or array, you can, just like in JavaScript, provide defaults. The difference with JavaScript is that CoffeeScript, as always, treats both null and undefined the same.
+The above example also demonstrates that if properties are missing in the destructured object or array, you can, just like in JavaScript, provide defaults. Note though that unlike with the existential operator, the default is only applied with the value is missing or `undefined`—[passing `null` will set a value of `null`](#breaking-changes-default-values), not the default.

documentation/sections/es2015plus_output.md

@@ -0,0 +1,13 @@
+### ES2015+ Output
+
+CoffeeScript 2 outputs the latest 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 [CoffeeScript 1.x](/v1/). CoffeeScript 2 [breaks compatibility](#breaking-changes) 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](http://babeljs.io/), [Rollup](https://github.com/rollup/rollup) or [Traceur Compiler](https://github.com/google/traceur-compiler). In general, [CoffeeScript 2’s output is supported as is by Node.js 7.6+](http://node.green/), except for modules and JSX which require transpilation.
+
+There are many great task runners for setting up JavaScript build chains, such as [Gulp](http://gulpjs.com/), [Webpack](https://webpack.github.io/), [Grunt](https://gruntjs.com/) and [Broccoli](http://broccolijs.com/). If you’re looking for a very minimal solution to get started, you can use [babel-preset-env](https://babeljs.io/docs/plugins/preset-env/) and the command line:
+
+```bash
+npm install --global coffeescript@next
+npm install --save-dev coffeescript@next babel-cli babel-preset-env
+coffee --print *.coffee | babel --presets env > app.js
+```

documentation/sections/existential_operator.md

@@ -1,17 +1,37 @@
 ## The Existential Operator
 
-It’s a little difficult to check for the existence of a variable in JavaScript. `if (variable) …` comes close, but fails for zero, the empty string, and false. CoffeeScript’s existential operator `?` returns true unless a variable is **null** or **undefined**, which makes it analogous to Ruby’s `nil?`
+It’s a little difficult to check for the existence of a variable in JavaScript. `if (variable) …` comes close, but fails for zero, the empty string, and false (to name just the most common cases). CoffeeScript’s existential operator `?` returns true unless a variable is `null` or `undefined` or undeclared, which makes it analogous to Ruby’s `nil?`.
 
-It can also be used for safer conditional assignment than `||=` provides, for cases where you may be handling numbers or strings.
+It can also be used for safer conditional assignment than the JavaScript pattern `a = a || value` provides, for cases where you may be handling numbers or strings.
 
 ```
 codeFor('existence', 'footprints')
 ```
 
-The accessor variant of the existential operator `?.` can be used to soak up null references in a chain of properties. Use it instead of the dot accessor `.` in cases where the base value may be **null** or **undefined**. If all of the properties exist then you’ll get the expected result, if the chain is broken, **undefined** is returned instead of the **TypeError** that would be raised otherwise.
+Note that if the compiler knows that `a` is in scope and therefore declared, `a?` compiles to `a != null`, _not_ `a !== null`. The `!=` makes a loose comparison to `null`, which does double duty also comparing against `undefined`. The reverse also holds for `not a?` or `unless a?`.
+
+```
+codeFor('existence_declared')
+```
+
+If a variable might be undeclared, the compiler does a thorough check. This is what JavaScript coders _should_ be typing when they want to check if a mystery variable exists.
+
+```
+codeFor('existence_undeclared')
+```
+
+The accessor variant of the existential operator `?.` can be used to soak up null references in a chain of properties. Use it instead of the dot accessor `.` in cases where the base value may be `null` or `undefined`. If all of the properties exist then you’ll get the expected result, if the chain is broken, `undefined` is returned instead of the `TypeError` that would be raised otherwise.
 
 ```
 codeFor('soaks')
 ```
 
-Soaking up nulls is similar to Ruby’s [andand gem](https://rubygems.org/gems/andand), and to the [safe navigation operator](http://docs.groovy-lang.org/latest/html/documentation/index.html#_safe_navigation_operator) in Groovy.
+For completeness:
+
+| Example | Definition |
+| --- | --- |
+| `a?` | tests that `a` is in scope and `a != null` |
+| `a ? b` | returns `a` if `a` is in scope and `a != null`; otherwise, `b` |
+| `a?.b` or `a?['b']` | returns `a.b` if `a` is in scope and `a != null`; otherwise, `undefined` |
+| `a?(b, c)` or `a? b, c`  | returns the result of calling `a` (with arguments `b` and `c`) if `a` is in scope and callable; otherwise, `undefined` |
+| `a ?= b` | assigns the value of `b` to `a` if `a` is not in scope or if `a == null`; produces the new value of `a` |

documentation/sections/expressions.md

@@ -20,7 +20,7 @@ Things that would otherwise be statements in JavaScript, when used as part of an
 codeFor('expressions_comprehension', 'globals')
 ```
 
-As well as silly things, like passing a **try/catch** statement directly into a function call:
+As well as silly things, like passing a `try`/`catch` statement directly into a function call:
 
 ```
 codeFor('expressions_try', true)

documentation/sections/fat_arrow.md

@@ -1,4 +1,4 @@
-## Bound Functions, Generator Functions
+## Bound (Fat Arrow) Functions
 
 In JavaScript, the `this` keyword is dynamically scoped to mean the object that the current function is attached to. If you pass a function as a callback or attach it to a different object, the original value of `this` will be lost. If you’re not familiar with this behavior, [this Digital Web article](http://64.13.255.16/articles/scope_in_javascript/) gives a good overview of the quirks.
 
@@ -10,22 +10,4 @@ codeFor('fat_arrow')
 
 If we had used `->` in the callback above, `@customer` would have referred to the undefined “customer” property of the DOM element, and trying to call `purchase()` on it would have raised an exception.
 
-When used in a class definition, methods declared with the fat arrow will be automatically bound to each instance of the class when the instance is constructed.
-
-<div id="generator-functions" class="bookmark"></div>
-
-CoffeeScript functions also support [ES2015 generator functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*) through the `yield` keyword. There’s no `function*(){}` nonsense — a generator in CoffeeScript is simply a function that yields.
-
-```
-codeFor('generators', 'ps.next().value')
-```
-
-`yield*` is called `yield from`, and `yield return` may be used if you need to force a generator that doesn’t yield.
-
-<div id="generator-iteration" class="bookmark"></div>
-
-You can iterate over a generator function using `for…from`.
-
-```
-codeFor('generator_iteration', 'getFibonacciNumbers(10)')
-```
+The fat arrow was one of the most popular features of CoffeeScript, and ES2015 [adopted it](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions); so CoffeeScript 2 compiles `=>` to ES `=>`.

documentation/sections/functions.md

@@ -6,7 +6,7 @@ Functions are defined by an optional list of parameters in parentheses, an arrow
 codeFor('functions', 'cube(5)')
 ```
 
-Functions may also have default values for arguments, which will be used if the incoming argument is missing (`null` or `undefined`).
+Functions may also have default values for arguments, which will be used if the incoming argument is missing (`undefined`).
 
 ```
 codeFor('default_args', 'fill("cup")')

documentation/sections/generators.md

@@ -0,0 +1,17 @@
+## Generator Functions
+
+CoffeeScript supports ES2015 [generator functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*) through the `yield` keyword. There's no `function*(){}` nonsense — a generator in CoffeeScript is simply a function that yields.
+
+```
+codeFor('generators', 'ps.next().value')
+```
+
+`yield*` is called `yield from`, and `yield return` may be used if you need to force a generator that doesn’t yield.
+
+<div id="generator-iteration" class="bookmark"></div>
+
+You can iterate over a generator function using `for…from`.
+
+```
+codeFor('generator_iteration', 'getFibonacciNumbers(10)')
+```

documentation/sections/installation.md

@@ -1,11 +1,11 @@
 ## Installation
 
-The command-line version of `coffee` is available as a [Node.js](https://nodejs.org/) utility. The [core compiler](/v<%= majorVersion %>/browser-compiler/coffee-script.js) however, does not depend on Node, and can be run in any JavaScript environment, or in the browser (see [Try CoffeeScript](#try)).
+The command-line version of `coffee` is available as a [Node.js](https://nodejs.org/) utility. The [core compiler](/v<%= majorVersion %>/browser-compiler/coffeescript.js) however, does not depend on Node, and can be run in any JavaScript environment, or in the browser (see [Try CoffeeScript](#try)).
 
 To install, first make sure you have a working copy of the latest stable version of [Node.js](https://nodejs.org/). You can then install CoffeeScript globally with [npm](https://www.npmjs.com/):
 
 ```bash
-npm install --global coffeescript
+npm install --global coffeescript@next
 ```
 
 This will make the `coffee` and `cake` commands available globally.
@@ -13,7 +13,7 @@ This will make the `coffee` and `cake` commands available globally.
 When you need CoffeeScript as a dependency of a project, within that project’s folder you can install it locally:
 
 ```bash
-npm install --save coffeescript
+npm install --save coffeescript@next
 ```
 
-The `coffee` and `cake` commands will first look in the current folder to see if CoffeeScript is installed locally, and use that version if so. This allows different versions of CoffeeScript to be installed globally and locally.
+The `coffee` and `cake` commands will first look in the current folder to see if CoffeeScript is installed locally, and use that version if so. This allows different versions of CoffeeScript to be installed globally and locally.

documentation/sections/introduction.md

@@ -1,13 +1,9 @@
 **CoffeeScript is a little language that compiles into JavaScript.** Underneath that awkward Java-esque patina, JavaScript has always had a gorgeous heart. CoffeeScript is an attempt to expose the good parts of JavaScript in a simple way.
 
-The golden rule of CoffeeScript is: _“It’s just JavaScript”_. The code compiles one-to-one into the equivalent JS, and there is no interpretation at runtime. You can use any existing JavaScript library seamlessly from CoffeeScript (and vice-versa). The compiled output is readable, pretty-printed, and tends to run as fast or faster than the equivalent handwritten JavaScript.
-
-The CoffeeScript compiler goes to great lengths to generate output JavaScript that runs in every JavaScript runtime, but there are exceptions. Use [generator functions](#generator-functions), [`for…from`](#generator-iteration), or [tagged template literals](#tagged-template-literals) only if you know that your [target runtimes can support them](http://kangax.github.io/compat-table/es6/). If you use [modules](#modules), you will need to [use an additional tool to resolve them](#modules-note).
+The golden rule of CoffeeScript is: _“It’s just JavaScript.”_ The code compiles one-to-one into the equivalent JS, and there is no interpretation at runtime. You can use any existing JavaScript library seamlessly from CoffeeScript (and vice-versa). The compiled output is readable, pretty-printed, and tends to run as fast or faster than the equivalent handwritten JavaScript.
 
 **Latest Version:** [<%= fullVersion %>](https://github.com/jashkenas/coffeescript/tarball/<%= fullVersion %>)
 
 ```bash
-npm install -g coffeescript
+npm install -g coffeescript@next
 ```
-
-**CoffeeScript 2 is coming!** It adds support for [ES2015 classes](/v2/#classes), [`async`/`await`](/v2/#fat-arrow), [JSX](/v2/#jsx), <span class="nowrap">[object rest/spread syntax](/v2/#splats)</span>, and JavaScript generated using ES2015+ syntax. [Learn more](/v2/).

documentation/sections/jsx.md

@@ -0,0 +1,13 @@
+## JSX
+
+[JSX](https://facebook.github.io/react/docs/introducing-jsx.html) is JavaScript containing interspersed XML elements. While conceived for [React](https://facebook.github.io/react/), it is not specific to any particular library or framework.
+
+CoffeeScript supports interspersed XML elements, without the need for separate plugins or special settings. The XML elements will be compiled as such, outputting JSX that could be parsed like any normal JSX file, for example by [Babel with the React JSX transform](https://babeljs.io/docs/plugins/transform-react-jsx/). CoffeeScript does _not_ output `React.createElement` calls or any code specific to React or any other framework. It is up to you to attach another step in your build chain to convert this JSX to whatever function calls you wish the XML elements to compile to.
+
+Just like in JSX and HTML, denote XML tags using `<` and `>`. You can interpolate CoffeeScript code inside a tag using `{` and `}`. To avoid compiler errors, when using `<` and `>` to mean “less than” or “greater than,” you should wrap the operators in spaces to distinguish them from XML tags. So `i < len`, not `i<len`. The compiler tries to be forgiving when it can be sure what you intend, but always putting spaces around the “less than” and “greater than” operators will remove ambiguity.
+
+```
+codeFor('jsx')
+```
+
+Older plugins or forks of CoffeeScript supported JSX syntax and referred to it as CSX or CJSX. They also often used a `.cjsx` file extension, but this is no longer necessary; regular `.coffee` will do.

documentation/sections/language.md

@@ -2,7 +2,7 @@
 
 _This reference is structured so that it can be read from top to bottom, if you like. Later sections use ideas and syntax previously introduced. Familiarity with JavaScript is assumed. In all of the following examples, the source CoffeeScript is provided on the left, and the direct compilation into JavaScript is on the right._
 
-_Many of the examples can be run (where it makes sense) by pressing the **run** button on the right, and can be loaded into the “Try CoffeeScript” console by pressing the **load** button on the left._
+_Many of the examples can be run (where it makes sense) by pressing the_ <small>▶</small> _button on the right. The CoffeeScript on the left is editable, and the JavaScript will update as you edit._
 
 First, the basics: CoffeeScript uses significant whitespace to delimit blocks of code. You don’t need to use semicolons `;` to terminate expressions, ending the line will do just as well (although semicolons can still be used to fit multiple expressions onto a single line). Instead of using curly braces `{ }` to surround blocks of code in [functions](#literals), [if-statements](#conditionals), [switch](#switch), and [try/catch](#try), use indentation.
 

documentation/sections/lexical_scope.md

@@ -6,10 +6,12 @@ The CoffeeScript compiler takes care to make sure that all of your variables are
 codeFor('scope', 'inner')
 ```
 
-Notice how all of the variable declarations have been pushed up to the top of the closest scope, the first time they appear. **outer** is not redeclared within the inner function, because it’s already in scope; **inner** within the function, on the other hand, should not be able to change the value of the external variable of the same name, and therefore has a declaration of its own.
+Notice how all of the variable declarations have been pushed up to the top of the closest scope, the first time they appear. `outer` is not redeclared within the inner function, because it’s already in scope; `inner` within the function, on the other hand, should not be able to change the value of the external variable of the same name, and therefore has a declaration of its own.
 
-This behavior is effectively identical to Ruby’s scope for local variables. Because you don’t have direct access to the `var` keyword, it’s impossible to shadow an outer variable on purpose, you may only refer to it. So be careful that you’re not reusing the name of an external variable accidentally, if you’re writing a deeply nested function.
+Because you don’t have direct access to the `var` keyword, it’s impossible to shadow an outer variable on purpose, you may only refer to it. So be careful that you’re not reusing the name of an external variable accidentally, if you’re writing a deeply nested function.
 
-Although suppressed within this documentation for clarity, all CoffeeScript output is wrapped in an anonymous function: `(function(){ … })();` This safety wrapper, combined with the automatic generation of the `var` keyword, make it exceedingly difficult to pollute the global namespace by accident.
+Although suppressed within this documentation for clarity, all CoffeeScript output (except in files with `import` or `export` statements) is wrapped in an anonymous function: `(function(){ … })();`. This safety wrapper, combined with the automatic generation of the `var` keyword, make it exceedingly difficult to pollute the global namespace by accident. (The safety wrapper can be disabled with the [`bare` option](#usage), and is unnecessary and automatically disabled when using modules.)
 
-If you’d like to create top-level variables for other scripts to use, attach them as properties on **window**; attach them as properties on the **exports** object in CommonJS; or use an [`export` statement](#modules). If you’re targeting both CommonJS and the browser, the **existential operator** (covered below), gives you a reliable way to figure out where to add them: `exports ? this`
+If you’d like to create top-level variables for other scripts to use, attach them as properties on `window`; attach them as properties on the `exports` object in CommonJS; or use an [`export` statement](#modules). If you’re targeting both CommonJS and the browser, the [existential operator](#existential-operator) (covered below), gives you a reliable way to figure out where to add them: `exports ? this`.
+
+Since CoffeeScript takes care of all variable declaration, it is not possible to declare variables with ES2015’s `let` or `const`. [This is intentional](#unsupported-let-const); we feel that the simplicity gained by not having to think about variable declaration outweighs the benefit of having three separate ways to declare variables.

documentation/sections/literate.md

@@ -1,5 +1,11 @@
 ## Literate CoffeeScript
 
-Besides being used as an ordinary programming language, CoffeeScript may also be written in “literate” mode. If you name your file with a `.litcoffee` extension, you can write it as a Markdown document — a document that also happens to be executable CoffeeScript code. The compiler will treat any indented blocks (Markdown’s way of indicating source code) as code, and ignore the rest as comments.
+Besides being used as an ordinary programming language, CoffeeScript may also be written in “literate” mode. If you name your file with a `.litcoffee` extension, you can write it as a Markdown document — a document that also happens to be executable CoffeeScript code. The compiler will treat any indented blocks (Markdown’s way of indicating source code) as executable code, and ignore the rest as comments. Code blocks must also be separated from comments by at least one blank line.
 
 Just for kicks, a little bit of the compiler is currently implemented in this fashion: See it [as a document](https://gist.github.com/jashkenas/3fc3c1a8b1009c00d9df), [raw](https://raw.githubusercontent.com/jashkenas/coffeescript/master/src/scope.litcoffee), and [properly highlighted in a text editor](http://cl.ly/LxEu).
+
+A few caveats:
+
+* Code blocks need to maintain consistent indentation relative to each other. When the compiler parses your Literate CoffeeScript file, it first discards all the non-code block lines and then parses the remainder as a regular CoffeeScript file. Therefore the code blocks need to be written as if the comment lines don’t exist, with consistent indentation (including whether they are indented with tabs or spaces).
+* Along those lines, code blocks within list items or blockquotes are not treated as executable code. Since list items and blockquotes imply their own indentation, it would be ambiguous how to treat indentation between successive code blocks when some are within these other blocks and some are not.
+* List items can be at most only one paragraph long. The second paragraph of a list item would be indented after a blank line, and therefore indistinguishable from a code block.

documentation/sections/loops.md

@@ -1,12 +1,12 @@
 ## Loops and Comprehensions
 
-Most of the loops you’ll write in CoffeeScript will be **comprehensions** over arrays, objects, and ranges. Comprehensions replace (and compile into) **for** loops, with optional guard clauses and the value of the current array index. Unlike for loops, array comprehensions are expressions, and can be returned and assigned.
+Most of the loops you’ll write in CoffeeScript will be **comprehensions** over arrays, objects, and ranges. Comprehensions replace (and compile into) `for` loops, with optional guard clauses and the value of the current array index. Unlike for loops, array comprehensions are expressions, and can be returned and assigned.
 
 ```
 codeFor('array_comprehensions')
 ```
 
-Comprehensions should be able to handle most places where you otherwise would use a loop, **each**/**forEach**, **map**, or **select**/**filter**, for example:<br>
+Comprehensions should be able to handle most places where you otherwise would use a loop, `each`/`forEach`, `map`, or `select`/`filter`, for example:<br>
 `shortNames = (name for name in list when name.length < 5)`<br>
 If you know the start and end of your loop, or would like to step through in fixed-size increments, you can use a range to specify the start and end of your comprehension.
 
@@ -32,13 +32,13 @@ If you would like to iterate over just the keys that are defined on the object i
 
 To iterate a generator function, use `from`. See [Generator Functions](#generator-iteration).
 
-The only low-level loop that CoffeeScript provides is the **while** loop. The main difference from JavaScript is that the **while** loop can be used as an expression, returning an array containing the result of each iteration through the loop.
+The only low-level loop that CoffeeScript provides is the `while` loop. The main difference from JavaScript is that the `while` loop can be used as an expression, returning an array containing the result of each iteration through the loop.
 
 ```
 codeFor('while', 'lyrics.join("\\n")')
 ```
 
-For readability, the **until** keyword is equivalent to `while not`, and the **loop** keyword is equivalent to `while true`.
+For readability, the `until` keyword is equivalent to `while not`, and the `loop` keyword is equivalent to `while true`.
 
 When using a JavaScript loop to generate functions, it’s common to insert a closure wrapper in order to ensure that loop variables are closed over, and all the generated functions don’t just share the final values. CoffeeScript provides the `do` keyword, which immediately invokes a passed function, forwarding any arguments.
 

documentation/sections/nodejs_usage.md

@@ -0,0 +1,25 @@
+### Node.js
+
+If you’d like to use Node.js’ CommonJS to `require` CoffeeScript files, e.g. `require './app.coffee'`, you must first “register” CoffeeScript as an extension:
+
+```coffee
+require 'coffeescript/register'
+
+App = require './app' # The .coffee extension is optional
+```
+
+If you want to use the compiler’s API, for example to make an app that compiles strings of CoffeeScript on the fly, you can `require` the full module:
+
+```coffee
+CoffeeScript = require 'coffeescript'
+
+eval CoffeeScript.compile 'console.log "Mmmmm, I could really go for some #{Math.pi}"'
+```
+
+The `compile` method has the signature `compile(code, options)` where `code` is a string of CoffeeScript code, and the optional `options` is an object with some or all of the following properties:
+
+* `options.sourceMap`, boolean: if true, a source map will be generated; and instead of returning a string, `compile` will return an object of the form `{js, v3SourceMap, sourceMap}`.
+* `options.inlineMap`, boolean: if true, output the source map as a base64-encoded string in a comment at the bottom.
+* `options.filename`, string: the filename to use for the source map.
+* `options.bare`, boolean: if true, output without the [top-level function safety wrapper](#lexical-scope).
+* `options.header`, boolean: if true, output the `Generated by CoffeeScript` header.

documentation/sections/operators.md

@@ -6,7 +6,7 @@ You can use `not` as an alias for `!`.
 
 For logic, `and` compiles to `&&`, and `or` into `||`.
 
-Instead of a newline or semicolon, `then` can be used to separate conditions from expressions, in **while**, **if**/**else**, and **switch**/**when** statements.
+Instead of a newline or semicolon, `then` can be used to separate conditions from expressions, in `while`, `if`/`else`, and `switch`/`when` statements.
 
 As in [YAML](http://yaml.org/), `on` and `yes` are the same as boolean `true`, while `off` and `no` are boolean `false`.
 
@@ -16,6 +16,8 @@ As a shortcut for `this.property`, you can use `@property`.
 
 You can use `in` to test for array presence, and `of` to test for JavaScript object-key presence.
 
+In a `for` loop, `from` compiles to the [ES2015 `of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of). (Yes, it’s unfortunate; the CoffeeScript `of` predates the ES2015 `of`.)
+
 To simplify math expressions, `**` can be used for exponentiation and `//` performs integer division. `%` works just like in JavaScript, while `%%` provides [“dividend dependent modulo”](https://en.wikipedia.org/wiki/Modulo_operation):
 
 ```
@@ -34,8 +36,9 @@ All together now:
 | `true`, `yes`, `on` | `true` |
 | `false`, `no`, `off`  | `false` |
 | `@`, `this` | `this` |
-| `of` | `in` |
-| `in` | _no JS equivalent_ |
+| `a in b` | `[].indexOf.call(b, a) >= 0` |
+| `a of b` | `a in b` |
+| `for a from b` | `for (a of b)` |
 | `a ** b` | `Math.pow(a, b)` |
 | `a // b` | `Math.floor(a / b)` |
 | `a %% b` | `(a % b + b) % b` |

documentation/sections/overview.md

@@ -1,6 +1,6 @@
 ## Overview
 
-_CoffeeScript on the left, compiled JavaScript output on the right._
+_CoffeeScript on the <span class="hidden-md-up">top</span><span class="hidden-sm-down">left</span>, compiled JavaScript output on the <span class="hidden-md-up">bottom</span><span class="hidden-sm-down">right</span>. The CoffeeScript is editable!_
 
 ```
 codeFor('overview', 'cubes', false)

documentation/sections/prototypal_inheritance.md

@@ -0,0 +1,7 @@
+## Prototypal Inheritance
+
+In addition to supporting ES2015 classes, CoffeeScript provides a shortcut for working with prototypes. The `::` operator gives you quick access to an object’s prototype:
+
+```
+codeFor('prototypes', '"one_two".dasherize()')
+```

documentation/sections/resources.md

@@ -1,14 +1,6 @@
 ## Resources
 
-*   [Source Code](https://github.com/jashkenas/coffeescript/)<br>
-    Use `bin/coffee` to test your changes,<br>
-    `bin/cake test` to run the test suite,<br>
-    `bin/cake build` to rebuild the full CoffeeScript compiler, and<br>
-    `bin/cake build:except-parser` to recompile much faster if you’re not editing `grammar.coffee`.
-
-    `git checkout lib && bin/cake build:full` is a good command to run when you’re working on the core language. It’ll refresh the `lib` folder (in case you broke something), build your altered compiler, use that to rebuild itself (a good sanity test) and then run all of the tests. If they pass, there’s a good chance you’ve made a successful change.
-*   [Browser Tests](/v<%= majorVersion %>/test.html)<br>
-    Run CoffeeScript’s test suite in your current browser.
+*   [CoffeeScript on GitHub](https://github.com/jashkenas/coffeescript/)
 *   [CoffeeScript Issues](https://github.com/jashkenas/coffeescript/issues)<br>
     Bug reports, feature proposals, and ideas for changes to the language belong here.
 *   [CoffeeScript Google Group](https://groups.google.com/forum/#!forum/coffeescript)<br>
@@ -17,7 +9,7 @@
     If you’ve ever learned a neat CoffeeScript tip or trick, or ran into a gotcha — share it on the wiki. The wiki also serves as a directory of handy [text editor extensions](https://github.com/jashkenas/coffeescript/wiki/Text-editor-plugins), [web framework plugins](https://github.com/jashkenas/coffeescript/wiki/Web-framework-plugins), and general [CoffeeScript build tools](https://github.com/jashkenas/coffeescript/wiki/Build-tools).
 *   [The FAQ](https://github.com/jashkenas/coffeescript/wiki/FAQ)<br>
     Perhaps your CoffeeScript-related question has been asked before. Check the FAQ first.
-*   [JS2Coffee](http://js2coffee.org)<br>
+*   [JS2Coffee](http://js2.coffee/)<br>
     Is a very well done reverse JavaScript-to-CoffeeScript compiler. It’s not going to be perfect (infer what your JavaScript classes are, when you need bound functions, and so on…) — but it’s a great starting point for converting simple scripts.
 *   [High-Rez Logo](https://github.com/jashkenas/coffeescript/tree/master/documentation/images)<br>
     The CoffeeScript logo is available in SVG for use in presentations.

documentation/sections/scripts.md

@@ -1,7 +1,7 @@
-## "text/coffeescript" Script Tags
+## `"text/coffeescript"` Script Tags
 
-While it’s not recommended for serious use, CoffeeScripts may be included directly within the browser using `<script type="text/coffeescript">` tags. The source includes a compressed and minified version of the compiler ([Download current version here, 51k when gzipped](/v<%= majorVersion %>/browser-compiler/coffee-script.js)) as `v<%= majorVersion %>/browser-compiler/coffee-script.js`. Include this file on a page with inline CoffeeScript tags, and it will compile and evaluate them in order.
+While it’s not recommended for serious use, CoffeeScripts may be included directly within the browser using `<script type="text/coffeescript">` tags. The source includes a compressed and minified version of the compiler ([Download current version here, 51k when gzipped](/v<%= majorVersion %>/browser-compiler/coffeescript.js)) as `docs/v<%= majorVersion %>/browser-compiler/coffeescript.js`. Include this file on a page with inline CoffeeScript tags, and it will compile and evaluate them in order.
 
-In fact, the little bit of glue script that runs “Try CoffeeScript” above, as well as the jQuery for the menu, is implemented in just this way. View source and look at the bottom of the page to see the example. Including the script also gives you access to `CoffeeScript.compile()` so you can pop open Firebug and try compiling some strings.
+In fact, the little bit of glue script that runs [Try CoffeeScript](#try), as well as the code examples and other interactive parts of this site, is implemented in just this way. View source and look at the bottom of the page to see the example. Including the script also gives you access to `CoffeeScript.compile()` so you can pop open your JavaScript console and try compiling some strings.
 
 The usual caveats about CoffeeScript apply — your inline scripts will run within a closure wrapper, so if you want to expose global variables or functions, attach them to the `window` object.

documentation/sections/source_maps.md

@@ -1,5 +1,5 @@
 ## Source Maps
 
-CoffeeScript 1.6.1 and above include support for generating source maps, a way to tell your JavaScript engine what part of your CoffeeScript program matches up with the code being evaluated. Browsers that support it can automatically use source maps to show your original source code in the debugger. To generate source maps alongside your JavaScript files, pass the `--map` or `-m` flag to the compiler.
+CoffeeScript includes support for generating source maps, a way to tell your JavaScript engine what part of your CoffeeScript program matches up with the code being evaluated. Browsers that support it can automatically use source maps to show your original source code in the debugger. To generate source maps alongside your JavaScript files, pass the `--map` or `-m` flag to the compiler.
 
 For a full introduction to source maps, how they work, and how to hook them up in your browser, read the [HTML5 Tutorial](https://www.html5rocks.com/en/tutorials/developertools/sourcemaps/).

documentation/sections/splats.md

@@ -1,7 +1,25 @@
-## Splats…
+## Splats, or Rest Parameters/Spread Syntax
 
-The JavaScript **arguments object** is a useful way to work with functions that accept variable numbers of arguments. CoffeeScript provides splats `...`, both for function definition as well as invocation, making variable numbers of arguments a little bit more palatable.
+The JavaScript `arguments` object is a useful way to work with functions that accept variable numbers of arguments. CoffeeScript provides splats `...`, both for function definition as well as invocation, making variable numbers of arguments a little bit more palatable. ES2015 adopted this feature as their [rest parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters).
 
 ```
 codeFor('splats', true)
 ```
+
+<div id="array-spread" class="bookmark"></div>
+
+Splats also let us elide array elements...
+
+```
+codeFor('array_spread', 'all')
+```
+
+<div id="object-spread" class="bookmark"></div>
+
+...and object properties.
+
+```
+codeFor('object_spread', 'JSON.stringify(currentUser)')
+```
+
+In ECMAScript this is called [spread syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator), and has been supported for arrays since ES2015 but is [coming soon for objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator#Spread_in_object_literals). Until object spread syntax is officially supported, the CoffeeScript compiler outputs the same polyfill as [Babel’s rest spread transform](https://babeljs.io/docs/plugins/transform-object-rest-spread/); but once it is supported, we will revise the compiler’s output. Note that there are [very subtle differences](https://developers.google.com/web/updates/2017/06/object-rest-spread) between the polyfill and the current proposal.

documentation/sections/strings.md

@@ -1,6 +1,6 @@
-## String Interpolation, Block Strings, and Block Comments
+## Strings
 
-Ruby-style string interpolation is included in CoffeeScript. Double-quoted strings allow for interpolated values, using `#{ … }`, and single-quoted strings are literal. You may even use interpolation in object keys.
+Like JavaScript and many other languages, CoffeeScript supports strings as delimited by the `"` or `'` characters. CoffeeScript also supports string interpolation within `"`-quoted strings, using `#{ … }`. Single-quoted strings are literal. You may even use interpolation in object keys.
 
 ```
 codeFor('interpolation', 'sentence')
@@ -12,16 +12,10 @@ Multiline strings are allowed in CoffeeScript. Lines are joined by a single spac
 codeFor('strings', 'mobyDick')
 ```
 
-Block strings can be used to hold formatted or indentation-sensitive text (or, if you just don’t feel like escaping quotes and apostrophes). The indentation level that begins the block is maintained throughout, so you can keep it all aligned with the body of your code.
+Block strings, delimited by `"""` or `'''`, can be used to hold formatted or indentation-sensitive text (or, if you just don’t feel like escaping quotes and apostrophes). The indentation level that begins the block is maintained throughout, so you can keep it all aligned with the body of your code.
 
 ```
 codeFor('heredocs', 'html')
 ```
 
 Double-quoted block strings, like other double-quoted strings, allow interpolation.
-
-Sometimes you’d like to pass a block comment through to the generated JavaScript. For example, when you need to embed a licensing header at the top of a file. Block comments, which mirror the syntax for block strings, are preserved in the generated code.
-
-```
-codeFor('block_comment')
-```

documentation/sections/switch.md

@@ -1,14 +1,14 @@
 ## Switch/When/Else
 
-**Switch** statements in JavaScript are a bit awkward. You need to remember to **break** at the end of every **case** statement to avoid accidentally falling through to the default case. CoffeeScript prevents accidental fall-through, and can convert the `switch` into a returnable, assignable expression. The format is: `switch` condition, `when` clauses, `else` the default case.
+`switch` statements in JavaScript are a bit awkward. You need to remember to `break` at the end of every `case` statement to avoid accidentally falling through to the default case. CoffeeScript prevents accidental fall-through, and can convert the `switch` into a returnable, assignable expression. The format is: `switch` condition, `when` clauses, `else` the default case.
 
-As in Ruby, **switch** statements in CoffeeScript can take multiple values for each **when** clause. If any of the values match, the clause runs.
+As in Ruby, `switch` statements in CoffeeScript can take multiple values for each `when` clause. If any of the values match, the clause runs.
 
 ```
 codeFor('switch')
 ```
 
-Switch statements can also be used without a control expression, turning them in to a cleaner alternative to if/else chains.
+`switch` statements can also be used without a control expression, turning them in to a cleaner alternative to `if`/`else` chains.
 
 ```
 codeFor('switch_with_no_expression')

documentation/sections/tagged_template_literals.md

@@ -2,8 +2,6 @@
 
 CoffeeScript supports [ES2015 tagged template literals](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals), which enable customized string interpolation. If you immediately prefix a string with a function name (no space between the two), CoffeeScript will output this “function plus string” combination as an ES2015 tagged template literal, which will [behave accordingly](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals): the function is called, with the parameters being the input text and expression parts that make up the interpolated string. The function can then assemble these parts into an output string, providing custom string interpolation.
 
-Be aware that the CoffeeScript compiler is outputting ES2015 syntax for this feature, so your target JavaScript runtime(s) must support this syntax for your code to work; or you could use tools like [Babel](http://babeljs.io/) or [Traceur Compiler](https://github.com/google/traceur-compiler) to convert this ES2015 syntax into compatible JavaScript.
-
 ```
 codeFor('tagged_template_literals', 'greet("greg", "awesome")')
 ```

documentation/sections/test.md

@@ -0,0 +1,7 @@
+## Browser-based Tests
+
+CoffeeScript includes an extensive test suite, which verifies that the compiler generates JavaScript that behaves as it should. The tests canonically run via the Node runtime, and must all pass there before we consider publishing a new release of CoffeeScript; but you can also run the tests in a web browser. This can be a good way to determine which features of CoffeeScript your current browser may not support. In general, the latest version of [Google Chrome Canary](https://www.google.com/chrome/browser/canary.html) should pass all the tests.
+
+Note that since no JavaScript runtime yet supports ES2015 modules, the tests for module support verify only that the CoffeeScript compiler’s output is the correct syntax; the tests don’t verify that the modules resolve properly.
+
+[Run the tests in your browser.](http://coffeescript.org/v<%= majorVersion %>/test.html)

documentation/sections/try.md

@@ -1,6 +1,6 @@
 ## Try/Catch/Finally
 
-Try-expressions have the same semantics as try-statements in JavaScript, though in CoffeeScript, you may omit _both_ the catch and finally parts. The catch part may also omit the error parameter if it is not needed.
+`try` expressions have the same semantics as `try` statements in JavaScript, though in CoffeeScript, you may omit _both_ the catch and finally parts. The catch part may also omit the error parameter if it is not needed.
 
 ```
 codeFor('try')

documentation/sections/type_annotations.md

@@ -0,0 +1,17 @@
+## Type Annotations
+
+Static type checking can be achieved in CoffeeScript by using [Flow](https://flow.org/)’s [Comment Types syntax](https://flow.org/en/docs/types/comments/):
+
+```
+codeFor('type_annotations')
+```
+
+CoffeeScript does not do any type checking itself; the JavaScript output you see above needs to get passed to Flow for it to validate your code. We expect most people will use a [build tool](#es2015plus-output) for this, but here’s how to do it the simplest way possible using the [CoffeeScript](#cli) and [Flow](https://flow.org/en/docs/usage/) command-line tools, assuming you’ve already [installed Flow](https://flow.org/en/docs/install/) and the [latest CoffeeScript](#installation) in your project folder:
+
+```bash
+coffee --bare --no-header --compile app.coffee && npm run flow
+```
+
+`--bare` and `--no-header` are important because Flow requires the first line of the file to be the comment `// @flow`. If you configure your build chain to compile CoffeeScript and pass the result to Flow in-memory, you can get better performance than this example; and a proper build tool should be able to watch your CoffeeScript files and recompile and type-check them for you on save.
+
+If you know of another way to achieve static type checking with CoffeeScript, please [create an issue](https://github.com/jashkenas/coffeescript/issues/new) and let us know.

documentation/sections/unsupported.md

@@ -0,0 +1,3 @@
+## Unsupported ECMAScript Features
+
+There are a few ECMAScript features that CoffeeScript intentionally doesn’t support.

documentation/sections/unsupported_get_set.md

@@ -0,0 +1,9 @@
+### `get` and `set` keyword shorthand syntax
+
+`get` 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty) that is slightly more verbose but just as effective:
+
+```
+codeFor('get_set', 'screen.height')
+```

documentation/sections/unsupported_let_const.md

@@ -0,0 +1,13 @@
+### `let` and `const`: block-scoped and reassignment-protected variables
+
+When CoffeeScript was designed, `var` was [intentionally omitted](https://github.com/jashkenas/coffeescript/issues/238#issuecomment-153502). 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:
+
+```js
+const obj = {foo: 'bar'};
+obj.foo = 'baz'; // Allowed!
+obj = {}; // Throws error
+```

documentation/sections/unsupported_named_functions.md

@@ -0,0 +1,5 @@
+### Named functions and function declarations
+
+Newcomers to CoffeeScript often wonder how to generate the JavaScript `function foo() {}`, as opposed to the `foo = function() {}` that CoffeeScript produces. The first form is a [function declaration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function), and the second is a [function expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/function). As stated above, in CoffeeScript [everything is an expression](#expressions), so naturally we favor the expression form. Supporting only one variant helps avoid confusing bugs that can arise from the [subtle differences between the two forms](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function#Function_declaration_hoisting).
+
+Technically, `foo = function() {}` is creating an anonymous function that gets assigned to a variable named `foo`. Some very early versions of CoffeeScript named this function, e.g. `foo = function foo() {}`, but this was dropped because of compatibility issues with Internet Explorer. For a while this annoyed people, as these functions would be unnamed in stack traces; but modern JavaScript runtimes [infer the names of such anonymous functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/name) from the names of the variables to which they’re assigned. Given that this is the case, and given that not all functions in function expressions can be named (for example, the functions in `first.fn = ->; second.fn = ->` can’t both be named `fn`) it’s simplest to just preserve the current behavior.

documentation/sections/usage.md

@@ -1,37 +1 @@
 ## Usage
-
-Once installed, you should have access to the `coffee` command, which can execute scripts, compile `.coffee` files into `.js`, and provide an interactive REPL. The `coffee` command takes the following options:
-
-| Option | Description |
-| --- | --- |
-| `-c, --compile` | Compile a `.coffee` script into a `.js` JavaScript file of the same name. |
-| `-m, --map` | Generate source maps alongside the compiled JavaScript files. Adds `sourceMappingURL` directives to the JavaScript as well. |
-| `-M, --inline-map` | Just like `--map`, but include the source map directly in the compiled JavaScript files, rather than in a separate file. |
-| `-i, --interactive` | Launch an interactive CoffeeScript session to try short snippets. Identical to calling `coffee` with no arguments. |
-| `-o, --output [DIR]` | Write out all compiled JavaScript files into the specified directory. Use in conjunction with `--compile` or `--watch`. |
-| `-w, --watch` | Watch files for changes, rerunning the specified command when any file is updated. |
-| `-p, --print` | Instead of writing out the JavaScript as a file, print it directly to **stdout**. |
-| `-s, --stdio` | Pipe in CoffeeScript to STDIN and get back JavaScript over STDOUT. Good for use with processes written in other languages. An example:<br>`cat src/cake.coffee | coffee -sc` |
-| `-l, --literate` | Parses the code as Literate CoffeeScript. You only need to specify this when passing in code directly over **stdio**, or using some sort of extension-less file name. |
-| `-e, --eval` | Compile and print a little snippet of CoffeeScript directly from the command line. For example:<br>`coffee -e "console.log num for num in [10..1]"` |
-| `-r, --require [MODULE]`&emsp; | `require()` the given module before starting the REPL or evaluating the code given with the `--eval` flag. |
-| `-b, --bare` | Compile the JavaScript without the [top-level function safety wrapper](#lexical-scope). |
-| `-t, --tokens` | Instead of parsing the CoffeeScript, just lex it, and print out the token stream. Used for debugging the compiler. |
-| `-n, --nodes` | Instead of compiling the CoffeeScript, just lex and parse it, and print out the parse tree. Used for debugging the compiler. |
-| `--nodejs` | The `node` executable has some useful options you can set, such as `--debug`, `--debug-brk`, `--max-stack-size`, and `--expose-gc`. Use this flag to forward options directly to Node.js. To pass multiple flags, use `--nodejs` multiple times. |
-| `--no-header` | Suppress the “Generated by CoffeeScript” header. |
-
-### Examples:
-
-*   Compile a directory tree of `.coffee` files in `src` into a parallel tree of `.js` files in `lib`:<br>
-    `coffee --compile --output lib/ src/`
-*   Watch a file for changes, and recompile it every time the file is saved:<br>
-    `coffee --watch --compile experimental.coffee`
-*   Concatenate a list of files into a single script:<br>
-    `coffee --join project.js --compile src/*.coffee`
-*   Print out the compiled JS from a one-liner:<br>
-    `coffee -bpe "alert i for i in [0..10]"`
-*   All together now, watch and recompile an entire project as you work on it:<br>
-    `coffee -o lib/ -cw src/`
-*   Start the CoffeeScript REPL (`Ctrl-D` to exit, `Ctrl-V`for multi-line):<br>
-    `coffee`

documentation/test.html

@@ -3,7 +3,7 @@
 <head>
   <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
   <title>CoffeeScript Test Suite</title>
-  <script src="browser-compiler/coffee-script.js"></script>
+  <script src="browser-compiler/coffeescript.js"></script>
   <script src="https://cdn.jsdelivr.net/underscorejs/1.8.3/underscore-min.js"></script>
   <style>
     body, pre {
@@ -39,9 +39,11 @@
 <script type="text/coffeescript">
 @testingBrowser = yes
 @global = window
-stdout  = document.getElementById 'stdout'
-start   = new Date
-success = total = done = failed = 0
+bold = red = green = reset = ''
+stdout = document.getElementById 'stdout'
+start = new Date
+@currentFile = ''
+@passedTests = failedTests = total = done = 0
 
 say = (msg, className) ->
   div = document.createElement 'div'
@@ -54,12 +56,20 @@ say = (msg, className) ->
   ++total
   try
     fn.call(fn)
-    ++success
-  catch exception
-    say "#{description}:", 'bad'
-    say fn.toString(), 'subtle' if fn.toString?
-    say exception, 'bad'
-    console.error exception
+    ++passedTests
+  catch error
+    failures.push
+      error: error
+      description: description
+      source: fn.toString() if fn.toString?
+
+@failures =
+  push: (failure) -> # Match function called by regular tests
+    ++failedTests
+    say "#{failure.description}:", 'bad'
+    say failure.source, 'subtle' if failure.source?
+    say failure.error, 'bad'
+    console.error failure.error
 
 @ok = (good, msg = 'Error') ->
   throw Error msg unless good
@@ -99,14 +109,15 @@ say = (msg, className) ->
 for test in document.getElementsByClassName 'test'
   say '\u2714 ' + test.id
   options = {}
+  options.filename = currentFile = test.id
   options.literate = yes if test.type is 'text/x-literate-coffeescript'
   CoffeeScript.run test.innerHTML, options
 
 # Finish up
-yay = success is total and not failed
+yay = passedTests is total and not failedTests
 sec = (new Date - start) / 1000
-msg = "passed #{success} tests in #{ sec.toFixed 2 } seconds"
-msg = "failed #{ total - success } tests and #{msg}" unless yay
+msg = "passed #{passedTests} tests in #{sec.toFixed 2} seconds"
+msg = "failed #{total - passedTests} tests and #{msg}" unless yay
 say msg, (if yay then 'good' else 'bad')
 </script>
 

documentation/v1/body.html

@@ -35,7 +35,7 @@
       <a href="#source-maps">Source Maps</a>
       <a href="#scripts">"text/coffeescript" Script Tags</a>
       <a href="#resources">Books, Screencasts, Examples and Resources</a>
-      <a href="#changelog">Change Log</a>
+      <a href="#changelog">Changelog</a>
     </div>
   </div>
   <div class="navigation try">

documentation/v1/code.coffee

@@ -1,5 +1,5 @@
 fs           = require 'fs'
-CoffeeScript = require '../../lib/coffee-script'
+CoffeeScript = require '../../lib/coffeescript'
 
 
 module.exports = ->

documentation/v1/scripts.html

@@ -3,4 +3,4 @@
 </script>
 
 <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
-<script src="v<%= majorVersion %>/browser-compiler/coffee-script.js"></script>
+<script src="v<%= majorVersion %>/browser-compiler/coffeescript.js"></script>

documentation/v2/body.html

@@ -0,0 +1,203 @@
+<%= include('navbar.html') %>
+
+<%= include('try.html') %>
+
+<div class="container-fluid" id="top">
+  <div class="row row-offcanvas row-offcanvas-left">
+    <nav class="sidebar sidebar-offcanvas col-xs-12 col-lg-3 bg-ribbed-light">
+      <%= include('sidebar.html') %>
+    </nav>
+    <main class="main col-xs-12 col-lg-9 offset-lg-3">
+
+      <header class="title-logo hidden-md-down">
+        <%= include('documentation/images/logo.svg') %>
+      </header>
+
+      <section id="overview">
+        <%= htmlFor('introduction') %>
+        <%= htmlFor('overview') %>
+      </section>
+      <section id="coffeescript-2">
+        <%= htmlFor('coffeescript_2') %>
+      </section>
+      <section id="installation">
+        <%= htmlFor('installation') %>
+      </section>
+      <section id="usage">
+        <%= htmlFor('usage') %>
+        <section id="cli">
+          <%= htmlFor('command_line_interface') %>
+        </section>
+        <section id="es2015plus-output">
+          <%= htmlFor('es2015plus_output') %>
+        </section>
+        <section id="nodejs-usage">
+          <%= htmlFor('nodejs_usage') %>
+        </section>
+      </section>
+      <section id="language">
+        <%= htmlFor('language') %>
+        <section id="functions">
+          <%= htmlFor('functions') %>
+        </section>
+        <section id="strings">
+          <%= htmlFor('strings') %>
+        </section>
+        <section id="objects-and-arrays">
+          <%= htmlFor('objects_and_arrays') %>
+        </section>
+        <section id="comments">
+          <%= htmlFor('comments') %>
+        </section>
+        <section id="lexical-scope">
+          <%= htmlFor('lexical_scope') %>
+        </section>
+        <section id="conditionals">
+          <%= htmlFor('conditionals') %>
+        </section>
+        <section id="splats">
+          <%= htmlFor('splats') %>
+        </section>
+        <section id="loops">
+          <%= htmlFor('loops') %>
+        </section>
+        <section id="slices">
+          <%= htmlFor('slices') %>
+        </section>
+        <section id="expressions">
+          <%= htmlFor('expressions') %>
+        </section>
+        <section id="operators">
+          <%= htmlFor('operators') %>
+        </section>
+        <section id="existential-operator">
+          <%= htmlFor('existential_operator') %>
+        </section>
+        <section id="chaining">
+          <%= htmlFor('chaining') %>
+        </section>
+        <section id="destructuring">
+          <%= htmlFor('destructuring') %>
+        </section>
+        <section id="fat-arrow">
+          <%= htmlFor('fat_arrow') %>
+        </section>
+        <section id="generators">
+          <%= htmlFor('generators') %>
+        </section>
+        <section id="async-functions">
+          <%= htmlFor('async_functions') %>
+        </section>
+        <section id="classes">
+          <%= htmlFor('classes') %>
+        </section>
+        <section id="prototypal-inheritance">
+          <%= htmlFor('prototypal_inheritance') %>
+        </section>
+        <section id="switch">
+          <%= htmlFor('switch') %>
+        </section>
+        <section id="try">
+          <%= htmlFor('try') %>
+        </section>
+        <section id="comparisons">
+          <%= htmlFor('comparisons') %>
+        </section>
+        <section id="regexes">
+          <%= htmlFor('heregexes') %>
+        </section>
+        <section id="tagged-template-literals">
+          <%= htmlFor('tagged_template_literals') %>
+        </section>
+        <section id="modules">
+          <%= htmlFor('modules') %>
+        </section>
+        <section id="embedded">
+          <%= htmlFor('embedded') %>
+        </section>
+        <section id="jsx">
+          <%= htmlFor('jsx') %>
+        </section>
+      </section>
+      <section id="type-annotations">
+        <%= htmlFor('type_annotations') %>
+      </section>
+      <section id="literate">
+        <%= htmlFor('literate') %>
+      </section>
+      <section id="source-maps">
+        <%= htmlFor('source_maps') %>
+      </section>
+      <section id="cake">
+        <%= htmlFor('cake') %>
+      </section>
+      <section id="scripts">
+        <%= htmlFor('scripts') %>
+      </section>
+      <section id="resources">
+        <%= htmlFor('resources') %>
+        <section id="books">
+          <%= htmlFor('books') %>
+        </section>
+        <section id="screencasts">
+          <%= htmlFor('screencasts') %>
+        </section>
+        <section id="examples">
+          <%= htmlFor('examples') %>
+        </section>
+        <section id="chat">
+          <%= htmlFor('chat') %>
+        </section>
+        <section id="annotated-source">
+          <%= htmlFor('annotated_source') %>
+        </section>
+        <section id="contributing">
+          <%= htmlFor('contributing') %>
+        </section>
+      </section>
+      <section id="unsupported">
+        <%= htmlFor('unsupported') %>
+        <section id="unsupported-let-const">
+          <%= htmlFor('unsupported_let_const') %>
+        </section>
+        <section id="unsupported-named-functions">
+          <%= htmlFor('unsupported_named_functions') %>
+        </section>
+        <section id="unsupported-get-set">
+          <%= htmlFor('unsupported_get_set') %>
+        </section>
+      </section>
+      <section id="breaking-changes">
+        <%= htmlFor('breaking_changes') %>
+        <section id="breaking-change-fat-arrow">
+          <%= htmlFor('breaking_change_fat_arrow') %>
+        </section>
+        <section id="breaking-changes-default-values">
+          <%= htmlFor('breaking_changes_default_values') %>
+        </section>
+        <section id="breaking-changes-bound-generator-functions">
+          <%= htmlFor('breaking_changes_bound_generator_functions') %>
+        </section>
+        <section id="breaking-changes-classes">
+          <%= htmlFor('breaking_changes_classes') %>
+        </section>
+        <section id="breaking-changes-super-extends">
+          <%= htmlFor('breaking_changes_super_extends') %>
+        </section>
+        <section id="breaking-changes-jsx-and-the-less-than-and-greater-than-operators">
+          <%= htmlFor('breaking_changes_jsx_and_the_less_than_and_greater_than_operators') %>
+        </section>
+        <section id="breaking-changes-literate-coffeescript">
+          <%= htmlFor('breaking_changes_literate_coffeescript') %>
+        </section>
+        <section id="breaking-changes-argument-parsing-and-shebang-lines">
+          <%= htmlFor('breaking_changes_argument_parsing_and_shebang_lines') %>
+        </section>
+      </section>
+      <section id="changelog">
+        <%= htmlFor('changelog') %>
+      </section>
+
+    </main>
+  </div>
+</div>

documentation/v2/code.coffee

@@ -0,0 +1,11 @@
+fs           = require 'fs'
+_            = require 'underscore'
+CoffeeScript = require '../../lib/coffeescript'
+
+
+module.exports = ->
+  (file, run = no) ->
+    cs = fs.readFileSync "documentation/examples/#{file}.coffee", 'utf-8'
+    js = CoffeeScript.compile cs, bare: yes # This is just the initial JavaScript output; it is replaced by dynamic compilation on changes of the CoffeeScript pane
+    render = _.template fs.readFileSync('documentation/v2/code.html', 'utf-8')
+    output = render {file, cs, js, run}