2.0.0-beta3 (#4594)

* Don’t confuse the syntax highlighter

* Comment Assign::compilePatternMatch a bit

* Assignment expressions in conditionals are a bad practice

* Rename `wrapInBraces` to `wrapInParentheses`, to set the stage for future `wrapInBraces` that uses `{` and `wrapInBrackets` that uses `[`

* Correct comment

* object destructuring

* Allow custom position of the rest element.

* Output simple array destructuring assignments to ES2015

* Output simple object destructured assignments to ES2015

* Compile shorthand object properties to ES2015 shorthand properties

This dramatically improves the appearance of destructured imports.

* Don’t confuse the syntax highlighter

* Comment Assign::compilePatternMatch a bit

* Assignment expressions in conditionals are a bad practice

* Rename `wrapInBraces` to `wrapInParentheses`, to set the stage for future `wrapInBraces` that uses `{` and `wrapInBrackets` that uses `[`

* object destructuring

* Allow custom position of the rest element.

* rest element in object destructuring

* rest element in object destructuring

* fix string interpolation

* merging

* fixing splats in object literal

* Rest element in parameter destructuring

* merging with CS2

* merged with CS2

* Add support for the object spread initializer. https://github.com/tc39/proposal-object-rest-spread/blob/master/Spread.md

* Fix misspellings, trailing whitespace, other minor details

* merging with beta2

* refactor object spread properties

* small fix

* - Fixed object spread function parameters.
- Clean up "Assign" and moved all logic for object rest properties in single method (compileObjectDestruct).
- Add helper function "objectWithoutKeys" to the "UTILITIES" for use with object rest properties,
  e.g. {a, b, r...} = obj => {a, b} = obj, r = objectWithoutKeys(...)
- Clean up "Obj" and moved all logic for object spread properties in single method (compileSpread).
- Clean up "Code".
- Add method "hasSplat" to "Obj" and "Value" for checking if Obj contains the splat.
- Enable placing spread syntax triple dots on either right or left, per #85 (https://github.com/coffeescript6/discuss/issues/85)

* Fixed typos

* Remove unused code

* Removed dots (e.g. splat) on the left side from the grammar

* Initial release for deep spread properties, e.g. obj2 = {obj.b..., a: 1} or {obj[b][c]..., d: 7}
Tests need to be prepared!

* 1. Object literal spread properties

Object literals:
- obj = { {b:{c:{d:1}}}..., a:1 }

Parenthetical:
- obj = { ( body ), a:1 }
- obj = { ( body )..., a:1 }

Invocation:
- obj = { ( (args) -> ... )(params), a:1 }
- obj = { ( (args) -> ... )(params)..., a:1 }
- obj = { foo(), a:1 }
- obj = { foo()..., a:1 }

2. Refactor, cleanup & other optimizations.

* Merged with 2.0

* Cleanup

* Some more cleanup.

* Fixed error with freeVariable and object destructuring.

* Fixed errors with object spread properties.

* Improvements, fixed errors.

* Minor improvement.

* Minor improvements.

* Typo.

* Remove unnecessary whitespace.

* Remove unnecessary whitespace.

* Changed few "assertErrorFormat" tests since parentheses are now allowed in the Obj.

* Whitespace cleanup

* Comments cleanup

* fix destructured obj param declarations

* refine fix; add test

* Refactor function args ({a, b...})

* Additional tests for object destructuring in function argument.

* Minor improvement for object destructuring variable declaration.

* refactor function args ({a, b...}) and ({a, b...} = {}); Obj And Param cleanup

* fix comment

* Fix object destructuring variable declaration.

* more tests with default values

* fix typo

* Fixed default values in object destructuring.

* small fix

* Babel’s tests for object rest spread

* Style: spaces after colons in object declarations

* Cleanup comments

* Simplify Babel tests

* Fix comments

* Fix destructuring with splats in multiple objects

* Add test for default values in detsructuring assignment with splats

* Handle default values when assigning to object splats

* Rewrite traverseRest to fix handling of dynamic keys

* Fix double parens around destructuring with splats

* Update compileObjectDestruct comments

* Improve formatting of top-level destructures with splats and tidy parens

* Added a bigger destructuring-with-defaults test and fixed a bug

* Refactor destructuring grammar to allow additional forms

* Add a missing case to ObjSpreadExpr

* These tests shouldn’t run in the browser

* Fix test.html

* Fix docs scroll position getting screwed up by CodeMirror initialization

* Breaking change documentation about => (fixes #4593)

* Spread/rest syntax documentation

* Documentation about bound class methods

* 2.0.0-beta3 changelog

* Add note about ‘lib’

* Fix accidentally converting this to tabs

* Bump version to 2.0.0-beta3

* Update annotated source and test.html

.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,9 +1,10 @@
 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 = ''
@@ -51,27 +52,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 +117,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 +130,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 +140,20 @@ 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'
+  presets.push 'babili' unless process.env.MINIFY is 'false'
+  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 +194,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 +340,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 +363,25 @@ 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.reset = reset
 
   # Our test helper function for delimiting different test cases.
   global.test = (description, fn) ->
@@ -415,9 +433,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/browser.html

@@ -124,7 +124,6 @@ We add support for loading remote Coffee scripts via <strong>XHR</strong>, and
             
             <div class="content"><div class='highlight'><pre>
 CoffeeScript = <span class="hljs-built_in">require</span> <span class="hljs-string">'./coffeescript'</span>
-CoffeeScript.<span class="hljs-built_in">require</span> = <span class="hljs-built_in">require</span>
 compile = CoffeeScript.compile</pre></div></div>
             
         </li>
@@ -171,11 +170,12 @@ compile = CoffeeScript.compile</pre></div></div>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-4">&#182;</a>
               </div>
-              <p>If we’re not in a browser environment, we’re finished with the public API.</p>
+              <p>Export this more limited <code>CoffeeScript</code> than what is exported by
+<code>index.coffee</code>, which is intended for a Node environment.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre><span class="hljs-keyword">return</span> <span class="hljs-keyword">unless</span> <span class="hljs-built_in">window</span>?</pre></div></div>
+            <div class="content"><div class='highlight'><pre><span class="hljs-built_in">module</span>.exports = CoffeeScript</pre></div></div>
             
         </li>
         
@@ -186,6 +186,21 @@ compile = CoffeeScript.compile</pre></div></div>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-5">&#182;</a>
               </div>
+              <p>If we’re not in a browser environment, we’re finished with the public API.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre><span class="hljs-keyword">return</span> <span class="hljs-keyword">unless</span> <span class="hljs-built_in">window</span>?</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-6">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-6">&#182;</a>
+              </div>
               <p>Include source maps where possible. If we’ve got a base64 encoder, a
 JSON serializer, and tools for escaping unicode characters, we’re good to go.
 Ported from <a href="https://developer.mozilla.org/en-US/docs/DOM/window.btoa">https://developer.mozilla.org/en-US/docs/DOM/window.btoa</a></p>
@@ -200,11 +215,11 @@ Ported from <a href="https://developer.mozilla.org/en-US/docs/DOM/window.btoa">h
         </li>
         
         
-        <li id="section-6">
+        <li id="section-7">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-6">&#182;</a>
+                <a class="pilcrow" href="#section-7">&#182;</a>
               </div>
               <p>Load a remote script from the current domain via XHR.</p>
 
@@ -231,11 +246,11 @@ Ported from <a href="https://developer.mozilla.org/en-US/docs/DOM/window.btoa">h
         </li>
         
         
-        <li id="section-7">
+        <li id="section-8">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-7">&#182;</a>
+                <a class="pilcrow" href="#section-8">&#182;</a>
               </div>
               <p>Activate CoffeeScript in the browser by having it compile and evaluate
 all script tags with a content-type of <code>text/coffeescript</code>.
@@ -273,11 +288,11 @@ This happens on page load.</p>
         </li>
         
         
-        <li id="section-8">
+        <li id="section-9">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-8">&#182;</a>
+                <a class="pilcrow" href="#section-9">&#182;</a>
               </div>
               <p><code>options.filename</code> defines the filename the source map appears as
 in Developer Tools. If a script tag has an <code>id</code>, use that as the
@@ -296,11 +311,11 @@ only one CoffeeScript script block to parse.</p>
         </li>
         
         
-        <li id="section-9">
+        <li id="section-10">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-9">&#182;</a>
+                <a class="pilcrow" href="#section-10">&#182;</a>
               </div>
               <p>Listen for window load, both in decent browsers and in IE.</p>
 

docs/v2/annotated-source/cake.html

@@ -141,7 +141,7 @@ current directory’s Cakefile.</p>
 path         = <span class="hljs-built_in">require</span> <span class="hljs-string">'path'</span>
 helpers      = <span class="hljs-built_in">require</span> <span class="hljs-string">'./helpers'</span>
 optparse     = <span class="hljs-built_in">require</span> <span class="hljs-string">'./optparse'</span>
-CoffeeScript = <span class="hljs-built_in">require</span> <span class="hljs-string">'./coffeescript'</span></pre></div></div>
+CoffeeScript = <span class="hljs-built_in">require</span> <span class="hljs-string">'./'</span></pre></div></div>
             
         </li>
         

docs/v2/annotated-source/coffeescript.html

@@ -123,9 +123,6 @@ source CoffeeScript into JavaScript.</p>
             </div>
             
             <div class="content"><div class='highlight'><pre>
-fs            = <span class="hljs-built_in">require</span> <span class="hljs-string">'fs'</span>
-vm            = <span class="hljs-built_in">require</span> <span class="hljs-string">'vm'</span>
-path          = <span class="hljs-built_in">require</span> <span class="hljs-string">'path'</span>
 {Lexer}       = <span class="hljs-built_in">require</span> <span class="hljs-string">'./lexer'</span>
 {parser}      = <span class="hljs-built_in">require</span> <span class="hljs-string">'./parser'</span>
 helpers       = <span class="hljs-built_in">require</span> <span class="hljs-string">'./helpers'</span>
@@ -493,13 +490,16 @@ or traverse it by using <code>.traverseChildren()</code> with a callback.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-19">&#182;</a>
               </div>
-              <p>Compile and execute a string of CoffeeScript (on the server), correctly
-setting <code>__filename</code>, <code>__dirname</code>, and relative <code>require()</code>.</p>
+              <p>This file used to export these methods; leave stubs that throw warnings
+instead. These methods have been moved into <code>index.coffee</code> to provide
+separate entrypoints for Node and non-Node environments, so that static
+analysis tools don’t choke on Node packages when compiling for a non-Node
+environment.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>exports.run = <span class="hljs-function"><span class="hljs-params">(code, options = {})</span> -&gt;</span>
-  mainModule = <span class="hljs-built_in">require</span>.main</pre></div></div>
+            <div class="content"><div class='highlight'><pre>exports.run = exports.eval = exports.register = <span class="hljs-function">-&gt;</span>
+  <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> Error <span class="hljs-string">'require index.coffee, not this file'</span></pre></div></div>
             
         </li>
         
@@ -510,221 +510,6 @@ setting <code>__filename</code>, <code>__dirname</code>, and relative <code>requ
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-20">&#182;</a>
               </div>
-              <p>Set the filename.</p>
-
-            </div>
-            
-            <div class="content"><div class='highlight'><pre>  mainModule.filename = process.argv[<span class="hljs-number">1</span>] =
-    <span class="hljs-keyword">if</span> options.filename <span class="hljs-keyword">then</span> fs.realpathSync(options.filename) <span class="hljs-keyword">else</span> <span class="hljs-string">'&lt;anonymous&gt;'</span></pre></div></div>
-            
-        </li>
-        
-        
-        <li id="section-21">
-            <div class="annotation">
-              
-              <div class="pilwrap ">
-                <a class="pilcrow" href="#section-21">&#182;</a>
-              </div>
-              <p>Clear the module cache.</p>
-
-            </div>
-            
-            <div class="content"><div class='highlight'><pre>  mainModule.moduleCache <span class="hljs-keyword">and</span>= {}</pre></div></div>
-            
-        </li>
-        
-        
-        <li id="section-22">
-            <div class="annotation">
-              
-              <div class="pilwrap ">
-                <a class="pilcrow" href="#section-22">&#182;</a>
-              </div>
-              <p>Assign paths for node_modules loading</p>
-
-            </div>
-            
-            <div class="content"><div class='highlight'><pre>  dir = <span class="hljs-keyword">if</span> options.filename?
-    path.dirname fs.realpathSync options.filename
-  <span class="hljs-keyword">else</span>
-    fs.realpathSync <span class="hljs-string">'.'</span>
-  mainModule.paths = <span class="hljs-built_in">require</span>(<span class="hljs-string">'module'</span>)._nodeModulePaths dir</pre></div></div>
-            
-        </li>
-        
-        
-        <li id="section-23">
-            <div class="annotation">
-              
-              <div class="pilwrap ">
-                <a class="pilcrow" href="#section-23">&#182;</a>
-              </div>
-              <p>Compile.</p>
-
-            </div>
-            
-            <div class="content"><div class='highlight'><pre>  <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> helpers.isCoffee(mainModule.filename) <span class="hljs-keyword">or</span> <span class="hljs-built_in">require</span>.extensions
-    answer = compile code, options
-    code = answer.js ? answer
-
-  mainModule._compile code, mainModule.filename</pre></div></div>
-            
-        </li>
-        
-        
-        <li id="section-24">
-            <div class="annotation">
-              
-              <div class="pilwrap ">
-                <a class="pilcrow" href="#section-24">&#182;</a>
-              </div>
-              <p>Compile and evaluate a string of CoffeeScript (in a Node.js-like environment).
-The CoffeeScript REPL uses this to run the input.</p>
-
-            </div>
-            
-            <div class="content"><div class='highlight'><pre>exports.eval = <span class="hljs-function"><span class="hljs-params">(code, options = {})</span> -&gt;</span>
-  <span class="hljs-keyword">return</span> <span class="hljs-keyword">unless</span> code = code.trim()
-  createContext = vm.Script.createContext ? vm.createContext
-
-  isContext = vm.isContext ? (ctx) -&gt;
-    options.sandbox <span class="hljs-keyword">instanceof</span> createContext().constructor
-
-  <span class="hljs-keyword">if</span> createContext
-    <span class="hljs-keyword">if</span> options.sandbox?
-      <span class="hljs-keyword">if</span> isContext options.sandbox
-        sandbox = options.sandbox
-      <span class="hljs-keyword">else</span>
-        sandbox = createContext()
-        sandbox[k] = v <span class="hljs-keyword">for</span> own k, v <span class="hljs-keyword">of</span> options.sandbox
-      sandbox.<span class="hljs-built_in">global</span> = sandbox.root = sandbox.GLOBAL = sandbox
-    <span class="hljs-keyword">else</span>
-      sandbox = <span class="hljs-built_in">global</span>
-    sandbox.__filename = options.filename || <span class="hljs-string">'eval'</span>
-    sandbox.__dirname  = path.dirname sandbox.__filename</pre></div></div>
-            
-        </li>
-        
-        
-        <li id="section-25">
-            <div class="annotation">
-              
-              <div class="pilwrap ">
-                <a class="pilcrow" href="#section-25">&#182;</a>
-              </div>
-              <p>define module/require only if they chose not to specify their own</p>
-
-            </div>
-            
-            <div class="content"><div class='highlight'><pre>    <span class="hljs-keyword">unless</span> sandbox <span class="hljs-keyword">isnt</span> <span class="hljs-built_in">global</span> <span class="hljs-keyword">or</span> sandbox.<span class="hljs-built_in">module</span> <span class="hljs-keyword">or</span> sandbox.<span class="hljs-built_in">require</span>
-      Module = <span class="hljs-built_in">require</span> <span class="hljs-string">'module'</span>
-      sandbox.<span class="hljs-built_in">module</span>  = _module  = <span class="hljs-keyword">new</span> Module(options.modulename || <span class="hljs-string">'eval'</span>)
-      sandbox.<span class="hljs-built_in">require</span> = _require = <span class="hljs-function"><span class="hljs-params">(path)</span> -&gt;</span>  Module._load path, _module, <span class="hljs-literal">true</span>
-      _module.filename = sandbox.__filename
-      <span class="hljs-keyword">for</span> r <span class="hljs-keyword">in</span> Object.getOwnPropertyNames <span class="hljs-built_in">require</span> <span class="hljs-keyword">when</span> r <span class="hljs-keyword">not</span> <span class="hljs-keyword">in</span> [<span class="hljs-string">'paths'</span>, <span class="hljs-string">'arguments'</span>, <span class="hljs-string">'caller'</span>]
-        _require[r] = <span class="hljs-built_in">require</span>[r]</pre></div></div>
-            
-        </li>
-        
-        
-        <li id="section-26">
-            <div class="annotation">
-              
-              <div class="pilwrap ">
-                <a class="pilcrow" href="#section-26">&#182;</a>
-              </div>
-              <p>use the same hack node currently uses for their own REPL</p>
-
-            </div>
-            
-            <div class="content"><div class='highlight'><pre>      _require.paths = _module.paths = Module._nodeModulePaths process.cwd()
-      _require.resolve = <span class="hljs-function"><span class="hljs-params">(request)</span> -&gt;</span> Module._resolveFilename request, _module
-  o = {}
-  o[k] = v <span class="hljs-keyword">for</span> own k, v <span class="hljs-keyword">of</span> options
-  o.bare = <span class="hljs-literal">on</span> <span class="hljs-comment"># ensure return value</span>
-  js = compile code, o
-  <span class="hljs-keyword">if</span> sandbox <span class="hljs-keyword">is</span> <span class="hljs-built_in">global</span>
-    vm.runInThisContext js
-  <span class="hljs-keyword">else</span>
-    vm.runInContext js, sandbox
-
-exports.register = <span class="hljs-function">-&gt;</span> <span class="hljs-built_in">require</span> <span class="hljs-string">'./register'</span></pre></div></div>
-            
-        </li>
-        
-        
-        <li id="section-27">
-            <div class="annotation">
-              
-              <div class="pilwrap ">
-                <a class="pilcrow" href="#section-27">&#182;</a>
-              </div>
-              <p>Throw error with deprecation warning when depending upon implicit <code>require.extensions</code> registration</p>
-
-            </div>
-            
-            <div class="content"><div class='highlight'><pre><span class="hljs-keyword">if</span> <span class="hljs-built_in">require</span>.extensions
-  <span class="hljs-keyword">for</span> ext <span class="hljs-keyword">in</span> @FILE_EXTENSIONS <span class="hljs-keyword">then</span> <span class="hljs-keyword">do</span> (ext) -&gt;
-    <span class="hljs-built_in">require</span>.extensions[ext] ?= <span class="hljs-function">-&gt;</span>
-      <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> Error <span class="hljs-string">"""
-      Use CoffeeScript.register() or require the coffeescript/register module to require <span class="hljs-subst">#{ext}</span> files.
-      """</span>
-
-exports._compileFile = <span class="hljs-function"><span class="hljs-params">(filename, sourceMap = <span class="hljs-literal">no</span>, inlineMap = <span class="hljs-literal">no</span>)</span> -&gt;</span>
-  raw = fs.readFileSync filename, <span class="hljs-string">'utf8'</span></pre></div></div>
-            
-        </li>
-        
-        
-        <li id="section-28">
-            <div class="annotation">
-              
-              <div class="pilwrap ">
-                <a class="pilcrow" href="#section-28">&#182;</a>
-              </div>
-              <p>Strip the Unicode byte order mark, if this file begins with one.</p>
-
-            </div>
-            
-            <div class="content"><div class='highlight'><pre>  stripped = <span class="hljs-keyword">if</span> raw.charCodeAt(<span class="hljs-number">0</span>) <span class="hljs-keyword">is</span> <span class="hljs-number">0xFEFF</span> <span class="hljs-keyword">then</span> raw.substring <span class="hljs-number">1</span> <span class="hljs-keyword">else</span> raw
-
-  <span class="hljs-keyword">try</span>
-    answer = compile stripped, {
-      filename, sourceMap, inlineMap
-      sourceFiles: [filename]
-      literate: helpers.isLiterate filename
-    }
-  <span class="hljs-keyword">catch</span> err</pre></div></div>
-            
-        </li>
-        
-        
-        <li id="section-29">
-            <div class="annotation">
-              
-              <div class="pilwrap ">
-                <a class="pilcrow" href="#section-29">&#182;</a>
-              </div>
-              <p>As the filename and code of a dynamically loaded file will be different
-from the original file compiled with CoffeeScript.run, add that
-information to error so it can be pretty-printed later.</p>
-
-            </div>
-            
-            <div class="content"><div class='highlight'><pre>    <span class="hljs-keyword">throw</span> helpers.updateSyntaxError err, stripped, filename
-
-  answer</pre></div></div>
-            
-        </li>
-        
-        
-        <li id="section-30">
-            <div class="annotation">
-              
-              <div class="pilwrap ">
-                <a class="pilcrow" href="#section-30">&#182;</a>
-              </div>
               <p>Instantiate a Lexer for our use here.</p>
 
             </div>
@@ -734,11 +519,11 @@ information to error so it can be pretty-printed later.</p>
         </li>
         
         
-        <li id="section-31">
+        <li id="section-21">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-31">&#182;</a>
+                <a class="pilcrow" href="#section-21">&#182;</a>
               </div>
               <p>The real Lexer produces a generic stream of tokens. This object provides a
 thin wrapper around it, compatible with the Jison API. We can then pass it
@@ -766,11 +551,11 @@ directly as a “Jison lexer”.</p>
         </li>
         
         
-        <li id="section-32">
+        <li id="section-22">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-32">&#182;</a>
+                <a class="pilcrow" href="#section-22">&#182;</a>
               </div>
               <p>Make all the AST nodes visible to the parser.</p>
 
@@ -781,11 +566,11 @@ directly as a “Jison lexer”.</p>
         </li>
         
         
-        <li id="section-33">
+        <li id="section-23">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-33">&#182;</a>
+                <a class="pilcrow" href="#section-23">&#182;</a>
               </div>
               <p>Override Jison’s default error handling function.</p>
 
@@ -796,11 +581,11 @@ directly as a “Jison lexer”.</p>
         </li>
         
         
-        <li id="section-34">
+        <li id="section-24">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-34">&#182;</a>
+                <a class="pilcrow" href="#section-24">&#182;</a>
               </div>
               <p>Disregard Jison’s message, it contains redundant line number information.
 Disregard the token, we take its value directly from the lexer in case
@@ -824,11 +609,11 @@ the error is caused by a generated token which might refer to its origin.</p>
         </li>
         
         
-        <li id="section-35">
+        <li id="section-25">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-35">&#182;</a>
+                <a class="pilcrow" href="#section-25">&#182;</a>
               </div>
               <p>The second argument has a <code>loc</code> property, which should have the location
 data for this token. Unfortunately, Jison seems to send an outdated <code>loc</code>
@@ -842,11 +627,11 @@ from the lexer.</p>
         </li>
         
         
-        <li id="section-36">
+        <li id="section-26">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-36">&#182;</a>
+                <a class="pilcrow" href="#section-26">&#182;</a>
               </div>
               <p>Based on <a href="http://v8.googlecode.com/svn/branches/bleeding_edge/src/messages.js">http://v8.googlecode.com/svn/branches/bleeding_edge/src/messages.js</a>
 Modified to handle sourceMap</p>
@@ -874,11 +659,11 @@ Modified to handle sourceMap</p>
         </li>
         
         
-        <li id="section-37">
+        <li id="section-27">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-37">&#182;</a>
+                <a class="pilcrow" href="#section-27">&#182;</a>
               </div>
               <p>Check for a sourceMap position</p>
 
@@ -923,11 +708,11 @@ Modified to handle sourceMap</p>
         </li>
         
         
-        <li id="section-38">
+        <li id="section-28">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-38">&#182;</a>
+                <a class="pilcrow" href="#section-28">&#182;</a>
               </div>
               <p>CoffeeScript compiled in a browser may get compiled with <code>options.filename</code>
 of <code>&lt;anonymous&gt;</code>, but the browser may request the stack trace with the
@@ -949,11 +734,11 @@ filename of the script file.</p>
         </li>
         
         
-        <li id="section-39">
+        <li id="section-29">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-39">&#182;</a>
+                <a class="pilcrow" href="#section-29">&#182;</a>
               </div>
               <p>Based on <a href="http://goo.gl/ZTx1p">michaelficarra/CoffeeScriptRedux</a>
 NodeJS / V8 have no support for transforming positions in stack traces using

docs/v2/annotated-source/command.html

@@ -140,7 +140,7 @@ interactive REPL.</p>
 path           = <span class="hljs-built_in">require</span> <span class="hljs-string">'path'</span>
 helpers        = <span class="hljs-built_in">require</span> <span class="hljs-string">'./helpers'</span>
 optparse       = <span class="hljs-built_in">require</span> <span class="hljs-string">'./optparse'</span>
-CoffeeScript   = <span class="hljs-built_in">require</span> <span class="hljs-string">'./coffeescript'</span>
+CoffeeScript   = <span class="hljs-built_in">require</span> <span class="hljs-string">'./'</span>
 {spawn, exec}  = <span class="hljs-built_in">require</span> <span class="hljs-string">'child_process'</span>
 {EventEmitter} = <span class="hljs-built_in">require</span> <span class="hljs-string">'events'</span>
 
@@ -238,7 +238,10 @@ sources      = []
 sourceCode   = []
 notSources   = {}
 watchedDirs  = {}
-optionParser = <span class="hljs-literal">null</span></pre></div></div>
+optionParser = <span class="hljs-literal">null</span>
+
+exports.buildCSOptionParser = buildCSOptionParser = <span class="hljs-function">-&gt;</span>
+  <span class="hljs-keyword">new</span> optparse.OptionParser SWITCHES, BANNER</pre></div></div>
             
         </li>
         
@@ -256,6 +259,7 @@ Many flags cause us to divert before compiling anything. Flags passed after
             </div>
             
             <div class="content"><div class='highlight'><pre>exports.run = <span class="hljs-function">-&gt;</span>
+  optionParser = buildCSOptionParser()
   parseOptions()</pre></div></div>
             
         </li>
@@ -771,7 +775,6 @@ same directory as the <code>.js</code> file.</p>
             </div>
             
             <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">parseOptions</span> = -&gt;</span>
-  optionParser  = <span class="hljs-keyword">new</span> optparse.OptionParser SWITCHES, BANNER
   o = opts      = optionParser.parse process.argv[<span class="hljs-number">2.</span>.]
   o.compile     <span class="hljs-keyword">or</span>=  !!o.output
   o.run         = <span class="hljs-keyword">not</span> (o.compile <span class="hljs-keyword">or</span> o.<span class="hljs-built_in">print</span> <span class="hljs-keyword">or</span> o.map)
@@ -856,7 +859,7 @@ shown.</p>
             </div>
             
             <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">usage</span> = -&gt;</span>
-  printLine (<span class="hljs-keyword">new</span> optparse.OptionParser SWITCHES, BANNER).help()</pre></div></div>
+  printLine optionParser.help()</pre></div></div>
             
         </li>
         

docs/v2/annotated-source/grammar.html

@@ -221,7 +221,7 @@ previous nonterminal.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-7">&#182;</a>
               </div>
-              <p>All runtime functions we need are defined on “yy”</p>
+              <p>All runtime functions we need are defined on <code>yy</code></p>
 
             </div>
             
@@ -238,7 +238,7 @@ previous nonterminal.</p>
                 <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
+in, and returns the parameter. If the parameter is not a node, it will
 just be passed through unaffected.</p>
 
             </div>
@@ -292,7 +292,7 @@ just be passed through unaffected.</p>
 the key to a list of alternative matches. With each match’s action, the
 dollar-sign variables are provided by Jison as references to the value of
 their numeric position, so in this rule:</p>
-<pre><code><span class="hljs-string">"Expression UNLESS Expression"</span>
+<pre><code><span class="hljs-string">'Expression UNLESS Expression'</span>
 </code></pre><p><code>$1</code> would be the value of the first <code>Expression</code>, <code>$2</code> would be the token
 for the <code>UNLESS</code> terminal, and <code>$3</code> would be the value of the second
 <code>Expression</code>.</p>
@@ -446,6 +446,7 @@ token stream.</p>
 
   Identifier: [
     o <span class="hljs-string">'IDENTIFIER'</span>,                             <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> IdentifierLiteral $<span class="hljs-number">1</span>
+    o <span class="hljs-string">'CSX_TAG'</span>,                                <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> CSXTag $<span class="hljs-number">1</span>
   ]
 
   Property: [
@@ -541,6 +542,7 @@ the ordinary <strong>Assign</strong> is that these allow numbers and strings as
             
             <div class="content"><div class='highlight'><pre>  AssignObj: [
     o <span class="hljs-string">'ObjAssignable'</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">'ObjRestValue'</span>
     o <span class="hljs-string">'ObjAssignable : Expression'</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">3</span>, <span class="hljs-string">'object'</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">'ObjAssignable :
@@ -574,6 +576,40 @@ the ordinary <strong>Assign</strong> is that these allow numbers and strings as
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-22">&#182;</a>
               </div>
+              <p>Object literal spread properties.</p>
+
+            </div>
+            
+            <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">'ObjSpreadExpr ...'</span>,       <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Splat $<span class="hljs-number">1</span>
+  ]
+
+  ObjSpreadExpr: [
+    o <span class="hljs-string">'ObjSpreadIdentifier'</span>
+    o <span class="hljs-string">'Object'</span>
+    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">'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>)
+  ]</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-23">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-23">&#182;</a>
+              </div>
               <p>A return statement from a function body.</p>
 
             </div>
@@ -596,11 +632,11 @@ the ordinary <strong>Assign</strong> is that these allow numbers and strings as
         </li>
         
         
-        <li id="section-23">
+        <li id="section-24">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-23">&#182;</a>
+                <a class="pilcrow" href="#section-24">&#182;</a>
               </div>
               <p>A block comment.</p>
 
@@ -613,11 +649,11 @@ the ordinary <strong>Assign</strong> is that these allow numbers and strings as
         </li>
         
         
-        <li id="section-24">
+        <li id="section-25">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-24">&#182;</a>
+                <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>
@@ -632,11 +668,11 @@ of <strong>Block</strong> preceded by a function arrow, with an optional paramet
         </li>
         
         
-        <li id="section-25">
+        <li id="section-26">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-25">&#182;</a>
+                <a class="pilcrow" href="#section-26">&#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>
@@ -651,11 +687,11 @@ functions, and <code>=&gt;</code> is for functions bound to the current value of
         </li>
         
         
-        <li id="section-26">
+        <li id="section-27">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-26">&#182;</a>
+                <a class="pilcrow" href="#section-27">&#182;</a>
               </div>
               <p>An optional, trailing comma.</p>
 
@@ -669,11 +705,11 @@ functions, and <code>=&gt;</code> is for functions bound to the current value of
         </li>
         
         
-        <li id="section-27">
+        <li id="section-28">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-27">&#182;</a>
+                <a class="pilcrow" href="#section-28">&#182;</a>
               </div>
               <p>The list of parameters that a function accepts can be of any length.</p>
 
@@ -690,11 +726,11 @@ functions, and <code>=&gt;</code> is for functions bound to the current value of
         </li>
         
         
-        <li id="section-28">
+        <li id="section-29">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-28">&#182;</a>
+                <a class="pilcrow" href="#section-29">&#182;</a>
               </div>
               <p>A single parameter in a function definition can be ordinary, or a splat
 that hoovers up the remaining arguments.</p>
@@ -711,11 +747,11 @@ that hoovers up the remaining arguments.</p>
         </li>
         
         
-        <li id="section-29">
+        <li id="section-30">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-29">&#182;</a>
+                <a class="pilcrow" href="#section-30">&#182;</a>
               </div>
               <p>Function Parameters</p>
 
@@ -731,11 +767,11 @@ that hoovers up the remaining arguments.</p>
         </li>
         
         
-        <li id="section-30">
+        <li id="section-31">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-30">&#182;</a>
+                <a class="pilcrow" href="#section-31">&#182;</a>
               </div>
               <p>A splat that occurs outside of a parameter list.</p>
 
@@ -748,11 +784,11 @@ that hoovers up the remaining arguments.</p>
         </li>
         
         
-        <li id="section-31">
+        <li id="section-32">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-31">&#182;</a>
+                <a class="pilcrow" href="#section-32">&#182;</a>
               </div>
               <p>Variables and properties that can be assigned to.</p>
 
@@ -768,11 +804,11 @@ that hoovers up the remaining arguments.</p>
         </li>
         
         
-        <li id="section-32">
+        <li id="section-33">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-32">&#182;</a>
+                <a class="pilcrow" href="#section-33">&#182;</a>
               </div>
               <p>Everything that can be assigned to.</p>
 
@@ -787,11 +823,11 @@ that hoovers up the remaining arguments.</p>
         </li>
         
         
-        <li id="section-33">
+        <li id="section-34">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-33">&#182;</a>
+                <a class="pilcrow" href="#section-34">&#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>
@@ -810,11 +846,11 @@ as functions, indexed into, named as a class, etc.</p>
         </li>
         
         
-        <li id="section-34">
+        <li id="section-35">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-34">&#182;</a>
+                <a class="pilcrow" href="#section-35">&#182;</a>
               </div>
               <p>A <code>super</code>-based expression that can be used as a value.</p>
 
@@ -828,11 +864,11 @@ as functions, indexed into, named as a class, etc.</p>
         </li>
         
         
-        <li id="section-35">
+        <li id="section-36">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-35">&#182;</a>
+                <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>
@@ -851,11 +887,11 @@ or by array index or slice.</p>
         </li>
         
         
-        <li id="section-36">
+        <li id="section-37">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-36">&#182;</a>
+                <a class="pilcrow" href="#section-37">&#182;</a>
               </div>
               <p>Indexing into an object or array using bracket notation.</p>
 
@@ -874,11 +910,11 @@ or by array index or slice.</p>
         </li>
         
         
-        <li id="section-37">
+        <li id="section-38">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-37">&#182;</a>
+                <a class="pilcrow" href="#section-38">&#182;</a>
               </div>
               <p>In CoffeeScript, an object literal is simply a list of assignments.</p>
 
@@ -891,11 +927,11 @@ or by array index or slice.</p>
         </li>
         
         
-        <li id="section-38">
+        <li id="section-39">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-38">&#182;</a>
+                <a class="pilcrow" href="#section-39">&#182;</a>
               </div>
               <p>Assignment of properties within an object literal can be separated by
 comma, as in JavaScript, or simply by newline.</p>
@@ -913,11 +949,11 @@ comma, as in JavaScript, or simply by newline.</p>
         </li>
         
         
-        <li id="section-39">
+        <li id="section-40">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-39">&#182;</a>
+                <a class="pilcrow" href="#section-40">&#182;</a>
               </div>
               <p>Class definitions have optional bodies of prototype property assignments,
 and optional references to the superclass.</p>
@@ -1002,11 +1038,11 @@ and optional references to the superclass.</p>
         </li>
         
         
-        <li id="section-40">
+        <li id="section-41">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-40">&#182;</a>
+                <a class="pilcrow" href="#section-41">&#182;</a>
               </div>
               <p>Ordinary function invocation, or a chained series of calls.</p>
 
@@ -1022,11 +1058,11 @@ and optional references to the superclass.</p>
         </li>
         
         
-        <li id="section-41">
+        <li id="section-42">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-41">&#182;</a>
+                <a class="pilcrow" href="#section-42">&#182;</a>
               </div>
               <p>An optional existence check on a function.</p>
 
@@ -1040,11 +1076,11 @@ and optional references to the superclass.</p>
         </li>
         
         
-        <li id="section-42">
+        <li id="section-43">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-42">&#182;</a>
+                <a class="pilcrow" href="#section-43">&#182;</a>
               </div>
               <p>The list of arguments to a function call.</p>
 
@@ -1058,11 +1094,11 @@ and optional references to the superclass.</p>
         </li>
         
         
-        <li id="section-43">
+        <li id="section-44">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-43">&#182;</a>
+                <a class="pilcrow" href="#section-44">&#182;</a>
               </div>
               <p>A reference to the <em>this</em> current object.</p>
 
@@ -1076,11 +1112,11 @@ and optional references to the superclass.</p>
         </li>
         
         
-        <li id="section-44">
+        <li id="section-45">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-44">&#182;</a>
+                <a class="pilcrow" href="#section-45">&#182;</a>
               </div>
               <p>A reference to a property on <em>this</em>.</p>
 
@@ -1093,11 +1129,11 @@ and optional references to the superclass.</p>
         </li>
         
         
-        <li id="section-45">
+        <li id="section-46">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-45">&#182;</a>
+                <a class="pilcrow" href="#section-46">&#182;</a>
               </div>
               <p>The array literal.</p>
 
@@ -1111,11 +1147,11 @@ and optional references to the superclass.</p>
         </li>
         
         
-        <li id="section-46">
+        <li id="section-47">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-46">&#182;</a>
+                <a class="pilcrow" href="#section-47">&#182;</a>
               </div>
               <p>Inclusive and exclusive range dots.</p>
 
@@ -1129,11 +1165,11 @@ and optional references to the superclass.</p>
         </li>
         
         
-        <li id="section-47">
+        <li id="section-48">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-47">&#182;</a>
+                <a class="pilcrow" href="#section-48">&#182;</a>
               </div>
               <p>The CoffeeScript range literal.</p>
 
@@ -1146,11 +1182,11 @@ and optional references to the superclass.</p>
         </li>
         
         
-        <li id="section-48">
+        <li id="section-49">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-48">&#182;</a>
+                <a class="pilcrow" href="#section-49">&#182;</a>
               </div>
               <p>Array slice literals.</p>
 
@@ -1166,11 +1202,11 @@ and optional references to the superclass.</p>
         </li>
         
         
-        <li id="section-49">
+        <li id="section-50">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-49">&#182;</a>
+                <a class="pilcrow" href="#section-50">&#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
@@ -1189,11 +1225,11 @@ as well as the contents of an array literal
         </li>
         
         
-        <li id="section-50">
+        <li id="section-51">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-50">&#182;</a>
+                <a class="pilcrow" href="#section-51">&#182;</a>
               </div>
               <p>Valid arguments are Blocks or Splats.</p>
 
@@ -1208,11 +1244,11 @@ as well as the contents of an array literal
         </li>
         
         
-        <li id="section-51">
+        <li id="section-52">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-51">&#182;</a>
+                <a class="pilcrow" href="#section-52">&#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
@@ -1228,11 +1264,11 @@ having the newlines wouldn’t make sense.</p>
         </li>
         
         
-        <li id="section-52">
+        <li id="section-53">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-52">&#182;</a>
+                <a class="pilcrow" href="#section-53">&#182;</a>
               </div>
               <p>The variants of <em>try/catch/finally</em> exception handling blocks.</p>
 
@@ -1248,11 +1284,11 @@ having the newlines wouldn’t make sense.</p>
         </li>
         
         
-        <li id="section-53">
+        <li id="section-54">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-53">&#182;</a>
+                <a class="pilcrow" href="#section-54">&#182;</a>
               </div>
               <p>A catch clause names its error and runs a block of code.</p>
 
@@ -1267,11 +1303,11 @@ having the newlines wouldn’t make sense.</p>
         </li>
         
         
-        <li id="section-54">
+        <li id="section-55">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-54">&#182;</a>
+                <a class="pilcrow" href="#section-55">&#182;</a>
               </div>
               <p>Throw an exception object.</p>
 
@@ -1284,11 +1320,11 @@ having the newlines wouldn’t make sense.</p>
         </li>
         
         
-        <li id="section-55">
+        <li id="section-56">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-55">&#182;</a>
+                <a class="pilcrow" href="#section-56">&#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
@@ -1305,11 +1341,11 @@ the trick.</p>
         </li>
         
         
-        <li id="section-56">
+        <li id="section-57">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-56">&#182;</a>
+                <a class="pilcrow" href="#section-57">&#182;</a>
               </div>
               <p>The condition portion of a while loop.</p>
 
@@ -1325,11 +1361,11 @@ the trick.</p>
         </li>
         
         
-        <li id="section-57">
+        <li id="section-58">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-57">&#182;</a>
+                <a class="pilcrow" href="#section-58">&#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>
@@ -1351,11 +1387,11 @@ or postfix, with a single expression. There is no do..while.</p>
         </li>
         
         
-        <li id="section-58">
+        <li id="section-59">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-58">&#182;</a>
+                <a class="pilcrow" href="#section-59">&#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,
@@ -1383,11 +1419,11 @@ or postfix, with a single expression.</p>
         </li>
         
         
-        <li id="section-59">
+        <li id="section-60">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-59">&#182;</a>
+                <a class="pilcrow" href="#section-60">&#182;</a>
               </div>
               <p>An array of all accepted values for a variable inside the loop.
 This enables support for pattern matching.</p>
@@ -1404,11 +1440,11 @@ This enables support for pattern matching.</p>
         </li>
         
         
-        <li id="section-60">
+        <li id="section-61">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-60">&#182;</a>
+                <a class="pilcrow" href="#section-61">&#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
@@ -1424,11 +1460,11 @@ of object comprehensions.</p>
         </li>
         
         
-        <li id="section-61">
+        <li id="section-62">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-61">&#182;</a>
+                <a class="pilcrow" href="#section-62">&#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
@@ -1463,11 +1499,11 @@ in fixed-size increments.</p>
         </li>
         
         
-        <li id="section-62">
+        <li id="section-63">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-62">&#182;</a>
+                <a class="pilcrow" href="#section-63">&#182;</a>
               </div>
               <p>An individual <strong>When</strong> clause, with action.</p>
 
@@ -1481,11 +1517,11 @@ in fixed-size increments.</p>
         </li>
         
         
-        <li id="section-63">
+        <li id="section-64">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-63">&#182;</a>
+                <a class="pilcrow" href="#section-64">&#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
@@ -1501,11 +1537,11 @@ ambiguity.</p>
         </li>
         
         
-        <li id="section-64">
+        <li id="section-65">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-64">&#182;</a>
+                <a class="pilcrow" href="#section-65">&#182;</a>
               </div>
               <p>The full complement of <em>if</em> expressions, including postfix one-liner
 <em>if</em> and <em>unless</em>.</p>
@@ -1522,11 +1558,11 @@ ambiguity.</p>
         </li>
         
         
-        <li id="section-65">
+        <li id="section-66">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-65">&#182;</a>
+                <a class="pilcrow" href="#section-66">&#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
@@ -1553,11 +1589,11 @@ rules are necessary.</p>
         </li>
         
         
-        <li id="section-66">
+        <li id="section-67">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-66">&#182;</a>
+                <a class="pilcrow" href="#section-67">&#182;</a>
               </div>
               <p><a href="http://coffeescript.org/#existential-operator">The existential operator</a>.</p>
 
@@ -1590,32 +1626,19 @@ rules are necessary.</p>
        INDENT Expression OUTDENT'</span>,              <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Assign $<span class="hljs-number">1</span>, $<span class="hljs-number">4</span>, $<span class="hljs-number">2</span>
     o <span class="hljs-string">'SimpleAssignable COMPOUND_ASSIGN TERMINATOR
        Expression'</span>,                             <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Assign $<span class="hljs-number">1</span>, $<span class="hljs-number">4</span>, $<span class="hljs-number">2</span>
-    o <span class="hljs-string">'SimpleAssignable EXTENDS Expression'</span>,    <span class="hljs-function">-&gt;</span> <span class="hljs-keyword">new</span> Extends $<span class="hljs-number">1</span>, $<span class="hljs-number">3</span>
   ]</pre></div></div>
             
         </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>
@@ -1627,6 +1650,18 @@ 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>)
@@ -1666,26 +1701,14 @@ 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>
@@ -1697,6 +1720,18 @@ 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)
@@ -1715,11 +1750,11 @@ as “tokens”.</p>
         </li>
         
         
-        <li id="section-73">
+        <li id="section-74">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-73">&#182;</a>
+                <a class="pilcrow" href="#section-74">&#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

@@ -121,9 +121,6 @@ arrays, count characters, that sort of thing.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>
-md = <span class="hljs-built_in">require</span>(<span class="hljs-string">'markdown-it'</span>)()</pre></div></div>
-            
         </li>
         
         
@@ -331,16 +328,38 @@ looking for a particular method in an options hash.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-13">&#182;</a>
               </div>
-              <p>Simple function for extracting code from Literate CoffeeScript by stripping
+              <p>Helper function for extracting code from Literate CoffeeScript by stripping
 out all non-code blocks, producing a string of CoffeeScript code that can
-be compiled “normally.” Uses <a href="https://markdown-it.github.io/">MarkdownIt</a>
-to tell the difference between Markdown and code blocks.</p>
+be compiled “normally.”</p>
 
             </div>
             
             <div class="content"><div class='highlight'><pre>exports.invertLiterate = <span class="hljs-function"><span class="hljs-params">(code)</span> -&gt;</span>
   out = []
-  md.renderer.rules =</pre></div></div>
+  blankLine = <span class="hljs-regexp">/^\s*$/</span>
+  indented = <span class="hljs-regexp">/^[\t ]/</span>
+  listItemStart = <span class="hljs-regexp">/// ^
+    (?:\t?|\ {0,3})   <span class="hljs-comment"># Up to one tab, or up to three spaces, or neither;</span>
+    (?:
+      [\*\-\+] |      <span class="hljs-comment"># followed by `*`, `-` or `+`;</span>
+      [0-9]{1,9}\.    <span class="hljs-comment"># or by an integer up to 9 digits long, followed by a period;</span>
+    )
+    [\ \t]            <span class="hljs-comment"># followed by a space or a tab.</span>
+  ///</span>
+  insideComment = <span class="hljs-literal">no</span>
+  <span class="hljs-keyword">for</span> line <span class="hljs-keyword">in</span> code.split(<span class="hljs-string">'\n'</span>)
+    <span class="hljs-keyword">if</span> blankLine.test(line)
+      insideComment = <span class="hljs-literal">no</span>
+      out.push line
+    <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> insideComment <span class="hljs-keyword">or</span> listItemStart.test(line)
+      insideComment = <span class="hljs-literal">yes</span>
+      out.push <span class="hljs-string">"# <span class="hljs-subst">#{line}</span>"</span>
+    <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> insideComment <span class="hljs-keyword">and</span> indented.test(line)
+      out.push line
+    <span class="hljs-keyword">else</span>
+      insideComment = <span class="hljs-literal">yes</span>
+      out.push <span class="hljs-string">"# <span class="hljs-subst">#{line}</span>"</span>
+  out.join <span class="hljs-string">'\n'</span></pre></div></div>
             
         </li>
         
@@ -351,27 +370,6 @@ to tell the difference between Markdown and code blocks.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-14">&#182;</a>
               </div>
-              <p>Delete all other rules, since all we want are the code blocks.</p>
-
-            </div>
-            
-            <div class="content"><div class='highlight'><pre>    code_block: <span class="hljs-function"><span class="hljs-params">(tokens, idx, options, env, slf)</span> -&gt;</span>
-      startLine = tokens[idx].map[<span class="hljs-number">0</span>]
-      lines = tokens[idx].content.split <span class="hljs-string">'\n'</span>
-      <span class="hljs-keyword">for</span> line, i <span class="hljs-keyword">in</span> lines
-        out[startLine + i] = line
-  md.render code
-  out.join <span class="hljs-string">'\n'</span></pre></div></div>
-            
-        </li>
-        
-        
-        <li id="section-15">
-            <div class="annotation">
-              
-              <div class="pilwrap ">
-                <a class="pilcrow" href="#section-15">&#182;</a>
-              </div>
               <p>Merge two jison-style location data objects together.
 If <code>last</code> is not provided, this will simply return <code>first</code>.</p>
 
@@ -389,11 +387,11 @@ If <code>last</code> is not provided, this will simply return <code>first</code>
         </li>
         
         
-        <li id="section-16">
+        <li id="section-15">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-16">&#182;</a>
+                <a class="pilcrow" href="#section-15">&#182;</a>
               </div>
               <p>This returns a function which takes an object as a parameter, and if that
 object is an AST node, updates that object’s locationData.
@@ -411,11 +409,11 @@ The object is returned either way.</p>
         </li>
         
         
-        <li id="section-17">
+        <li id="section-16">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-17">&#182;</a>
+                <a class="pilcrow" href="#section-16">&#182;</a>
               </div>
               <p>Convert jison location data to a string.
 <code>obj</code> can be a token, or a locationData.</p>
@@ -435,11 +433,11 @@ The object is returned either way.</p>
         </li>
         
         
-        <li id="section-18">
+        <li id="section-17">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-18">&#182;</a>
+                <a class="pilcrow" href="#section-17">&#182;</a>
               </div>
               <p>A <code>.coffee.md</code> compatible version of <code>basename</code>, that returns the file sans-extension.</p>
 
@@ -458,11 +456,11 @@ The object is returned either way.</p>
         </li>
         
         
-        <li id="section-19">
+        <li id="section-18">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-19">&#182;</a>
+                <a class="pilcrow" href="#section-18">&#182;</a>
               </div>
               <p>Determine if a filename represents a CoffeeScript file.</p>
 
@@ -473,11 +471,11 @@ The object is returned either way.</p>
         </li>
         
         
-        <li id="section-20">
+        <li id="section-19">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-20">&#182;</a>
+                <a class="pilcrow" href="#section-19">&#182;</a>
               </div>
               <p>Determine if a filename represents a Literate CoffeeScript file.</p>
 
@@ -488,11 +486,11 @@ The object is returned either way.</p>
         </li>
         
         
-        <li id="section-21">
+        <li id="section-20">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-21">&#182;</a>
+                <a class="pilcrow" href="#section-20">&#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”
@@ -509,11 +507,11 @@ marker showing where the error is.</p>
         </li>
         
         
-        <li id="section-22">
+        <li id="section-21">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-22">&#182;</a>
+                <a class="pilcrow" href="#section-21">&#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
@@ -528,11 +526,11 @@ compile CoffeeScript for example).</p>
         </li>
         
         
-        <li id="section-23">
+        <li id="section-22">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-23">&#182;</a>
+                <a class="pilcrow" href="#section-22">&#182;</a>
               </div>
               <p>Update a compiler SyntaxError with source code information if it didn’t have
 it already.</p>
@@ -544,11 +542,11 @@ it already.</p>
         </li>
         
         
-        <li id="section-24">
+        <li id="section-23">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-24">&#182;</a>
+                <a class="pilcrow" href="#section-23">&#182;</a>
               </div>
               <p>Avoid screwing up the <code>stack</code> property of other errors (i.e. possible bugs).</p>
 
@@ -574,11 +572,11 @@ it already.</p>
         </li>
         
         
-        <li id="section-25">
+        <li id="section-24">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-25">&#182;</a>
+                <a class="pilcrow" href="#section-24">&#182;</a>
               </div>
               <p>Show only the first line on multi-line errors.</p>
 
@@ -590,11 +588,11 @@ it already.</p>
         </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>Check to see if we’re running on a color-enabled TTY.</p>
 

docs/v2/annotated-source/index.html

@@ -115,11 +115,251 @@
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-1">&#182;</a>
               </div>
-              <p>Loader for CoffeeScript as a Node.js library.</p>
+              <p>Node.js Implementation</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>exports[key] = val <span class="hljs-keyword">for</span> key, val <span class="hljs-keyword">of</span> <span class="hljs-built_in">require</span> <span class="hljs-string">'./coffeescript'</span></pre></div></div>
+            <div class="content"><div class='highlight'><pre>CoffeeScript  = <span class="hljs-built_in">require</span> <span class="hljs-string">'./coffeescript'</span>
+fs            = <span class="hljs-built_in">require</span> <span class="hljs-string">'fs'</span>
+vm            = <span class="hljs-built_in">require</span> <span class="hljs-string">'vm'</span>
+path          = <span class="hljs-built_in">require</span> <span class="hljs-string">'path'</span>
+
+helpers       = CoffeeScript.helpers
+compile       = CoffeeScript.compile</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-2">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-2">&#182;</a>
+              </div>
+              <p>Compile and execute a string of CoffeeScript (on the server), correctly
+setting <code>__filename</code>, <code>__dirname</code>, and relative <code>require()</code>.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>CoffeeScript.run = <span class="hljs-function"><span class="hljs-params">(code, options = {})</span> -&gt;</span>
+  mainModule = <span class="hljs-built_in">require</span>.main</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-3">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-3">&#182;</a>
+              </div>
+              <p>Set the filename.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>  mainModule.filename = process.argv[<span class="hljs-number">1</span>] =
+    <span class="hljs-keyword">if</span> options.filename <span class="hljs-keyword">then</span> fs.realpathSync(options.filename) <span class="hljs-keyword">else</span> <span class="hljs-string">'&lt;anonymous&gt;'</span></pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-4">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-4">&#182;</a>
+              </div>
+              <p>Clear the module cache.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>  mainModule.moduleCache <span class="hljs-keyword">and</span>= {}</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-5">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-5">&#182;</a>
+              </div>
+              <p>Assign paths for node_modules loading</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>  dir = <span class="hljs-keyword">if</span> options.filename?
+    path.dirname fs.realpathSync options.filename
+  <span class="hljs-keyword">else</span>
+    fs.realpathSync <span class="hljs-string">'.'</span>
+  mainModule.paths = <span class="hljs-built_in">require</span>(<span class="hljs-string">'module'</span>)._nodeModulePaths dir</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-6">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-6">&#182;</a>
+              </div>
+              <p>Compile.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>  <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> helpers.isCoffee(mainModule.filename) <span class="hljs-keyword">or</span> <span class="hljs-built_in">require</span>.extensions
+    answer = compile code, options
+    code = answer.js ? answer
+
+  mainModule._compile code, mainModule.filename</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-7">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-7">&#182;</a>
+              </div>
+              <p>Compile and evaluate a string of CoffeeScript (in a Node.js-like environment).
+The CoffeeScript REPL uses this to run the input.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>CoffeeScript.eval = <span class="hljs-function"><span class="hljs-params">(code, options = {})</span> -&gt;</span>
+  <span class="hljs-keyword">return</span> <span class="hljs-keyword">unless</span> code = code.trim()
+  createContext = vm.Script.createContext ? vm.createContext
+
+  isContext = vm.isContext ? (ctx) -&gt;
+    options.sandbox <span class="hljs-keyword">instanceof</span> createContext().constructor
+
+  <span class="hljs-keyword">if</span> createContext
+    <span class="hljs-keyword">if</span> options.sandbox?
+      <span class="hljs-keyword">if</span> isContext options.sandbox
+        sandbox = options.sandbox
+      <span class="hljs-keyword">else</span>
+        sandbox = createContext()
+        sandbox[k] = v <span class="hljs-keyword">for</span> own k, v <span class="hljs-keyword">of</span> options.sandbox
+      sandbox.<span class="hljs-built_in">global</span> = sandbox.root = sandbox.GLOBAL = sandbox
+    <span class="hljs-keyword">else</span>
+      sandbox = <span class="hljs-built_in">global</span>
+    sandbox.__filename = options.filename || <span class="hljs-string">'eval'</span>
+    sandbox.__dirname  = path.dirname sandbox.__filename</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-8">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-8">&#182;</a>
+              </div>
+              <p>define module/require only if they chose not to specify their own</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>    <span class="hljs-keyword">unless</span> sandbox <span class="hljs-keyword">isnt</span> <span class="hljs-built_in">global</span> <span class="hljs-keyword">or</span> sandbox.<span class="hljs-built_in">module</span> <span class="hljs-keyword">or</span> sandbox.<span class="hljs-built_in">require</span>
+      Module = <span class="hljs-built_in">require</span> <span class="hljs-string">'module'</span>
+      sandbox.<span class="hljs-built_in">module</span>  = _module  = <span class="hljs-keyword">new</span> Module(options.modulename || <span class="hljs-string">'eval'</span>)
+      sandbox.<span class="hljs-built_in">require</span> = _require = <span class="hljs-function"><span class="hljs-params">(path)</span> -&gt;</span>  Module._load path, _module, <span class="hljs-literal">true</span>
+      _module.filename = sandbox.__filename
+      <span class="hljs-keyword">for</span> r <span class="hljs-keyword">in</span> Object.getOwnPropertyNames <span class="hljs-built_in">require</span> <span class="hljs-keyword">when</span> r <span class="hljs-keyword">not</span> <span class="hljs-keyword">in</span> [<span class="hljs-string">'paths'</span>, <span class="hljs-string">'arguments'</span>, <span class="hljs-string">'caller'</span>]
+        _require[r] = <span class="hljs-built_in">require</span>[r]</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-9">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-9">&#182;</a>
+              </div>
+              <p>use the same hack node currently uses for their own REPL</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>      _require.paths = _module.paths = Module._nodeModulePaths process.cwd()
+      _require.resolve = <span class="hljs-function"><span class="hljs-params">(request)</span> -&gt;</span> Module._resolveFilename request, _module
+  o = {}
+  o[k] = v <span class="hljs-keyword">for</span> own k, v <span class="hljs-keyword">of</span> options
+  o.bare = <span class="hljs-literal">on</span> <span class="hljs-comment"># ensure return value</span>
+  js = compile code, o
+  <span class="hljs-keyword">if</span> sandbox <span class="hljs-keyword">is</span> <span class="hljs-built_in">global</span>
+    vm.runInThisContext js
+  <span class="hljs-keyword">else</span>
+    vm.runInContext js, sandbox
+
+CoffeeScript.register = <span class="hljs-function">-&gt;</span> <span class="hljs-built_in">require</span> <span class="hljs-string">'./register'</span></pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-10">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-10">&#182;</a>
+              </div>
+              <p>Throw error with deprecation warning when depending upon implicit <code>require.extensions</code> registration</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre><span class="hljs-keyword">if</span> <span class="hljs-built_in">require</span>.extensions
+  <span class="hljs-keyword">for</span> ext <span class="hljs-keyword">in</span> CoffeeScript.FILE_EXTENSIONS <span class="hljs-keyword">then</span> <span class="hljs-keyword">do</span> (ext) -&gt;
+    <span class="hljs-built_in">require</span>.extensions[ext] ?= <span class="hljs-function">-&gt;</span>
+      <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> Error <span class="hljs-string">"""
+      Use CoffeeScript.register() or require the coffeescript/register module to require <span class="hljs-subst">#{ext}</span> files.
+      """</span>
+
+CoffeeScript._compileFile = <span class="hljs-function"><span class="hljs-params">(filename, sourceMap = <span class="hljs-literal">no</span>, inlineMap = <span class="hljs-literal">no</span>)</span> -&gt;</span>
+  raw = fs.readFileSync filename, <span class="hljs-string">'utf8'</span></pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-11">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-11">&#182;</a>
+              </div>
+              <p>Strip the Unicode byte order mark, if this file begins with one.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>  stripped = <span class="hljs-keyword">if</span> raw.charCodeAt(<span class="hljs-number">0</span>) <span class="hljs-keyword">is</span> <span class="hljs-number">0xFEFF</span> <span class="hljs-keyword">then</span> raw.substring <span class="hljs-number">1</span> <span class="hljs-keyword">else</span> raw
+
+  <span class="hljs-keyword">try</span>
+    answer = compile stripped, {
+      filename, sourceMap, inlineMap
+      sourceFiles: [filename]
+      literate: helpers.isLiterate filename
+    }
+  <span class="hljs-keyword">catch</span> err</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-12">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-12">&#182;</a>
+              </div>
+              <p>As the filename and code of a dynamically loaded file will be different
+from the original file compiled with CoffeeScript.run, add that
+information to error so it can be pretty-printed later.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>    <span class="hljs-keyword">throw</span> helpers.updateSyntaxError err, stripped, filename
+
+  answer
+
+<span class="hljs-built_in">module</span>.exports = CoffeeScript</pre></div></div>
             
         </li>
         

docs/v2/annotated-source/optparse.html

@@ -135,6 +135,8 @@ Use it like so:</p>
 options = parser.parse process.argv
 </code></pre><p>The first non-option is considered to be the start of the file (and file
 option) list, and all subsequent arguments are left unparsed.</p>
+<p>The <code>coffee</code> command uses an instance of <strong>OptionParser</strong> to parse its
+command-line arguments in <code>src/command.coffee</code>.</p>
 
             </div>
             

docs/v2/annotated-source/register.html

@@ -118,7 +118,7 @@
               
             </div>
             
-            <div class="content"><div class='highlight'><pre>CoffeeScript  = <span class="hljs-built_in">require</span> <span class="hljs-string">'./coffeescript'</span>
+            <div class="content"><div class='highlight'><pre>CoffeeScript  = <span class="hljs-built_in">require</span> <span class="hljs-string">'./'</span>
 child_process = <span class="hljs-built_in">require</span> <span class="hljs-string">'child_process'</span>
 helpers       = <span class="hljs-built_in">require</span> <span class="hljs-string">'./helpers'</span>
 path          = <span class="hljs-built_in">require</span> <span class="hljs-string">'path'</span></pre></div></div>

docs/v2/annotated-source/repl.html

@@ -122,12 +122,14 @@
 path = <span class="hljs-built_in">require</span> <span class="hljs-string">'path'</span>
 vm = <span class="hljs-built_in">require</span> <span class="hljs-string">'vm'</span>
 nodeREPL = <span class="hljs-built_in">require</span> <span class="hljs-string">'repl'</span>
-CoffeeScript = <span class="hljs-built_in">require</span> <span class="hljs-string">'./coffeescript'</span>
+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>
 
 replDefaults =
   prompt: <span class="hljs-string">'coffee&gt; '</span>,
-  historyFile: path.join process.env.HOME, <span class="hljs-string">'.coffee_history'</span> <span class="hljs-keyword">if</span> process.env.HOME
+  historyFile: <span class="hljs-keyword">do</span> -&gt;
+    historyPath = process.env.XDG_CACHE_HOME <span class="hljs-keyword">or</span> process.env.HOME
+    path.join historyPath, <span class="hljs-string">'.coffee_history'</span> <span class="hljs-keyword">if</span> historyPath
   historyMaxInputSize: <span class="hljs-number">10240</span>
   eval: <span class="hljs-function"><span class="hljs-params">(input, context, filename, cb)</span> -&gt;</span></pre></div></div>
             
@@ -256,7 +258,7 @@ Unwrap that too.</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>
+        <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
@@ -585,7 +587,7 @@ Unwrap that too.</p>
 
 <span class="hljs-built_in">module</span>.exports =
   start: <span class="hljs-function"><span class="hljs-params">(opts = {})</span> -&gt;</span>
-    [major, minor, build] = process.versions.node.split(<span class="hljs-string">'.'</span>).map (n) -&gt; parseInt(n)
+    [major, minor, build] = process.versions.node.split(<span class="hljs-string">'.'</span>).map (n) -&gt; parseInt(n, <span class="hljs-number">10</span>)
 
     <span class="hljs-keyword">if</span> major &lt; <span class="hljs-number">6</span>
       <span class="hljs-built_in">console</span>.warn <span class="hljs-string">"Node 6+ required for CoffeeScript REPL"</span>

docs/v2/annotated-source/rewriter.html

@@ -124,6 +124,9 @@ parentheses, and generally clean things up.</p>
 
             </div>
             
+            <div class="content"><div class='highlight'><pre>
+{throwSyntaxError} = <span class="hljs-built_in">require</span> <span class="hljs-string">'./helpers'</span></pre></div></div>
+            
         </li>
         
         
@@ -157,7 +160,7 @@ its internal array of tokens.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre><span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">exports</span>.<span class="hljs-title">Rewriter</span></span></pre></div></div>
+            <div class="content"><div class='highlight'><pre>exports.Rewriter = <span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">Rewriter</span></span></pre></div></div>
             
         </li>
         
@@ -168,11 +171,16 @@ its internal array of tokens.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-4">&#182;</a>
               </div>
-              <p>Helpful snippet for debugging:</p>
-<pre><code><span class="hljs-built_in">console</span>.log (t[<span class="hljs-number">0</span>] + <span class="hljs-string">'/'</span> + t[<span class="hljs-number">1</span>] <span class="hljs-keyword">for</span> t <span class="hljs-keyword">in</span> @tokens).join <span class="hljs-string">' '</span>
-</code></pre>
+              <p>Rewrite the token stream in multiple passes, one logical filter at
+a time. This could certainly be changed into a single pass through the
+stream, with a big ol’ efficient switch, but it’s much nicer to work with
+like this. The order of these passes matters – indentation must be
+corrected before implicit parentheses can be wrapped around blocks of code.</p>
+
             </div>
             
+            <div class="content"><div class='highlight'><pre>  rewrite: <span class="hljs-function"><span class="hljs-params">(@tokens)</span> -&gt;</span></pre></div></div>
+            
         </li>
         
         
@@ -182,22 +190,19 @@ its internal array of tokens.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-5">&#182;</a>
               </div>
-              <p>Rewrite the token stream in multiple passes, one logical filter at
-a time. This could certainly be changed into a single pass through the
-stream, with a big ol’ efficient switch, but it’s much nicer to work with
-like this. The order of these passes matters – indentation must be
-corrected before implicit parentheses can be wrapped around blocks of code.</p>
+              <p>Helpful snippet for debugging:
+    console.log (t[0] + ‘/‘ + t[1] for t in @tokens).join ‘ ‘</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>  rewrite: <span class="hljs-function"><span class="hljs-params">(@tokens)</span> -&gt;</span>
-    @removeLeadingNewlines()
+            <div class="content"><div class='highlight'><pre>    @removeLeadingNewlines()
     @closeOpenCalls()
     @closeOpenIndexes()
     @normalizeLines()
     @tagPostfixConditionals()
     @addImplicitBracesAndParens()
     @addLocationDataToGeneratedTokens()
+    @enforceValidCSXAttributes()
     @fixOutdentLocationData()
     @tokens</pre></div></div>
             
@@ -224,16 +229,18 @@ our feet.</p>
     i += block.call <span class="hljs-keyword">this</span>, token, i, tokens <span class="hljs-keyword">while</span> token = tokens[i]
     <span class="hljs-literal">true</span>
 
-  detectEnd: <span class="hljs-function"><span class="hljs-params">(i, condition, action)</span> -&gt;</span>
+  detectEnd: <span class="hljs-function"><span class="hljs-params">(i, condition, action, opts = {})</span> -&gt;</span>
     {tokens} = <span class="hljs-keyword">this</span>
     levels = <span class="hljs-number">0</span>
     <span class="hljs-keyword">while</span> token = tokens[i]
-      <span class="hljs-keyword">return</span> action.call <span class="hljs-keyword">this</span>, token, i     <span class="hljs-keyword">if</span> levels <span class="hljs-keyword">is</span> <span class="hljs-number">0</span> <span class="hljs-keyword">and</span> condition.call <span class="hljs-keyword">this</span>, token, i
-      <span class="hljs-keyword">return</span> action.call <span class="hljs-keyword">this</span>, token, i - <span class="hljs-number">1</span> <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> token <span class="hljs-keyword">or</span> levels &lt; <span class="hljs-number">0</span>
+      <span class="hljs-keyword">return</span> action.call <span class="hljs-keyword">this</span>, token, i <span class="hljs-keyword">if</span> levels <span class="hljs-keyword">is</span> <span class="hljs-number">0</span> <span class="hljs-keyword">and</span> condition.call <span class="hljs-keyword">this</span>, token, i
       <span class="hljs-keyword">if</span> token[<span class="hljs-number">0</span>] <span class="hljs-keyword">in</span> EXPRESSION_START
         levels += <span class="hljs-number">1</span>
       <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> token[<span class="hljs-number">0</span>] <span class="hljs-keyword">in</span> EXPRESSION_END
         levels -= <span class="hljs-number">1</span>
+      <span class="hljs-keyword">if</span> levels &lt; <span class="hljs-number">0</span>
+        <span class="hljs-keyword">return</span> <span class="hljs-keyword">if</span> opts.returnOnNegativeLevel
+        <span class="hljs-keyword">return</span> action.call <span class="hljs-keyword">this</span>, token, i
       i += <span class="hljs-number">1</span>
     i - <span class="hljs-number">1</span></pre></div></div>
             
@@ -265,18 +272,16 @@ dispatch them here.</p>
                 <a class="pilcrow" href="#section-8">&#182;</a>
               </div>
               <p>The lexer has tagged the opening parenthesis of a method call. Match it with
-its paired close. We have the mis-nested outdent case included here for
-calls that close on the same line, just before their outdent.</p>
+its paired close.</p>
 
             </div>
             
             <div class="content"><div class='highlight'><pre>  closeOpenCalls: <span class="hljs-function">-&gt;</span>
 <span class="hljs-function">    <span class="hljs-title">condition</span> = <span class="hljs-params">(token, i)</span> -&gt;</span>
-      token[<span class="hljs-number">0</span>] <span class="hljs-keyword">in</span> [<span class="hljs-string">')'</span>, <span class="hljs-string">'CALL_END'</span>] <span class="hljs-keyword">or</span>
-      token[<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'OUTDENT'</span> <span class="hljs-keyword">and</span> @tag(i - <span class="hljs-number">1</span>) <span class="hljs-keyword">is</span> <span class="hljs-string">')'</span>
+      token[<span class="hljs-number">0</span>] <span class="hljs-keyword">in</span> [<span class="hljs-string">')'</span>, <span class="hljs-string">'CALL_END'</span>]
 <span class="hljs-function">
     <span class="hljs-title">action</span> = <span class="hljs-params">(token, i)</span> -&gt;</span>
-      @tokens[<span class="hljs-keyword">if</span> token[<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'OUTDENT'</span> <span class="hljs-keyword">then</span> i - <span class="hljs-number">1</span> <span class="hljs-keyword">else</span> i][<span class="hljs-number">0</span>] = <span class="hljs-string">'CALL_END'</span>
+      token[<span class="hljs-number">0</span>] = <span class="hljs-string">'CALL_END'</span>
 
     @scanTokens (token, i) -&gt;
       @detectEnd i + <span class="hljs-number">1</span>, condition, action <span class="hljs-keyword">if</span> token[<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'CALL_START'</span>
@@ -291,7 +296,7 @@ calls that close on the same line, just before their outdent.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-9">&#182;</a>
               </div>
-              <p>The lexer has tagged the opening parenthesis of an indexing operation call.
+              <p>The lexer has tagged the opening bracket of an indexing operation call.
 Match it with its paired close.</p>
 
             </div>
@@ -416,7 +421,7 @@ add them.</p>
     @scanTokens (token, i, tokens) -&gt;
       [tag]     = token
       [prevTag] = prevToken = <span class="hljs-keyword">if</span> i &gt; <span class="hljs-number">0</span> <span class="hljs-keyword">then</span> tokens[i - <span class="hljs-number">1</span>] <span class="hljs-keyword">else</span> []
-      [nextTag] = <span class="hljs-keyword">if</span> i &lt; tokens.length - <span class="hljs-number">1</span> <span class="hljs-keyword">then</span> tokens[i + <span class="hljs-number">1</span>] <span class="hljs-keyword">else</span> []
+      [nextTag] = nextToken = <span class="hljs-keyword">if</span> i &lt; tokens.length - <span class="hljs-number">1</span> <span class="hljs-keyword">then</span> tokens[i + <span class="hljs-number">1</span>] <span class="hljs-keyword">else</span> []
 <span class="hljs-function">      <span class="hljs-title">stackTop</span>  = -&gt;</span> stack[stack.length - <span class="hljs-number">1</span>]
       startIdx  = i</pre></div></div>
             
@@ -449,9 +454,12 @@ and spliced, when returning for getting a new token.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre><span class="hljs-function">      <span class="hljs-title">inImplicit</span>        = -&gt;</span> stackTop()?[<span class="hljs-number">2</span>]?.ours
-<span class="hljs-function">      <span class="hljs-title">inImplicitCall</span>    = -&gt;</span> inImplicit() <span class="hljs-keyword">and</span> stackTop()?[<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'('</span>
-<span class="hljs-function">      <span class="hljs-title">inImplicitObject</span>  = -&gt;</span> inImplicit() <span class="hljs-keyword">and</span> stackTop()?[<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'{'</span></pre></div></div>
+            <div class="content"><div class='highlight'><pre><span class="hljs-function">      <span class="hljs-title">isImplicit</span>        = <span class="hljs-params">(stackItem)</span> -&gt;</span> stackItem?[<span class="hljs-number">2</span>]?.ours
+<span class="hljs-function">      <span class="hljs-title">isImplicitObject</span>  = <span class="hljs-params">(stackItem)</span> -&gt;</span> isImplicit(stackItem) <span class="hljs-keyword">and</span> stackItem?[<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'{'</span>
+<span class="hljs-function">      <span class="hljs-title">isImplicitCall</span>    = <span class="hljs-params">(stackItem)</span> -&gt;</span> isImplicit(stackItem) <span class="hljs-keyword">and</span> stackItem?[<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'('</span>
+<span class="hljs-function">      <span class="hljs-title">inImplicit</span>        = -&gt;</span> isImplicit stackTop()
+<span class="hljs-function">      <span class="hljs-title">inImplicitCall</span>    = -&gt;</span> isImplicitCall stackTop()
+<span class="hljs-function">      <span class="hljs-title">inImplicitObject</span>  = -&gt;</span> isImplicitObject stackTop()</pre></div></div>
             
         </li>
         
@@ -467,32 +475,37 @@ class declaration or if-conditionals)</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre><span class="hljs-function">      <span class="hljs-title">inImplicitControl</span> = -&gt;</span> inImplicit <span class="hljs-keyword">and</span> stackTop()?[<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'CONTROL'</span>
+            <div class="content"><div class='highlight'><pre><span class="hljs-function">      <span class="hljs-title">inImplicitControl</span> = -&gt;</span> inImplicit() <span class="hljs-keyword">and</span> stackTop()?[<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'CONTROL'</span>
 <span class="hljs-function">
-      <span class="hljs-title">startImplicitCall</span> = <span class="hljs-params">(j)</span> -&gt;</span>
-        idx = j ? i
+      <span class="hljs-title">startImplicitCall</span> = <span class="hljs-params">(idx)</span> -&gt;</span>
         stack.push [<span class="hljs-string">'('</span>, idx, ours: <span class="hljs-literal">yes</span>]
         tokens.splice idx, <span class="hljs-number">0</span>, generate <span class="hljs-string">'CALL_START'</span>, <span class="hljs-string">'('</span>
-        i += <span class="hljs-number">1</span> <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> j?
 <span class="hljs-function">
       <span class="hljs-title">endImplicitCall</span> = -&gt;</span>
         stack.pop()
         tokens.splice i, <span class="hljs-number">0</span>, generate <span class="hljs-string">'CALL_END'</span>, <span class="hljs-string">')'</span>, [<span class="hljs-string">''</span>, <span class="hljs-string">'end of input'</span>, token[<span class="hljs-number">2</span>]]
         i += <span class="hljs-number">1</span>
 <span class="hljs-function">
-      <span class="hljs-title">startImplicitObject</span> = <span class="hljs-params">(j, startsLine = <span class="hljs-literal">yes</span>)</span> -&gt;</span>
-        idx = j ? i
+      <span class="hljs-title">startImplicitObject</span> = <span class="hljs-params">(idx, startsLine = <span class="hljs-literal">yes</span>)</span> -&gt;</span>
         stack.push [<span class="hljs-string">'{'</span>, idx, sameLine: <span class="hljs-literal">yes</span>, startsLine: startsLine, ours: <span class="hljs-literal">yes</span>]
         val = <span class="hljs-keyword">new</span> String <span class="hljs-string">'{'</span>
         val.generated = <span class="hljs-literal">yes</span>
         tokens.splice idx, <span class="hljs-number">0</span>, generate <span class="hljs-string">'{'</span>, val, token
-        i += <span class="hljs-number">1</span> <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> j?
 <span class="hljs-function">
       <span class="hljs-title">endImplicitObject</span> = <span class="hljs-params">(j)</span> -&gt;</span>
         j = j ? i
         stack.pop()
         tokens.splice j, <span class="hljs-number">0</span>, generate <span class="hljs-string">'}'</span>, <span class="hljs-string">'}'</span>, token
-        i += <span class="hljs-number">1</span></pre></div></div>
+        i += <span class="hljs-number">1</span>
+<span class="hljs-function">
+      <span class="hljs-title">implicitObjectContinues</span> = <span class="hljs-params">(j)</span> =&gt;</span>
+        nextTerminatorIdx = <span class="hljs-literal">null</span>
+        @detectEnd j,
+          <span class="hljs-function"><span class="hljs-params">(token)</span> -&gt;</span> token[<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'TERMINATOR'</span>
+          (token, i) -&gt; nextTerminatorIdx = i
+          returnOnNegativeLevel: <span class="hljs-literal">yes</span>
+        <span class="hljs-keyword">return</span> <span class="hljs-literal">no</span> <span class="hljs-keyword">unless</span> nextTerminatorIdx?
+        @looksObjectish nextTerminatorIdx + <span class="hljs-number">1</span></pre></div></div>
             
         </li>
         
@@ -503,13 +516,15 @@ class declaration or if-conditionals)</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-18">&#182;</a>
               </div>
-              <p>Don’t end an implicit call on next indent if any of these are in an argument</p>
+              <p>Don’t end an implicit call/object on next indent if any of these are in an argument/value</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>      <span class="hljs-keyword">if</span> inImplicitCall() <span class="hljs-keyword">and</span> tag <span class="hljs-keyword">in</span> [<span class="hljs-string">'IF'</span>, <span class="hljs-string">'TRY'</span>, <span class="hljs-string">'FINALLY'</span>, <span class="hljs-string">'CATCH'</span>,
-        <span class="hljs-string">'CLASS'</span>, <span class="hljs-string">'SWITCH'</span>]
-        stack.push [<span class="hljs-string">'CONTROL'</span>, i, ours: <span class="hljs-literal">true</span>]
+            <div class="content"><div class='highlight'><pre>      <span class="hljs-keyword">if</span> (
+        (inImplicitCall() <span class="hljs-keyword">or</span> inImplicitObject()) <span class="hljs-keyword">and</span> tag <span class="hljs-keyword">in</span> CONTROL_IN_IMPLICIT <span class="hljs-keyword">or</span>
+        inImplicitObject() <span class="hljs-keyword">and</span> prevTag <span class="hljs-keyword">is</span> <span class="hljs-string">':'</span> <span class="hljs-keyword">and</span> tag <span class="hljs-keyword">is</span> <span class="hljs-string">'FOR'</span>
+      )
+        stack.push [<span class="hljs-string">'CONTROL'</span>, i, ours: <span class="hljs-literal">yes</span>]
         <span class="hljs-keyword">return</span> forward(<span class="hljs-number">1</span>)
 
       <span class="hljs-keyword">if</span> tag <span class="hljs-keyword">is</span> <span class="hljs-string">'INDENT'</span> <span class="hljs-keyword">and</span> inImplicit()</pre></div></div>
@@ -531,8 +546,12 @@ class declaration or if-conditionals)</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>        <span class="hljs-keyword">if</span> prevTag <span class="hljs-keyword">not</span> <span class="hljs-keyword">in</span> [<span class="hljs-string">'=&gt;'</span>, <span class="hljs-string">'-&gt;'</span>, <span class="hljs-string">'['</span>, <span class="hljs-string">'('</span>, <span class="hljs-string">','</span>, <span class="hljs-string">'{'</span>, <span class="hljs-string">'TRY'</span>, <span class="hljs-string">'ELSE'</span>, <span class="hljs-string">'='</span>]
-          endImplicitCall() <span class="hljs-keyword">while</span> inImplicitCall()
+            <div class="content"><div class='highlight'><pre>        <span class="hljs-keyword">if</span> prevTag <span class="hljs-keyword">not</span> <span class="hljs-keyword">in</span> [<span class="hljs-string">'=&gt;'</span>, <span class="hljs-string">'-&gt;'</span>, <span class="hljs-string">'['</span>, <span class="hljs-string">'('</span>, <span class="hljs-string">','</span>, <span class="hljs-string">'{'</span>, <span class="hljs-string">'ELSE'</span>, <span class="hljs-string">'='</span>]
+          <span class="hljs-keyword">while</span> inImplicitCall() <span class="hljs-keyword">or</span> inImplicitObject() <span class="hljs-keyword">and</span> prevTag <span class="hljs-keyword">isnt</span> <span class="hljs-string">':'</span>
+            <span class="hljs-keyword">if</span> inImplicitCall()
+              endImplicitCall()
+            <span class="hljs-keyword">else</span>
+              endImplicitObject()
         stack.pop() <span class="hljs-keyword">if</span> inImplicitControl()
         stack.push [tag, i]
         <span class="hljs-keyword">return</span> forward(<span class="hljs-number">1</span>)</pre></div></div>
@@ -595,7 +614,7 @@ f a, f() b, f? c, h[0] d etc.</p>
           tag <span class="hljs-keyword">is</span> <span class="hljs-string">'?'</span> <span class="hljs-keyword">and</span> i &gt; <span class="hljs-number">0</span> <span class="hljs-keyword">and</span> <span class="hljs-keyword">not</span> tokens[i - <span class="hljs-number">1</span>].spaced) <span class="hljs-keyword">and</span>
          (nextTag <span class="hljs-keyword">in</span> IMPLICIT_CALL <span class="hljs-keyword">or</span>
           nextTag <span class="hljs-keyword">in</span> IMPLICIT_UNSPACED_CALL <span class="hljs-keyword">and</span>
-          <span class="hljs-keyword">not</span> tokens[i + <span class="hljs-number">1</span>]?.spaced <span class="hljs-keyword">and</span> <span class="hljs-keyword">not</span> tokens[i + <span class="hljs-number">1</span>]?.newLine)
+          <span class="hljs-keyword">not</span> nextToken.spaced <span class="hljs-keyword">and</span> <span class="hljs-keyword">not</span> nextToken.newLine)
         tag = token[<span class="hljs-number">0</span>] = <span class="hljs-string">'FUNC_EXIST'</span> <span class="hljs-keyword">if</span> tag <span class="hljs-keyword">is</span> <span class="hljs-string">'?'</span>
         startImplicitCall i + <span class="hljs-number">1</span>
         <span class="hljs-keyword">return</span> forward(<span class="hljs-number">2</span>)</pre></div></div>
@@ -613,11 +632,6 @@ f a, f() b, f? c, h[0] d etc.</p>
 <pre><code>f
   a: b
   c: d
-</code></pre><p>and</p>
-<pre><code>f
-  <span class="hljs-number">1</span>
-  a: b
-  b: c
 </code></pre><p>Don’t accept implicit calls of this type, when on the same line
 as the control structures below as that may misinterpret constructs like:</p>
 <pre><code><span class="hljs-keyword">if</span> f
@@ -670,7 +684,9 @@ that creates grammatical ambiguities.</p>
           <span class="hljs-keyword">when</span> @tag(i - <span class="hljs-number">1</span>) <span class="hljs-keyword">in</span> EXPRESSION_END <span class="hljs-keyword">then</span> start[<span class="hljs-number">1</span>]
           <span class="hljs-keyword">when</span> @tag(i - <span class="hljs-number">2</span>) <span class="hljs-keyword">is</span> <span class="hljs-string">'@'</span> <span class="hljs-keyword">then</span> i - <span class="hljs-number">2</span>
           <span class="hljs-keyword">else</span> i - <span class="hljs-number">1</span>
-        s -= <span class="hljs-number">2</span> <span class="hljs-keyword">while</span> @tag(s - <span class="hljs-number">2</span>) <span class="hljs-keyword">is</span> <span class="hljs-string">'HERECOMMENT'</span></pre></div></div>
+        s -= <span class="hljs-number">2</span> <span class="hljs-keyword">while</span> @tag(s - <span class="hljs-number">2</span>) <span class="hljs-keyword">is</span> <span class="hljs-string">'HERECOMMENT'</span>
+
+        startsLine = s <span class="hljs-keyword">is</span> <span class="hljs-number">0</span> <span class="hljs-keyword">or</span> @tag(s - <span class="hljs-number">1</span>) <span class="hljs-keyword">in</span> LINEBREAKS <span class="hljs-keyword">or</span> tokens[s - <span class="hljs-number">1</span>].newLine</pre></div></div>
             
         </li>
         
@@ -681,23 +697,6 @@ that creates grammatical ambiguities.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-26">&#182;</a>
               </div>
-              <p>Mark if the value is a for loop</p>
-
-            </div>
-            
-            <div class="content"><div class='highlight'><pre>        @insideForDeclaration = nextTag <span class="hljs-keyword">is</span> <span class="hljs-string">'FOR'</span>
-
-        startsLine = s <span class="hljs-keyword">is</span> <span class="hljs-number">0</span> <span class="hljs-keyword">or</span> @tag(s - <span class="hljs-number">1</span>) <span class="hljs-keyword">in</span> LINEBREAKS <span class="hljs-keyword">or</span> tokens[s - <span class="hljs-number">1</span>].newLine</pre></div></div>
-            
-        </li>
-        
-        
-        <li id="section-27">
-            <div class="annotation">
-              
-              <div class="pilwrap ">
-                <a class="pilcrow" href="#section-27">&#182;</a>
-              </div>
               <p>Are we just continuing an already declared object?</p>
 
             </div>
@@ -714,11 +713,11 @@ that creates grammatical ambiguities.</p>
         </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>End implicit calls when chaining method calls
 like e.g.:</p>
@@ -734,8 +733,22 @@ like e.g.:</p>
 </code></pre>
             </div>
             
-            <div class="content"><div class='highlight'><pre>
-      stackTop()[<span class="hljs-number">2</span>].sameLine = <span class="hljs-literal">no</span> <span class="hljs-keyword">if</span> inImplicitObject() <span class="hljs-keyword">and</span> tag <span class="hljs-keyword">in</span> LINEBREAKS
+        </li>
+        
+        
+        <li id="section-28">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-28">&#182;</a>
+              </div>
+              <p>Mark all enclosing objects as not sameLine</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>      <span class="hljs-keyword">if</span> tag <span class="hljs-keyword">in</span> LINEBREAKS
+        <span class="hljs-keyword">for</span> stackItem <span class="hljs-keyword">in</span> stack <span class="hljs-keyword">by</span> <span class="hljs-number">-1</span> <span class="hljs-keyword">when</span> isImplicitObject stackItem
+          stackItem[<span class="hljs-number">2</span>].sameLine = <span class="hljs-literal">no</span>
 
       newLine = prevTag <span class="hljs-keyword">is</span> <span class="hljs-string">'OUTDENT'</span> <span class="hljs-keyword">or</span> prevToken.newLine
       <span class="hljs-keyword">if</span> tag <span class="hljs-keyword">in</span> IMPLICIT_END <span class="hljs-keyword">or</span> tag <span class="hljs-keyword">in</span> CALL_CLOSERS <span class="hljs-keyword">and</span> newLine
@@ -772,8 +785,9 @@ return a: 1, b: 2 unless true</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>          <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> inImplicitObject() <span class="hljs-keyword">and</span> <span class="hljs-keyword">not</span> @insideForDeclaration <span class="hljs-keyword">and</span> sameLine <span class="hljs-keyword">and</span>
-                  tag <span class="hljs-keyword">isnt</span> <span class="hljs-string">'TERMINATOR'</span> <span class="hljs-keyword">and</span> prevTag <span class="hljs-keyword">isnt</span> <span class="hljs-string">':'</span>
+            <div class="content"><div class='highlight'><pre>          <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> inImplicitObject() <span class="hljs-keyword">and</span> sameLine <span class="hljs-keyword">and</span>
+                  tag <span class="hljs-keyword">isnt</span> <span class="hljs-string">'TERMINATOR'</span> <span class="hljs-keyword">and</span> prevTag <span class="hljs-keyword">isnt</span> <span class="hljs-string">':'</span> <span class="hljs-keyword">and</span>
+                  <span class="hljs-keyword">not</span> (tag <span class="hljs-keyword">in</span> [<span class="hljs-string">'POST_IF'</span>, <span class="hljs-string">'FOR'</span>, <span class="hljs-string">'WHILE'</span>, <span class="hljs-string">'UNTIL'</span>] <span class="hljs-keyword">and</span> startsLine <span class="hljs-keyword">and</span> implicitObjectContinues(i + <span class="hljs-number">1</span>))
             endImplicitObject()</pre></div></div>
             
         </li>
@@ -820,7 +834,6 @@ e = <span class="hljs-number">2</span>
             </div>
             
             <div class="content"><div class='highlight'><pre>      <span class="hljs-keyword">if</span> tag <span class="hljs-keyword">is</span> <span class="hljs-string">','</span> <span class="hljs-keyword">and</span> <span class="hljs-keyword">not</span> @looksObjectish(i + <span class="hljs-number">1</span>) <span class="hljs-keyword">and</span> inImplicitObject() <span class="hljs-keyword">and</span>
-         <span class="hljs-keyword">not</span> @insideForDeclaration <span class="hljs-keyword">and</span>
          (nextTag <span class="hljs-keyword">isnt</span> <span class="hljs-string">'TERMINATOR'</span> <span class="hljs-keyword">or</span> <span class="hljs-keyword">not</span> @looksObjectish(i + <span class="hljs-number">2</span>))</pre></div></div>
             
         </li>
@@ -854,6 +867,27 @@ array further up the stack, so give it a chance.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-34">&#182;</a>
               </div>
+              <p>Make sure only strings and wrapped expressions are used in CSX attributes</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>  enforceValidCSXAttributes: <span class="hljs-function">-&gt;</span>
+    @scanTokens (token, i, tokens) -&gt;
+      <span class="hljs-keyword">if</span> token.csxColon
+        next = tokens[i + <span class="hljs-number">1</span>]
+        <span class="hljs-keyword">if</span> next[<span class="hljs-number">0</span>] <span class="hljs-keyword">not</span> <span class="hljs-keyword">in</span> [<span class="hljs-string">'STRING_START'</span>, <span class="hljs-string">'STRING'</span>, <span class="hljs-string">'('</span>]
+          throwSyntaxError <span class="hljs-string">'expected wrapped or quoted CSX attribute'</span>, next[<span class="hljs-number">2</span>]
+      <span class="hljs-keyword">return</span> <span class="hljs-number">1</span></pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-35">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-35">&#182;</a>
+              </div>
               <p>Add location data to all tokens generated by the rewriter.</p>
 
             </div>
@@ -878,11 +912,11 @@ array further up the stack, so give it a chance.</p>
         </li>
         
         
-        <li id="section-35">
+        <li id="section-36">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-35">&#182;</a>
+                <a class="pilcrow" href="#section-36">&#182;</a>
               </div>
               <p>OUTDENT tokens should always be positioned at the last character of the
 previous token, so that AST nodes ending in an OUTDENT token end up with a
@@ -906,11 +940,11 @@ location corresponding to the last “real” token under the node.</p>
         </li>
         
         
-        <li id="section-36">
+        <li id="section-37">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-36">&#182;</a>
+                <a class="pilcrow" href="#section-37">&#182;</a>
               </div>
               <p>Because our grammar is LALR(1), it can’t handle some single-line
 expressions that lack ending delimiters. The <strong>Rewriter</strong> adds the implicit
@@ -928,7 +962,8 @@ blocks are added.</p>
       <span class="hljs-keyword">not</span> (token[<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'TERMINATOR'</span> <span class="hljs-keyword">and</span> @tag(i + <span class="hljs-number">1</span>) <span class="hljs-keyword">in</span> EXPRESSION_CLOSE) <span class="hljs-keyword">and</span>
       <span class="hljs-keyword">not</span> (token[<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'ELSE'</span> <span class="hljs-keyword">and</span> starter <span class="hljs-keyword">isnt</span> <span class="hljs-string">'THEN'</span>) <span class="hljs-keyword">and</span>
       <span class="hljs-keyword">not</span> (token[<span class="hljs-number">0</span>] <span class="hljs-keyword">in</span> [<span class="hljs-string">'CATCH'</span>, <span class="hljs-string">'FINALLY'</span>] <span class="hljs-keyword">and</span> starter <span class="hljs-keyword">in</span> [<span class="hljs-string">'-&gt;'</span>, <span class="hljs-string">'=&gt;'</span>]) <span class="hljs-keyword">or</span>
-      token[<span class="hljs-number">0</span>] <span class="hljs-keyword">in</span> CALL_CLOSERS <span class="hljs-keyword">and</span> @tokens[i - <span class="hljs-number">1</span>].newLine
+      token[<span class="hljs-number">0</span>] <span class="hljs-keyword">in</span> CALL_CLOSERS <span class="hljs-keyword">and</span>
+      (@tokens[i - <span class="hljs-number">1</span>].newLine <span class="hljs-keyword">or</span> @tokens[i - <span class="hljs-number">1</span>][<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'OUTDENT'</span>)
 <span class="hljs-function">
     <span class="hljs-title">action</span> = <span class="hljs-params">(token, i)</span> -&gt;</span>
       @tokens.splice (<span class="hljs-keyword">if</span> @tag(i - <span class="hljs-number">1</span>) <span class="hljs-keyword">is</span> <span class="hljs-string">','</span> <span class="hljs-keyword">then</span> i - <span class="hljs-number">1</span> <span class="hljs-keyword">else</span> i), <span class="hljs-number">0</span>, outdent
@@ -946,6 +981,10 @@ blocks are added.</p>
         <span class="hljs-keyword">for</span> j <span class="hljs-keyword">in</span> [<span class="hljs-number">1.</span><span class="hljs-number">.2</span>] <span class="hljs-keyword">when</span> @tag(i + j) <span class="hljs-keyword">in</span> [<span class="hljs-string">'OUTDENT'</span>, <span class="hljs-string">'TERMINATOR'</span>, <span class="hljs-string">'FINALLY'</span>]
           tokens.splice i + j, <span class="hljs-number">0</span>, @indentation()...
           <span class="hljs-keyword">return</span> <span class="hljs-number">2</span> + j
+      <span class="hljs-keyword">if</span> tag <span class="hljs-keyword">in</span> [<span class="hljs-string">'-&gt;'</span>, <span class="hljs-string">'=&gt;'</span>] <span class="hljs-keyword">and</span> (@tag(i + <span class="hljs-number">1</span>) <span class="hljs-keyword">is</span> <span class="hljs-string">','</span> <span class="hljs-keyword">or</span> @tag(i + <span class="hljs-number">1</span>) <span class="hljs-keyword">is</span> <span class="hljs-string">'.'</span> <span class="hljs-keyword">and</span> token.newLine)
+        [indent, outdent] = @indentation tokens[i]
+        tokens.splice i + <span class="hljs-number">1</span>, <span class="hljs-number">0</span>, indent, outdent
+        <span class="hljs-keyword">return</span> <span class="hljs-number">1</span>
       <span class="hljs-keyword">if</span> tag <span class="hljs-keyword">in</span> SINGLE_LINERS <span class="hljs-keyword">and</span> @tag(i + <span class="hljs-number">1</span>) <span class="hljs-keyword">isnt</span> <span class="hljs-string">'INDENT'</span> <span class="hljs-keyword">and</span>
          <span class="hljs-keyword">not</span> (tag <span class="hljs-keyword">is</span> <span class="hljs-string">'ELSE'</span> <span class="hljs-keyword">and</span> @tag(i + <span class="hljs-number">1</span>) <span class="hljs-keyword">is</span> <span class="hljs-string">'IF'</span>)
         starter = tag
@@ -960,11 +999,11 @@ blocks are added.</p>
         </li>
         
         
-        <li id="section-37">
+        <li id="section-38">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-37">&#182;</a>
+                <a class="pilcrow" href="#section-38">&#182;</a>
               </div>
               <p>Tag postfix conditionals as such, so that we can parse them with a
 different precedence.</p>
@@ -993,11 +1032,11 @@ different precedence.</p>
         </li>
         
         
-        <li id="section-38">
+        <li id="section-39">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-38">&#182;</a>
+                <a class="pilcrow" href="#section-39">&#182;</a>
               </div>
               <p>Generate the indentation tokens, based on another token on the same line.</p>
 
@@ -1018,11 +1057,11 @@ different precedence.</p>
         </li>
         
         
-        <li id="section-39">
+        <li id="section-40">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-39">&#182;</a>
+                <a class="pilcrow" href="#section-40">&#182;</a>
               </div>
               <p>Look up a tag by token index.</p>
 
@@ -1033,26 +1072,14 @@ different precedence.</p>
         </li>
         
         
-        <li id="section-40">
-            <div class="annotation">
-              
-              <div class="pilwrap ">
-                <a class="pilcrow" href="#section-40">&#182;</a>
-              </div>
-              <h2 id="constants">Constants</h2>
-
-            </div>
-            
-        </li>
-        
-        
         <li id="section-41">
             <div class="annotation">
               
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-41">&#182;</a>
               </div>
-              
+              <h2 id="constants">Constants</h2>
+
             </div>
             
         </li>
@@ -1064,6 +1091,18 @@ different precedence.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-42">&#182;</a>
               </div>
+              
+            </div>
+            
+        </li>
+        
+        
+        <li id="section-43">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-43">&#182;</a>
+              </div>
               <p>List of the token pairs that must be balanced.</p>
 
             </div>
@@ -1083,11 +1122,11 @@ different precedence.</p>
         </li>
         
         
-        <li id="section-43">
+        <li id="section-44">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-43">&#182;</a>
+                <a class="pilcrow" href="#section-44">&#182;</a>
               </div>
               <p>The inverse mappings of <code>BALANCED_PAIRS</code> we’re trying to fix up, so we can
 look things up from either end.</p>
@@ -1099,11 +1138,11 @@ look things up from either end.</p>
         </li>
         
         
-        <li id="section-44">
+        <li id="section-45">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-44">&#182;</a>
+                <a class="pilcrow" href="#section-45">&#182;</a>
               </div>
               <p>The tokens that signal the start/end of a balanced pair.</p>
 
@@ -1119,11 +1158,11 @@ EXPRESSION_END   = []
         </li>
         
         
-        <li id="section-45">
+        <li id="section-46">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-45">&#182;</a>
+                <a class="pilcrow" href="#section-46">&#182;</a>
               </div>
               <p>Tokens that indicate the close of a clause of an expression.</p>
 
@@ -1134,11 +1173,11 @@ EXPRESSION_END   = []
         </li>
         
         
-        <li id="section-46">
+        <li id="section-47">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-46">&#182;</a>
+                <a class="pilcrow" href="#section-47">&#182;</a>
               </div>
               <p>Tokens that, if followed by an <code>IMPLICIT_CALL</code>, indicate a function invocation.</p>
 
@@ -1149,18 +1188,18 @@ EXPRESSION_END   = []
         </li>
         
         
-        <li id="section-47">
+        <li id="section-48">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-47">&#182;</a>
+                <a class="pilcrow" href="#section-48">&#182;</a>
               </div>
               <p>If preceded by an <code>IMPLICIT_FUNC</code>, indicates a function invocation.</p>
 
             </div>
             
             <div class="content"><div class='highlight'><pre>IMPLICIT_CALL    = [
-  <span class="hljs-string">'IDENTIFIER'</span>, <span class="hljs-string">'PROPERTY'</span>, <span class="hljs-string">'NUMBER'</span>, <span class="hljs-string">'INFINITY'</span>, <span class="hljs-string">'NAN'</span>
+  <span class="hljs-string">'IDENTIFIER'</span>, <span class="hljs-string">'CSX_TAG'</span>, <span class="hljs-string">'PROPERTY'</span>, <span class="hljs-string">'NUMBER'</span>, <span class="hljs-string">'INFINITY'</span>, <span class="hljs-string">'NAN'</span>
   <span class="hljs-string">'STRING'</span>, <span class="hljs-string">'STRING_START'</span>, <span class="hljs-string">'REGEX'</span>, <span class="hljs-string">'REGEX_START'</span>, <span class="hljs-string">'JS'</span>
   <span class="hljs-string">'NEW'</span>, <span class="hljs-string">'PARAM_START'</span>, <span class="hljs-string">'CLASS'</span>, <span class="hljs-string">'IF'</span>, <span class="hljs-string">'TRY'</span>, <span class="hljs-string">'SWITCH'</span>, <span class="hljs-string">'THIS'</span>
   <span class="hljs-string">'UNDEFINED'</span>, <span class="hljs-string">'NULL'</span>, <span class="hljs-string">'BOOL'</span>
@@ -1173,11 +1212,11 @@ IMPLICIT_UNSPACED_CALL = [<span class="hljs-string">'+'</span>, <span class="hlj
         </li>
         
         
-        <li id="section-48">
+        <li id="section-49">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-48">&#182;</a>
+                <a class="pilcrow" href="#section-49">&#182;</a>
               </div>
               <p>Tokens that always mark the end of an implicit call for single-liners.</p>
 
@@ -1189,11 +1228,11 @@ IMPLICIT_UNSPACED_CALL = [<span class="hljs-string">'+'</span>, <span class="hlj
         </li>
         
         
-        <li id="section-49">
+        <li id="section-50">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-49">&#182;</a>
+                <a class="pilcrow" href="#section-50">&#182;</a>
               </div>
               <p>Single-line flavors of block expressions that have unclosed endings.
 The grammar can’t disambiguate them, so we insert the implicit indentation.</p>
@@ -1206,11 +1245,11 @@ SINGLE_CLOSERS   = [<span class="hljs-string">'TERMINATOR'</span>, <span class="
         </li>
         
         
-        <li id="section-50">
+        <li id="section-51">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-50">&#182;</a>
+                <a class="pilcrow" href="#section-51">&#182;</a>
               </div>
               <p>Tokens that end a line.</p>
 
@@ -1221,11 +1260,11 @@ SINGLE_CLOSERS   = [<span class="hljs-string">'TERMINATOR'</span>, <span class="
         </li>
         
         
-        <li id="section-51">
+        <li id="section-52">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-51">&#182;</a>
+                <a class="pilcrow" href="#section-52">&#182;</a>
               </div>
               <p>Tokens that close open calls when they follow a newline.</p>
 
@@ -1235,6 +1274,21 @@ SINGLE_CLOSERS   = [<span class="hljs-string">'TERMINATOR'</span>, <span class="
             
         </li>
         
+        
+        <li id="section-53">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-53">&#182;</a>
+              </div>
+              <p>Tokens that prevent a subsequent indent from ending implicit calls/objects</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>CONTROL_IN_IMPLICIT = [<span class="hljs-string">'IF'</span>, <span class="hljs-string">'TRY'</span>, <span class="hljs-string">'FINALLY'</span>, <span class="hljs-string">'CATCH'</span>, <span class="hljs-string">'CLASS'</span>, <span class="hljs-string">'SWITCH'</span>]</pre></div></div>
+            
+        </li>
+        
     </ul>
   </div>
 </body>

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/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 @@
+code = 2 * 617 # The code is 1234

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/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/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_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 accomodated 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,31 @@
-## Change Log
+## Changelog
+
+```
+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')
@@ -11,6 +38,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')
 ```
@@ -18,6 +55,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')
 ```
@@ -173,7 +228,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.
 
 ```
@@ -186,14 +241,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.
@@ -286,7 +336,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)**.
@@ -405,7 +455,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')
@@ -430,7 +480,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')
@@ -519,7 +569,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 (`import` and `export` 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 [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/comments.md

@@ -0,0 +1,13 @@
+## Comments
+
+In CoffeeScript, comments are denoted by the `#` character. Everything from a `#` to the end of the line is ignored by the compiler, and will be excluded from the JavaScript output.
+
+```
+codeFor('comment')
+```
+
+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.
+
+```
+codeFor('block_comment')
+```

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/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), and generates JavaScript using ES2015+ syntax. <a href="/v2/">Learn more</a>.</p>

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; regalar `.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/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/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

@@ -35,3 +35,43 @@ Once installed, you should have access to the `coffee` command, which can execut
     `coffee -o lib/ -cw src/`
 *   Start the CoffeeScript REPL (`Ctrl-D` to exit, `Ctrl-V`for multi-line):<br>
     `coffee`
+
+### 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
+```
+
+### 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/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,188 @@
+<%= 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>
+      <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="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>
+      <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}

documentation/v2/code.html

@@ -0,0 +1,17 @@
+<aside class="code-example container-fluid bg-ribbed-dark" data-example="<%= file %>">
+  <div class="row">
+    <div class="col-md-6 coffeescript-input-column">
+      <textarea class="coffeescript-input" id="<%= file %>-coffee"><%= cs %></textarea>
+    </div>
+    <div class="col-md-6 javascript-output-column">
+      <textarea class="javascript-output" id="<%= file %>-js"><%= js %></textarea>
+    </div>
+  </div>
+  <% if (run) { %>
+  <div class="row">
+    <div class="col-xs-12 text-xs-right">
+      <button type="button" class="btn btn-primary" data-action="run-code-example" data-example="<%= file %>" data-run="<%= escape(run) %>"><% if (run === true) { %>▶<% } else { %><small>▶</small>&ensp;<%= run.replace(/"/g, '&quot;') %><% } %></button>
+    </div>
+  </div>
+  <% } %>
+</aside>

documentation/v2/docs.coffee

@@ -0,0 +1,128 @@
+$(document).ready ->
+  # Mobile navigation
+  toggleSidebar = ->
+    $('.menu-button, .row-offcanvas').toggleClass 'active'
+
+  $('[data-toggle="offcanvas"]').click toggleSidebar
+
+  $('[data-action="sidebar-nav"]').click (event) ->
+    if $('.menu-button').is(':visible')
+      event.preventDefault()
+      toggleSidebar()
+      setTimeout ->
+        window.location = event.target.href
+      , 260 # Wait for the sidebar to slide away before navigating
+
+  # Initialize Scrollspy for sidebar navigation; http://v4-alpha.getbootstrap.com/components/scrollspy/
+  # See also http://www.codingeverything.com/2014/02/BootstrapDocsSideBar.html and http://jsfiddle.net/KyleMit/v6zhz/
+  $('body').scrollspy
+    target: '#contents'
+    offset: Math.round $('main').css('padding-top').replace('px', '')
+
+  initializeScrollspyFromHash = (hash) ->
+    $(".nav-link.active[href!='#{hash}']").removeClass 'active'
+
+  $(window).on 'activate.bs.scrollspy', (event, target) -> # Why `window`? https://github.com/twbs/bootstrap/issues/20086
+    # We only want one active link in the nav
+    $(".nav-link.active[href!='#{target.relatedTarget}']").removeClass 'active'
+    $target = $(".nav-link[href='#{target.relatedTarget}']")
+    # Update the browser address bar on scroll or navigation
+    window.history.pushState {}, $target.text(), $target.prop('href')
+
+
+  # Initialize CodeMirror for code examples; https://codemirror.net/doc/manual.html
+  editors = []
+  lastCompilationElapsedTime = 200
+  $('textarea').each (index) ->
+    $(@).data 'index', index
+    mode = if $(@).hasClass('javascript-output') then 'javascript' else 'coffeescript'
+
+    editors[index] = editor = CodeMirror.fromTextArea @,
+      mode: mode
+      theme: 'twilight'
+      indentUnit: 2
+      tabSize: 2
+      lineWrapping: on
+      lineNumbers: off
+      inputStyle: 'contenteditable'
+      readOnly: mode isnt 'coffeescript' # Can’t use 'nocursor' if we want the JavaScript to be copyable
+      viewportMargin: Infinity
+
+    # Whenever the user edits the CoffeeScript side of a code example, update the JavaScript output
+    # If the editor is Try CoffeeScript, also update the hash and save this code in localStorage
+    if mode is 'coffeescript'
+      pending = null
+      editor.on 'change', (instance, change) ->
+        clearTimeout pending
+        pending = setTimeout ->
+          lastCompilationStartTime = Date.now()
+          try
+            coffee = editor.getValue()
+            if index is 0 and $('#try').hasClass('active') # If this is the editor in Try CoffeeScript and it’s still visible
+              # Update the hash with the current code
+              link = "try:#{encodeURIComponent coffee}"
+              window.history.pushState {}, 'CoffeeScript', "#{location.href.split('#')[0]}##{link}"
+              # Save this to the user’s localStorage
+              try
+                if window.localStorage?
+                  window.localStorage.setItem 'tryCoffeeScriptCode', coffee
+              catch exception
+            output = CoffeeScript.compile coffee, bare: yes
+            lastCompilationElapsedTime = Math.max(200, Date.now() - lastCompilationStartTime)
+          catch exception
+            output = "#{exception}"
+          editors[index + 1].setValue output
+        , lastCompilationElapsedTime
+
+      # Fix the code editors’ handling of tab-indented code
+      editor.addKeyMap
+        'Tab': (cm) ->
+          if cm.somethingSelected()
+            cm.indentSelection 'add'
+          else if /^\t/m.test cm.getValue()
+            # If any lines start with a tab, treat this as tab-indented code
+            cm.execCommand 'insertTab'
+          else
+            cm.execCommand 'insertSoftTab'
+        'Shift-Tab': (cm) ->
+          cm.indentSelection 'subtract'
+        'Enter': (cm) ->
+          cm.options.indentWithTabs = /^\t/m.test cm.getValue()
+          cm.execCommand 'newlineAndIndent'
+
+  # Handle the code example buttons
+  $('[data-action="run-code-example"]').click ->
+    run = $(@).data 'run'
+    index = $("##{$(@).data('example')}-js").data 'index'
+    js = editors[index].getValue()
+    js = "#{js}\nalert(#{unescape run});" unless run is yes
+    eval js
+
+
+  # Try CoffeeScript
+  toggleTry = (checkLocalStorage = no) ->
+    if checkLocalStorage and window.localStorage?
+      try
+        coffee = window.localStorage.getItem 'tryCoffeeScriptCode'
+        if coffee?
+          editors[0].setValue coffee
+      catch exception
+    $('#try, #try-link').toggleClass 'active'
+  closeTry = ->
+    $('#try, #try-link').removeClass 'active'
+
+  $('[data-toggle="try"]').click toggleTry
+  $('[data-close="try"]').click closeTry
+
+
+  # Configure the initial state
+  if window.location.hash?
+    if window.location.hash is '#try'
+      toggleTry yes
+    else if window.location.hash.indexOf('#try') is 0
+      editors[0].setValue decodeURIComponent window.location.hash[5..]
+      toggleTry()
+    else
+      initializeScrollspyFromHash window.location.hash
+      # Initializing the code editors might’ve thrown off our vertical scroll position
+      document.getElementById(window.location.hash.slice(1)).scrollIntoView()

documentation/v2/docs.css

@@ -0,0 +1,416 @@
+/* Adapted from https://v4-alpha.getbootstrap.com/examples/dashboard/dashboard.css and http://v4-alpha.getbootstrap.com/examples/offcanvas/offcanvas.css */
+
+html,
+body {
+  /* Prevent scroll on narrow devices */
+  overflow-x: hidden;
+}
+body {
+  /* Required for Scrollspy */
+  position: relative;
+  /* Push below header bar */
+  margin-top: 3.5rem;
+}
+
+svg {
+  width: auto;
+  height: 100%;
+}
+
+a {
+  color: #1b5e20;
+  transition: 0.1s ease-in-out;
+}
+a:focus, a:hover, a:active {
+  color: #388e3c;
+  cursor: pointer;
+  text-decoration: none;
+}
+
+.bg-inverse {
+  background-color: #3e2723 !important;
+}
+
+.bg-ribbed-light {
+  background-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1 3"><path opacity=".03" fill="#000" d="M0 0h1v1H0z"/><path opacity=".005" fill="#000" d="M0 1h1v2H0z"/></svg>');
+  background-size: 1px 3px;
+}
+.bg-ribbed-dark {
+  background-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1 3"><path opacity=".2" fill="#000" d="M0 0h1v1H0z"/><path opacity=".15" fill="#000" d="M0 1h1v2H0z"/></svg>');
+  background-size: 1px 3px;
+}
+
+
+/*
+ * Header
+ */
+.navbar-fixed-top {
+  height: 3.5rem;
+}
+
+.navbar-brand {
+  height: 2em;
+  margin-right: 2em;
+}
+
+.navbar-dark path {
+  fill: #fff;
+}
+
+.navbar-nav {
+  font-family: Lato;
+  font-weight: 400;
+  font-size: 1.1em;
+}
+
+.navbar-nav .nav-link {
+  padding-left: 0.6em;
+  padding-right: 0.6em;
+  border-radius: 0.4em;
+}
+.navbar-nav .nav-link:hover,
+.navbar-nav .nav-link:active,
+.navbar-nav .nav-link.active {
+  background-color: #4e342e;
+}
+
+/* Adapted from https://codepen.io/GeoffreyBooth/pen/QGzwYK */
+.navbar-menu-button,
+.navbar-menu-button:focus {
+  float: right;
+  width: 2.3em;
+  padding: 0;
+  margin-top: 0.25em;
+  background: transparent;
+  border: 0;
+  outline: 0;
+}
+.menu-button {
+  width: 2em;
+  height: 1.5em;
+  position: relative;
+  transform: rotate(0deg);
+  transition: .25s ease-in-out;
+  cursor: pointer;
+}
+.menu-button span {
+  display: block;
+  position: absolute;
+  height: 4px;
+  width: 100%;
+  background: #efebe9;
+  border-radius: 4px;
+  opacity: 1;
+  left: 0;
+  transform: rotate(0deg);
+  transition: .25s ease-in-out;
+}
+.menu-button span:nth-child(1) {
+  top: 0;
+}
+.menu-button span:nth-child(2),
+.menu-button span:nth-child(3) {
+  top: 0.7em;
+}
+.menu-button span:nth-child(4) {
+  top: 1.4em;
+}
+.menu-button.active span:nth-child(1) {
+  top: 0.7em;
+  width: 0%;
+  left: 50%;
+}
+.menu-button.active span:nth-child(2) {
+  transform: rotate(45deg);
+}
+.menu-button.active span:nth-child(3) {
+  transform: rotate(-45deg);
+}
+.menu-button.active span:nth-child(4) {
+  top: 0.7em;
+  width: 0%;
+  left: 50%;
+}
+
+
+/*
+ * Sidebar
+ */
+
+.sidebar {
+  background-color: #efebe9;
+  border-right: 1px solid #efebe9;
+  top: 3.5rem;
+  bottom: 0;
+  left: 0;
+  z-index: 1000;
+  display: block;
+  padding: 0;
+}
+.sidebar .contents {
+  height: 100%;
+  /* Scrollable contents if viewport is shorter than content */
+  overflow-y: auto;
+  overflow-x: hidden;
+  font-family: 'Alegreya Sans';
+  font-weight: 400;
+  font-size: 1.2em;
+  line-height: 2;
+}
+@media screen and (max-width: 991px) {
+  .sidebar .contents {
+    position: fixed;
+    height: calc(100% - 3.5rem);
+    padding: 1em 1.6em;
+  }
+}
+@media screen and (min-width: 992px) {
+  .sidebar {
+    position: fixed;
+  }
+  .sidebar .contents {
+    padding: 1.3em;
+  }
+  .sidebar .contents::-webkit-scrollbar {
+    display: none;
+  }
+}
+
+.sidebar .nav-link.active,
+.sidebar .nav-link.active a:hover,
+.sidebar .nav-link.active a:focus {
+  font-weight: 800;
+}
+
+.nav .nav {
+  margin-left: 1em;
+  font-size: 0.9em;
+  line-height: 1.7;
+}
+
+
+/*
+ * Off Canvas
+ */
+@media screen and (max-width: 991px) {
+  .row-offcanvas {
+    position: relative;
+    transition: all .25s ease-in-out;
+  }
+  .row-offcanvas-left {
+    left: 0;
+  }
+  .sidebar-offcanvas {
+    position: absolute;
+    top: 0;
+  }
+}
+@media screen and (max-width: 767px) {
+  .row-offcanvas-left .sidebar-offcanvas {
+    left: -100%;
+  }
+  .row-offcanvas-left.active {
+    left: calc(100% + 30px)
+  }
+}
+@media screen and (min-width: 768px) and (max-width: 991px) {
+  .row-offcanvas-left .sidebar-offcanvas {
+    left: calc(-66.667% - 15px);
+    width: 66.667%;
+  }
+  .row-offcanvas-left.active {
+    left: calc(66.667% + 30px);
+  }
+  .row-offcanvas-left .sidebar-offcanvas .contents {
+    width: 66.667%;
+  }
+}
+
+
+/*
+ * Main content
+ */
+
+.main {
+  padding: 1.3em;
+}
+@media (min-width: 992px) {
+  .main {
+    padding-right: 2em;
+    padding-left: 2em;
+  }
+}
+
+.title-logo {
+  width: 30rem;
+  margin: 3rem auto;
+}
+.title-logo path {
+  fill: #2f2625;
+}
+
+.main p, .main li, .main td, .main th {
+  font-family: Lato;
+  font-size: 1.3rem;
+  font-weight: 300;
+}
+.main td {
+  vertical-align: top;
+  padding: 0.3em 0;
+}
+.main strong, .main th {
+  font-weight: 700;
+}
+.main a {
+  border-bottom: 2px solid transparent;
+  font-weight: 400;
+}
+.main a:focus, .main a:hover, .main a:active {
+  border-bottom: 2px solid rgba(56, 142, 60, 0.2);
+}
+.main blockquote {
+  font-size: 1.3rem;
+}
+.main blockquote pre {
+  background-color: #f8f3f0;
+  color: #2f2625;
+  border-radius: .3em;
+  padding: 0.4em 0.6em;
+}
+
+p, blockquote, table, .code-example {
+  margin-bottom: 1.3rem;
+}
+
+td code {
+  white-space: nowrap;
+}
+
+h2, h3 {
+  margin-top: 1.3em;
+  margin-bottom: 0.6em;
+  font-family: 'Alegreya Sans';
+}
+h2 {
+  font-weight: 800;
+}
+h3, h2 time {
+  font-weight: 400;
+}
+
+.main section {
+  /* Offset the anchor so that clicking on the sidebar links don’t hide the heading under the header bar */
+  padding-top: 2.3rem;
+  margin-top: -2.3rem;
+}
+
+code, button {
+  font-family: 'Roboto Mono';
+  font-weight: 400;
+}
+code {
+  background-color: #f8f3f0;
+  color: #2f2625;
+}
+
+
+/*
+ * Code examples
+ */
+
+textarea {
+  position: absolute;
+  left: -99999px; /* Hide off canvas, while still remaining visible */
+}
+
+.code-example {
+  background-color: #2f2625;
+  padding: 1em;
+  border-radius: 0.3em;
+  margin-bottom: 1em;
+}
+
+.javascript-output-column {
+  border-left: 1px solid rgba(255, 255, 255, 0.2);
+}
+
+.btn-primary {
+  background-color: #69f0ae;
+  color: #0b140f;
+  border-color: #53d88f;
+  transition: 0.2s ease-in-out;
+  min-width: 3.125rem;
+}
+.btn-primary:active, .btn-primary:focus, .btn-primary:hover, .btn-primary:active:hover, .btn-primary:active:focus {
+  background-color: #61fea8;
+  color: #060a08;
+  border-color: #4de486;
+  outline: 0;
+}
+
+.CodeMirror {
+  /* https://codemirror.net/demo/resize.html */
+  height: auto;
+  background: transparent;
+  font-family: 'Roboto Mono';
+  font-weight: 400;
+  line-height: 1.25;
+}
+.javascript-output-column .CodeMirror-cursor {
+  /* https://github.com/codemirror/CodeMirror/issues/2568 */
+  display: none;
+}
+
+/*
+ * Try CoffeeScript
+ */
+.try-coffeescript {
+  position: fixed;
+  height: calc(100% - 3.5rem);
+  top: 3.5rem;
+  left: 0;
+  right: 0;
+  opacity: 0;
+  transition: opacity 0.15s ease-in-out;
+}
+.try-coffeescript.active {
+  opacity: 1;
+  z-index: 1001;
+}
+
+.try-coffeescript .CodeMirror {
+  height: calc(100vh - 7rem);
+  cursor: text;
+}
+
+.try-coffeescript .code-column {
+  overflow: hidden;
+  background-color: #2f2625;
+  color: #2f2625;
+}
+
+@media screen and (max-width: 767px) {
+  .try-coffeescript .code-column {
+    height: calc(50vh - 0.5 * 3.5rem);
+  }
+}
+@media screen and (min-width: 768px) {
+  .try-coffeescript .code-column {
+    padding-bottom: 100%;
+    margin-bottom: -100%;
+  }
+}
+
+.try-coffeescript button svg {
+  height: 1em;
+  transform: scale(1.3) translateY(0.1em);
+  fill: #0b140f;
+}
+
+@media screen and (max-width: 767px) {
+  .try-coffeescript .try-buttons {
+    position: absolute;
+    bottom: 1em;
+    z-index: 1002;
+  }
+}

documentation/v2/navbar.html

@@ -0,0 +1,17 @@
+<nav class="navbar navbar-dark navbar-fixed-top bg-inverse bg-ribbed-dark">
+  <a class="navbar-brand" href="#" data-close="try"><%= include('documentation/images/logo.svg') %></a>
+  <nav class="nav navbar-nav float-xs-left hidden-md-down">
+    <a href="#try" id="try-link" class="nav-item nav-link" data-toggle="try">Try CoffeeScript</a>
+    <a href="#language" class="nav-item nav-link" data-close="try">Language Reference</a>
+    <a href="#resources" class="nav-item nav-link" data-close="try">Resources</a>
+    <a href="http://github.com/jashkenas/coffeescript/" class="nav-item nav-link" data-close="try">GitHub</a>
+  </nav>
+  <button type="button" class="navbar-menu-button hidden-lg-up" data-toggle="offcanvas" aria-label="Toggle sidebar">
+    <div class="menu-button">
+      <span></span>
+      <span></span>
+      <span></span>
+      <span></span>
+    </div>
+  </button>
+</nav>