Don't publish .DS_Store to npm

* Fix #5133: Document that braces are required for object shorthand.

* Changelog for 2.4.1

* Update output

.babelrc

@@ -0,0 +1,3 @@
+{
+  "presets": ["@babel/env"]
+}

.gitignore

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

.travis.yml

@@ -0,0 +1,20 @@
+language: node_js
+
+node_js:
+  - 6
+  - 8
+  - 10
+
+cache:
+  directories:
+    - node_modules
+
+script:
+  - node ./bin/cake build:except-parser
+  - node ./bin/cake build:parser
+  - node ./bin/cake build:full
+  - node ./bin/cake build:browser
+  - node ./bin/cake test
+  - node --harmony ./bin/cake test
+  - node ./bin/cake test:browser
+  - node ./bin/cake test:integrations

CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at maintainers@coffeescript.org. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

CONTRIBUTING.md

@@ -4,6 +4,11 @@
 
 * 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`.
+
+* To get started, read the guides in the wiki:
+	* [Hacking on the CoffeeScript Compiler](https://github.com/jashkenas/coffeescript/wiki/%5BHowTo%5D-Hacking-on-the-CoffeeScript-Compiler)
+	* [How parsing works](https://github.com/jashkenas/coffeescript/wiki/%5BHowTo%5D-How-parsing-works)
+	* [Update the docs](https://github.com/jashkenas/coffeescript/wiki/%5BHowTo%5D-Update-the-docs)

Cakefile

@@ -1,25 +1,27 @@
 fs                        = require 'fs'
+os                        = require 'os'
 path                      = require 'path'
 _                         = require 'underscore'
 { spawn, exec, execSync } = require 'child_process'
-CoffeeScript              = require './lib/coffee-script'
-helpers                   = require './lib/coffee-script/helpers'
+CoffeeScript              = require './lib/coffeescript'
+helpers                   = require './lib/coffeescript/helpers'
 
 # ANSI Terminal Colors.
-bold = red = green = reset = ''
+bold = red = green = yellow = reset = ''
 unless process.env.NODE_DISABLE_COLORS
-  bold  = '\x1B[0;1m'
-  red   = '\x1B[0;31m'
-  green = '\x1B[0;32m'
-  reset = '\x1B[0m'
+  bold   = '\x1B[0;1m'
+  red    = '\x1B[0;31m'
+  green  = '\x1B[0;32m'
+  yellow = '\x1B[0;33m'
+  reset  = '\x1B[0m'
 
 # Built file header.
 header = """
   /**
    * CoffeeScript Compiler v#{CoffeeScript.VERSION}
-   * http://coffeescript.org
+   * https://coffeescript.org
    *
-   * Copyright 2011, Jeremy Ashkenas
+   * Copyright 2011-#{new Date().getFullYear()}, Jeremy Ashkenas
    * Released under the MIT License
    */
 """
@@ -51,27 +53,39 @@ 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
 
+transpile = (code, options = {}) ->
+  options.minify =      process.env.MINIFY    isnt 'false'
+  options.transform =   process.env.TRANSFORM isnt 'false'
+  options.sourceType ?= 'script'
+  babel = require '@babel/core'
+  presets = []
+  # Exclude the `modules` plugin in order to not break the `}(this));`
+  # at the end of the `build:browser` code block.
+  presets.push ['@babel/env', {modules: no}] if options.transform
+  presets.push ['minify', {mangle: no, evaluate: no, removeUndefined: no}] if options.minify
+  babelOptions =
+    presets: presets
+    compact: not options.minify
+    comments: not options.minify
+    sourceType: options.sourceType
+  { code } = babel.transform code, babelOptions unless presets.length is 0
+  code
+
 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]
@@ -83,7 +97,7 @@ testBuiltCode = (watch = no) ->
 
 buildAndTest = (includingParser = yes, harmony = no) ->
   process.stdout.write '\x1Bc' # Clear terminal screen.
-  execSync 'git checkout lib/*', stdio: [0,1,2] # Reset the generated compiler.
+  execSync 'git checkout lib/*', stdio: 'inherit' # Reset the generated compiler.
 
   buildArgs = ['bin/cake']
   buildArgs.push if includingParser then 'build' else 'build:except-parser'
@@ -122,21 +136,26 @@ 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;
       })();
     """
+  # From here, we generate two outputs: a legacy script output for all browsers
+  # and a module output for browsers that support `<script type="module">`.
   code = """
+    var CoffeeScript = function() {
+      function require(path){ return require[path]; }
+      #{code}
+      return require['./browser'];
+    }();
+  """
+  scriptCode = transpile """
     (function(root) {
-      var CoffeeScript = function() {
-        function require(path){ return require[path]; }
-        #{code}
-        return require['./coffee-script'];
-      }();
+      #{code}
 
       if (typeof define === 'function' && define.amd) {
         define(function() { return CoffeeScript; });
@@ -145,15 +164,25 @@ 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'
-      ]
-  outputFolder = "docs/v#{majorVersion}/browser-compiler"
-  fs.mkdirSync outputFolder unless fs.existsSync outputFolder
-  fs.writeFileSync "#{outputFolder}/coffee-script.js", header + '\n' + code
+  moduleCode = transpile """
+    #{code}
+
+    export default CoffeeScript;
+    const { VERSION, compile, eval: evaluate, load, run, runScripts } = CoffeeScript;
+    export { VERSION, compile, evaluate as eval, load, run, runScripts };
+  """, {sourceType: 'module'}
+  outputFolders = [
+    "docs/v#{majorVersion}/browser-compiler-legacy"
+    "docs/v#{majorVersion}/browser-compiler-modern"
+    "lib/coffeescript-browser-compiler-legacy"
+    "lib/coffeescript-browser-compiler-modern"
+  ]
+  for outputFolder in outputFolders
+    fs.mkdirSync outputFolder unless fs.existsSync outputFolder
+    fs.writeFileSync "#{outputFolder}/coffeescript.js", """
+      #{header}
+      #{if outputFolder.includes('legacy') then scriptCode else moduleCode}
+    """
 
 task 'build:browser:full', 'merge the built scripts into a single file for use in a browser, and test it', ->
   invoke 'build:browser'
@@ -169,34 +198,37 @@ task 'build:watch:harmony', 'watch and continually rebuild the CoffeeScript comp
 
 buildDocs = (watch = no) ->
   # Constants
-  indexFile = 'documentation/index.html'
-  versionedSourceFolder = "documentation/v#{majorVersion}"
-  sectionsSourceFolder = 'documentation/sections'
-  examplesSourceFolder = 'documentation/examples'
-  outputFolder = "docs/v#{majorVersion}"
+  indexFile             = 'documentation/site/index.html'
+  siteSourceFolder      = "documentation/site"
+  sectionsSourceFolder  = 'documentation/sections'
+  changelogSourceFolder = 'documentation/sections/changelog'
+  examplesSourceFolder  = 'documentation/examples'
+  outputFolder          = "docs/v#{majorVersion}"
 
   # Helpers
   releaseHeader = (date, version, prevVersion) ->
-    monthNames = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
-
-    formatDate = (date) ->
-      date.replace /^(\d\d\d\d)-(\d\d)-(\d\d)$/, (match, $1, $2, $3) ->
-        "#{monthNames[$2 - 1]} #{+$3}, #{$1}"
-
     """
-      <div class="anchor" id="#{version}"></div>
-      <h2 class="header">
-        #{prevVersion and "<a href=\"https://github.com/jashkenas/coffeescript/compare/#{prevVersion}...#{version}\">#{version}</a>" or version}
-        <span class="timestamp"> &mdash; <time datetime="#{date}">#{formatDate date}</time></span>
-      </h2>
+      <h3>#{prevVersion and "<a href=\"https://github.com/jashkenas/coffeescript/compare/#{prevVersion}...#{version}\">#{version}</a>" or version}
+        <span class="timestamp"> &mdash; <time datetime="#{date}">#{date}</time></span>
+      </h3>
     """
 
-  codeFor = require "./documentation/v#{majorVersion}/code.coffee"
+  codeFor = require "./documentation/site/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
@@ -209,7 +241,7 @@ buildDocs = (watch = no) ->
         "<blockquote class=\"uneditable-code-block\">#{defaultFence.apply @, arguments}</blockquote>"
 
     (file, bookmark) ->
-      md = fs.readFileSync "#{sectionsSourceFolder}/#{file}.md", 'utf-8'
+      md = fs.readFileSync "#{sectionsSourceFolder}/#{file.replace /\//g, path.sep}.md", 'utf-8'
       md = md.replace /<%= releaseHeader %>/g, releaseHeader
       md = md.replace /<%= majorVersion %>/g, majorVersion
       md = md.replace /<%= fullVersion %>/g, CoffeeScript.VERSION
@@ -218,9 +250,17 @@ buildDocs = (watch = no) ->
         codeFor: codeFor()
         releaseHeader: releaseHeader
 
+  includeScript = ->
+    (file) ->
+      file = "#{siteSourceFolder}/#{file}" unless '/' in file
+      code = fs.readFileSync file, 'utf-8'
+      code = CoffeeScript.compile code
+      code = transpile code
+      code
+
   include = ->
     (file) ->
-      file = "#{versionedSourceFolder}/#{file}" if file.indexOf('/') is -1
+      file = "#{siteSourceFolder}/#{file}" unless '/' in file
       output = fs.readFileSync file, 'utf-8'
       if /\.html$/.test(file)
         render = _.template output
@@ -231,6 +271,7 @@ buildDocs = (watch = no) ->
           htmlFor: htmlFor()
           codeFor: codeFor()
           include: include()
+          includeScript: includeScript()
       output
 
   # Task
@@ -245,7 +286,7 @@ buildDocs = (watch = no) ->
   catch exception
 
   if watch
-    for target in [indexFile, versionedSourceFolder, examplesSourceFolder, sectionsSourceFolder]
+    for target in [indexFile, siteSourceFolder, examplesSourceFolder, sectionsSourceFolder, changelogSourceFolder]
       fs.watch target, interval: 200, renderIndex
     log 'watching...', green
 
@@ -258,9 +299,9 @@ task 'doc:site:watch', 'watch and continually rebuild the documentation for the
 
 buildDocTests = (watch = no) ->
   # Constants
-  testFile = 'documentation/test.html'
+  testFile          = 'documentation/site/test.html'
   testsSourceFolder = 'test'
-  outputFolder = "docs/v#{majorVersion}"
+  outputFolder      = "docs/v#{majorVersion}"
 
   # Included in test.html
   testHelpers = fs.readFileSync('test/support/helpers.coffee', 'utf-8').replace /exports\./g, '@'
@@ -308,7 +349,7 @@ task 'doc:test:watch', 'watch and continually rebuild the browser-based tests',
 
 buildAnnotatedSource = (watch = no) ->
   do generateAnnotatedSource = ->
-    exec "node_modules/docco/bin/docco src/*.*coffee --output docs/v#{majorVersion}/annotated-source", (err) -> throw err if err
+    exec "cd src && ../node_modules/docco/bin/docco *.*coffee --output ../docs/v#{majorVersion}/annotated-source", (err) -> throw err if err
     log 'generated', green, "annotated source in docs/v#{majorVersion}/annotated-source/"
 
   if watch
@@ -323,15 +364,19 @@ task 'doc:source:watch', 'watch and continually rebuild the annotated source doc
 
 
 task 'release', 'build and test the CoffeeScript source, and build the documentation', ->
-  invoke 'build:full'
-  invoke 'build:browser:full'
-  invoke 'doc:site'
-  invoke 'doc:test'
-  invoke 'doc:source'
+  execSync '''
+    cake build:full
+    cake build:browser
+    cake test:browser
+    cake test:integrations
+    cake doc:site
+    cake doc:test
+    cake doc:source''', stdio: 'inherit'
+
 
 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,30 +398,49 @@ 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
+
+  # These are attached to `global` so that they’re accessible from within
+  # `test/async.coffee`, which has an async-capable version of
+  # `global.test`.
+  global.currentFile = null
+  global.passedTests = 0
+  global.failures    = []
 
   global[name] = func for name, func of require 'assert'
 
   # Convenience aliases.
   global.CoffeeScript = CoffeeScript
-  global.Repl = require './lib/coffee-script/repl'
+  global.Repl   = require './lib/coffeescript/repl'
+  global.bold   = bold
+  global.red    = red
+  global.green  = green
+  global.yellow = yellow
+  global.reset  = reset
+
+  asyncTests = []
+  onFail = (description, fn, err) ->
+    failures.push
+      filename: global.currentFile
+      error: err
+      description: description
+      source: fn.toString() if fn.toString?
 
   # Our test helper function for delimiting different test cases.
   global.test = (description, fn) ->
     try
       fn.test = {description, currentFile}
-      fn.call(fn)
-      ++passedTests
-    catch e
-      failures.push
-        filename: currentFile
-        error: e
-        description: description if description?
-        source: fn.toString() if fn.toString?
+      result = fn.call(fn)
+      if result instanceof Promise # An async test.
+        asyncTests.push result
+        result.then ->
+          passedTests++
+        .catch (err) ->
+          onFail description, fn, err
+      else
+        passedTests++
+    catch err
+      onFail description, fn, err
 
   helpers.extend global, require './test/support/helpers'
 
@@ -395,9 +459,22 @@ runTests = (CoffeeScript) ->
       console.log "  #{source}" if source
     return
 
-  # Run every test in the `test` folder, recording failures.
-  files = fs.readdirSync 'test'
+  # Run every test in the `test` folder, recording failures, except for files
+  # we’re skipping because the features to be tested are unsupported in the
+  # current Node runtime.
+  testFilesToSkip = []
+  skipUnless = (featureDetect, filenames) ->
+    unless (try new Function featureDetect)
+      testFilesToSkip = testFilesToSkip.concat filenames
+  skipUnless 'async () => {}', ['async.coffee', 'async_iterators.coffee']
+  skipUnless 'async function* generator() { yield 42; }', ['async_iterators.coffee']
+  skipUnless 'var a = 2 ** 2; a **= 3', ['exponentiation.coffee']
+  skipUnless 'var {...a} = {}', ['object_rest_spread.coffee']
+  skipUnless '/foo.bar/s.test("foo\tbar")', ['regex_dotall.coffee']
+  files = fs.readdirSync('test').filter (filename) ->
+    filename not in testFilesToSkip
 
+  startTime = Date.now()
   for file in files when helpers.isCoffee file
     literate = helpers.isLiterate file
     currentFile = filename = path.join 'test', file
@@ -406,18 +483,56 @@ runTests = (CoffeeScript) ->
       CoffeeScript.run code.toString(), {filename, literate}
     catch error
       failures.push {filename, error}
-  return !failures.length
+
+  Promise.all(asyncTests).then ->
+    Promise.reject() if failures.length isnt 0
 
 
 task 'test', 'run the CoffeeScript language test suite', ->
-  testResults = runTests CoffeeScript
-  process.exit 1 unless testResults
+  runTests(CoffeeScript).catch -> process.exit 1
 
 
 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 "lib/coffeescript-browser-compiler-legacy/coffeescript.js", 'utf-8'
   result = {}
   global.testingBrowser = yes
   (-> eval source).call result
-  testResults = runTests result.CoffeeScript
-  process.exit 1 unless testResults
+  runTests(CoffeeScript).catch -> process.exit 1
+
+
+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()
+  webpack = require 'webpack'
+  webpack {
+    entry: './'
+    optimization:
+      # Webpack’s minification causes the CoffeeScript module to fail some tests.
+      minimize: off
+    output:
+      path: tmpdir
+      filename: 'coffeescript.js'
+      library: 'CoffeeScript'
+      libraryTarget: 'commonjs2'
+  }, (err, stats) ->
+    if err or stats.hasErrors()
+      if err
+        console.error err.stack or err
+        console.error err.details if err.details
+      if stats.hasErrors()
+        console.error error for error in stats.compilation.errors
+      if stats.hasWarnings()
+        console.warn warning for warning in stats.compilation.warnings
+      process.exit 1
+
+    builtCompiler = path.join tmpdir, 'coffeescript.js'
+    CoffeeScript = require builtCompiler
+    global.testingBrowser = yes
+    testResults = runTests CoffeeScript
+    fs.unlinkSync builtCompiler
+    process.exit 1 unless testResults

ISSUE_TEMPLATE.md

@@ -0,0 +1,62 @@
+<!---
+Thanks for filing an issue 😄! Before you submit, please read the following:
+
+Search open/closed issues before submitting since someone might have asked the same thing before!
+Our issues history stretches back to 2009, so the odds are good that your topic has come up.
+
+If you have a support request or question please use Stack Overflow:
+https://stackoverflow.com/questions/tagged/coffeescript
+
+Issues on GitHub are only related to problems of the CoffeeScript compiler itself and we cannot answer
+support questions here.
+-->
+
+Choose one: is this a bug report or feature request?
+
+<!---
+Provide a general summary of the issue in the title above.
+
+For bugs, please also preface your title with “Bug:”. For feature requests, please preface your title
+with “Proposal:”. Once your issue is reviewed, a maintainer will edit the title to refer to the part
+of the codebase most relevant to the issue (if applicable).
+
+If your request is that CoffeeScript support a new feature recently arrived to JavaScript, please note
+that we generally only add features that have reached Stage 4 in the specification (in other words,
+the syntax is finalized and the feature is approved to be part of the next ES release). You can still
+open an issue, but it will likely be tagged with “[Awaiting Stage 4]” until the relevant ES feature is
+approved for release. See https://coffeescript.org/#contributing
+
+There are also a handful of JavaScript features that CoffeeScript intentionally does not support.
+Please do not open issues regarding these. They’re listed in https://coffeescript.org/#unsupported
+-->
+
+### Input Code
+<!--- If you're describing a bug, please let us know which sample code reproduces your problem. -->
+<!--- If you have link from https://coffeescript.org/#try or a standalone repo please include that! -->
+
+```coffee
+your (code) => here
+```
+
+### Expected Behavior
+<!--- If you’re describing a bug, tell us what should happen. -->
+<!--- If you’re suggesting a change/improvement, tell us how it should work. -->
+
+### Current Behavior
+<!--- If describing a bug, tell us what happens instead of the expected behavior. -->
+<!--- If suggesting a change/improvement, explain the difference from current behavior. -->
+
+### Possible Solution
+<!--- Not obligatory, but suggest a fix/reason for the bug, -->
+<!--- or ideas how to implement the addition or change. -->
+
+### Context
+<!--- How has this issue affected you? What are you trying to accomplish? -->
+<!--- Providing context helps us come up with a solution that is most useful in the real world. -->
+
+### Environment
+<!--- For bugs, please let us know what version of CoffeeScript you’re running: `coffee -v`. -->
+<!--- If you think it might be relevant, please also let us know your version of Node. -->
+
+* CoffeeScript version:
+* Node.js version:

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009-2017 Jeremy Ashkenas
+Copyright (c) 2009-2018 Jeremy Ashkenas
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,22 @@
+<!--
+Before making a PR please make sure to read our contributing guidelines:
+https://coffeescript.org/#contributing
+
+For issue references: Add a comma-separated list of a
+[closing word](https://help.github.com/articles/closing-issues-via-commit-messages/) followed by
+the ticket number fixed by the PR. It should be underlined in the preview if done correctly.
+
+All new features require tests. All but the most trivial bug fixes should also have new or updated tests.
+
+Ensure that all new code you add to the compiler can be run in the minimum version of Node listed in
+`package.json`. New tests can require newer Node runtimes, but you may need to ensure that such tests
+only run in supported runtimes; see `Cakefile` for examples of how to filter out certain tests in
+runtimes that don’t support them.
+
+Please follow the code style of the rest of the CoffeeScript codebase. Write comments in complete
+sentences using Markdown, as the comments become the [annotated source](https://coffeescript.org/#annotated-source).
+For tests proving a bug is fixed, please mention the issue number in the test description (see examples
+in the codebase).
+
+Describe your changes below in as much detail as possible.
+-->

README.md

@@ -1,22 +1,29 @@
-            {
-         }   }   {
-        {   {  }  }
-         }   }{  {
-        {  }{  }  }                    _____       __  __
-       { }{ }{  { }                   / ____|     / _|/ _|
-     .- { { }  { }} -.               | |     ___ | |_| |_ ___  ___
-    (  { } { } { } }  )              | |    / _ \|  _|  _/ _ \/ _ \
-    |`-..________ ..-'|              | |___| (_) | | | ||  __/  __/
-    |                 |               \_____\___/|_| |_| \___|\___|
-    |                 ;--.
-    |                (__  \            _____           _       _
-    |                 | )  )          / ____|         (_)     | |
-    |                 |/  /          | (___   ___ _ __ _ _ __ | |_
-    |                 (  /            \___ \ / __| '__| | '_ \| __|
-    |                 |/              ____) | (__| |  | | |_) | |_
-    |                 |              |_____/ \___|_|  |_| .__/ \__|
-     `-.._________..-'                                  | |
-                                                        |_|
+```
+      @@@@@@@                @@@@  @@@@@
+     @@@@@@@@@@              @@@   @@@                                           {
+    @@@@     @@              @@@   @@@                                        }   }   {
+   @@@@          @@@@@@@    @@@   @@@     @@@@@@    @@@@@@                   {   {  }  }
+  @@@@          @@@   @@  @@@@@  @@@@@@  @@@   @@  @@@@  @@                   }   }{  {
+  @@@@         @@@@   @@   @@@    @@@   @@@   @@@ @@@   @@@                  {  }{  }  }
+  @@@@        @@@@    @@   @@@    @@@   @@@@@@@@  @@@@@@@@                  { }{ }{  { }
+  @@@@@       @@@@   @@    @@@    @@@   @@@       @@@                     {  { } { } { }  }
+   @@@@@@@@@@ @@@@@@@@    @@@    @@@    @@@@@@@@  @@@@@@@@                 { }   { }   { }
+      @@@@@               @@@    @@@      @@@@@     @@@@@           @@@@@@   { }   { }    @@@@@@@
+                         @@@    @@@                                 @@@@@@@@@@@@@@@@@@@@@@@@@@@@
+      @@@@@@            @@@    @@@                                @@ @@@@@@@@@@@@@@@@@@@@@@@@@@
+   @@@@    @@          @@@   @@@@                                @@   @@@@@@@@@@@@@@@@@@@@@@@@
+   @@@@   @@@                       @@                  @@@@     @@@   @@@@@@@@@@@@@@@@@@@@@
+   @@@@@          @@@@@   @@  @@   @@@     @@@@@@@     @@@@@      @@@    @@@@@@@@@@@@@@@@@@
+     @@@@@      @@@  @@@ @@@@@@@@         @@@@  @@@@  @@@@@@@       @@@   @@@@@@@@@@@@@@@@
+       @@@@@   @@@       @@@@     @@@@    @@@    @@@   @@@                 @@@@@@@@@@@@@@
+ @@@@@  @@@@  @@@@      @@@@      @@@@   @@@@   @@@@  @@@@
+@@@     @@@@  @@@       @@@@     @@@@    @@@    @@@@  @@@@
+@@@     @@@@  @@@@     @@@@      @@@@   @@@@   @@@@  @@@@
+ @@@@@@@@@     @@@@@@  @@@@       @@@@  @@@@@@@@@    @@@@
+                                       @@@          @@@@
+                                      @@@
+                                      @@@
+```
 
 CoffeeScript is a little language that compiles into JavaScript.
 
@@ -25,11 +32,13 @@ CoffeeScript is a little language that compiles into JavaScript.
 Once you have Node.js installed:
 
 ```shell
+# Install locally for a project:
+npm install --save-dev coffeescript
+
+# Install globally to execute .coffee files anywhere:
 npm install --global coffeescript
 ```
 
-Leave off the `--global` if you don’t wish to install globally.
-
 ## Getting Started
 
 Execute a script:
@@ -44,7 +53,7 @@ Compile a script:
 coffee -c /path/to/script.coffee
 ```
 
-For documentation, usage, and examples, see: http://coffeescript.org/
+For documentation, usage, and examples, see: https://coffeescript.org/
 
 To suggest a feature or report a bug: https://github.com/jashkenas/coffeescript/issues
 
@@ -52,6 +61,6 @@ If you’d like to chat, drop by #coffeescript on Freenode IRC.
 
 The source repository: https://github.com/jashkenas/coffeescript.git
 
-Changelog: http://coffeescript.org/#changelog
+Changelog: https://coffeescript.org/#changelog
 
 Our lovely and talented contributors are listed here: https://github.com/jashkenas/coffeescript/contributors

appveyor.yml

@@ -0,0 +1,29 @@
+environment:
+  matrix:
+    - nodejs_version: '6'
+    - nodejs_version: '8'
+    - nodejs_version: '10'
+    - nodejs_version: '' # Installs latest.
+
+install:
+  - ps: Install-Product node $env:nodejs_version
+  - node --version
+  - npm --version
+  - npm install
+
+cache:
+  - node_modules
+
+test_script:
+  - node ./bin/cake build:except-parser
+  - node ./bin/cake build:parser
+  - node ./bin/cake build:full
+  - node ./bin/cake build:browser
+  - node ./bin/cake test
+  - node --harmony ./bin/cake test
+  - node ./bin/cake test:browser
+  - node ./bin/cake test:integrations
+
+build: off
+
+version: "{build}"

bin/cake

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
 
+try {
+  new Function('var {a} = {a: 1}')();
+} catch (error) {
+  console.error('Your JavaScript runtime does not support some features used by the cake command. Please use Node 6 or later.');
+  process.exit(1);
+}
+
 var path = require('path');
 var fs   = require('fs');
 
@@ -7,7 +14,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

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
 
+try {
+  new Function('var {a} = {a: 1}')();
+} catch (error) {
+  console.error('Your JavaScript runtime does not support some features used by the coffee command. Please use Node 6 or later.');
+  process.exit(1);
+}
+
 var path = require('path');
 var fs   = require('fs');
 
@@ -7,7 +14,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/CNAME

@@ -1 +1 @@
-coffeescript.org
+coffeescript.org

docs/annotated-source

@@ -0,0 +1 @@
+v2/annotated-source

docs/announcing-coffeescript-2

@@ -0,0 +1 @@
+v2/announcing-coffeescript-2

docs/browser-compiler

@@ -0,0 +1 @@
+v2/browser-compiler-legacy

docs/browser-compiler-legacy

@@ -0,0 +1 @@
+v2/browser-compiler-legacy

docs/browser-compiler-modern

@@ -0,0 +1 @@
+v2/browser-compiler-modern

docs/index.html

@@ -1 +1 @@
-v1/index.html
+v2/index.html

docs/manifest.json

@@ -1,5 +1,6 @@
 {
-	"name": "",
+	"name": "CoffeeScript",
+	"description": "Unfancy JavaScript",
 	"icons": [
 		{
 			"src": "\/android-chrome-192x192.png",

docs/test.html

@@ -0,0 +1 @@
+v2/test.html

docs/v1/index.html

@@ -594,18 +594,18 @@ pre .xml .cdata {
       Annotated Source
     </div>
     <div class="contents menu">
-      <a href="/v1/annotated-source/grammar.html">Grammar Rules — src/grammar</a>
-      <a href="/v1/annotated-source/lexer.html">Lexing Tokens — src/lexer</a>
-      <a href="/v1/annotated-source/rewriter.html">The Rewriter — src/rewriter</a>
-      <a href="/v1/annotated-source/nodes.html">The Syntax Tree — src/nodes</a>
-      <a href="/v1/annotated-source/scope.html">Lexical Scope — src/scope</a>
-      <a href="/v1/annotated-source/helpers.html">Helpers &amp; Utility Functions — src/helpers</a>
-      <a href="/v1/annotated-source/coffee-script.html">The CoffeeScript Module — src/coffee-script</a>
-      <a href="/v1/annotated-source/cake.html">Cake &amp; Cakefiles — src/cake</a>
-      <a href="/v1/annotated-source/command.html">“coffee” Command-Line Utility — src/command</a>
-      <a href="/v1/annotated-source/optparse.html">Option Parsing — src/optparse</a>
-      <a href="/v1/annotated-source/repl.html">Interactive REPL — src/repl</a>
-      <a href="/v1/annotated-source/sourcemap.html">Source Maps — src/sourcemap</a>
+      <a href="annotated-source/grammar.html">Grammar Rules — src/grammar</a>
+      <a href="annotated-source/lexer.html">Lexing Tokens — src/lexer</a>
+      <a href="annotated-source/rewriter.html">The Rewriter — src/rewriter</a>
+      <a href="annotated-source/nodes.html">The Syntax Tree — src/nodes</a>
+      <a href="annotated-source/scope.html">Lexical Scope — src/scope</a>
+      <a href="annotated-source/helpers.html">Helpers &amp; Utility Functions — src/helpers</a>
+      <a href="annotated-source/coffee-script.html">The CoffeeScript Module — src/coffee-script</a>
+      <a href="annotated-source/cake.html">Cake &amp; Cakefiles — src/cake</a>
+      <a href="annotated-source/command.html">“coffee” Command-Line Utility — src/command</a>
+      <a href="annotated-source/optparse.html">Option Parsing — src/optparse</a>
+      <a href="annotated-source/repl.html">Interactive REPL — src/repl</a>
+      <a href="annotated-source/sourcemap.html">Source Maps — src/sourcemap</a>
     </div>
   </div>
 </div>
@@ -615,10 +615,10 @@ pre .xml .cdata {
     <p><strong>CoffeeScript is a little language that compiles into JavaScript.</strong> Underneath that awkward Java-esque patina, JavaScript has always had a gorgeous heart. CoffeeScript is an attempt to expose the good parts of JavaScript in a simple way.</p>
 <p>The golden rule of CoffeeScript is: <em>“It’s just JavaScript”</em>. The code compiles one-to-one into the equivalent JS, and there is no interpretation at runtime. You can use any existing JavaScript library seamlessly from CoffeeScript (and vice-versa). The compiled output is readable, pretty-printed, and tends to run as fast or faster than the equivalent handwritten JavaScript.</p>
 <p>The CoffeeScript compiler goes to great lengths to generate output JavaScript that runs in every JavaScript runtime, but there are exceptions. Use <a href="#generator-functions">generator functions</a>, <a href="#generator-iteration"><code>for…from</code></a>, or <a href="#tagged-template-literals">tagged template literals</a> only if you know that your <a href="http://kangax.github.io/compat-table/es6/">target runtimes can support them</a>. If you use <a href="#modules">modules</a>, you will need to <a href="#modules-note">use an additional tool to resolve them</a>.</p>
-<p><strong>Latest Version:</strong> <a href="https://github.com/jashkenas/coffeescript/tarball/1.12.7">1.12.7</a></p>
+<p><strong>Latest 1.x Version:</strong> <a href="https://github.com/jashkenas/coffeescript/tarball/1.12.7">1.12.7</a></p>
 <blockquote class="uneditable-code-block"><pre><code class="language-bash">npm install -g coffeescript
 </code></pre>
-</blockquote><p><strong>CoffeeScript 2 is coming!</strong> It adds support for <a href="/v2/#classes">ES2015 classes</a>, <a href="/v2/#fat-arrow"><code>async</code>/<code>await</code></a>, <a href="/v2/#jsx">JSX</a>, <span class="nowrap"><a href="/v2/#splats">object rest/spread syntax</a></span>, and JavaScript generated using ES2015+ syntax. <a href="/v2/">Learn more</a>.</p>
+</blockquote><p><strong>Upgrade to CoffeeScript 2!</strong> It adds support for <a href="/#classes">ES2015 classes</a>, <a href="/#async-functions"><code>async</code>/<code>await</code></a>, <a href="/#jsx">JSX</a>, <span class="nowrap"><a href="/#splats">object rest/spread syntax</a></span>, and <a href="/#coffeescript-2">JavaScript generated using modern syntax</a>. <a href="/announcing-coffeescript-2/">Learn more</a>.</p>
 
     <h2>Overview</h2>
 <p><em>CoffeeScript on the left, compiled JavaScript output on the right.</em></p>
@@ -741,7 +741,7 @@ cubes = (function() {
 ;alert(cubes);">run: cubes</div><br class='clear' /></div>
   <span class="bookmark" id="installation"></span>
     <h2>Installation</h2>
-<p>The command-line version of <code>coffee</code> is available as a <a href="https://nodejs.org/">Node.js</a> utility. The <a href="/v1/browser-compiler/coffee-script.js">core compiler</a> however, does not depend on Node, and can be run in any JavaScript environment, or in the browser (see <a href="#try">Try CoffeeScript</a>).</p>
+<p>The command-line version of <code>coffee</code> is available as a <a href="https://nodejs.org/">Node.js</a> utility. The <a href="browser-compiler/coffee-script.js">core compiler</a> however, does not depend on Node, and can be run in any JavaScript environment, or in the browser (see <a href="#try">Try CoffeeScript</a>).</p>
 <p>To install, first make sure you have a working copy of the latest stable version of <a href="https://nodejs.org/">Node.js</a>. You can then install CoffeeScript globally with <a href="https://www.npmjs.com/">npm</a>:</p>
 <blockquote class="uneditable-code-block"><pre><code class="language-bash">npm install --global coffeescript
 </code></pre>
@@ -2441,7 +2441,7 @@ task(<span class="string">'build:parser'</span>, <span class="string">'rebuild t
   dir = options.output || <span class="string">'lib'</span>;
   <span class="keyword">return</span> fs.writeFile(dir + <span class="string">"/parser.js"</span>, code);
 });
-</code></pre><script>window.example1 = "fs = require 'fs'\n\noption '-o', '--output [DIR]', 'directory for compiled code'\n\ntask 'build:parser', 'rebuild the Jison parser', (options) ->\n  require 'jison'\n  code = require('./lib/grammar').parser.generate()\n  dir  = options.output or 'lib'\n  fs.writeFile \"#{dir}/parser.js\", code\n"</script><div class='minibutton load' onclick='javascript: loadConsole(example1);'>load</div><br class='clear' /></div><p>If you need to invoke one task before another — for example, running <code>build</code> before <code>test</code>, you can use the <code>invoke</code> function: <code>invoke 'build'</code>. Cake tasks are a minimal way to expose your CoffeeScript functions to the command line, so <a href="/v1/annotated-source/cake.html">don’t expect any fanciness built-in</a>. If you need dependencies, or async callbacks, it’s best to put them in your code itself — not the cake task.</p>
+</code></pre><script>window.example1 = "fs = require 'fs'\n\noption '-o', '--output [DIR]', 'directory for compiled code'\n\ntask 'build:parser', 'rebuild the Jison parser', (options) ->\n  require 'jison'\n  code = require('./lib/grammar').parser.generate()\n  dir  = options.output or 'lib'\n  fs.writeFile \"#{dir}/parser.js\", code\n"</script><div class='minibutton load' onclick='javascript: loadConsole(example1);'>load</div><br class='clear' /></div><p>If you need to invoke one task before another — for example, running <code>build</code> before <code>test</code>, you can use the <code>invoke</code> function: <code>invoke 'build'</code>. Cake tasks are a minimal way to expose your CoffeeScript functions to the command line, so <a href="annotated-source/cake.html">don’t expect any fanciness built-in</a>. If you need dependencies, or async callbacks, it’s best to put them in your code itself — not the cake task.</p>
 
   <span class="bookmark" id="source-maps"></span>
     <h2>Source Maps</h2>
@@ -2450,7 +2450,7 @@ task(<span class="string">'build:parser'</span>, <span class="string">'rebuild t
 
   <span class="bookmark" id="scripts"></span>
     <h2>“text/coffeescript” Script Tags</h2>
-<p>While it’s not recommended for serious use, CoffeeScripts may be included directly within the browser using <code>&lt;script type=&quot;text/coffeescript&quot;&gt;</code> tags. The source includes a compressed and minified version of the compiler (<a href="/v1/browser-compiler/coffee-script.js">Download current version here, 51k when gzipped</a>) as <code>v1/browser-compiler/coffee-script.js</code>. Include this file on a page with inline CoffeeScript tags, and it will compile and evaluate them in order.</p>
+<p>While it’s not recommended for serious use, CoffeeScripts may be included directly within the browser using <code>&lt;script type=&quot;text/coffeescript&quot;&gt;</code> tags. The source includes a compressed and minified version of the compiler (<a href="browser-compiler/coffee-script.js">Download current version here, 51k when gzipped</a>) as <code>docs/v1/browser-compiler/coffee-script.js</code>. Include this file on a page with inline CoffeeScript tags, and it will compile and evaluate them in order.</p>
 <p>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 <code>CoffeeScript.compile()</code> so you can pop open Firebug and try compiling some strings.</p>
 <p>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 <code>window</code> object.</p>
 
@@ -2501,7 +2501,7 @@ Use <code>bin/coffee</code> to test your changes,<br>
 <p><code>git checkout lib &amp;&amp; bin/cake build:full</code> is a good command to run when you’re working on the core language. It’ll refresh the <code>lib</code> 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.</p>
 </li>
 <li>
-<p><a href="/v1/test.html">Browser Tests</a><br>
+<p><a href="test.html">Browser Tests</a><br>
 Run CoffeeScript’s test suite in your current browser.</p>
 </li>
 <li>
@@ -2592,7 +2592,7 @@ The CoffeeScript logo is available in SVG for use in presentations.</p>
 <li>The browser compiler can once again be built unminified via <code>MINIFY=false cake build:browser</code>.</li>
 <li>The error-prone patched version of <code>Error.prepareStackTrace</code> has been removed.</li>
 <li>Command completion in the REPL (pressing tab to get suggestions) has been fixed for Node 6.9.1+.</li>
-<li>The <a href="/v1/test.html">browser-based tests</a> now include all the tests as the Node-based version.</li>
+<li>The <a href="test.html">browser-based tests</a> now include all the tests as the Node-based version.</li>
 </ul>
 <div class="anchor" id="1.12.1"></div>
 <h2 class="header">
@@ -2611,7 +2611,7 @@ The CoffeeScript logo is available in SVG for use in presentations.</p>
 <li>CoffeeScript now provides a <a href="#generator-iteration"><code>for…from</code></a> syntax for outputting ES2015 <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of"><code>for…of</code></a>. (Sorry they couldn’t match, but we came up with <code>for…of</code> first for something else.) This allows iterating over generators or any other iterable object. Note that using <code>for…from</code> in your code makes you responsible for ensuring that either your runtime supports <code>for…of</code> or that you transpile the output JavaScript further to a version your target runtime(s) support.</li>
 <li>Triple backticks (<code>```​</code>) allow the creation of embedded JavaScript blocks where escaping single backticks is not required, which should improve interoperability with ES2015 template literals and with Markdown.</li>
 <li>Within single-backtick embedded JavaScript, backticks can now be escaped via <code>\`​</code>.</li>
-<li>The browser tests now run in the browser again, and are accessible <a href="/v1/test.html">here</a> if you would like to test your browser.</li>
+<li>The browser tests now run in the browser again, and are accessible <a href="test.html">here</a> if you would like to test your browser.</li>
 <li>CoffeeScript-only keywords in ES2015 <code>import</code>s and <code>export</code>s are now ignored.</li>
 <li>The compiler now throws an error on trying to export an anonymous class.</li>
 <li>Bugfixes related to tokens and location data, for better source maps and improved compatibility with downstream tools.</li>
@@ -3016,7 +3016,7 @@ used to parse as <code>result = (i for i in list)</code> by default … it now p
   <a href="https://github.com/jashkenas/coffeescript/compare/0.5.1...0.5.2">0.5.2</a>
   <span class="timestamp"> &mdash; <time datetime="2010-02-25">February 25, 2010</time></span>
 </h2><p>Added a compressed version of the compiler for inclusion in web pages as
-<code>/v1/browser-compiler/coffee-script.js</code>. It’ll automatically run any script tags with type <code>text/coffeescript</code> for you. Added a <code>--stdio</code> option to the <code>coffee</code> command, for piped-in compiles.</p>
+<code>browser-compiler/coffee-script.js</code>. It’ll automatically run any script tags with type <code>text/coffeescript</code> for you. Added a <code>--stdio</code> option to the <code>coffee</code> command, for piped-in compiles.</p>
 <div class="anchor" id="0.5.1"></div>
 <h2 class="header">
   <a href="https://github.com/jashkenas/coffeescript/compare/0.5.0...0.5.1">0.5.1</a>
@@ -3222,7 +3222,7 @@ compileSource()
 </script>
 
 <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
-<script src="v1/browser-compiler/coffee-script.js"></script>
+<script src="browser-compiler/coffee-script.js"></script>
 
 </body>
 </html>

docs/v2/annotated-source/browser.html

@@ -124,7 +124,7 @@ 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>
-compile = CoffeeScript.compile</pre></div></div>
+{ compile } = CoffeeScript</pre></div></div>
             
         </li>
         
@@ -135,13 +135,17 @@ compile = CoffeeScript.compile</pre></div></div>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-2">&#182;</a>
               </div>
-              <p>Use standard JavaScript <code>eval</code> to eval code.</p>
+              <p>Use <code>window.eval</code> to evaluate code, rather than just <code>eval</code>, to run the
+script in a clean global scope rather than inheriting the scope of the
+CoffeeScript compiler. (So that <code>cake test:browser</code> also works in Node,
+use either <code>window.eval</code> or <code>global.eval</code> as appropriate).</p>
 
             </div>
             
             <div class="content"><div class='highlight'><pre>CoffeeScript.eval = <span class="hljs-function"><span class="hljs-params">(code, options = {})</span> -&gt;</span>
   options.bare ?= <span class="hljs-literal">on</span>
-  eval compile code, options</pre></div></div>
+  globalRoot = <span class="hljs-keyword">if</span> <span class="hljs-built_in">window</span>? <span class="hljs-keyword">then</span> <span class="hljs-built_in">window</span> <span class="hljs-keyword">else</span> <span class="hljs-built_in">global</span>
+  globalRoot[<span class="hljs-string">'eval'</span>] compile code, options</pre></div></div>
             
         </li>
         
@@ -258,7 +262,7 @@ This happens on page load.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">runScripts</span> = -&gt;</span>
+            <div class="content"><div class='highlight'><pre>CoffeeScript.runScripts = <span class="hljs-function">-&gt;</span>
   scripts = <span class="hljs-built_in">window</span>.<span class="hljs-built_in">document</span>.getElementsByTagName <span class="hljs-string">'script'</span>
   coffeetypes = [<span class="hljs-string">'text/coffeescript'</span>, <span class="hljs-string">'text/literate-coffeescript'</span>]
   coffees = (s <span class="hljs-keyword">for</span> s <span class="hljs-keyword">in</span> scripts <span class="hljs-keyword">when</span> s.type <span class="hljs-keyword">in</span> coffeetypes)
@@ -317,14 +321,19 @@ only one CoffeeScript script block to parse.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-10">&#182;</a>
               </div>
-              <p>Listen for window load, both in decent browsers and in IE.</p>
+              <p>Listen for window load, both in decent browsers and in IE.
+Only attach this event handler on startup for the
+non-ES module version of the browser compiler, to preserve
+backward compatibility while letting the ES module version
+be importable without side effects.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre><span class="hljs-keyword">if</span> <span class="hljs-built_in">window</span>.addEventListener
-  <span class="hljs-built_in">window</span>.addEventListener <span class="hljs-string">'DOMContentLoaded'</span>, runScripts, <span class="hljs-literal">no</span>
-<span class="hljs-keyword">else</span>
-  <span class="hljs-built_in">window</span>.attachEvent <span class="hljs-string">'onload'</span>, runScripts</pre></div></div>
+            <div class="content"><div class='highlight'><pre><span class="hljs-keyword">if</span> <span class="hljs-keyword">this</span> <span class="hljs-keyword">is</span> <span class="hljs-built_in">window</span>
+  <span class="hljs-keyword">if</span> <span class="hljs-built_in">window</span>.addEventListener
+    <span class="hljs-built_in">window</span>.addEventListener <span class="hljs-string">'DOMContentLoaded'</span>, CoffeeScript.runScripts, <span class="hljs-literal">no</span>
+  <span class="hljs-keyword">else</span>
+    <span class="hljs-built_in">window</span>.attachEvent <span class="hljs-string">'onload'</span>, CoffeeScript.runScripts</pre></div></div>
             
         </li>
         

docs/v2/annotated-source/coffeescript.html

@@ -159,7 +159,7 @@ evaluated from <code>lib/coffeescript</code>.</p>
             
             <div class="content"><div class='highlight'><pre>exports.VERSION = packageJson.version
 
-exports.FILE_EXTENSIONS = [<span class="hljs-string">'.coffee'</span>, <span class="hljs-string">'.litcoffee'</span>, <span class="hljs-string">'.coffee.md'</span>]</pre></div></div>
+exports.FILE_EXTENSIONS = FILE_EXTENSIONS = [<span class="hljs-string">'.coffee'</span>, <span class="hljs-string">'.litcoffee'</span>, <span class="hljs-string">'.coffee.md'</span>]</pre></div></div>
             
         </li>
         
@@ -252,7 +252,7 @@ didn’t create a source map (faster) but something went wrong and we need
 a stack trace. Assuming that most of the time, code isn’t throwing
 exceptions, it’s probably more efficient to compile twice only when we
 need a stack trace, rather than always generating a source map even when
-it’s not likely to be used. Save in form of <code>filename</code>: <code>(source)</code></p>
+it’s not likely to be used. Save in form of <code>filename</code>: [<code>(source)</code>]</p>
 
             </div>
             
@@ -267,7 +267,7 @@ it’s not likely to be used. Save in form of <code>filename</code>: <code>(sour
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-9">&#182;</a>
               </div>
-              <p>Also save source maps if generated, in form of <code>filename</code>: <code>(source map)</code>.</p>
+              <p>Also save source maps if generated, in form of <code>(source)</code>: [<code>(source map)</code>].</p>
 
             </div>
             
@@ -282,6 +282,32 @@ it’s not likely to be used. Save in form of <code>filename</code>: <code>(sour
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-10">&#182;</a>
               </div>
+              <p>This is exported to enable an external module to implement caching of
+compilation results. When the compiled js source is loaded from cache, the
+original coffee code should be added with this method in order to enable the
+Error.prepareStackTrace below to correctly adjust the stack trace for the
+corresponding file (the source map will be generated on demand).</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>exports.registerCompiled = registerCompiled = <span class="hljs-function"><span class="hljs-params">(filename, source, sourcemap)</span> -&gt;</span>
+
+  sources[filename] ?= []
+  sources[filename].push source
+
+  <span class="hljs-keyword">if</span> sourcemap?
+    sourceMaps[filename] ?= []
+    sourceMaps[filename].push sourcemap</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-11">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-11">&#182;</a>
+              </div>
               <p>Compile CoffeeScript code to JavaScript, using the Coffee/Jison compiler.</p>
 <p>If <code>options.sourceMap</code> is specified, then <code>options.filename</code> must also be
 specified. All options that can be passed to <code>SourceMap#generate</code> may also
@@ -293,18 +319,31 @@ doing programmatic lookups.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>exports.compile = compile = withPrettyErrors (code, options) -&gt;
-  {merge, extend} = helpers
-  options = extend {}, options</pre></div></div>
+            <div class="content"><div class='highlight'><pre>exports.compile = compile = withPrettyErrors (code, options = {}) -&gt;</pre></div></div>
             
         </li>
         
         
-        <li id="section-11">
+        <li id="section-12">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-11">&#182;</a>
+                <a class="pilcrow" href="#section-12">&#182;</a>
+              </div>
+              <p>Clone <code>options</code>, to avoid mutating the <code>options</code> object passed in.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>  options = Object.assign {}, options</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-13">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-13">&#182;</a>
               </div>
               <p>Always generate a source map if no filename is passed in, since without a
 a filename we have no way to retrieve this source later in the event that
@@ -315,7 +354,8 @@ we need to recompile it to get a source map for <code>prepareStackTrace</code>.<
             <div class="content"><div class='highlight'><pre>  generateSourceMap = options.sourceMap <span class="hljs-keyword">or</span> options.inlineMap <span class="hljs-keyword">or</span> <span class="hljs-keyword">not</span> options.filename?
   filename = options.filename <span class="hljs-keyword">or</span> <span class="hljs-string">'&lt;anonymous&gt;'</span>
 
-  sources[filename] = code
+  checkShebangLine filename, code
+
   map = <span class="hljs-keyword">new</span> SourceMap <span class="hljs-keyword">if</span> generateSourceMap
 
   tokens = lexer.tokenize code, options</pre></div></div>
@@ -323,11 +363,11 @@ we need to recompile it to get a source map for <code>prepareStackTrace</code>.<
         </li>
         
         
-        <li id="section-12">
+        <li id="section-14">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-12">&#182;</a>
+                <a class="pilcrow" href="#section-14">&#182;</a>
               </div>
               <p>Pass a list of referenced variables, so that generated variables won’t get
 the same name.</p>
@@ -341,11 +381,11 @@ the same name.</p>
         </li>
         
         
-        <li id="section-13">
+        <li id="section-15">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-13">&#182;</a>
+                <a class="pilcrow" href="#section-15">&#182;</a>
               </div>
               <p>Check for import or export; if found, force bare mode.</p>
 
@@ -369,11 +409,11 @@ the same name.</p>
         </li>
         
         
-        <li id="section-14">
+        <li id="section-16">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-14">&#182;</a>
+                <a class="pilcrow" href="#section-16">&#182;</a>
               </div>
               <p>Update the sourcemap with data from each fragment.</p>
 
@@ -384,11 +424,11 @@ the same name.</p>
         </li>
         
         
-        <li id="section-15">
+        <li id="section-17">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-15">&#182;</a>
+                <a class="pilcrow" href="#section-17">&#182;</a>
               </div>
               <p>Do not include empty, whitespace, or semicolon-only fragments.</p>
 
@@ -409,11 +449,11 @@ the same name.</p>
         </li>
         
         
-        <li id="section-16">
+        <li id="section-18">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-16">&#182;</a>
+                <a class="pilcrow" href="#section-18">&#182;</a>
               </div>
               <p>Copy the code from each fragment into the final JavaScript.</p>
 
@@ -426,8 +466,67 @@ the same name.</p>
     js = <span class="hljs-string">"// <span class="hljs-subst">#{header}</span>\n<span class="hljs-subst">#{js}</span>"</span>
 
   <span class="hljs-keyword">if</span> generateSourceMap
-    v3SourceMap = map.generate(options, code)
-    sourceMaps[filename] = map
+    v3SourceMap = map.generate options, code
+
+  <span class="hljs-keyword">if</span> options.transpile
+    <span class="hljs-keyword">if</span> <span class="hljs-keyword">typeof</span> options.transpile <span class="hljs-keyword">isnt</span> <span class="hljs-string">'object'</span></pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-19">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-19">&#182;</a>
+              </div>
+              <p>This only happens if run via the Node API and <code>transpile</code> is set to
+something other than an object.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>      <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> Error <span class="hljs-string">'The transpile option must be given an object with options to pass to Babel'</span></pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-20">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-20">&#182;</a>
+              </div>
+              <p>Get the reference to Babel that we have been passed if this compiler
+is run via the CLI or Node API.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>    transpiler = options.transpile.transpile
+    <span class="hljs-keyword">delete</span> options.transpile.transpile
+
+    transpilerOptions = Object.assign {}, options.transpile</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-21">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-21">&#182;</a>
+              </div>
+              <p>See <a href="https://github.com/babel/babel/issues/827#issuecomment-77573107">https://github.com/babel/babel/issues/827#issuecomment-77573107</a>:
+Babel can take a v3 source map object as input in <code>inputSourceMap</code>
+and it will return an <em>updated</em> v3 source map object in its output.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>    <span class="hljs-keyword">if</span> v3SourceMap <span class="hljs-keyword">and</span> <span class="hljs-keyword">not</span> transpilerOptions.inputSourceMap?
+      transpilerOptions.inputSourceMap = v3SourceMap
+    transpilerOutput = transpiler js, transpilerOptions
+    js = transpilerOutput.code
+    <span class="hljs-keyword">if</span> v3SourceMap <span class="hljs-keyword">and</span> transpilerOutput.map
+      v3SourceMap = transpilerOutput.map
 
   <span class="hljs-keyword">if</span> options.inlineMap
     encoded = base64encode JSON.stringify v3SourceMap
@@ -435,6 +534,8 @@ the same name.</p>
     sourceURL = <span class="hljs-string">"//# sourceURL=<span class="hljs-subst">#{options.filename ? <span class="hljs-string">'coffeescript'</span>}</span>"</span>
     js = <span class="hljs-string">"<span class="hljs-subst">#{js}</span>\n<span class="hljs-subst">#{sourceMapDataURI}</span>\n<span class="hljs-subst">#{sourceURL}</span>"</span>
 
+  registerCompiled filename, code, map
+
   <span class="hljs-keyword">if</span> options.sourceMap
     {
       js
@@ -447,11 +548,11 @@ the same name.</p>
         </li>
         
         
-        <li id="section-17">
+        <li id="section-22">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-17">&#182;</a>
+                <a class="pilcrow" href="#section-22">&#182;</a>
               </div>
               <p>Tokenize a string of CoffeeScript code, and return the array of tokens.</p>
 
@@ -463,11 +564,11 @@ the same name.</p>
         </li>
         
         
-        <li id="section-18">
+        <li id="section-23">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-18">&#182;</a>
+                <a class="pilcrow" href="#section-23">&#182;</a>
               </div>
               <p>Parse a string of CoffeeScript code or an array of lexed tokens, and
 return the AST. You can then compile it by calling <code>.compile()</code> on the root,
@@ -484,11 +585,11 @@ or traverse it by using <code>.traverseChildren()</code> with a callback.</p>
         </li>
         
         
-        <li id="section-19">
+        <li id="section-24">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-19">&#182;</a>
+                <a class="pilcrow" href="#section-24">&#182;</a>
               </div>
               <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
@@ -504,11 +605,11 @@ environment.</p>
         </li>
         
         
-        <li id="section-20">
+        <li id="section-25">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-20">&#182;</a>
+                <a class="pilcrow" href="#section-25">&#182;</a>
               </div>
               <p>Instantiate a Lexer for our use here.</p>
 
@@ -519,15 +620,15 @@ environment.</p>
         </li>
         
         
-        <li id="section-21">
+        <li id="section-26">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-21">&#182;</a>
+                <a class="pilcrow" href="#section-26">&#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
-directly as a “Jison lexer”.</p>
+directly as a “Jison lexer.”</p>
 
             </div>
             
@@ -540,22 +641,20 @@ directly as a “Jison lexer”.</p>
       @yylineno = @yylloc.first_line
     <span class="hljs-keyword">else</span>
       tag = <span class="hljs-string">''</span>
-
     tag
   setInput: <span class="hljs-function"><span class="hljs-params">(tokens)</span> -&gt;</span>
     parser.tokens = tokens
     @pos = <span class="hljs-number">0</span>
-  upcomingInput: <span class="hljs-function">-&gt;</span>
-    <span class="hljs-string">""</span></pre></div></div>
+  upcomingInput: <span class="hljs-function">-&gt;</span> <span class="hljs-string">''</span></pre></div></div>
             
         </li>
         
         
-        <li id="section-22">
+        <li id="section-27">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-22">&#182;</a>
+                <a class="pilcrow" href="#section-27">&#182;</a>
               </div>
               <p>Make all the AST nodes visible to the parser.</p>
 
@@ -566,11 +665,11 @@ directly as a “Jison lexer”.</p>
         </li>
         
         
-        <li id="section-23">
+        <li id="section-28">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-23">&#182;</a>
+                <a class="pilcrow" href="#section-28">&#182;</a>
               </div>
               <p>Override Jison’s default error handling function.</p>
 
@@ -581,11 +680,11 @@ directly as a “Jison lexer”.</p>
         </li>
         
         
-        <li id="section-24">
+        <li id="section-29">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-24">&#182;</a>
+                <a class="pilcrow" href="#section-29">&#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
@@ -609,11 +708,11 @@ the error is caused by a generated token which might refer to its origin.</p>
         </li>
         
         
-        <li id="section-25">
+        <li id="section-30">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-25">&#182;</a>
+                <a class="pilcrow" href="#section-30">&#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>
@@ -627,11 +726,11 @@ from the lexer.</p>
         </li>
         
         
-        <li id="section-26">
+        <li id="section-31">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-26">&#182;</a>
+                <a class="pilcrow" href="#section-31">&#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>
@@ -659,11 +758,11 @@ Modified to handle sourceMap</p>
         </li>
         
         
-        <li id="section-27">
+        <li id="section-32">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-27">&#182;</a>
+                <a class="pilcrow" href="#section-32">&#182;</a>
               </div>
               <p>Check for a sourceMap position</p>
 
@@ -701,29 +800,87 @@ Modified to handle sourceMap</p>
   <span class="hljs-keyword">else</span>
     fileLocation
 <span class="hljs-function">
-<span class="hljs-title">getSourceMap</span> = <span class="hljs-params">(filename)</span> -&gt;</span>
-  <span class="hljs-keyword">if</span> sourceMaps[filename]?
-    sourceMaps[filename]</pre></div></div>
+<span class="hljs-title">getSourceMap</span> = <span class="hljs-params">(filename, line, column)</span> -&gt;</span></pre></div></div>
             
         </li>
         
         
-        <li id="section-28">
+        <li id="section-33">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-28">&#182;</a>
+                <a class="pilcrow" href="#section-33">&#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
-filename of the script file.</p>
+              <p>Skip files that we didn’t compile, like Node system files that appear in
+the stack trace, as they never have source maps.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>  <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> sourceMaps[<span class="hljs-string">'&lt;anonymous&gt;'</span>]?
-    sourceMaps[<span class="hljs-string">'&lt;anonymous&gt;'</span>]
-  <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> sources[filename]?
-    answer = compile sources[filename],
+            <div class="content"><div class='highlight'><pre>  <span class="hljs-keyword">return</span> <span class="hljs-literal">null</span> <span class="hljs-keyword">unless</span> filename <span class="hljs-keyword">is</span> <span class="hljs-string">'&lt;anonymous&gt;'</span> <span class="hljs-keyword">or</span> filename.slice(filename.lastIndexOf(<span class="hljs-string">'.'</span>)) <span class="hljs-keyword">in</span> FILE_EXTENSIONS
+
+  <span class="hljs-keyword">if</span> filename <span class="hljs-keyword">isnt</span> <span class="hljs-string">'&lt;anonymous&gt;'</span> <span class="hljs-keyword">and</span> sourceMaps[filename]?
+    <span class="hljs-keyword">return</span> sourceMaps[filename][sourceMaps[filename].length - <span class="hljs-number">1</span>]</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-34">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-34">&#182;</a>
+              </div>
+              <p>CoffeeScript compiled in a browser or via <code>CoffeeScript.compile</code> or <code>.run</code>
+may get compiled with <code>options.filename</code> that’s missing, which becomes
+<code>&lt;anonymous&gt;</code>; but the runtime might request the stack trace with the
+filename of the script file. See if we have a source map cached under
+<code>&lt;anonymous&gt;</code> that matches the error.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>  <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> sourceMaps[<span class="hljs-string">'&lt;anonymous&gt;'</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>Work backwards from the most recent anonymous source maps, until we find
+one that works. This isn’t foolproof; there is a chance that multiple
+source maps will have line/column pairs that match. But we have no other
+way to match them. <code>frame.getFunction().toString()</code> doesn’t always work,
+and it’s not foolproof either.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>    <span class="hljs-keyword">for</span> map <span class="hljs-keyword">in</span> sourceMaps[<span class="hljs-string">'&lt;anonymous&gt;'</span>] <span class="hljs-keyword">by</span> <span class="hljs-number">-1</span>
+      sourceLocation = map.sourceLocation [line - <span class="hljs-number">1</span>, column - <span class="hljs-number">1</span>]
+      <span class="hljs-keyword">return</span> map <span class="hljs-keyword">if</span> sourceLocation?[<span class="hljs-number">0</span>]? <span class="hljs-keyword">and</span> sourceLocation[<span class="hljs-number">1</span>]?</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-36">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-36">&#182;</a>
+              </div>
+              <p>If all else fails, recompile this source to get a source map. We need the
+previous section (for <code>&lt;anonymous&gt;</code>) despite this option, because after it
+gets compiled we will still need to look it up from
+<code>sourceMaps[&#39;&lt;anonymous&gt;&#39;]</code> in order to find and return it. That’s why we
+start searching from the end in the previous block, because most of the
+time the source map we want is the last one.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>  <span class="hljs-keyword">if</span> sources[filename]?
+    answer = compile sources[filename][sources[filename].length - <span class="hljs-number">1</span>],
       filename: filename
       sourceMap: <span class="hljs-literal">yes</span>
       literate: helpers.isLiterate filename
@@ -734,11 +891,11 @@ filename of the script file.</p>
         </li>
         
         
-        <li id="section-29">
+        <li id="section-37">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-29">&#182;</a>
+                <a class="pilcrow" href="#section-37">&#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
@@ -749,7 +906,7 @@ positions.</p>
             
             <div class="content"><div class='highlight'><pre>Error.prepareStackTrace = <span class="hljs-function"><span class="hljs-params">(err, stack)</span> -&gt;</span>
 <span class="hljs-function">  <span class="hljs-title">getSourceMapping</span> = <span class="hljs-params">(filename, line, column)</span> -&gt;</span>
-    sourceMap = getSourceMap filename
+    sourceMap = getSourceMap filename, line, column
     answer = sourceMap.sourceLocation [line - <span class="hljs-number">1</span>, column - <span class="hljs-number">1</span>] <span class="hljs-keyword">if</span> sourceMap?
     <span class="hljs-keyword">if</span> answer? <span class="hljs-keyword">then</span> [answer[<span class="hljs-number">0</span>] + <span class="hljs-number">1</span>, answer[<span class="hljs-number">1</span>] + <span class="hljs-number">1</span>] <span class="hljs-keyword">else</span> <span class="hljs-literal">null</span>
 
@@ -757,7 +914,20 @@ positions.</p>
     <span class="hljs-keyword">break</span> <span class="hljs-keyword">if</span> frame.getFunction() <span class="hljs-keyword">is</span> exports.run
     <span class="hljs-string">"    at <span class="hljs-subst">#{formatSourcePosition frame, getSourceMapping}</span>"</span>
 
-  <span class="hljs-string">"<span class="hljs-subst">#{err.toString()}</span>\n<span class="hljs-subst">#{frames.join <span class="hljs-string">'\n'</span>}</span>\n"</span></pre></div></div>
+  <span class="hljs-string">"<span class="hljs-subst">#{err.toString()}</span>\n<span class="hljs-subst">#{frames.join <span class="hljs-string">'\n'</span>}</span>\n"</span>
+<span class="hljs-function">
+<span class="hljs-title">checkShebangLine</span> = <span class="hljs-params">(file, input)</span> -&gt;</span>
+  firstLine = input.split(<span class="hljs-regexp">/$/m</span>)[<span class="hljs-number">0</span>]
+  rest = firstLine?.match(<span class="hljs-regexp">/^#!\s*([^\s]+\s*)(.*)/</span>)
+  args = rest?[<span class="hljs-number">2</span>]?.split(<span class="hljs-regexp">/\s/</span>).filter (s) -&gt; s <span class="hljs-keyword">isnt</span> <span class="hljs-string">''</span>
+  <span class="hljs-keyword">if</span> args?.length &gt; <span class="hljs-number">1</span>
+    <span class="hljs-built_in">console</span>.error <span class="hljs-string">'''
+      The script to be run begins with a shebang line with more than one
+      argument. This script will fail on platforms such as Linux which only
+      allow a single argument.
+    '''</span>
+    <span class="hljs-built_in">console</span>.error <span class="hljs-string">"The shebang line was: '<span class="hljs-subst">#{firstLine}</span>' in file '<span class="hljs-subst">#{file}</span>'"</span>
+    <span class="hljs-built_in">console</span>.error <span class="hljs-string">"The arguments were: <span class="hljs-subst">#{JSON.stringify args}</span>"</span></pre></div></div>
             
         </li>
         

docs/v2/annotated-source/command.html

@@ -180,7 +180,7 @@ useWinPathSep  = path.sep <span class="hljs-keyword">is</span> <span class="hljs
             </div>
             
             <div class="content"><div class='highlight'><pre>BANNER = <span class="hljs-string">'''
-  Usage: coffee [options] path/to/script.coffee -- [args]
+  Usage: coffee [options] path/to/script.coffee [args]
 
   If called without options, `coffee` will run your script.
 '''</span></pre></div></div>
@@ -199,25 +199,26 @@ useWinPathSep  = path.sep <span class="hljs-keyword">is</span> <span class="hljs
             </div>
             
             <div class="content"><div class='highlight'><pre>SWITCHES = [
-  [<span class="hljs-string">'-b'</span>, <span class="hljs-string">'--bare'</span>,            <span class="hljs-string">'compile without a top-level function wrapper'</span>]
-  [<span class="hljs-string">'-c'</span>, <span class="hljs-string">'--compile'</span>,         <span class="hljs-string">'compile to JavaScript and save as .js files'</span>]
-  [<span class="hljs-string">'-e'</span>, <span class="hljs-string">'--eval'</span>,            <span class="hljs-string">'pass a string from the command line as input'</span>]
-  [<span class="hljs-string">'-h'</span>, <span class="hljs-string">'--help'</span>,            <span class="hljs-string">'display this help message'</span>]
-  [<span class="hljs-string">'-i'</span>, <span class="hljs-string">'--interactive'</span>,     <span class="hljs-string">'run an interactive CoffeeScript REPL'</span>]
-  [<span class="hljs-string">'-j'</span>, <span class="hljs-string">'--join [FILE]'</span>,     <span class="hljs-string">'concatenate the source CoffeeScript before compiling'</span>]
-  [<span class="hljs-string">'-m'</span>, <span class="hljs-string">'--map'</span>,             <span class="hljs-string">'generate source map and save as .js.map files'</span>]
-  [<span class="hljs-string">'-M'</span>, <span class="hljs-string">'--inline-map'</span>,      <span class="hljs-string">'generate source map and include it directly in output'</span>]
-  [<span class="hljs-string">'-n'</span>, <span class="hljs-string">'--nodes'</span>,           <span class="hljs-string">'print out the parse tree that the parser produces'</span>]
-  [      <span class="hljs-string">'--nodejs [ARGS]'</span>,   <span class="hljs-string">'pass options directly to the "node" binary'</span>]
-  [      <span class="hljs-string">'--no-header'</span>,       <span class="hljs-string">'suppress the "Generated by" header'</span>]
-  [<span class="hljs-string">'-o'</span>, <span class="hljs-string">'--output [DIR]'</span>,    <span class="hljs-string">'set the output directory for compiled JavaScript'</span>]
-  [<span class="hljs-string">'-p'</span>, <span class="hljs-string">'--print'</span>,           <span class="hljs-string">'print out the compiled JavaScript'</span>]
+  [<span class="hljs-string">'-b'</span>, <span class="hljs-string">'--bare'</span>,              <span class="hljs-string">'compile without a top-level function wrapper'</span>]
+  [<span class="hljs-string">'-c'</span>, <span class="hljs-string">'--compile'</span>,           <span class="hljs-string">'compile to JavaScript and save as .js files'</span>]
+  [<span class="hljs-string">'-e'</span>, <span class="hljs-string">'--eval'</span>,              <span class="hljs-string">'pass a string from the command line as input'</span>]
+  [<span class="hljs-string">'-h'</span>, <span class="hljs-string">'--help'</span>,              <span class="hljs-string">'display this help message'</span>]
+  [<span class="hljs-string">'-i'</span>, <span class="hljs-string">'--interactive'</span>,       <span class="hljs-string">'run an interactive CoffeeScript REPL'</span>]
+  [<span class="hljs-string">'-j'</span>, <span class="hljs-string">'--join [FILE]'</span>,       <span class="hljs-string">'concatenate the source CoffeeScript before compiling'</span>]
+  [<span class="hljs-string">'-m'</span>, <span class="hljs-string">'--map'</span>,               <span class="hljs-string">'generate source map and save as .js.map files'</span>]
+  [<span class="hljs-string">'-M'</span>, <span class="hljs-string">'--inline-map'</span>,        <span class="hljs-string">'generate source map and include it directly in output'</span>]
+  [<span class="hljs-string">'-n'</span>, <span class="hljs-string">'--nodes'</span>,             <span class="hljs-string">'print out the parse tree that the parser produces'</span>]
+  [      <span class="hljs-string">'--nodejs [ARGS]'</span>,     <span class="hljs-string">'pass options directly to the "node" binary'</span>]
+  [      <span class="hljs-string">'--no-header'</span>,         <span class="hljs-string">'suppress the "Generated by" header'</span>]
+  [<span class="hljs-string">'-o'</span>, <span class="hljs-string">'--output [PATH]'</span>,     <span class="hljs-string">'set the output path or path/filename for compiled JavaScript'</span>]
+  [<span class="hljs-string">'-p'</span>, <span class="hljs-string">'--print'</span>,             <span class="hljs-string">'print out the compiled JavaScript'</span>]
   [<span class="hljs-string">'-r'</span>, <span class="hljs-string">'--require [MODULE*]'</span>, <span class="hljs-string">'require the given module before eval or REPL'</span>]
-  [<span class="hljs-string">'-s'</span>, <span class="hljs-string">'--stdio'</span>,           <span class="hljs-string">'listen for and compile scripts over stdio'</span>]
-  [<span class="hljs-string">'-l'</span>, <span class="hljs-string">'--literate'</span>,        <span class="hljs-string">'treat stdio as literate style coffeescript'</span>]
-  [<span class="hljs-string">'-t'</span>, <span class="hljs-string">'--tokens'</span>,          <span class="hljs-string">'print out the tokens that the lexer/rewriter produce'</span>]
-  [<span class="hljs-string">'-v'</span>, <span class="hljs-string">'--version'</span>,         <span class="hljs-string">'display the version number'</span>]
-  [<span class="hljs-string">'-w'</span>, <span class="hljs-string">'--watch'</span>,           <span class="hljs-string">'watch scripts for changes and rerun commands'</span>]
+  [<span class="hljs-string">'-s'</span>, <span class="hljs-string">'--stdio'</span>,             <span class="hljs-string">'listen for and compile scripts over stdio'</span>]
+  [<span class="hljs-string">'-l'</span>, <span class="hljs-string">'--literate'</span>,          <span class="hljs-string">'treat stdio as literate style coffeescript'</span>]
+  [<span class="hljs-string">'-t'</span>, <span class="hljs-string">'--transpile'</span>,         <span class="hljs-string">'pipe generated JavaScript through Babel'</span>]
+  [      <span class="hljs-string">'--tokens'</span>,            <span class="hljs-string">'print out the tokens that the lexer/rewriter produce'</span>]
+  [<span class="hljs-string">'-v'</span>, <span class="hljs-string">'--version'</span>,           <span class="hljs-string">'display the version number'</span>]
+  [<span class="hljs-string">'-w'</span>, <span class="hljs-string">'--watch'</span>,             <span class="hljs-string">'watch scripts for changes and rerun commands'</span>]
 ]</pre></div></div>
             
         </li>
@@ -260,7 +261,21 @@ Many flags cause us to divert before compiling anything. Flags passed after
             
             <div class="content"><div class='highlight'><pre>exports.run = <span class="hljs-function">-&gt;</span>
   optionParser = buildCSOptionParser()
-  parseOptions()</pre></div></div>
+  <span class="hljs-keyword">try</span> parseOptions()
+  <span class="hljs-keyword">catch</span> err
+    <span class="hljs-built_in">console</span>.error <span class="hljs-string">"option parsing error: <span class="hljs-subst">#{err.message}</span>"</span>
+    process.exit <span class="hljs-number">1</span>
+
+  <span class="hljs-keyword">if</span> (<span class="hljs-keyword">not</span> opts.doubleDashed) <span class="hljs-keyword">and</span> (opts.arguments[<span class="hljs-number">1</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'--'</span>)
+    printWarn <span class="hljs-string">'''
+      coffee was invoked with '--' as the second positional argument, which is
+      now deprecated. To pass '--' as an argument to a script to run, put an
+      additional '--' before the path to your script.
+
+      '--' will be removed from the argument list.
+    '''</span>
+    printWarn <span class="hljs-string">"The positional arguments were: <span class="hljs-subst">#{JSON.stringify opts.arguments}</span>"</span>
+    opts.arguments = [opts.arguments[<span class="hljs-number">0</span>]].concat opts.arguments[<span class="hljs-number">2.</span>.]</pre></div></div>
             
         </li>
         
@@ -280,6 +295,7 @@ Many flags cause us to divert before compiling anything. Flags passed after
             <div class="content"><div class='highlight'><pre>  replCliOpts = useGlobal: <span class="hljs-literal">yes</span>
   opts.prelude = makePrelude opts.<span class="hljs-built_in">require</span>       <span class="hljs-keyword">if</span> opts.<span class="hljs-built_in">require</span>
   replCliOpts.prelude = opts.prelude
+  replCliOpts.transpile = opts.transpile
   <span class="hljs-keyword">return</span> forkNode()                             <span class="hljs-keyword">if</span> opts.nodejs
   <span class="hljs-keyword">return</span> usage()                                <span class="hljs-keyword">if</span> opts.help
   <span class="hljs-keyword">return</span> version()                              <span class="hljs-keyword">if</span> opts.version
@@ -291,7 +307,45 @@ Many flags cause us to divert before compiling anything. Flags passed after
   process.argv = process.argv[<span class="hljs-number">0.</span><span class="hljs-number">.1</span>].concat literals
   process.argv[<span class="hljs-number">0</span>] = <span class="hljs-string">'coffee'</span>
 
-  opts.output = path.resolve opts.output  <span class="hljs-keyword">if</span> opts.output
+  <span class="hljs-keyword">if</span> opts.output
+    outputBasename = path.basename opts.output
+    <span class="hljs-keyword">if</span> <span class="hljs-string">'.'</span> <span class="hljs-keyword">in</span> outputBasename <span class="hljs-keyword">and</span>
+       outputBasename <span class="hljs-keyword">not</span> <span class="hljs-keyword">in</span> [<span class="hljs-string">'.'</span>, <span class="hljs-string">'..'</span>] <span class="hljs-keyword">and</span>
+       <span class="hljs-keyword">not</span> helpers.ends(opts.output, path.sep)</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-9">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-9">&#182;</a>
+              </div>
+              <p>An output filename was specified, e.g. <code>/dist/scripts.js</code>.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>      opts.outputFilename = outputBasename
+      opts.outputPath = path.resolve path.dirname opts.output
+    <span class="hljs-keyword">else</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>An output path was specified, e.g. <code>/dist</code>.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>      opts.outputFilename = <span class="hljs-literal">null</span>
+      opts.outputPath = path.resolve opts.output
+
   <span class="hljs-keyword">if</span> opts.join
     opts.join = path.resolve opts.join
     <span class="hljs-built_in">console</span>.error <span class="hljs-string">'''
@@ -314,19 +368,19 @@ Many flags cause us to divert before compiling anything. Flags passed after
 <span class="hljs-function">
 <span class="hljs-title">makePrelude</span> = <span class="hljs-params">(requires)</span> -&gt;</span>
   requires.map (<span class="hljs-built_in">module</span>) -&gt;
-    [_, name, <span class="hljs-built_in">module</span>] = match <span class="hljs-keyword">if</span> match = <span class="hljs-built_in">module</span>.match(<span class="hljs-regexp">/^(.*)=(.*)$/</span>)
-    name ||= helpers.baseFileName <span class="hljs-built_in">module</span>, <span class="hljs-literal">yes</span>, useWinPathSep
-    <span class="hljs-string">"<span class="hljs-subst">#{name}</span> = require('<span class="hljs-subst">#{<span class="hljs-built_in">module</span>}</span>')"</span>
+    [full, name, <span class="hljs-built_in">module</span>] = match <span class="hljs-keyword">if</span> match = <span class="hljs-built_in">module</span>.match(<span class="hljs-regexp">/^(.*)=(.*)$/</span>)
+    name <span class="hljs-keyword">or</span>= helpers.baseFileName <span class="hljs-built_in">module</span>, <span class="hljs-literal">yes</span>, useWinPathSep
+    <span class="hljs-string">"global['<span class="hljs-subst">#{name}</span>'] = require('<span class="hljs-subst">#{<span class="hljs-built_in">module</span>}</span>')"</span>
   .join <span class="hljs-string">';'</span></pre></div></div>
             
         </li>
         
         
-        <li id="section-9">
+        <li id="section-11">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-9">&#182;</a>
+                <a class="pilcrow" href="#section-11">&#182;</a>
               </div>
               <p>Compile a path, which could be a script or a directory. If a directory
 is passed, recursively compile all ‘.coffee’, ‘.litcoffee’, and ‘.coffee.md’
@@ -368,7 +422,7 @@ extension source files in it and all subdirectories.</p>
       code = fs.readFileSync source
     <span class="hljs-keyword">catch</span> err
       <span class="hljs-keyword">if</span> err.code <span class="hljs-keyword">is</span> <span class="hljs-string">'ENOENT'</span> <span class="hljs-keyword">then</span> <span class="hljs-keyword">return</span> <span class="hljs-keyword">else</span> <span class="hljs-keyword">throw</span> err
-    compileScript(source, code.toString(), base)
+    compileScript source, code.toString(), base
   <span class="hljs-keyword">else</span>
     notSources[source] = <span class="hljs-literal">yes</span>
 <span class="hljs-function">
@@ -385,53 +439,56 @@ extension source files in it and all subdirectories.</p>
         </li>
         
         
-        <li id="section-10">
+        <li id="section-12">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-10">&#182;</a>
+                <a class="pilcrow" href="#section-12">&#182;</a>
               </div>
               <p>Compile a single source script, containing the given code, according to the
-requested options. If evaluating the script directly sets <code>__filename</code>,
+requested options. If evaluating the script directly, set <code>__filename</code>,
 <code>__dirname</code> and <code>module.filename</code> to be correct relative to the script’s path.</p>
 
             </div>
             
             <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">compileScript</span> = <span class="hljs-params">(file, input, base = <span class="hljs-literal">null</span>)</span> -&gt;</span>
-  o = opts
   options = compileOptions file, base
   <span class="hljs-keyword">try</span>
-    t = task = {file, input, options}
+    task = {file, input, options}
     CoffeeScript.emit <span class="hljs-string">'compile'</span>, task
-    <span class="hljs-keyword">if</span> o.tokens
-      printTokens CoffeeScript.tokens t.input, t.options
-    <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> o.nodes
-      printLine CoffeeScript.nodes(t.input, t.options).toString().trim()
-    <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> o.run
+    <span class="hljs-keyword">if</span> opts.tokens
+      printTokens CoffeeScript.tokens task.input, task.options
+    <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> opts.nodes
+      printLine CoffeeScript.nodes(task.input, task.options).toString().trim()
+    <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> opts.run
       CoffeeScript.register()
-      CoffeeScript.eval opts.prelude, t.options <span class="hljs-keyword">if</span> opts.prelude
-      CoffeeScript.run t.input, t.options
-    <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> o.join <span class="hljs-keyword">and</span> t.file <span class="hljs-keyword">isnt</span> o.join
-      t.input = helpers.invertLiterate t.input <span class="hljs-keyword">if</span> helpers.isLiterate file
-      sourceCode[sources.indexOf(t.file)] = t.input
+      CoffeeScript.eval opts.prelude, task.options <span class="hljs-keyword">if</span> opts.prelude
+      CoffeeScript.run task.input, task.options
+    <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> opts.join <span class="hljs-keyword">and</span> task.file <span class="hljs-keyword">isnt</span> opts.join
+      task.input = helpers.invertLiterate task.input <span class="hljs-keyword">if</span> helpers.isLiterate file
+      sourceCode[sources.indexOf(task.file)] = task.input
       compileJoin()
     <span class="hljs-keyword">else</span>
-      compiled = CoffeeScript.compile t.input, t.options
-      t.output = compiled
-      <span class="hljs-keyword">if</span> o.map
-        t.output = compiled.js
-        t.sourceMap = compiled.v3SourceMap
+      compiled = CoffeeScript.compile task.input, task.options
+      task.output = compiled
+      <span class="hljs-keyword">if</span> opts.map
+        task.output = compiled.js
+        task.sourceMap = compiled.v3SourceMap
 
       CoffeeScript.emit <span class="hljs-string">'success'</span>, task
-      <span class="hljs-keyword">if</span> o.<span class="hljs-built_in">print</span>
-        printLine t.output.trim()
-      <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> o.compile <span class="hljs-keyword">or</span> o.map
-        writeJs base, t.file, t.output, options.jsPath, t.sourceMap
+      <span class="hljs-keyword">if</span> opts.<span class="hljs-built_in">print</span>
+        printLine task.output.trim()
+      <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> opts.compile <span class="hljs-keyword">or</span> opts.map
+        saveTo = <span class="hljs-keyword">if</span> opts.outputFilename <span class="hljs-keyword">and</span> sources.length <span class="hljs-keyword">is</span> <span class="hljs-number">1</span>
+          path.join opts.outputPath, opts.outputFilename
+        <span class="hljs-keyword">else</span>
+          options.jsPath
+        writeJs base, task.file, task.output, saveTo, task.sourceMap
   <span class="hljs-keyword">catch</span> err
     CoffeeScript.emit <span class="hljs-string">'failure'</span>, err, task
     <span class="hljs-keyword">return</span> <span class="hljs-keyword">if</span> CoffeeScript.listeners(<span class="hljs-string">'failure'</span>).length
     message = err?.stack <span class="hljs-keyword">or</span> <span class="hljs-string">"<span class="hljs-subst">#{err}</span>"</span>
-    <span class="hljs-keyword">if</span> o.watch
+    <span class="hljs-keyword">if</span> opts.watch
       printLine message + <span class="hljs-string">'\x07'</span>
     <span class="hljs-keyword">else</span>
       printWarn message
@@ -440,11 +497,11 @@ requested options. If evaluating the script directly sets <code>__filename</code
         </li>
         
         
-        <li id="section-11">
+        <li id="section-13">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-11">&#182;</a>
+                <a class="pilcrow" href="#section-13">&#182;</a>
               </div>
               <p>Attach the appropriate listeners to compile scripts incoming over <strong>stdin</strong>,
 and write them back to <strong>stdout</strong>.</p>
@@ -452,6 +509,9 @@ and write them back to <strong>stdout</strong>.</p>
             </div>
             
             <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">compileStdio</span> = -&gt;</span>
+  <span class="hljs-keyword">if</span> opts.map
+    <span class="hljs-built_in">console</span>.error <span class="hljs-string">'--stdio and --map cannot be used together'</span>
+    process.exit <span class="hljs-number">1</span>
   buffers = []
   stdin = process.openStdin()
   stdin.<span class="hljs-literal">on</span> <span class="hljs-string">'data'</span>, <span class="hljs-function"><span class="hljs-params">(buffer)</span> -&gt;</span>
@@ -462,11 +522,11 @@ and write them back to <strong>stdout</strong>.</p>
         </li>
         
         
-        <li id="section-12">
+        <li id="section-14">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-12">&#182;</a>
+                <a class="pilcrow" href="#section-14">&#182;</a>
               </div>
               <p>If all of the source files are done being read, concatenate and compile
 them together.</p>
@@ -484,11 +544,11 @@ them together.</p>
         </li>
         
         
-        <li id="section-13">
+        <li id="section-15">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-13">&#182;</a>
+                <a class="pilcrow" href="#section-15">&#182;</a>
               </div>
               <p>Watch a source CoffeeScript file using <code>fs.watch</code>, recompiling it every
 time the file is updated. May be used in combination with other options,
@@ -544,11 +604,11 @@ such as <code>--print</code>.</p>
         </li>
         
         
-        <li id="section-14">
+        <li id="section-16">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-14">&#182;</a>
+                <a class="pilcrow" href="#section-16">&#182;</a>
               </div>
               <p>Watch a directory of files for new additions.</p>
 
@@ -595,11 +655,11 @@ such as <code>--print</code>.</p>
         </li>
         
         
-        <li id="section-15">
+        <li id="section-17">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-15">&#182;</a>
+                <a class="pilcrow" href="#section-17">&#182;</a>
               </div>
               <p>Remove a file from our source list, and source code cache. Optionally remove
 the compiled JS version as well.</p>
@@ -624,11 +684,11 @@ the compiled JS version as well.</p>
         </li>
         
         
-        <li id="section-16">
+        <li id="section-18">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-16">&#182;</a>
+                <a class="pilcrow" href="#section-18">&#182;</a>
               </div>
               <p>Get the corresponding output JavaScript path for a source file.</p>
 
@@ -637,22 +697,22 @@ the compiled JS version as well.</p>
             <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">outputPath</span> = <span class="hljs-params">(source, base, extension=<span class="hljs-string">".js"</span>)</span> -&gt;</span>
   basename  = helpers.baseFileName source, <span class="hljs-literal">yes</span>, useWinPathSep
   srcDir    = path.dirname source
-  <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> opts.output
-    dir = srcDir
+  dir = <span class="hljs-keyword">unless</span> opts.outputPath
+    srcDir
   <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> source <span class="hljs-keyword">is</span> base
-    dir = opts.output
+    opts.outputPath
   <span class="hljs-keyword">else</span>
-    dir = path.join opts.output, path.relative base, srcDir
+    path.join opts.outputPath, path.relative base, srcDir
   path.join dir, basename + extension</pre></div></div>
             
         </li>
         
         
-        <li id="section-17">
+        <li id="section-19">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-17">&#182;</a>
+                <a class="pilcrow" href="#section-19">&#182;</a>
               </div>
               <p>Recursively mkdir, like <code>mkdir -p</code>.</p>
 
@@ -674,11 +734,11 @@ the compiled JS version as well.</p>
         </li>
         
         
-        <li id="section-18">
+        <li id="section-20">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-18">&#182;</a>
+                <a class="pilcrow" href="#section-20">&#182;</a>
               </div>
               <p>Write out a JavaScript source file with the compiled code. By default, files
 are written out in <code>cwd</code> as <code>.js</code> files with the same name, but the output
@@ -689,7 +749,7 @@ 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">writeJs</span> = <span class="hljs-params">(base, sourcePath, js, jsPath, generatedSourceMap = <span class="hljs-literal">null</span>)</span> -&gt;</span>
-  sourceMapPath = outputPath sourcePath, base, <span class="hljs-string">".js.map"</span>
+  sourceMapPath = <span class="hljs-string">"<span class="hljs-subst">#{jsPath}</span>.map"</span>
   jsDir  = path.dirname jsPath
 <span class="hljs-function">  <span class="hljs-title">compile</span> = -&gt;</span>
     <span class="hljs-keyword">if</span> opts.compile
@@ -712,11 +772,11 @@ same directory as the <code>.js</code> file.</p>
         </li>
         
         
-        <li id="section-19">
+        <li id="section-21">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-19">&#182;</a>
+                <a class="pilcrow" href="#section-21">&#182;</a>
               </div>
               <p>Convenience for cleaner setTimeouts.</p>
 
@@ -727,11 +787,11 @@ same directory as the <code>.js</code> file.</p>
         </li>
         
         
-        <li id="section-20">
+        <li id="section-22">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-20">&#182;</a>
+                <a class="pilcrow" href="#section-22">&#182;</a>
               </div>
               <p>When watching scripts, it’s useful to log changes with the timestamp.</p>
 
@@ -743,11 +803,11 @@ same directory as the <code>.js</code> file.</p>
         </li>
         
         
-        <li id="section-21">
+        <li id="section-23">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-21">&#182;</a>
+                <a class="pilcrow" href="#section-23">&#182;</a>
               </div>
               <p>Pretty-print a stream of tokens, sans location data.</p>
 
@@ -763,11 +823,11 @@ same directory as the <code>.js</code> file.</p>
         </li>
         
         
-        <li id="section-22">
+        <li id="section-24">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-22">&#182;</a>
+                <a class="pilcrow" href="#section-24">&#182;</a>
               </div>
               <p>Use the <a href="optparse.html">OptionParser module</a> to extract all options from
 <code>process.argv</code> that are specified in <code>SWITCHES</code>.</p>
@@ -783,25 +843,124 @@ same directory as the <code>.js</code> file.</p>
         </li>
         
         
-        <li id="section-23">
+        <li id="section-25">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-23">&#182;</a>
+                <a class="pilcrow" href="#section-25">&#182;</a>
               </div>
               <p>The compile-time options to pass to the CoffeeScript compiler.</p>
 
             </div>
             
             <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">compileOptions</span> = <span class="hljs-params">(filename, base)</span> -&gt;</span>
-  answer = {
-    filename
+  <span class="hljs-keyword">if</span> opts.transpile</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-26">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-26">&#182;</a>
+              </div>
+              <p>The user has requested that the CoffeeScript compiler also transpile
+via Babel. We don’t include Babel as a dependency because we want to
+avoid dependencies in general, and most users probably won’t be relying
+on us to transpile for them; we assume most users will probably either
+run CoffeeScript’s output without transpilation (modern Node or evergreen
+browsers) or use a proper build chain like Gulp or Webpack.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>    <span class="hljs-keyword">try</span>
+      <span class="hljs-built_in">require</span> <span class="hljs-string">'@babel/core'</span>
+    <span class="hljs-keyword">catch</span>
+      <span class="hljs-keyword">try</span>
+        <span class="hljs-built_in">require</span> <span class="hljs-string">'babel-core'</span>
+      <span class="hljs-keyword">catch</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>Give appropriate instructions depending on whether <code>coffee</code> was run
+locally or globally.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>        <span class="hljs-keyword">if</span> <span class="hljs-built_in">require</span>.resolve(<span class="hljs-string">'.'</span>).indexOf(process.cwd()) <span class="hljs-keyword">is</span> <span class="hljs-number">0</span>
+          <span class="hljs-built_in">console</span>.error <span class="hljs-string">'''
+            To use --transpile, you must have @babel/core installed:
+              npm install --save-dev @babel/core
+            And you must save options to configure Babel in one of the places it looks to find its options.
+            See https://coffeescript.org/#transpilation
+          '''</span>
+        <span class="hljs-keyword">else</span>
+          <span class="hljs-built_in">console</span>.error <span class="hljs-string">'''
+            To use --transpile with globally-installed CoffeeScript, you must have @babel/core installed globally:
+              npm install --global @babel/core
+            And you must save options to configure Babel in one of the places it looks to find its options, relative to the file being compiled or to the current folder.
+            See https://coffeescript.org/#transpilation
+          '''</span>
+        process.exit <span class="hljs-number">1</span>
+
+    opts.transpile = {} <span class="hljs-keyword">unless</span> <span class="hljs-keyword">typeof</span> opts.transpile <span class="hljs-keyword">is</span> <span class="hljs-string">'object'</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>Pass a reference to Babel into the compiler, so that the transpile option
+is available for the CLI. We need to do this so that tools like Webpack
+can <code>require(&#39;coffeescript&#39;)</code> and build correctly, without trying to
+require Babel.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>    opts.transpile.transpile = CoffeeScript.transpile</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-29">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-29">&#182;</a>
+              </div>
+              <p>Babel searches for its options (a <code>.babelrc</code> file, a <code>.babelrc.js</code> file,
+a <code>package.json</code> file with a <code>babel</code> key, etc.) relative to the path
+given to it in its <code>filename</code> option. Make sure we have a path to pass
+along.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>    <span class="hljs-keyword">unless</span> opts.transpile.filename
+      opts.transpile.filename = filename <span class="hljs-keyword">or</span> path.resolve(base <span class="hljs-keyword">or</span> process.cwd(), <span class="hljs-string">'&lt;anonymous&gt;'</span>)
+  <span class="hljs-keyword">else</span>
+    opts.transpile = <span class="hljs-literal">no</span>
+
+  answer =
+    filename: filename
     literate: opts.literate <span class="hljs-keyword">or</span> helpers.isLiterate(filename)
     bare: opts.bare
     header: opts.compile <span class="hljs-keyword">and</span> <span class="hljs-keyword">not</span> opts[<span class="hljs-string">'no-header'</span>]
+    transpile: opts.transpile
     sourceMap: opts.map
     inlineMap: opts[<span class="hljs-string">'inline-map'</span>]
-  }
+
   <span class="hljs-keyword">if</span> filename
     <span class="hljs-keyword">if</span> base
       cwd = process.cwd()
@@ -823,11 +982,11 @@ same directory as the <code>.js</code> file.</p>
         </li>
         
         
-        <li id="section-24">
+        <li id="section-30">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-24">&#182;</a>
+                <a class="pilcrow" href="#section-30">&#182;</a>
               </div>
               <p>Start up a new Node.js instance with the arguments in <code>--nodejs</code> passed to
 the <code>node</code> binary, preserving the other options.</p>
@@ -842,16 +1001,19 @@ the <code>node</code> binary, preserving the other options.</p>
     cwd:        process.cwd()
     env:        process.env
     stdio:      [<span class="hljs-number">0</span>, <span class="hljs-number">1</span>, <span class="hljs-number">2</span>]
+  <span class="hljs-keyword">for</span> signal <span class="hljs-keyword">in</span> [<span class="hljs-string">'SIGINT'</span>, <span class="hljs-string">'SIGTERM'</span>]
+    process.<span class="hljs-literal">on</span> signal, <span class="hljs-keyword">do</span> (signal) -&gt;
+      -&gt; p.kill signal
   p.<span class="hljs-literal">on</span> <span class="hljs-string">'exit'</span>, <span class="hljs-function"><span class="hljs-params">(code)</span> -&gt;</span> process.exit code</pre></div></div>
             
         </li>
         
         
-        <li id="section-25">
+        <li id="section-31">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-25">&#182;</a>
+                <a class="pilcrow" href="#section-31">&#182;</a>
               </div>
               <p>Print the <code>--help</code> usage message and exit. Deprecated switches are not
 shown.</p>
@@ -864,11 +1026,11 @@ shown.</p>
         </li>
         
         
-        <li id="section-26">
+        <li id="section-32">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-26">&#182;</a>
+                <a class="pilcrow" href="#section-32">&#182;</a>
               </div>
               <p>Print the <code>--version</code> message and exit.</p>
 

docs/v2/annotated-source/helpers.html

@@ -382,7 +382,10 @@ If <code>last</code> is not provided, this will simply return <code>first</code>
     first_line: first.first_line
     first_column: first.first_column
     last_line: last.last_line
-    last_column: last.last_column</pre></div></div>
+    last_column: last.last_column
+<span class="hljs-function">
+<span class="hljs-title">buildLocationHash</span> = <span class="hljs-params">(loc)</span> -&gt;</span>
+  <span class="hljs-string">"<span class="hljs-subst">#{loc.first_line}</span>x<span class="hljs-subst">#{loc.first_column}</span>-<span class="hljs-subst">#{loc.last_line}</span>x<span class="hljs-subst">#{loc.last_column}</span>"</span></pre></div></div>
             
         </li>
         
@@ -393,18 +396,15 @@ If <code>last</code> is not provided, this will simply return <code>first</code>
               <div class="pilwrap ">
                 <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.
-The object is returned either way.</p>
+              <p>Build a dictionary of extra token properties organized by tokens’ locations
+used as lookup hashes.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>exports.addLocationDataFn = <span class="hljs-function"><span class="hljs-params">(first, last)</span> -&gt;</span>
-  (obj) -&gt;
-    <span class="hljs-keyword">if</span> ((<span class="hljs-keyword">typeof</span> obj) <span class="hljs-keyword">is</span> <span class="hljs-string">'object'</span>) <span class="hljs-keyword">and</span> (!!obj[<span class="hljs-string">'updateLocationDataIfMissing'</span>])
-      obj.updateLocationDataIfMissing buildLocationData(first, last)
-
-    <span class="hljs-keyword">return</span> obj</pre></div></div>
+            <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">buildTokenDataDictionary</span> = <span class="hljs-params">(parserState)</span> -&gt;</span>
+  tokenData = {}
+  <span class="hljs-keyword">for</span> token <span class="hljs-keyword">in</span> parserState.parser.tokens <span class="hljs-keyword">when</span> token.comments
+    tokenHash = buildLocationHash token[<span class="hljs-number">2</span>]</pre></div></div>
             
         </li>
         
@@ -415,6 +415,103 @@ The object is returned either way.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-16">&#182;</a>
               </div>
+              <p>Multiple tokens might have the same location hash, such as the generated
+<code>JS</code> tokens added at the start or end of the token stream to hold
+comments that start or end a file.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>    tokenData[tokenHash] ?= {}
+    <span class="hljs-keyword">if</span> token.comments <span class="hljs-comment"># `comments` is always an array.</span></pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-17">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-17">&#182;</a>
+              </div>
+              <p>For “overlapping” tokens, that is tokens with the same location data
+and therefore matching <code>tokenHash</code>es, merge the comments from both/all
+tokens together into one array, even if there are duplicate comments;
+they will get sorted out later.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>      (tokenData[tokenHash].comments ?= []).push token.comments...
+  tokenData</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-18">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-18">&#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.
+The object is returned either way.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>exports.addDataToNode = <span class="hljs-function"><span class="hljs-params">(parserState, first, last)</span> -&gt;</span>
+  (obj) -&gt;</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-19">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-19">&#182;</a>
+              </div>
+              <p>Add location data.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>    <span class="hljs-keyword">if</span> obj?.updateLocationDataIfMissing? <span class="hljs-keyword">and</span> first?
+      obj.updateLocationDataIfMissing buildLocationData(first, last)</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-20">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-20">&#182;</a>
+              </div>
+              <p>Add comments, building the dictionary of token data if it hasn’t been
+built yet.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>    parserState.tokenData ?= buildTokenDataDictionary parserState
+    <span class="hljs-keyword">if</span> obj.locationData?
+      objHash = buildLocationHash obj.locationData
+      <span class="hljs-keyword">if</span> parserState.tokenData[objHash]?.comments?
+        attachCommentsToNode parserState.tokenData[objHash].comments, obj
+    obj
+
+exports.attachCommentsToNode = attachCommentsToNode = <span class="hljs-function"><span class="hljs-params">(comments, node)</span> -&gt;</span>
+  <span class="hljs-keyword">return</span> <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> comments? <span class="hljs-keyword">or</span> comments.length <span class="hljs-keyword">is</span> <span class="hljs-number">0</span>
+  node.comments ?= []
+  node.comments.push comments...</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-21">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-21">&#182;</a>
+              </div>
               <p>Convert jison location data to a string.
 <code>obj</code> can be a token, or a locationData.</p>
 
@@ -433,11 +530,11 @@ The object is returned either way.</p>
         </li>
         
         
-        <li id="section-17">
+        <li id="section-22">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-17">&#182;</a>
+                <a class="pilcrow" href="#section-22">&#182;</a>
               </div>
               <p>A <code>.coffee.md</code> compatible version of <code>basename</code>, that returns the file sans-extension.</p>
 
@@ -456,11 +553,11 @@ The object is returned either way.</p>
         </li>
         
         
-        <li id="section-18">
+        <li id="section-23">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-18">&#182;</a>
+                <a class="pilcrow" href="#section-23">&#182;</a>
               </div>
               <p>Determine if a filename represents a CoffeeScript file.</p>
 
@@ -471,11 +568,11 @@ The object is returned either way.</p>
         </li>
         
         
-        <li id="section-19">
+        <li id="section-24">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-19">&#182;</a>
+                <a class="pilcrow" href="#section-24">&#182;</a>
               </div>
               <p>Determine if a filename represents a Literate CoffeeScript file.</p>
 
@@ -486,11 +583,11 @@ The object is returned either way.</p>
         </li>
         
         
-        <li id="section-20">
+        <li id="section-25">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-20">&#182;</a>
+                <a class="pilcrow" href="#section-25">&#182;</a>
               </div>
               <p>Throws a SyntaxError from a given location.
 The error’s <code>toString</code> will return an error message following the “standard”
@@ -507,11 +604,11 @@ marker showing where the error is.</p>
         </li>
         
         
-        <li id="section-21">
+        <li id="section-26">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-21">&#182;</a>
+                <a class="pilcrow" href="#section-26">&#182;</a>
               </div>
               <p>Instead of showing the compiler’s stacktrace, show our custom error message
 (this is useful when the error bubbles up in Node.js applications that
@@ -526,11 +623,11 @@ compile CoffeeScript for example).</p>
         </li>
         
         
-        <li id="section-22">
+        <li id="section-27">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-22">&#182;</a>
+                <a class="pilcrow" href="#section-27">&#182;</a>
               </div>
               <p>Update a compiler SyntaxError with source code information if it didn’t have
 it already.</p>
@@ -542,11 +639,11 @@ it already.</p>
         </li>
         
         
-        <li id="section-23">
+        <li id="section-28">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-23">&#182;</a>
+                <a class="pilcrow" href="#section-28">&#182;</a>
               </div>
               <p>Avoid screwing up the <code>stack</code> property of other errors (i.e. possible bugs).</p>
 
@@ -572,11 +669,11 @@ it already.</p>
         </li>
         
         
-        <li id="section-24">
+        <li id="section-29">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-24">&#182;</a>
+                <a class="pilcrow" href="#section-29">&#182;</a>
               </div>
               <p>Show only the first line on multi-line errors.</p>
 
@@ -588,11 +685,11 @@ it already.</p>
         </li>
         
         
-        <li id="section-25">
+        <li id="section-30">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-25">&#182;</a>
+                <a class="pilcrow" href="#section-30">&#182;</a>
               </div>
               <p>Check to see if we’re running on a color-enabled TTY.</p>
 

docs/v2/annotated-source/index.html

@@ -125,7 +125,14 @@ vm            = <span class="hljs-built_in">require</span> <span class="hljs-str
 path          = <span class="hljs-built_in">require</span> <span class="hljs-string">'path'</span>
 
 helpers       = CoffeeScript.helpers
-compile       = CoffeeScript.compile</pre></div></div>
+
+CoffeeScript.transpile = <span class="hljs-function"><span class="hljs-params">(js, options)</span> -&gt;</span>
+  <span class="hljs-keyword">try</span>
+    babel = <span class="hljs-built_in">require</span> <span class="hljs-string">'@babel/core'</span>
+  <span class="hljs-keyword">catch</span>
+    <span class="hljs-keyword">try</span>
+      babel = <span class="hljs-built_in">require</span> <span class="hljs-string">'babel-core'</span>
+    <span class="hljs-keyword">catch</span></pre></div></div>
             
         </li>
         
@@ -136,6 +143,73 @@ compile       = CoffeeScript.compile</pre></div></div>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-2">&#182;</a>
               </div>
+              <p>This error is only for Node, as CLI users will see a different error
+earlier if they don’t have Babel installed.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>      <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> Error <span class="hljs-string">'To use the transpile option, you must have the \'@babel/core\' module installed'</span>
+  babel.transform js, options</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-3">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-3">&#182;</a>
+              </div>
+              <p>The <code>compile</code> method shared by the CLI, Node and browser APIs.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>universalCompile = CoffeeScript.compile</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-4">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-4">&#182;</a>
+              </div>
+              <p>The <code>compile</code> method particular to the Node API.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>CoffeeScript.compile = <span class="hljs-function"><span class="hljs-params">(code, options)</span> -&gt;</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>Pass a reference to Babel into the compiler, so that the transpile option
+is available in the Node API. We need to do this so that tools like Webpack
+can <code>require(&#39;coffeescript&#39;)</code> and build correctly, without trying to
+require Babel.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>  <span class="hljs-keyword">if</span> options?.transpile
+    options.transpile.transpile = CoffeeScript.transpile
+  universalCompile.call CoffeeScript, code, options</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 and execute a string of CoffeeScript (on the server), correctly
 setting <code>__filename</code>, <code>__dirname</code>, and relative <code>require()</code>.</p>
 
@@ -147,11 +221,11 @@ setting <code>__filename</code>, <code>__dirname</code>, and relative <code>requ
         </li>
         
         
-        <li id="section-3">
+        <li id="section-7">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-3">&#182;</a>
+                <a class="pilcrow" href="#section-7">&#182;</a>
               </div>
               <p>Set the filename.</p>
 
@@ -163,11 +237,11 @@ setting <code>__filename</code>, <code>__dirname</code>, and relative <code>requ
         </li>
         
         
-        <li id="section-4">
+        <li id="section-8">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-4">&#182;</a>
+                <a class="pilcrow" href="#section-8">&#182;</a>
               </div>
               <p>Clear the module cache.</p>
 
@@ -178,11 +252,11 @@ setting <code>__filename</code>, <code>__dirname</code>, and relative <code>requ
         </li>
         
         
-        <li id="section-5">
+        <li id="section-9">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-5">&#182;</a>
+                <a class="pilcrow" href="#section-9">&#182;</a>
               </div>
               <p>Assign paths for node_modules loading</p>
 
@@ -197,18 +271,33 @@ setting <code>__filename</code>, <code>__dirname</code>, and relative <code>requ
         </li>
         
         
-        <li id="section-6">
+        <li id="section-10">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-6">&#182;</a>
+                <a class="pilcrow" href="#section-10">&#182;</a>
+              </div>
+              <p>Save the options for compiling child imports.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>  mainModule.options = options</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-11">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-11">&#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
+    answer = CoffeeScript.compile code, options
     code = answer.js ? answer
 
   mainModule._compile code, mainModule.filename</pre></div></div>
@@ -216,11 +305,11 @@ setting <code>__filename</code>, <code>__dirname</code>, and relative <code>requ
         </li>
         
         
-        <li id="section-7">
+        <li id="section-12">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-7">&#182;</a>
+                <a class="pilcrow" href="#section-12">&#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>
@@ -250,11 +339,11 @@ The CoffeeScript REPL uses this to run the input.</p>
         </li>
         
         
-        <li id="section-8">
+        <li id="section-13">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-8">&#182;</a>
+                <a class="pilcrow" href="#section-13">&#182;</a>
               </div>
               <p>define module/require only if they chose not to specify their own</p>
 
@@ -271,11 +360,11 @@ The CoffeeScript REPL uses this to run the input.</p>
         </li>
         
         
-        <li id="section-9">
+        <li id="section-14">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-9">&#182;</a>
+                <a class="pilcrow" href="#section-14">&#182;</a>
               </div>
               <p>use the same hack node currently uses for their own REPL</p>
 
@@ -286,7 +375,7 @@ The CoffeeScript REPL uses this to run the input.</p>
   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
+  js = CoffeeScript.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>
@@ -297,11 +386,11 @@ CoffeeScript.register = <span class="hljs-function">-&gt;</span> <span class="hl
         </li>
         
         
-        <li id="section-10">
+        <li id="section-15">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-10">&#182;</a>
+                <a class="pilcrow" href="#section-15">&#182;</a>
               </div>
               <p>Throw error with deprecation warning when depending upon implicit <code>require.extensions</code> registration</p>
 
@@ -314,17 +403,16 @@ CoffeeScript.register = <span class="hljs-function">-&gt;</span> <span class="hl
       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>
+CoffeeScript._compileRawFileContent = <span class="hljs-function"><span class="hljs-params">(raw, filename, options = {})</span> -&gt;</span></pre></div></div>
             
         </li>
         
         
-        <li id="section-11">
+        <li id="section-16">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-11">&#182;</a>
+                <a class="pilcrow" href="#section-16">&#182;</a>
               </div>
               <p>Strip the Unicode byte order mark, if this file begins with one.</p>
 
@@ -332,22 +420,24 @@ CoffeeScript._compileFile = <span class="hljs-function"><span class="hljs-params
             
             <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
 
+  options = Object.assign {}, options,
+    filename: filename
+    literate: helpers.isLiterate filename
+    sourceFiles: [filename]
+    inlineMap: <span class="hljs-literal">yes</span> <span class="hljs-comment"># Always generate a source map, so that stack traces line up.</span>
+
   <span class="hljs-keyword">try</span>
-    answer = compile stripped, {
-      filename, sourceMap, inlineMap
-      sourceFiles: [filename]
-      literate: helpers.isLiterate filename
-    }
+    answer = CoffeeScript.compile stripped, options
   <span class="hljs-keyword">catch</span> err</pre></div></div>
             
         </li>
         
         
-        <li id="section-12">
+        <li id="section-17">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-12">&#182;</a>
+                <a class="pilcrow" href="#section-17">&#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
@@ -359,6 +449,11 @@ information to error so it can be pretty-printed later.</p>
 
   answer
 
+CoffeeScript._compileFile = <span class="hljs-function"><span class="hljs-params">(filename, options = {})</span> -&gt;</span>
+  raw = fs.readFileSync filename, <span class="hljs-string">'utf8'</span>
+
+  CoffeeScript._compileRawFileContent raw, filename, options
+
 <span class="hljs-built_in">module</span>.exports = CoffeeScript</pre></div></div>
             
         </li>

docs/v2/annotated-source/optparse.html

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

docs/v2/annotated-source/register.html

@@ -137,7 +137,8 @@ path          = <span class="hljs-built_in">require</span> <span class="hljs-str
             </div>
             
             <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">loadFile</span> = <span class="hljs-params">(<span class="hljs-built_in">module</span>, filename)</span> -&gt;</span>
-  answer = CoffeeScript._compileFile filename, <span class="hljs-literal">no</span>, <span class="hljs-literal">yes</span>
+  options = <span class="hljs-built_in">module</span>.options <span class="hljs-keyword">or</span> getRootModule(<span class="hljs-built_in">module</span>).options
+  answer = CoffeeScript._compileFile filename, options
   <span class="hljs-built_in">module</span>._compile answer, filename</pre></div></div>
             
         </li>
@@ -245,6 +246,22 @@ to fork both CoffeeScript files, and JavaScript files, directly.</p>
             
         </li>
         
+        
+        <li id="section-8">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-8">&#182;</a>
+              </div>
+              <p>Utility function to find the <code>options</code> object attached to the topmost module.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">getRootModule</span> = <span class="hljs-params">(<span class="hljs-built_in">module</span>)</span> -&gt;</span>
+  <span class="hljs-keyword">if</span> <span class="hljs-built_in">module</span>.parent <span class="hljs-keyword">then</span> getRootModule <span class="hljs-built_in">module</span>.parent <span class="hljs-keyword">else</span> <span class="hljs-built_in">module</span></pre></div></div>
+            
+        </li>
+        
     </ul>
   </div>
 </body>

docs/v2/annotated-source/repl.html

@@ -125,6 +125,9 @@ nodeREPL = <span class="hljs-built_in">require</span> <span class="hljs-string">
 CoffeeScript = <span class="hljs-built_in">require</span> <span class="hljs-string">'./'</span>
 {merge, updateSyntaxError} = <span class="hljs-built_in">require</span> <span class="hljs-string">'./helpers'</span>
 
+sawSIGINT = <span class="hljs-literal">no</span>
+transpile = <span class="hljs-literal">no</span>
+
 replDefaults =
   prompt: <span class="hljs-string">'coffee&gt; '</span>,
   historyFile: <span class="hljs-keyword">do</span> -&gt;
@@ -193,7 +196,7 @@ Unwrap that too.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>    {Block, Assign, Value, Literal} = <span class="hljs-built_in">require</span> <span class="hljs-string">'./nodes'</span>
+            <div class="content"><div class='highlight'><pre>    {Block, Assign, Value, Literal, Call, Code} = <span class="hljs-built_in">require</span> <span class="hljs-string">'./nodes'</span>
 
     <span class="hljs-keyword">try</span></pre></div></div>
             
@@ -221,13 +224,17 @@ Unwrap that too.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-7">&#182;</a>
               </div>
-              <p>Collect referenced variable names just like in <code>CoffeeScript.compile</code>.</p>
+              <p>Filter out tokens generated just to hold comments.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>      referencedVars = (
-        token[<span class="hljs-number">1</span>] <span class="hljs-keyword">for</span> token <span class="hljs-keyword">in</span> tokens <span class="hljs-keyword">when</span> token[<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'IDENTIFIER'</span>
-      )</pre></div></div>
+            <div class="content"><div class='highlight'><pre>      <span class="hljs-keyword">if</span> tokens.length &gt;= <span class="hljs-number">2</span> <span class="hljs-keyword">and</span> tokens[<span class="hljs-number">0</span>].generated <span class="hljs-keyword">and</span>
+         tokens[<span class="hljs-number">0</span>].comments?.length <span class="hljs-keyword">isnt</span> <span class="hljs-number">0</span> <span class="hljs-keyword">and</span> tokens[<span class="hljs-number">0</span>][<span class="hljs-number">1</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">''</span> <span class="hljs-keyword">and</span>
+         tokens[<span class="hljs-number">1</span>][<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'TERMINATOR'</span>
+        tokens = tokens[<span class="hljs-number">2.</span>..]
+      <span class="hljs-keyword">if</span> tokens.length &gt;= <span class="hljs-number">1</span> <span class="hljs-keyword">and</span> tokens[tokens.length - <span class="hljs-number">1</span>].generated <span class="hljs-keyword">and</span>
+         tokens[tokens.length - <span class="hljs-number">1</span>].comments?.length <span class="hljs-keyword">isnt</span> <span class="hljs-number">0</span> <span class="hljs-keyword">and</span> tokens[tokens.length - <span class="hljs-number">1</span>][<span class="hljs-number">1</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">''</span>
+        tokens.pop()</pre></div></div>
             
         </li>
         
@@ -238,11 +245,11 @@ Unwrap that too.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-8">&#182;</a>
               </div>
-              <p>Generate the AST of the tokens.</p>
+              <p>Collect referenced variable names just like in <code>CoffeeScript.compile</code>.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>      ast = CoffeeScript.nodes tokens</pre></div></div>
+            <div class="content"><div class='highlight'><pre>      referencedVars = (token[<span class="hljs-number">1</span>] <span class="hljs-keyword">for</span> token <span class="hljs-keyword">in</span> tokens <span class="hljs-keyword">when</span> token[<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">'IDENTIFIER'</span>)</pre></div></div>
             
         </li>
         
@@ -253,16 +260,11 @@ Unwrap that too.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-9">&#182;</a>
               </div>
-              <p>Add assignment to <code>_</code> variable to force the input to be an expression.</p>
+              <p>Generate the AST of the tokens.</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>      ast = <span class="hljs-keyword">new</span> Block [
-        <span class="hljs-keyword">new</span> Assign (<span class="hljs-keyword">new</span> Value <span class="hljs-keyword">new</span> Literal <span class="hljs-string">'__'</span>), ast, <span class="hljs-string">'='</span>
-      ]
-      js = ast.compile {bare: <span class="hljs-literal">yes</span>, locals: Object.keys(context), referencedVars}
-      cb <span class="hljs-literal">null</span>, runInContext js, context, filename
-    <span class="hljs-keyword">catch</span> err</pre></div></div>
+            <div class="content"><div class='highlight'><pre>      ast = CoffeeScript.nodes tokens</pre></div></div>
             
         </li>
         
@@ -273,6 +275,93 @@ Unwrap that too.</p>
               <div class="pilwrap ">
                 <a class="pilcrow" href="#section-10">&#182;</a>
               </div>
+              <p>Add assignment to <code>__</code> variable to force the input to be an expression.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>      ast = <span class="hljs-keyword">new</span> Block [<span class="hljs-keyword">new</span> Assign (<span class="hljs-keyword">new</span> Value <span class="hljs-keyword">new</span> Literal <span class="hljs-string">'__'</span>), ast, <span class="hljs-string">'='</span>]</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-11">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-11">&#182;</a>
+              </div>
+              <p>Wrap the expression in a closure to support top-level <code>await</code>.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>      ast     = <span class="hljs-keyword">new</span> Code [], ast
+      isAsync = ast.isAsync</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-12">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-12">&#182;</a>
+              </div>
+              <p>Invoke the wrapping closure.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>      ast    = <span class="hljs-keyword">new</span> Block [<span class="hljs-keyword">new</span> Call ast]
+      js     = ast.compile {bare: <span class="hljs-literal">yes</span>, locals: Object.keys(context), referencedVars, sharedScope: <span class="hljs-literal">yes</span>}
+      <span class="hljs-keyword">if</span> transpile
+        js = transpile.transpile(js, transpile.options).code</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-13">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-13">&#182;</a>
+              </div>
+              <p>Strip <code>&quot;use strict&quot;</code>, to avoid an exception on assigning to
+undeclared variable <code>__</code>.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>        js = js.replace <span class="hljs-regexp">/^"use strict"|^'use strict'/</span>, <span class="hljs-string">''</span>
+      result = runInContext js, context, filename</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-14">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-14">&#182;</a>
+              </div>
+              <p>Await an async result, if necessary.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>      <span class="hljs-keyword">if</span> isAsync
+        result.<span class="hljs-keyword">then</span> (resolvedResult) -&gt;
+          cb <span class="hljs-literal">null</span>, resolvedResult <span class="hljs-keyword">unless</span> sawSIGINT
+        sawSIGINT = <span class="hljs-literal">no</span>
+      <span class="hljs-keyword">else</span>
+        cb <span class="hljs-literal">null</span>, result
+    <span class="hljs-keyword">catch</span> err</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-15">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-15">&#182;</a>
+              </div>
               <p>AST’s <code>compile</code> does not add source code information to syntax errors.</p>
 
             </div>
@@ -287,16 +376,16 @@ Unwrap that too.</p>
     vm.runInContext js, context, filename
 <span class="hljs-function">
 <span class="hljs-title">addMultilineHandler</span> = <span class="hljs-params">(repl)</span> -&gt;</span>
-  {rli, inputStream, outputStream} = repl</pre></div></div>
+  {inputStream, outputStream} = repl</pre></div></div>
             
         </li>
         
         
-        <li id="section-11">
+        <li id="section-16">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-11">&#182;</a>
+                <a class="pilcrow" href="#section-16">&#182;</a>
               </div>
               <p>Node 0.11.12 changed API, prompt is now _prompt.</p>
 
@@ -313,36 +402,36 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-12">
+        <li id="section-17">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-12">&#182;</a>
+                <a class="pilcrow" href="#section-17">&#182;</a>
               </div>
               <p>Proxy node’s line listener</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>  nodeLineListener = rli.listeners(<span class="hljs-string">'line'</span>)[<span class="hljs-number">0</span>]
-  rli.removeListener <span class="hljs-string">'line'</span>, nodeLineListener
-  rli.<span class="hljs-literal">on</span> <span class="hljs-string">'line'</span>, <span class="hljs-function"><span class="hljs-params">(cmd)</span> -&gt;</span>
+            <div class="content"><div class='highlight'><pre>  nodeLineListener = repl.listeners(<span class="hljs-string">'line'</span>)[<span class="hljs-number">0</span>]
+  repl.removeListener <span class="hljs-string">'line'</span>, nodeLineListener
+  repl.<span class="hljs-literal">on</span> <span class="hljs-string">'line'</span>, <span class="hljs-function"><span class="hljs-params">(cmd)</span> -&gt;</span>
     <span class="hljs-keyword">if</span> multiline.enabled
       multiline.buffer += <span class="hljs-string">"<span class="hljs-subst">#{cmd}</span>\n"</span>
-      rli.setPrompt multiline.prompt
-      rli.prompt <span class="hljs-literal">true</span>
+      repl.setPrompt multiline.prompt
+      repl.prompt <span class="hljs-literal">true</span>
     <span class="hljs-keyword">else</span>
-      rli.setPrompt origPrompt
+      repl.setPrompt origPrompt
       nodeLineListener cmd
     <span class="hljs-keyword">return</span></pre></div></div>
             
         </li>
         
         
-        <li id="section-13">
+        <li id="section-18">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-13">&#182;</a>
+                <a class="pilcrow" href="#section-18">&#182;</a>
               </div>
               <p>Handle Ctrl-v</p>
 
@@ -355,11 +444,11 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-14">
+        <li id="section-19">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-14">&#182;</a>
+                <a class="pilcrow" href="#section-19">&#182;</a>
               </div>
               <p>allow arbitrarily switching between modes any time before multiple lines are entered</p>
 
@@ -367,74 +456,74 @@ Unwrap that too.</p>
             
             <div class="content"><div class='highlight'><pre>      <span class="hljs-keyword">unless</span> multiline.buffer.match <span class="hljs-regexp">/\n/</span>
         multiline.enabled = <span class="hljs-keyword">not</span> multiline.enabled
-        rli.setPrompt origPrompt
-        rli.prompt <span class="hljs-literal">true</span>
+        repl.setPrompt origPrompt
+        repl.prompt <span class="hljs-literal">true</span>
         <span class="hljs-keyword">return</span></pre></div></div>
             
         </li>
         
         
-        <li id="section-15">
+        <li id="section-20">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-15">&#182;</a>
+                <a class="pilcrow" href="#section-20">&#182;</a>
               </div>
               <p>no-op unless the current line is empty</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>      <span class="hljs-keyword">return</span> <span class="hljs-keyword">if</span> rli.line? <span class="hljs-keyword">and</span> <span class="hljs-keyword">not</span> rli.line.match <span class="hljs-regexp">/^\s*$/</span></pre></div></div>
+            <div class="content"><div class='highlight'><pre>      <span class="hljs-keyword">return</span> <span class="hljs-keyword">if</span> repl.line? <span class="hljs-keyword">and</span> <span class="hljs-keyword">not</span> repl.line.match <span class="hljs-regexp">/^\s*$/</span></pre></div></div>
             
         </li>
         
         
-        <li id="section-16">
+        <li id="section-21">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-16">&#182;</a>
+                <a class="pilcrow" href="#section-21">&#182;</a>
               </div>
               <p>eval, print, loop</p>
 
             </div>
             
             <div class="content"><div class='highlight'><pre>      multiline.enabled = <span class="hljs-keyword">not</span> multiline.enabled
-      rli.line = <span class="hljs-string">''</span>
-      rli.cursor = <span class="hljs-number">0</span>
-      rli.output.cursorTo <span class="hljs-number">0</span>
-      rli.output.clearLine <span class="hljs-number">1</span></pre></div></div>
+      repl.line = <span class="hljs-string">''</span>
+      repl.cursor = <span class="hljs-number">0</span>
+      repl.output.cursorTo <span class="hljs-number">0</span>
+      repl.output.clearLine <span class="hljs-number">1</span></pre></div></div>
             
         </li>
         
         
-        <li id="section-17">
+        <li id="section-22">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-17">&#182;</a>
+                <a class="pilcrow" href="#section-22">&#182;</a>
               </div>
               <p>XXX: multiline hack</p>
 
             </div>
             
             <div class="content"><div class='highlight'><pre>      multiline.buffer = multiline.buffer.replace <span class="hljs-regexp">/\n/g</span>, <span class="hljs-string">'\uFF00'</span>
-      rli.emit <span class="hljs-string">'line'</span>, multiline.buffer
+      repl.emit <span class="hljs-string">'line'</span>, multiline.buffer
       multiline.buffer = <span class="hljs-string">''</span>
     <span class="hljs-keyword">else</span>
       multiline.enabled = <span class="hljs-keyword">not</span> multiline.enabled
-      rli.setPrompt multiline.initialPrompt
-      rli.prompt <span class="hljs-literal">true</span>
+      repl.setPrompt multiline.initialPrompt
+      repl.prompt <span class="hljs-literal">true</span>
     <span class="hljs-keyword">return</span></pre></div></div>
             
         </li>
         
         
-        <li id="section-18">
+        <li id="section-23">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-18">&#182;</a>
+                <a class="pilcrow" href="#section-23">&#182;</a>
               </div>
               <p>Store and load command history from a file</p>
 
@@ -447,11 +536,11 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-19">
+        <li id="section-24">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-19">&#182;</a>
+                <a class="pilcrow" href="#section-24">&#182;</a>
               </div>
               <p>Get file info and at most maxSize of command history</p>
 
@@ -463,11 +552,11 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-20">
+        <li id="section-25">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-20">&#182;</a>
+                <a class="pilcrow" href="#section-25">&#182;</a>
               </div>
               <p>Read last <code>size</code> bytes from the file</p>
 
@@ -481,81 +570,95 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-21">
+        <li id="section-26">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-21">&#182;</a>
+                <a class="pilcrow" href="#section-26">&#182;</a>
               </div>
               <p>Set the history on the interpreter</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>    repl.rli.history = buffer.toString().split(<span class="hljs-string">'\n'</span>).reverse()</pre></div></div>
+            <div class="content"><div class='highlight'><pre>    repl.history = buffer.toString().split(<span class="hljs-string">'\n'</span>).reverse()</pre></div></div>
             
         </li>
         
         
-        <li id="section-22">
+        <li id="section-27">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-22">&#182;</a>
+                <a class="pilcrow" href="#section-27">&#182;</a>
               </div>
               <p>If the history file was truncated we should pop off a potential partial line</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>    repl.rli.history.pop() <span class="hljs-keyword">if</span> stat.size &gt; maxSize</pre></div></div>
+            <div class="content"><div class='highlight'><pre>    repl.history.pop() <span class="hljs-keyword">if</span> stat.size &gt; maxSize</pre></div></div>
             
         </li>
         
         
-        <li id="section-23">
+        <li id="section-28">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-23">&#182;</a>
+                <a class="pilcrow" href="#section-28">&#182;</a>
               </div>
               <p>Shift off the final blank newline</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>    repl.rli.history.shift() <span class="hljs-keyword">if</span> repl.rli.history[<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">''</span>
-    repl.rli.historyIndex = <span class="hljs-number">-1</span>
-    lastLine = repl.rli.history[<span class="hljs-number">0</span>]
+            <div class="content"><div class='highlight'><pre>    repl.history.shift() <span class="hljs-keyword">if</span> repl.history[<span class="hljs-number">0</span>] <span class="hljs-keyword">is</span> <span class="hljs-string">''</span>
+    repl.historyIndex = <span class="hljs-number">-1</span>
+    lastLine = repl.history[<span class="hljs-number">0</span>]
 
   fd = fs.openSync filename, <span class="hljs-string">'a'</span>
 
-  repl.rli.addListener <span class="hljs-string">'line'</span>, <span class="hljs-function"><span class="hljs-params">(code)</span> -&gt;</span>
+  repl.addListener <span class="hljs-string">'line'</span>, <span class="hljs-function"><span class="hljs-params">(code)</span> -&gt;</span>
     <span class="hljs-keyword">if</span> code <span class="hljs-keyword">and</span> code.length <span class="hljs-keyword">and</span> code <span class="hljs-keyword">isnt</span> <span class="hljs-string">'.history'</span> <span class="hljs-keyword">and</span> code <span class="hljs-keyword">isnt</span> <span class="hljs-string">'.exit'</span> <span class="hljs-keyword">and</span> lastLine <span class="hljs-keyword">isnt</span> code</pre></div></div>
             
         </li>
         
         
-        <li id="section-24">
+        <li id="section-29">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-24">&#182;</a>
+                <a class="pilcrow" href="#section-29">&#182;</a>
               </div>
               <p>Save the latest command in the file</p>
 
             </div>
             
             <div class="content"><div class='highlight'><pre>      fs.writeSync fd, <span class="hljs-string">"<span class="hljs-subst">#{code}</span>\n"</span>
-      lastLine = code
+      lastLine = code</pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-30">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-30">&#182;</a>
+              </div>
+              <p>XXX: The SIGINT event from REPLServer is undocumented, so this is a bit fragile</p>
 
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>  repl.<span class="hljs-literal">on</span> <span class="hljs-string">'SIGINT'</span>, <span class="hljs-function">-&gt;</span> sawSIGINT = <span class="hljs-literal">yes</span>
   repl.<span class="hljs-literal">on</span> <span class="hljs-string">'exit'</span>, <span class="hljs-function">-&gt;</span> fs.closeSync fd</pre></div></div>
             
         </li>
         
         
-        <li id="section-25">
+        <li id="section-31">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-25">&#182;</a>
+                <a class="pilcrow" href="#section-31">&#182;</a>
               </div>
               <p>Add a command to show the history stack</p>
 
@@ -564,7 +667,7 @@ Unwrap that too.</p>
             <div class="content"><div class='highlight'><pre>  repl.commands[getCommandId(repl, <span class="hljs-string">'history'</span>)] =
     help: <span class="hljs-string">'Show command history'</span>
     action: <span class="hljs-function">-&gt;</span>
-      repl.outputStream.write <span class="hljs-string">"<span class="hljs-subst">#{repl.rli.history[..].reverse().join <span class="hljs-string">'\n'</span>}</span>\n"</span>
+      repl.outputStream.write <span class="hljs-string">"<span class="hljs-subst">#{repl.history[..].reverse().join <span class="hljs-string">'\n'</span>}</span>\n"</span>
       repl.displayPrompt()
 <span class="hljs-function">
 <span class="hljs-title">getCommandId</span> = <span class="hljs-params">(repl, commandName)</span> -&gt;</span></pre></div></div>
@@ -572,11 +675,11 @@ Unwrap that too.</p>
         </li>
         
         
-        <li id="section-26">
+        <li id="section-32">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-26">&#182;</a>
+                <a class="pilcrow" href="#section-32">&#182;</a>
               </div>
               <p>Node 0.11 changed API, a command such as ‘.help’ is now stored as ‘help’</p>
 
@@ -595,21 +698,62 @@ Unwrap that too.</p>
 
     CoffeeScript.register()
     process.argv = [<span class="hljs-string">'coffee'</span>].concat process.argv[<span class="hljs-number">2.</span>.]
+    <span class="hljs-keyword">if</span> opts.transpile
+      transpile = {}
+      <span class="hljs-keyword">try</span>
+        transpile.transpile = <span class="hljs-built_in">require</span>(<span class="hljs-string">'@babel/core'</span>).transform
+      <span class="hljs-keyword">catch</span>
+        <span class="hljs-keyword">try</span>
+          transpile.transpile = <span class="hljs-built_in">require</span>(<span class="hljs-string">'babel-core'</span>).transform
+        <span class="hljs-keyword">catch</span>
+          <span class="hljs-built_in">console</span>.error <span class="hljs-string">'''
+            To use --transpile with an interactive REPL, @babel/core must be installed either in the current folder or globally:
+              npm install --save-dev @babel/core
+            or
+              npm install --global @babel/core
+            And you must save options to configure Babel in one of the places it looks to find its options.
+            See https://coffeescript.org/#transpilation
+          '''</span>
+          process.exit <span class="hljs-number">1</span>
+      transpile.options =
+        filename: path.resolve process.cwd(), <span class="hljs-string">'&lt;repl&gt;'</span></pre></div></div>
+            
+        </li>
+        
+        
+        <li id="section-33">
+            <div class="annotation">
+              
+              <div class="pilwrap ">
+                <a class="pilcrow" href="#section-33">&#182;</a>
+              </div>
+              <p>Since the REPL compilation path is unique (in <code>eval</code> above), we need
+another way to get the <code>options</code> object attached to a module so that
+it knows later on whether it needs to be transpiled. In the case of
+the REPL, the only applicable option is <code>transpile</code>.</p>
+
+            </div>
+            
+            <div class="content"><div class='highlight'><pre>      Module = <span class="hljs-built_in">require</span> <span class="hljs-string">'module'</span>
+      originalModuleLoad = Module::load
+      Module::load = <span class="hljs-function"><span class="hljs-params">(filename)</span> -&gt;</span>
+        @options = transpile: transpile.options
+        originalModuleLoad.call @, filename
     opts = merge replDefaults, opts
     repl = nodeREPL.start opts
     runInContext opts.prelude, repl.context, <span class="hljs-string">'prelude'</span> <span class="hljs-keyword">if</span> opts.prelude
-    repl.<span class="hljs-literal">on</span> <span class="hljs-string">'exit'</span>, <span class="hljs-function">-&gt;</span> repl.outputStream.write <span class="hljs-string">'\n'</span> <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> repl.rli.closed
+    repl.<span class="hljs-literal">on</span> <span class="hljs-string">'exit'</span>, <span class="hljs-function">-&gt;</span> repl.outputStream.write <span class="hljs-string">'\n'</span> <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> repl.closed
     addMultilineHandler repl
     addHistory repl, opts.historyFile, opts.historyMaxInputSize <span class="hljs-keyword">if</span> opts.historyFile</pre></div></div>
             
         </li>
         
         
-        <li id="section-27">
+        <li id="section-34">
             <div class="annotation">
               
               <div class="pilwrap ">
-                <a class="pilcrow" href="#section-27">&#182;</a>
+                <a class="pilcrow" href="#section-34">&#182;</a>
               </div>
               <p>Adapt help inherited from the node REPL</p>
 

docs/v2/annotated-source/scope.html

@@ -139,12 +139,14 @@ with external scopes.</p>
 as well as a reference to the <strong>Block</strong> node it belongs to, which is
 where it should declare its variables, a reference to the function that
 it belongs to, and a list of variables referenced in the source code
-and therefore should be avoided when generating variables.</p>
+and therefore should be avoided when generating variables. Also track comments
+that should be output as part of variable declarations.</p>
 
             </div>
             
             <div class="content"><div class='highlight'><pre>  constructor: <span class="hljs-function"><span class="hljs-params">(@parent, @expressions, @method, @referencedVars)</span> -&gt;</span>
     @variables = [{name: <span class="hljs-string">'arguments'</span>, type: <span class="hljs-string">'arguments'</span>}]
+    @comments  = {}
     @positions = {}
     @utilities = {} <span class="hljs-keyword">unless</span> @parent</pre></div></div>
             

docs/v2/annotated-source/sourcemap.html

@@ -370,15 +370,22 @@ column for the current line:</p>
 
             </div>
             
-            <div class="content"><div class='highlight'><pre>    v3 =
+            <div class="content"><div class='highlight'><pre>    sources = <span class="hljs-keyword">if</span> options.sourceFiles
+      options.sourceFiles
+    <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> options.filename
+      [options.filename]
+    <span class="hljs-keyword">else</span>
+      [<span class="hljs-string">'&lt;anonymous&gt;'</span>]
+
+    v3 =
       version:    <span class="hljs-number">3</span>
       file:       options.generatedFile <span class="hljs-keyword">or</span> <span class="hljs-string">''</span>
       sourceRoot: options.sourceRoot <span class="hljs-keyword">or</span> <span class="hljs-string">''</span>
-      sources:    options.sourceFiles <span class="hljs-keyword">or</span> [<span class="hljs-string">''</span>]
+      sources:    sources
       names:      []
       mappings:   buffer
 
-    v3.sourcesContent = [code] <span class="hljs-keyword">if</span> options.inlineMap
+    v3.sourcesContent = [code] <span class="hljs-keyword">if</span> options.sourceMap <span class="hljs-keyword">or</span> options.inlineMap
 
     v3</pre></div></div>
             

docs/v2/announcing-coffeescript-2/index.html

@@ -0,0 +1,351 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=UTF-8" />
+<title>Announcing CoffeeScript 2</title>
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<link rel="canonical" href="http://coffeescript.org" />
+
+<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
+<link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
+<link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
+<link rel="manifest" href="/manifest.json">
+<link rel="mask-icon" href="/safari-pinned-tab.svg" color="#5bbad5">
+<meta name="theme-color" content="#ffffff">
+
+<link href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-beta/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-/Y6pD6FV/Vv2HJnA6t+vslU6fwYXjCFtcEpHbNJ0lyAFsXTsjBbfaDjzALeQsN6M" crossorigin="anonymous">
+<link href="https://fonts.googleapis.com/css?family=Alegreya+Sans:400,800|Galada:400|Lato:300,300i,400,700|Roboto+Mono:400,400i" rel="stylesheet" crossorigin="anonymous">
+<style>
+body {
+  /* Push below header bar */
+  margin-top: 3.5rem;
+  background-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1 3"><path opacity=".02" fill="#000" d="M0 0h1v1H0z"/><path opacity=".005" fill="#000" d="M0 1h1v2H0z"/></svg>');
+  background-size: 1px 3px;
+}
+
+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;
+}
+
+button:focus, .navbar-dark .navbar-toggler:focus {
+  outline: none;
+  border: thin solid rgba(248, 243, 240, 0.3);
+}
+
+.bg-dark {
+  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
+ */
+.site-navbar {
+  height: 3.5rem;
+  font-family: 'Lato';
+  font-weight: 400;
+  font-size: 1.1em;
+}
+
+.navbar-brand {
+  height: 2.2em;
+  margin-right: 1em;
+}
+
+.navbar-dark path {
+  fill: #fff;
+}
+
+.navbar-nav .nav-item {
+  margin-left: 0.6em;
+  margin-right: 0.6em;
+  border-radius: 0.4em;
+}
+.navbar-nav .nav-item:hover,
+.navbar-nav .nav-item:active,
+.navbar-nav .nav-item.show {
+  background-color: #4e342e;
+}
+
+.navbar-toggler {
+  transition: all 0.1s ease-in-out;
+}
+
+
+/*
+ * Main content
+ */
+
+.main {
+  padding: 1.3em;
+}
+@media (min-width: 992px) {
+  .main {
+    padding-right: 2em;
+    padding-left: 2em;
+  }
+}
+
+h1 {
+  font: 2.5em Galada;
+  color: #2f2625;
+  text-align: center;
+}
+@media (min-width: 768px) {
+  h1 {
+    font-size: 3em;
+  }
+}
+@media (min-width: 992px) {
+  h1 {
+    font-size: 4em;
+  }
+}
+
+.title-logo {
+  display: inline-block;
+  height: 1em;
+  transform: translateY(0.2em);
+  margin-left: 0.3em;
+  margin-right: 0.25em;
+  fill: #2f2625;
+}
+
+.main p, .main li {
+  font-family: Lato;
+  font-weight: 300;
+  font-size: 1.1em;
+  line-height: 1.6;
+}
+.main blockquote {
+  font-size: 1.1em;
+}
+@media (min-width: 768px) {
+  .main p, .main li {
+    font-size: 1.3em;
+  }
+  .main blockquote {
+    font-size: 1.3em;
+  }
+}
+.main strong {
+  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 pre {
+  background-color: #f8f3f0;
+  color: #2f2625;
+  border-radius: .3em;
+  padding: 0.4em 0.6em;
+}
+
+p, blockquote, li {
+  margin-bottom: 1.3rem;
+}
+.credits li {
+  margin-bottom: 0.3em;
+}
+
+h2, h3, h4 {
+  margin-top: 1.3em;
+  margin-bottom: 0.6em;
+  font-family: 'Alegreya Sans';
+}
+h2 {
+  font-weight: 800;
+}
+h3, h4, h2 time {
+  font-weight: 400;
+}
+
+.main h2 {
+  padding-top: 4rem;
+  margin-top: -4rem;
+}
+
+code {
+  font-family: 'Roboto Mono';
+  font-weight: 400;
+}
+code, a > code {
+  background-color: #f8f3f0;
+  padding: 0.2rem 0.4rem;
+}
+code {
+  color: #2f2625;
+}
+
+
+.uneditable-code-block .comment {
+  font-style: italic;
+  color: #837B85;
+}
+.uneditable-code-block .class,
+.uneditable-code-block .function,
+.uneditable-code-block .keyword,
+.uneditable-code-block .reserved,
+.uneditable-code-block .title {
+  color: #534328;
+}
+.uneditable-code-block .string
+.uneditable-code-block .value
+.uneditable-code-block .inheritance
+.uneditable-code-block .header {
+  color: #3A4029;
+}
+.uneditable-code-block .variable,
+.uneditable-code-block .literal,
+.uneditable-code-block .tag,
+.uneditable-code-block .regexp,
+.uneditable-code-block .subst,
+.uneditable-code-block .property {
+  color: #474429;
+}
+.uneditable-code-block .number,
+.uneditable-code-block .preprocessor,
+.uneditable-code-block .built_in,
+.uneditable-code-block .params,
+.uneditable-code-block .constant {
+  color: #474429;
+}
+</style>
+
+</head>
+<body>
+
+<nav class="navbar navbar-expand-lg fixed-top navbar-dark bg-dark bg-ribbed-dark site-navbar">
+  <a class="navbar-brand" href="/" data-close="try"><svg xmlns="http://www.w3.org/2000/svg" viewBox="-22 347 566 100">
+  <title>
+    CoffeeScript Logo
+  </title>
+  <path d="M21.7 351.1c.1.6-.2 1.1-1.2 1.6-1.3-.7-4.1-1.1-6.4-.9-2.5.2-4.6 1-4.3 2.7.4 1.7 2.8 2.7 7.1 2.3 10.5-.9 10.4-8 25.8-9.4 12-1.1 18.7 2.6 19.6 7.1.7 3.5-2.2 6.9-10.9 7.6-7.7.7-12.2-1.4-12.6-3.5-.2-1.1.4-2.7 4.1-3.1.4 1.7 2.5 3.5 7.5 3 3.6-.3 6.6-1.6 6.2-3.6-.4-2.1-4.2-3.3-10.2-2.8-12.2 1.1-15.2 7.8-25.6 8.7-7.4.7-13.4-2-14.2-6-.3-1.5-.3-5 7.5-5.7 4-.3 7.2.4 7.6 2zm-39 41.8c-3.4 4.3-4.9 9.3-4.6 14.2.3 4.9 2.7 8.9 6.5 12 4 3.1 8.3 4 13.2 3.1 1.9-.3 4-1.3 5.9-1.9-4 0-7.4-1.3-10.8-4-3.7-2.7-6.2-6.5-6.8-11.1-.9-4.3 0-8.3 2.4-11.8 2.7-3.4 6.2-5.3 10.8-5.9 4.6-.3 8.6.9 12.6 3.7-.9-1.3-2.2-2.2-3.4-3.4-4-2.7-8.3-4-13.6-2.7-4.8 1-8.8 3.5-12.2 7.8zm53.6-23.1c-12.9 0-24.4-1.3-32.7-3.1-8.9-2.2-13.6-4.6-13.6-7.7 0-1.3.6-2.4 2.4-3.7-5.6 2.2-8.6 4-8.6 6.8.3 3.1 5.3 6.2 15.5 8.6 9.6 2.4 21.9 3.7 36.7 3.7 15.1 0 27.1-1.3 36.7-3.7 10.2-2.4 15.1-5.6 15.1-8.6 0-2.2-2.2-4.3-6.2-5.9.9.6 1.6 1.6 1.6 2.7 0 3.1-4.6 5.6-13.9 7.7-8.6 1.9-19.6 3.2-33 3.2zm36.8 8.6c-9.6 2.2-21.9 3.7-36.7 3.7-15.1 0-27.4-1.6-37-3.7-8.6-2.2-13.2-4.6-14.8-7.1 1.6 10.8 5.3 21 10.2 30 3.7 5.6 7.4 10.5 11.1 15.8 1.6 3.1 2.7 6.2 3.4 9.3 2.4 3.4 5.9 5.6 10.2 6.8 5.3 1.9 10.8 2.7 16.4 2.4h.6c5.6.3 11.5-.6 16.9-2.4 4-1.3 7.4-3.4 9.9-6.8h.3c.6-3.1 1.6-6.2 3.1-9.3 3.7-5.3 7.4-10.2 11.1-15.8 4.9-8.9 8.3-19.1 10.2-30-2 2.8-6.6 5.2-14.9 7.1zm106.2 30.1c-4.8 12.1-17.6 16.9-25.9 16.9-13.4 0-19.9-6-19.9-22.3 0-16.5 7.9-47.3 31.7-47.3 8.5 0 15.2 3.3 15.2 12.1 0 4.8-1.8 8.3-6.4 8.3-1.5 0-3.4-.4-5.2-2.4 2.2-1.1 4.2-4.9 4.2-8.3 0-2.9-1.5-5.6-5.6-5.6-10 0-18.9 23.9-18.9 42.4 0 8.3 2.2 14.2 10.9 14.2 7.1 0 13.5-3.4 17.7-9.1l2.2 1.1zm32.9-16.3c.4.2.7.2 1 .2 4.2 0 10.1-2.7 14-5.5l.8 2.4c-3.4 3.7-9.5 6.5-16.1 7.5-1.5 16.8-10.6 27.3-21.7 27.3-8.4 0-14.5-4-14.5-14.4 0-10.5 6.2-32.2 24.9-32.2 7.8.3 11.6 5.3 11.6 14.7zm-7.7 5c-1.9-.5-2.4-2-2.4-3.8 0-2.5 1.2-4.2 2.8-4.9-.2-3.8-1.1-5.3-3.4-5.3-6.5 0-12 16.6-12 25.6 0 6 1.2 7.3 4.6 7.3 4.2.1 8.9-8 10.4-18.9zm-6.6 39.7c0-8.3 7.1-11 15.8-13.6l10.9-51.9c2.7-13 10.6-15.5 16.5-15.5 4.1 0 8 2.2 9.7 5.7 3.6-4.6 8.4-5.7 12.4-5.7 5.6 0 10.8 3.9 10.8 9.8 0 1.5-.1 2.6-.3 3.7h-4.3c.1-.9.2-1.7.2-2.4 0-2.1-1.7-3.1-3.4-3.1-2 0-4.8 1.1-6.2 7.1l-1.7 7.4h9.1l-.8 3.6h-9l-10.3 49.1c-2.7 13-10.6 15.5-16.5 15.5-5.2 0-8.3-2.3-9.8-5.7-3.5 4.6-8.3 5.7-12.3 5.7-5.6.1-10.8-3.8-10.8-9.7zm9.1 1.8c1.9 0 4.2-1.8 5.4-7.1l1.1-5.3c-5.7 2-10.1 4.4-10.1 9.4 0 1.2 1.7 3 3.6 3zm21.7 0c1.9 0 4.2-1.8 5.4-7.1l2.2-10.4-9.4 1.8-1.8 8.3c-.5 2.1-1.1 4-1.8 5.6.9 1.3 3 1.8 5.4 1.8zm-1.4-18l9.4-1.7 7.7-36.8h-9l-8.1 38.5zm16.6-56.7c-2 0-4.8 1.1-6.2 7.1l-1.7 7.4h9l2.1-9.5c.2-.7.2-1.3.2-2 .1-2-1.5-3-3.4-3zm37.9 53c7.1 0 11.6-4 16.1-9.2h3.1c-5.2 8.3-12.9 16.8-25 16.8-8.5 0-14.2-4.2-14.2-14.5 0-10.5 5.9-32.3 24.6-32.3 8.1 0 10 4.2 10 8.7 0 10.5-10 18.5-20.9 19.2-.1 1.3-.2 2.5-.2 3.6 0 6.2 2.2 7.7 6.5 7.7zm5.3-34.4c-4.6 0-9.1 9.7-10.9 18.7 7-.5 13.2-7.4 13.2-15 0-2.2-.5-3.7-2.3-3.7zm28.6 33.4c3.4 0 7.8-2.3 10.8-4.8-2 10.4-8.4 13.4-15.8 13.4-8.4 0-14.1-4.2-14.1-14.5 0-10.5 5.9-32.3 24.6-32.3 8.1 0 10 4.2 10 8.7 0 10.6-10 18.5-20.9 19.2-.1.9-.2 2-.2 2.7 0 5.7 2.5 7.6 5.6 7.6zm6.2-33.4c-4.5 0-9.1 10.1-11 18.7 7.1-.4 13.3-7.3 13.3-15 0-2.2-.6-3.7-2.3-3.7zm51.3-6.7c-1.7 0-3-.6-4.2-1.9 2.4-1.5 4.1-4.8 4.1-7.8 0-3.1-1.8-6.1-6.8-6.1s-8.3 2.8-8.3 8.2c0 13.3 20.5 15.2 20.5 34.8 0 15.3-12.3 22.7-25.6 22.7-10.4 0-19.3-4.5-19.3-15.7 0-9.8 7-14.9 13.3-14.9 3.1 0 7.7 1.3 8 6-4.9 0-10.7 2.3-10.7 8.5 0 4.5 2.9 8.7 8.7 8.7 6.1 0 10.6-4.4 10.6-12 0-15.6-18.6-21.1-18.6-34.5 0-9.5 9.3-16.3 21-16.3 4.3 0 14.6.9 14.6 10.9.1 5.5-2.8 9.4-7.3 9.4zm36.2 10.3c0-2.3-.8-3.7-2.5-3.7-5.7 0-11.7 16.6-11.7 26.7 0 6.2 2.2 7.6 6.6 7.6 7.1 0 11.6-4 16.1-9.2h3.1c-5.2 8.3-12.9 16.8-25 16.8-8.5 0-14.2-4.2-14.2-14.5 0-10.6 6-32.3 24.5-32.3 8.1 0 10.1 4.2 10.1 8.3 0 4.4-2.2 6.7-4.8 6.7-1 0-2.1-.4-3.1-1.1.5-1.9.9-3.6.9-5.3zm27.7-7.6l-1.2 5.7c3.1-2.7 6.7-5.7 11-5.7 4.1 0 6.3 3.3 6.3 6.9 0 3.1-2.1 6.7-6.6 6.7-5.1 0-2.5-6-5.3-6-2.7 0-4.4 1.4-6.7 3.4l-7.2 34.6h-13.1l9.6-45.4 13.2-.2zm34.2 0l-6.6 30.9c-.3 1.2-.4 2.1-.4 2.9 0 2.5 1.2 3.3 3.7 3.3 3.5 0 6.9-3.4 8.1-8h3.8c-5.2 14.8-14.2 16.8-19.1 16.8-5.5 0-9.7-3.2-9.7-10.9 0-1.8.3-3.7.7-5.9l6.2-29.2 13.3.1zm-4.1-19.4c4 0 7.2 3.2 7.2 7.2s-3.2 7.1-7.2 7.1-7.1-3.1-7.1-7.1c-.1-4 3.2-7.2 7.1-7.2zm29.1 16l-1.5 6.9c2.6-2.3 6.1-3.9 10.7-3.9 6.2 0 11.1 3.5 11.1 14.4 0 12.2-4.7 32.1-22.3 32.1-4.5 0-6.8-1.6-7.7-3.2l-4.7 22.1-13.7 3.2 15.2-71.5 12.9-.1zm7.8 17c0-7-2.9-7.5-4.5-7.5-2 0-4.5 1.6-6.3 4.4l-5.4 25.5c.4 1 1.4 2.1 3.4 2.1 9.7 0 12.8-15.9 12.8-24.5zm27.8 17.3c-.3 1.1-.5 2.2-.5 3.1 0 1.9.7 3.2 3.1 3.2.7 0 1.7 0 2.4-.3-2.5 7.8-6.6 8.9-9.6 8.9-6.4 0-9.1-4.4-9.1-10.3 0-1.6.2-3.1.6-4.8l5.8-27.2h-3l.7-3.6h3L528 366l13.4-1.9s-1.4 6.2-3.1 14.4h5.5l-.7 3.6h-5.5l-5.7 27.4z"/>
+</svg>
+</a>
+  <button class="navbar-toggler" type="button" data-toggle="offcanvas" data-close="try" aria-label="Toggle sidebar">
+    <span class="navbar-toggler-icon"></span>
+  </button>
+
+  <nav class="collapse navbar-collapse">
+    <div class="navbar-nav mr-auto d-none d-lg-flex">
+      <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="https://github.com/jashkenas/coffeescript" class="nav-item nav-link" data-close="try">GitHub
+        </a>
+    </div>
+  </nav>
+</nav>
+
+
+<div class="container" id="top">
+  <div class="row">
+    <main class="main">
+      <header>
+        <h1>Announcing <span class="text-nowrap"><svg class="title-logo" xmlns="http://www.w3.org/2000/svg" viewBox="-76 212 458 369">
+          <title>
+            CoffeeScript Icon
+          </title>
+          <path d="M106 228.6c.5 2.3-.9 4.4-5 6.5-5.5-3.1-16.9-4.4-26.7-3.5-10.4.9-19.4 4.2-17.9 11.3 1.5 7.1 11.7 11 29.5 9.5 43.6-3.8 43.4-33.3 107.4-39 49.8-4.4 77.8 11 81.8 29.7 3.1 14.7-9.1 28.6-45.2 31.8-32 2.8-50.7-5.6-52.6-14.6-1-4.5 1.8-11.3 17.2-13.1 1.5 7 10.6 14.4 31.1 12.6 14.8-1.3 27.6-6.6 25.9-14.9-1.8-8.6-17.7-13.7-42.6-11.5-50.7 4.5-63.2 32.5-106.8 36.3-30.8 2.7-55.9-8.5-59.4-25.1-1.3-6.1-1.4-21 31.2-23.9 17.1-1.5 30.7 1.5 32.1 7.9zM-56.4 402.5c-14.3 18-20.4 38.8-19.2 59.2 1.2 20.4 11.4 37.1 26.9 50.2C-32 525-14 528.6 6.4 525c7.8-1.2 16.7-5.3 24.5-7.8-16.7 0-31-5.3-44.9-16.7-15.5-11.4-25.7-26.9-28.2-46.1-3.7-18 0-34.7 10.2-49 11.4-14.3 25.7-22 44.9-24.5 19.2-1.2 35.9 3.7 52.6 15.5-3.7-5.3-9-9-14.3-14.3-16.7-11.4-34.7-16.7-56.7-11.4-19.9 3.6-36.7 13.8-50.9 31.8zm223.6-96.3c-53.9 0-101.6-5.3-136.3-13.1-37.1-9-56.7-19.2-56.7-32.2 0-5.3 2.4-10.2 10.2-15.5-23.3 9-35.9 16.7-35.9 28.2 1.2 13.1 22 25.7 64.5 35.9 40 10.2 91.4 15.5 153 15.5 62.8 0 113-5.3 153-15.5 42.4-10.2 62.8-23.3 62.8-35.9 0-9-9-18-25.7-24.5 3.7 2.4 6.5 6.5 6.5 11.4 0 13.1-19.2 23.3-57.9 32.2-36 8.2-82.1 13.5-137.5 13.5zm153 35.9c-40 9-91.4 15.5-153 15.5-62.8 0-114.2-6.5-154.2-15.5-35.9-9-55.1-19.2-61.6-29.4 6.5 44.9 22 87.3 42.4 124.8 15.5 23.3 31 43.7 46.1 65.7 6.5 13.1 11.4 25.7 14.3 38.8 10.2 14.3 24.5 23.3 42.4 28.2 22 7.8 44.9 11.4 68.1 10.2h2.4c23.3 1.2 47.7-2.4 70.6-10.2 16.7-5.3 31-14.3 41.2-28.2h1.2c2.4-13.1 6.5-25.7 13.1-38.8 15.5-22 31-42.4 46.1-65.7 20.4-37.1 34.7-79.6 42.4-124.8-7.7 11.4-26.9 21.6-61.5 29.4z"/>
+        </svg> CoffeeScript 2</span></h1>
+      </header>
+      <section>
+<p>We are pleased to announce CoffeeScript 2! This new release of the CoffeeScript language and compiler aims to bring CoffeeScript into the modern JavaScript era, closing gaps in compatibility with JavaScript while preserving the clean syntax that is CoffeeScript’s hallmark. In a nutshell:</p>
+<ul>
+<li>The CoffeeScript 2 compiler now translates CoffeeScript code into modern JavaScript syntax. So a CoffeeScript <code>=&gt;</code> is now output as <code>=&gt;</code>, a CoffeeScript <code>class</code> is now output using the <code>class</code> keyword, and so on. This means you may need to <a href="../#transpilation">transpile the CoffeeScript compiler’s output</a>.</li>
+<li>CoffeeScript 2 adds support for <a href="../#async-functions">async functions</a> syntax, for the future <a href="../#destructuring">object destructuring</a> syntax, and for <a href="../#jsx">JSX</a>. Some features, such as <a href="../#modules">modules</a> (<code>import</code> and <code>export</code> statements), <a href="../#generator-iteration"><code>for…of</code></a>, and <a href="../#tagged-template-literals">tagged template literals</a> were backported into CoffeeScript versions 1.11 and 1.12.</li>
+<li>All of the above was achieved with very few <a href="../#breaking-changes">breaking changes from 1.x</a>. Most current CoffeeScript projects should be able to upgrade with little or no refactoring necessary.</li>
+</ul>
+<p>CoffeeScript 2 was developed with two primary goals: remove any incompatibilities with modern JavaScript that might prevent CoffeeScript from being used on a project; and preserve as much backward compatibility as possible. <a href="../#installation">Install now</a>: <code>npm install -g coffeescript@2</code></p>
+<h2 id="modern-javascript-output">Modern JavaScript Output</h2>
+<p>From the beginning, CoffeeScript has been described as being “just JavaScript.” And today, JavaScript is ES2015 (well, ES2017; also commonly known as ES6). CoffeeScript welcomes the changes in the JavaScript world and we’re happy to stop outputting circa-1999 syntax for modern features.</p>
+<p>Many new JavaScript features, such as <code>=&gt;</code>, were informed by CoffeeScript and are one-to-one compatible, or very nearly so. This has made outputting many of CoffeeScript’s innovations into new JS syntax straightforward: not only does <code>=&gt;</code> become <code>=&gt;</code>, but <code>{ a } = obj</code> becomes <code>{ a } = obj</code>, <code>&quot;a#{b}c&quot;</code> becomes <code>`a${b}c`</code> and so on.</p>
+<p>The following CoffeeScript features were updated in 2.0 to output using modern JavaScript syntax (or added in CoffeeScript 1.11 through 2.0, output using modern syntax):</p>
+<ul>
+<li>Modules: <code>import</code>/<code>export</code></li>
+<li>Classes: <code>class Animal</code></li>
+<li>Async functions: <code>await someFunction()</code></li>
+<li>Bound/arrow functions: <code>=&gt;</code></li>
+<li>Function default parameters: <code>(options = {}) -&gt;</code></li>
+<li>Function splat/rest parameters: <code>(items...) -&gt;</code></li>
+<li>Destructuring, for both arrays and objects: <code>[first, second] = items</code>, <code>{length} = items</code></li>
+<li>Object rest/spread properties: <code>{options..., force: yes}</code>, <code>{force, otherOptions...} = options</code></li>
+<li>Interpolated strings/template literals (JS backticked strings): <code>&quot;Hello, #{user}!&quot;</code></li>
+<li>Tagged template literals: <code>html&quot;&lt;strong&gt;coffee&lt;/strong&gt;&quot;</code></li>
+<li>JavaScript’s <code>for…of</code> is now available as CoffeeScript’s <code>for…from</code> (we already had a <code>for…of</code>): <code>for n from generatorFunction()</code></li>
+</ul>
+<p>Not all CoffeeScript features were adopted into JavaScript in 100% the same way; most notably, <a href="../#breaking-changes-default-values">default values</a> in JavaScript (and also in CoffeeScript 2) are only applied when a variable is <code>undefined</code>, not <code>undefined</code> or <code>null</code> as in CoffeeScript 1; and <a href="../#breaking-changes-classes">classes</a> have their own differences. See the <a href="../#breaking-changes">breaking changes</a> for the fine details.</p>
+<p>In our experience, most breaking changes are edge cases that should affect very few people, like JavaScript’s <a href="../#breaking-change-fat-arrow">lack of an <code>arguments</code> object inside arrow functions</a>. There seem to be two breaking changes that affect a significant number of projects:</p>
+<ul>
+<li>In CoffeeScript 2, “bare” <code>super</code> (calling <code>super</code> without arguments) is now no longer allowed, and one must use <code>super()</code> or <code>super arguments...</code> instead.</li>
+<li>References to <code>this</code>/<code>@</code> cannot occur before a call to <code>super</code>, per the JS spec.</li>
+</ul>
+<p>See the <a href="../#breaking-changes-super-extends">full details</a>. Either the CoffeeScript compiler or your transpiler will throw errors for either of these cases, so updating your code is a matter of fixing each occurrence as the compiler errors on it, until your code compiles successfully.</p>
+<h2 id="other-features">Other Features</h2>
+<p>Besides supporting new JavaScript features and outputting older CoffeeScript features in modern JS syntax, CoffeeScript 2 has added support for the following:</p>
+<ul>
+<li><a href="../#jsx">JSX</a></li>
+<li><a href="../#comments">Line comments</a> are now output (in CoffeeScript 1 they were discarded)</li>
+<li>Block comments are now allowed anywhere, enabling <a href="../#type-annotations">static type annotations</a> using Flow’s comment-based syntax</li>
+</ul>
+<p>There are many smaller improvements as well, such as to the <code>coffee</code> command-line tool. You can read all the details in the <a href="../#changelog">changelog</a> for the 2.0.0 betas.</p>
+<h2 id="what-about-…">“What About …?”</h2>
+<p>A few JavaScript features have been intentionally omitted from CoffeeScript. These include <code>let</code> and <code>const</code> (and <code>var</code>), named functions and the <code>get</code> and <code>set</code> keywords. These get asked about so often that we added a section to the docs called <a href="../#unsupported">Unsupported ECMAScript Features</a>. CoffeeScript’s lack of equivalents for these features does not affect compatibility or interoperability with JavaScript modules or libraries.</p>
+<h2 id="future-compatibility">Future Compatibility</h2>
+<p>Back when CoffeeScript 1 was created, ES2015 JavaScript and transpilers like <a href="http://babeljs.io/">Babel</a>, <a href="https://buble.surge.sh/">Bublé</a> or <a href="https://github.com/google/traceur-compiler">Traceur Compiler</a> were several years away. The CoffeeScript compiler itself had to do what today’s transpilers do, converting modern features like destructuring and arrow functions into equivalent lowest-common-denominator JavaScript.</p>
+<p>But transpilers exist now, and they do their job well. With them around, there’s no need for the CoffeeScript compiler to duplicate this functionality. All the CoffeeScript compiler needs to worry about now is converting the CoffeeScript version of new syntax into the JS version of that syntax, e.g. <code>&quot;Hello, #{name}!&quot;</code> into <code>`Hello, ${name}!`</code>. This makes adding support for new JavaScript features much easier than before.</p>
+<p>Most features added by ECMA in recent years haven’t required any updates at all in CoffeeScript. New global objects, or new methods on global objects, don’t require any updates on CoffeeScript’s part to work. Some proposed future JS features <em>do</em> involve new syntax, like <a href="https://github.com/tc39/proposal-class-fields">class fields</a>. We have adopted a policy of supporting new syntax only when it reaches Stage 4 in ECMA’s process, which means that the syntax is final and will be in the next ES release. On occasion we might support a <em>feature</em> before it has reached Stage 4, but output it using equivalent non-experimental syntax instead of the newly-proposed syntax; that’s what’s happening in 2.0.0 for <a href="../#splats">object destructuring</a>, where our output uses the same polyfill that Babel uses. When the new syntax is finalized, we will update our output to use the final syntax.</p>
+<h2 id="credits">Credits</h2>
+<p>The major features of 2.0.0 would not have been possible without the following people:</p>
+<ul class="credits">
+<li><a href="https://github.com/GeoffreyBooth">@GeoffreyBooth</a>: Organizer of the CoffeeScript 2 effort, developer for modules; arrow functions, function default parameters and function rest parameters output using ES2015 syntax; line comments output and block comments output anywhere; block embedded JavaScript via triple backticks; improved parsing of Literate CoffeeScript; and the new docs website.</li>
+<li><a href="https://github.com/connec">@connec</a>: Classes; destructuring; splats/rest syntax in arrays and function calls; and computed properties all output using ES2015 syntax.</li>
+<li><a href="https://github.com/GabrielRatener">@GabrielRatener</a>: Async functions.</li>
+<li><a href="https://github.com/xixixao">@xixixao</a>: JSX.</li>
+<li><a href="https://github.com/zdenko">@zdenko</a>: Object rest/spread properties (object destructuring).</li>
+<li><a href="https://github.com/greghuc">@greghuc</a>: Tagged template literals, interpolated strings output in ES2015 syntax.</li>
+<li><a href="https://github.com/atg">@atg</a>: ES2015 <code>for…of</code>, supported as CoffeeScript’s <code>for…from</code>.</li>
+<li><a href="https://github.com/lydell">@lydell</a> and <a href="https://github.com/jashkenas">@jashkenas</a>: Guidance, code reviews and feedback.</li>
+</ul>
+<p>See the full <a href="https://github.com/jashkenas/coffeescript/wiki/CoffeeScript-2-Honor-Roll">honor roll</a>.</p>
+<p>Thanks and we hope you enjoy CoffeeScript 2!</p>
+
+      </section>
+    </main>
+  </div>
+</div>
+
+<script async src="https://www.googletagmanager.com/gtag/js?id=UA-106156830-1"></script>
+<script>
+  window.dataLayer = window.dataLayer || [];
+  function gtag(){dataLayer.push(arguments)};
+  gtag('js', new Date());
+  gtag('config', 'UA-106156830-1');
+</script>
+</body>
+</html>

documentation/examples/array_comprehensions.coffee

@@ -1,8 +1,10 @@
 # Eat lunch.
+eat = (food) -> "#{food} eaten."
 eat food for food in ['toast', 'cheese', 'wine']
 
 # Fine five course dining.
 courses = ['greens', 'caviar', 'truffles', 'roast', 'cake']
+menu = (i, dish) -> "Menu Item #{i}: #{dish}" 
 menu i + 1, dish for dish, i in courses
 
 # Health conscious meal.

documentation/examples/array_spread.coffee

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

documentation/examples/async.coffee

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

documentation/examples/block_comment.coffee

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

documentation/examples/breaking_change_bound_generator_function.coffee

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

documentation/examples/breaking_change_destructuring_default_values.coffee

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

documentation/examples/breaking_change_fat_arrow.coffee

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

documentation/examples/breaking_change_function_parameter_default_values.coffee

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

documentation/examples/breaking_change_super_in_non-class_methods_refactor_with_apply.coffee

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

documentation/examples/breaking_change_super_in_non-class_methods_refactor_with_class.coffee

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

documentation/examples/breaking_change_super_this.coffee

@@ -0,0 +1,4 @@
+class B extends A
+  constructor: (arg) ->
+    super arg
+    @arg = arg

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/chaining.coffee

@@ -2,5 +2,5 @@ $ 'body'
 .click (e) ->
   $ '.box'
   .fadeIn 'fast'
-  .addClass '.active'
+  .addClass 'show'
 .css 'background', 'white'

documentation/examples/comment.coffee

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

documentation/examples/do.coffee

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

documentation/examples/dynamic_import.coffee

@@ -0,0 +1,10 @@
+# Your browser must support dynamic import to run this example.
+
+do ->
+  { run } = await import('./browser-compiler-modern/coffeescript.js')
+  run '''
+    if 5 < new Date().getHours() < 9
+      alert 'Time to make the coffee!'
+    else
+      alert 'Time to get some work done.'
+  '''

documentation/examples/existence_declared.coffee

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

documentation/examples/existence_undeclared.coffee

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

documentation/examples/get_set.coffee

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

documentation/examples/heregexes.coffee

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

documentation/examples/jsx.coffee

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

documentation/examples/modules.coffee

@@ -1,4 +1,4 @@
-import 'local-file.coffee'
+import './local-file.coffee'
 import 'coffeescript'
 
 import _ from 'underscore'

documentation/examples/object_spread.coffee

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

documentation/examples/objects_reserved.coffee

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

documentation/examples/splats.coffee

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

documentation/examples/static.coffee

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

documentation/examples/type_annotations.coffee

@@ -0,0 +1,10 @@
+# @flow
+
+###::
+type Obj = {
+  num: number,
+};
+###
+
+fn = (str ###: string ###, obj ###: Obj ###) ###: string ### ->
+  str + obj.num

documentation/images/logo.svg

@@ -1,6 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="-22 347 566 100">
-	<title>
-		CoffeeScript Logo
-	</title>
-	<path d="M21.7 351.1c.1.6-.2 1.1-1.2 1.6-1.3-.7-4.1-1.1-6.4-.9-2.5.2-4.6 1-4.3 2.7.4 1.7 2.8 2.7 7.1 2.3 10.5-.9 10.4-8 25.8-9.4 12-1.1 18.7 2.6 19.6 7.1.7 3.5-2.2 6.9-10.9 7.6-7.7.7-12.2-1.4-12.6-3.5-.2-1.1.4-2.7 4.1-3.1.4 1.7 2.5 3.5 7.5 3 3.6-.3 6.6-1.6 6.2-3.6-.4-2.1-4.2-3.3-10.2-2.8-12.2 1.1-15.2 7.8-25.6 8.7-7.4.7-13.4-2-14.2-6-.3-1.5-.3-5 7.5-5.7 4-.3 7.2.4 7.6 2zm-39 41.8c-3.4 4.3-4.9 9.3-4.6 14.2.3 4.9 2.7 8.9 6.5 12 4 3.1 8.3 4 13.2 3.1 1.9-.3 4-1.3 5.9-1.9-4 0-7.4-1.3-10.8-4-3.7-2.7-6.2-6.5-6.8-11.1-.9-4.3 0-8.3 2.4-11.8 2.7-3.4 6.2-5.3 10.8-5.9 4.6-.3 8.6.9 12.6 3.7-.9-1.3-2.2-2.2-3.4-3.4-4-2.7-8.3-4-13.6-2.7-4.8 1-8.8 3.5-12.2 7.8zm53.6-23.1c-12.9 0-24.4-1.3-32.7-3.1-8.9-2.2-13.6-4.6-13.6-7.7 0-1.3.6-2.4 2.4-3.7-5.6 2.2-8.6 4-8.6 6.8.3 3.1 5.3 6.2 15.5 8.6 9.6 2.4 21.9 3.7 36.7 3.7 15.1 0 27.1-1.3 36.7-3.7 10.2-2.4 15.1-5.6 15.1-8.6 0-2.2-2.2-4.3-6.2-5.9.9.6 1.6 1.6 1.6 2.7 0 3.1-4.6 5.6-13.9 7.7-8.6 1.9-19.6 3.2-33 3.2zm36.8 8.6c-9.6 2.2-21.9 3.7-36.7 3.7-15.1 0-27.4-1.6-37-3.7-8.6-2.2-13.2-4.6-14.8-7.1 1.6 10.8 5.3 21 10.2 30 3.7 5.6 7.4 10.5 11.1 15.8 1.6 3.1 2.7 6.2 3.4 9.3 2.4 3.4 5.9 5.6 10.2 6.8 5.3 1.9 10.8 2.7 16.4 2.4h.6c5.6.3 11.5-.6 16.9-2.4 4-1.3 7.4-3.4 9.9-6.8h.3c.6-3.1 1.6-6.2 3.1-9.3 3.7-5.3 7.4-10.2 11.1-15.8 4.9-8.9 8.3-19.1 10.2-30-2 2.8-6.6 5.2-14.9 7.1zm106.2 30.1c-4.8 12.1-17.6 16.9-25.9 16.9-13.4 0-19.9-6-19.9-22.3 0-16.5 7.9-47.3 31.7-47.3 8.5 0 15.2 3.3 15.2 12.1 0 4.8-1.8 8.3-6.4 8.3-1.5 0-3.4-.4-5.2-2.4 2.2-1.1 4.2-4.9 4.2-8.3 0-2.9-1.5-5.6-5.6-5.6-10 0-18.9 23.9-18.9 42.4 0 8.3 2.2 14.2 10.9 14.2 7.1 0 13.5-3.4 17.7-9.1l2.2 1.1zm32.9-16.3c.4.2.7.2 1 .2 4.2 0 10.1-2.7 14-5.5l.8 2.4c-3.4 3.7-9.5 6.5-16.1 7.5-1.5 16.8-10.6 27.3-21.7 27.3-8.4 0-14.5-4-14.5-14.4 0-10.5 6.2-32.2 24.9-32.2 7.8.3 11.6 5.3 11.6 14.7zm-7.7 5c-1.9-.5-2.4-2-2.4-3.8 0-2.5 1.2-4.2 2.8-4.9-.2-3.8-1.1-5.3-3.4-5.3-6.5 0-12 16.6-12 25.6 0 6 1.2 7.3 4.6 7.3 4.2.1 8.9-8 10.4-18.9zm-6.6 39.7c0-8.3 7.1-11 15.8-13.6l10.9-51.9c2.7-13 10.6-15.5 16.5-15.5 4.1 0 8 2.2 9.7 5.7 3.6-4.6 8.4-5.7 12.4-5.7 5.6 0 10.8 3.9 10.8 9.8 0 1.5-.1 2.6-.3 3.7h-4.3c.1-.9.2-1.7.2-2.4 0-2.1-1.7-3.1-3.4-3.1-2 0-4.8 1.1-6.2 7.1l-1.7 7.4h9.1l-.8 3.6h-9l-10.3 49.1c-2.7 13-10.6 15.5-16.5 15.5-5.2 0-8.3-2.3-9.8-5.7-3.5 4.6-8.3 5.7-12.3 5.7-5.6.1-10.8-3.8-10.8-9.7zm9.1 1.8c1.9 0 4.2-1.8 5.4-7.1l1.1-5.3c-5.7 2-10.1 4.4-10.1 9.4 0 1.2 1.7 3 3.6 3zm21.7 0c1.9 0 4.2-1.8 5.4-7.1l2.2-10.4-9.4 1.8-1.8 8.3c-.5 2.1-1.1 4-1.8 5.6.9 1.3 3 1.8 5.4 1.8zm-1.4-18l9.4-1.7 7.7-36.8h-9l-8.1 38.5zm16.6-56.7c-2 0-4.8 1.1-6.2 7.1l-1.7 7.4h9l2.1-9.5c.2-.7.2-1.3.2-2 .1-2-1.5-3-3.4-3zm37.9 53c7.1 0 11.6-4 16.1-9.2h3.1c-5.2 8.3-12.9 16.8-25 16.8-8.5 0-14.2-4.2-14.2-14.5 0-10.5 5.9-32.3 24.6-32.3 8.1 0 10 4.2 10 8.7 0 10.5-10 18.5-20.9 19.2-.1 1.3-.2 2.5-.2 3.6 0 6.2 2.2 7.7 6.5 7.7zm5.3-34.4c-4.6 0-9.1 9.7-10.9 18.7 7-.5 13.2-7.4 13.2-15 0-2.2-.5-3.7-2.3-3.7zm28.6 33.4c3.4 0 7.8-2.3 10.8-4.8-2 10.4-8.4 13.4-15.8 13.4-8.4 0-14.1-4.2-14.1-14.5 0-10.5 5.9-32.3 24.6-32.3 8.1 0 10 4.2 10 8.7 0 10.6-10 18.5-20.9 19.2-.1.9-.2 2-.2 2.7 0 5.7 2.5 7.6 5.6 7.6zm6.2-33.4c-4.5 0-9.1 10.1-11 18.7 7.1-.4 13.3-7.3 13.3-15 0-2.2-.6-3.7-2.3-3.7zm51.3-6.7c-1.7 0-3-.6-4.2-1.9 2.4-1.5 4.1-4.8 4.1-7.8 0-3.1-1.8-6.1-6.8-6.1s-8.3 2.8-8.3 8.2c0 13.3 20.5 15.2 20.5 34.8 0 15.3-12.3 22.7-25.6 22.7-10.4 0-19.3-4.5-19.3-15.7 0-9.8 7-14.9 13.3-14.9 3.1 0 7.7 1.3 8 6-4.9 0-10.7 2.3-10.7 8.5 0 4.5 2.9 8.7 8.7 8.7 6.1 0 10.6-4.4 10.6-12 0-15.6-18.6-21.1-18.6-34.5 0-9.5 9.3-16.3 21-16.3 4.3 0 14.6.9 14.6 10.9.1 5.5-2.8 9.4-7.3 9.4zm36.2 10.3c0-2.3-.8-3.7-2.5-3.7-5.7 0-11.7 16.6-11.7 26.7 0 6.2 2.2 7.6 6.6 7.6 7.1 0 11.6-4 16.1-9.2h3.1c-5.2 8.3-12.9 16.8-25 16.8-8.5 0-14.2-4.2-14.2-14.5 0-10.6 6-32.3 24.5-32.3 8.1 0 10.1 4.2 10.1 8.3 0 4.4-2.2 6.7-4.8 6.7-1 0-2.1-.4-3.1-1.1.5-1.9.9-3.6.9-5.3zm27.7-7.6l-1.2 5.7c3.1-2.7 6.7-5.7 11-5.7 4.1 0 6.3 3.3 6.3 6.9 0 3.1-2.1 6.7-6.6 6.7-5.1 0-2.5-6-5.3-6-2.7 0-4.4 1.4-6.7 3.4l-7.2 34.6h-13.1l9.6-45.4 13.2-.2zm34.2 0l-6.6 30.9c-.3 1.2-.4 2.1-.4 2.9 0 2.5 1.2 3.3 3.7 3.3 3.5 0 6.9-3.4 8.1-8h3.8c-5.2 14.8-14.2 16.8-19.1 16.8-5.5 0-9.7-3.2-9.7-10.9 0-1.8.3-3.7.7-5.9l6.2-29.2 13.3.1zm-4.1-19.4c4 0 7.2 3.2 7.2 7.2s-3.2 7.1-7.2 7.1-7.1-3.1-7.1-7.1c-.1-4 3.2-7.2 7.1-7.2zm29.1 16l-1.5 6.9c2.6-2.3 6.1-3.9 10.7-3.9 6.2 0 11.1 3.5 11.1 14.4 0 12.2-4.7 32.1-22.3 32.1-4.5 0-6.8-1.6-7.7-3.2l-4.7 22.1-13.7 3.2 15.2-71.5 12.9-.1zm7.8 17c0-7-2.9-7.5-4.5-7.5-2 0-4.5 1.6-6.3 4.4l-5.4 25.5c.4 1 1.4 2.1 3.4 2.1 9.7 0 12.8-15.9 12.8-24.5zm27.8 17.3c-.3 1.1-.5 2.2-.5 3.1 0 1.9.7 3.2 3.1 3.2.7 0 1.7 0 2.4-.3-2.5 7.8-6.6 8.9-9.6 8.9-6.4 0-9.1-4.4-9.1-10.3 0-1.6.2-3.1.6-4.8l5.8-27.2h-3l.7-3.6h3L528 366l13.4-1.9s-1.4 6.2-3.1 14.4h5.5l-.7 3.6h-5.5l-5.7 27.4z"/>
-</svg>

documentation/sections/annotated_source.md

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

documentation/sections/announcing_coffeescript_2.md

@@ -0,0 +1,78 @@
+# Announcing CoffeeScript 2
+
+We are pleased to announce CoffeeScript 2! This new release of the CoffeeScript language and compiler aims to bring CoffeeScript into the modern JavaScript era, closing gaps in compatibility with JavaScript while preserving the clean syntax that is CoffeeScript’s hallmark. In a nutshell:
+
+- The CoffeeScript 2 compiler now translates CoffeeScript code into modern JavaScript syntax. So a CoffeeScript `=>` is now output as `=>`, a CoffeeScript `class` is now output using the `class` keyword, and so on. This means you may need to [transpile the CoffeeScript compiler’s output](../#es2015plus-output).
+- CoffeeScript 2 adds support for [async functions](../#async-functions) syntax, for the future [object destructuring](../#destructuring) syntax, and for [JSX](../#jsx). Some features, such as [modules](../#modules) (`import` and `export` statements), [`for…of`](../#generator-iteration), and [tagged template literals](../#tagged-template-literals) were backported into CoffeeScript versions 1.11 and 1.12.
+- All of the above was achieved with very few [breaking changes from 1.x](../#breaking-changes). Most current CoffeeScript projects should be able to upgrade with little or no refactoring necessary.
+
+CoffeeScript 2 was developed with two primary goals: remove any incompatibilities with modern JavaScript that might prevent CoffeeScript from being used on a project; and preserve as much backward compatibility as possible. [Install now](../#installation): `npm install -g coffeescript@2`
+
+## Modern JavaScript Output
+
+From the beginning, CoffeeScript has been described as being “just JavaScript.” And today, JavaScript is ES2015 (well, ES2017; also commonly known as ES6). CoffeeScript welcomes the changes in the JavaScript world and we’re happy to stop outputting circa-1999 syntax for modern features.
+
+Many new JavaScript features, such as `=>`, were informed by CoffeeScript and are one-to-one compatible, or very nearly so. This has made outputting many of CoffeeScript’s innovations into new JS syntax straightforward: not only does `=>` become `=>`, but `{ a } = obj` becomes `{ a } = obj`, `"a#{b}c"` becomes `` `a${b}c` `` and so on.
+
+The following CoffeeScript features were updated in 2.0 to output using modern JavaScript syntax (or added in CoffeeScript 1.11 through 2.0, output using modern syntax):
+
+- Modules: `import`/`export`
+- Classes: `class Animal`
+- Async functions: `await someFunction()`
+- Bound/arrow functions: `=>`
+- Function default parameters: `(options = {}) ->`
+- Function splat/rest parameters: `(items...) ->`
+- Destructuring, for both arrays and objects: `[first, second] = items`, `{length} = items`
+- Object rest/spread properties: `{options..., force: yes}`, `{force, otherOptions...} = options`
+- Interpolated strings/template literals (JS backticked strings): `"Hello, #{user}!"`
+- Tagged template literals: `html"<strong>coffee</strong>"`
+- JavaScript’s `for…of` is now available as CoffeeScript’s `for…from` (we already had a `for…of`): `for n from generatorFunction()`
+
+Not all CoffeeScript features were adopted into JavaScript in 100% the same way; most notably, [default values](../#breaking-changes-default-values) in JavaScript (and also in CoffeeScript 2) are only applied when a variable is `undefined`, not `undefined` or `null` as in CoffeeScript 1; and [classes](../#breaking-changes-classes) have their own differences. See the [breaking changes](../#breaking-changes) for the fine details.
+
+In our experience, most breaking changes are edge cases that should affect very few people, like JavaScript’s [lack of an `arguments` object inside arrow functions](../#breaking-change-fat-arrow). There seem to be two breaking changes that affect a significant number of projects:
+
+- In CoffeeScript 2, “bare” `super` (calling `super` without arguments) is now no longer allowed, and one must use `super()` or `super arguments...` instead.
+- References to `this`/`@` cannot occur before a call to `super`, per the JS spec.
+
+See the [full details](../#breaking-changes-super-extends). Either the CoffeeScript compiler or your transpiler will throw errors for either of these cases, so updating your code is a matter of fixing each occurrence as the compiler errors on it, until your code compiles successfully.
+
+## Other Features
+
+Besides supporting new JavaScript features and outputting older CoffeeScript features in modern JS syntax, CoffeeScript 2 has added support for the following:
+
+- [JSX](../#jsx)
+- [Line comments](../#comments) are now output (in CoffeeScript 1 they were discarded)
+- Block comments are now allowed anywhere, enabling [static type annotations](../#type-annotations) using Flow’s comment-based syntax
+
+There are many smaller improvements as well, such as to the `coffee` command-line tool. You can read all the details in the [changelog](../#changelog) for the 2.0.0 betas.
+
+## “What About …?”
+
+A few JavaScript features have been intentionally omitted from CoffeeScript. These include `let` and `const` (and `var`), named functions and the `get` and `set` keywords. These get asked about so often that we added a section to the docs called [Unsupported ECMAScript Features](../#unsupported). CoffeeScript’s lack of equivalents for these features does not affect compatibility or interoperability with JavaScript modules or libraries.
+
+## Future Compatibility
+
+Back when CoffeeScript 1 was created, ES2015 JavaScript and transpilers like [Babel](http://babeljs.io/), [Bublé](https://buble.surge.sh/) or [Traceur Compiler](https://github.com/google/traceur-compiler) were several years away. The CoffeeScript compiler itself had to do what today’s transpilers do, converting modern features like destructuring and arrow functions into equivalent lowest-common-denominator JavaScript.
+
+But transpilers exist now, and they do their job well. With them around, there’s no need for the CoffeeScript compiler to duplicate this functionality. All the CoffeeScript compiler needs to worry about now is converting the CoffeeScript version of new syntax into the JS version of that syntax, e.g. `"Hello, #{name}!"` into `` `Hello, ${name}!` ``. This makes adding support for new JavaScript features much easier than before.
+
+Most features added by ECMA in recent years haven’t required any updates at all in CoffeeScript. New global objects, or new methods on global objects, don’t require any updates on CoffeeScript’s part to work. Some proposed future JS features _do_ involve new syntax, like [class fields](https://github.com/tc39/proposal-class-fields). We have adopted a policy of supporting new syntax only when it reaches Stage 4 in ECMA’s process, which means that the syntax is final and will be in the next ES release. On occasion we might support a _feature_ before it has reached Stage 4, but output it using equivalent non-experimental syntax instead of the newly-proposed syntax; that’s what’s happening in 2.0.0 for [object destructuring](../#splats), where our output uses the same polyfill that Babel uses. When the new syntax is finalized, we will update our output to use the final syntax.
+
+## Credits
+
+The major features of 2.0.0 would not have been possible without the following people:
+
+- [@GeoffreyBooth](https://github.com/GeoffreyBooth): Organizer of the CoffeeScript 2 effort, developer for modules; arrow functions, function default parameters and function rest parameters output using ES2015 syntax; line comments output and block comments output anywhere; block embedded JavaScript via triple backticks; improved parsing of Literate CoffeeScript; and the new docs website.
+- [@connec](https://github.com/connec): Classes; destructuring; splats/rest syntax in arrays and function calls; and computed properties all output using ES2015 syntax.
+- [@GabrielRatener](https://github.com/GabrielRatener): Async functions.
+- [@xixixao](https://github.com/xixixao): JSX.
+- [@zdenko](https://github.com/zdenko): Object rest/spread properties (object destructuring).
+- [@greghuc](https://github.com/greghuc): Tagged template literals, interpolated strings output in ES2015 syntax.
+- [@atg](https://github.com/atg): ES2015 `for…of`, supported as CoffeeScript’s `for…from`.
+- [@lydell](https://github.com/lydell) and [@jashkenas](https://github.com/jashkenas): Guidance, code reviews and feedback.
+
+
+See the full [honor roll](https://github.com/jashkenas/coffeescript/wiki/CoffeeScript-2-Honor-Roll).
+
+Thanks and we hope you enjoy CoffeeScript 2!

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_changes.md

@@ -0,0 +1,3 @@
+## Breaking Changes From CoffeeScript 1.x to 2
+
+CoffeeScript 2 aims to output as much idiomatic ES2015+ syntax as possible with as few breaking changes from CoffeeScript 1.x as possible. Some breaking changes, unfortunately, were unavoidable.

documentation/sections/breaking_changes_argument_parsing_and_shebang_lines.md

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

documentation/sections/breaking_changes_bound_generator_functions.md

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

documentation/sections/breaking_changes_classes.md

@@ -0,0 +1,41 @@
+### 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
+```
+
+ES2015 classes don’t allow bound (fat arrow) methods. The CoffeeScript compiler goes through some contortions to preserve support for them, but one thing that can’t be accommodated is calling a bound method before it is bound:
+
+```coffee
+class Base
+  constructor: ->
+    @onClick()      # This works
+    clickHandler = @onClick
+    clickHandler()  # This throws a runtime error
+
+class Component extends Base
+  onClick: =>
+    console.log 'Clicked!', @
+```
+
+Class methods can’t be used with `new` (uncommon):
+
+```coffee
+class Namespace
+  @Klass = ->
+new Namespace.Klass  # Throws a TypeError at runtime
+```
+
+Due to the hoisting required to compile to ES2015 classes, dynamic keys in class methods can’t use values from the executable class body unless the methods are assigned in prototype style.
+
+```coffee
+class A
+  name = 'method'
+  "#{name}": ->   # This method will be named 'undefined'
+  @::[name] = ->  # This will work; assigns to `A.prototype.method`
+```

documentation/sections/breaking_changes_default_values.md

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

documentation/sections/breaking_changes_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_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/breaking_changes_super_this.md

@@ -0,0 +1,20 @@
+### `super` and `this`
+
+In the constructor of a derived class (a class that `extends` another class), `this` cannot be used before calling `super`:
+
+```coffee
+class B extends A
+  constructor: -> this  # Throws a compiler error
+```
+This also means you cannot pass a reference to `this` as an argument to `super` in the constructor of a derived class:
+
+```coffee
+class B extends A
+  constructor: (@arg) ->
+    super @arg  # Throws a compiler error
+```
+This is a limitation of ES2015 classes. As a workaround, assign to `this` after the `super` call:
+
+```
+codeFor('breaking_change_super_this')
+```

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,559 +1 @@
-## Change Log
-
-```
-releaseHeader('2017-07-16', '1.12.7', '1.12.6')
-```
-
-*   Fix regressions in 1.12.6 related to chained function calls and indented `return` and `throw` arguments.
-*   The REPL no longer warns about assigning to `_`.
-
-```
-releaseHeader('2017-05-15', '1.12.6', '1.12.5')
-```
-
-*   The `return` and `export` keywords can now accept implicit objects (defined by indentation, without needing braces).
-*   Support Unicode code point escapes (e.g. `\u{1F4A9}`).
-*   The `coffee` command now first looks to see if CoffeeScript is installed under `node_modules` in the current folder, and executes the `coffee` binary there if so; or otherwise it runs the globally installed one. This allows you to have one version of CoffeeScript installed globally and a different one installed locally for a particular project. (Likewise for the `cake` command.)
-*   Bugfixes for chained function calls not closing implicit objects or ternaries.
-*   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-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-18', '1.12.4', '1.12.3')
-```
-
-*   The `cake` commands have been updated, with new `watch` options for most tasks. Clone the [CoffeeScript repo](https://github.com/jashkenas/coffeescript) and run `cake` at the root of the repo to see the options.
-*   Fixed a bug where `export`ing a referenced variable was preventing the variable from being declared.
-*   Fixed a bug where the `coffee` command wasn’t working for a `.litcoffee` file.
-*   Bugfixes related to tokens and location data, for better source maps and improved compatibility with downstream tools.
-
-```
-releaseHeader('2017-01-24', '1.12.3', '1.12.2')
-```
-
-*   `@` values can now be used as indices in `for` expressions. This loosens the compilation of `for` expressions to allow the index variable to be an `@` value, e.g. `do @visit for @node, @index in nodes`. Within `@visit`, the index of the current node (`@node`) would be available as `@index`.
-*   CoffeeScript’s patched `Error.prepareStackTrace` has been restored, with some revisions that should prevent the erroneous exceptions that were making life difficult for some downstream projects. This fixes the incorrect line numbers in stack traces since 1.12.2.
-*   The `//=` operator’s output now wraps parentheses around the right operand, like the other assignment operators.
-
-```
-releaseHeader('2016-12-16', '1.12.2', '1.12.1')
-```
-
-*   The browser compiler can once again be built unminified via `MINIFY=false cake build:browser`.
-*   The error-prone patched version of `Error.prepareStackTrace` has been removed.
-*   Command completion in the REPL (pressing tab to get suggestions) has been fixed for Node 6.9.1+.
-*   The [browser-based tests](/v<%= majorVersion %>/test.html) now include all the tests as the Node-based version.
-
-```
-releaseHeader('2016-12-07', '1.12.1', '1.12.0')
-```
-
-*   You can now import a module member named `default`, e.g. `import { default } from 'lib'`. Though like in ES2015, you cannot import an entire module and name it `default` (so `import default from 'lib'` is not allowed).
-*   Fix regression where `from` as a variable name was breaking `for` loop declarations. For the record, `from` is not a reserved word in CoffeeScript; you may use it for variable names. `from` behaves like a keyword within the context of `import` and `export` statements, and in the declaration of a `for` loop; though you should also be able to use variables named `from` in those contexts, and the compiler should be able to tell the difference.
-
-```
-releaseHeader('2016-12-04', '1.12.0', '1.11.1')
-```
-
-*   CoffeeScript now supports ES2015 [tagged template literals](#tagged-template-literals). Note that using tagged template literals in your code makes you responsible for ensuring that either your runtime supports tagged template literals or that you transpile the output JavaScript further to a version your target runtime(s) support.
-*   CoffeeScript now provides a [`for…from`](#generator-iteration) syntax for outputting ES2015 [`for…of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of). (Sorry they couldn’t match, but we came up with `for…of` first for something else.) This allows iterating over generators or any other iterable object. Note that using `for…from` in your code makes you responsible for ensuring that either your runtime supports `for…of` or that you transpile the output JavaScript further to a version your target runtime(s) support.
-*   Triple backticks (`` ```​``) allow the creation of embedded JavaScript blocks where escaping single backticks is not required, which should improve interoperability with ES2015 template literals and with Markdown.
-*   Within single-backtick embedded JavaScript, backticks can now be escaped via `` \`​``.
-*   The browser tests now run in the browser again, and are accessible [here](/v<%= majorVersion %>/test.html) if you would like to test your browser.
-*   CoffeeScript-only keywords in ES2015 `import`s and `export`s are now ignored.
-*   The compiler now throws an error on trying to export an anonymous class.
-*   Bugfixes related to tokens and location data, for better source maps and improved compatibility with downstream tools.
-
-```
-releaseHeader('2016-10-02', '1.11.1', '1.11.0')
-```
-
-*   Bugfix for shorthand object syntax after interpolated keys.
-*   Bugfix for indentation-stripping in `"""` strings.
-*   Bugfix for not being able to use the name “arguments” for a prototype property of class.
-*   Correctly compile large hexadecimal numbers literals to `2e308` (just like all other large number literals do).
-
-```
-releaseHeader('2016-09-24', '1.11.0', '1.10.0')
-```
-
-*   CoffeeScript now supports ES2015 [`import` and `export` syntax](#modules).
-*   Added the `-M, --inline-map` flag to the compiler, allowing you embed the source map directly into the output JavaScript, rather than as a separate file.
-*   A bunch of fixes for `yield`:
-
-    *   `yield return` can no longer mistakenly be used as an expression.
-    *   `yield` now mirrors `return` in that it can be used stand-alone as well as with expressions. Where you previously wrote `yield undefined`, you may now write simply `yield`. However, this means also inheriting the same syntax limitations that `return` has, so these examples no longer compile:
-        ```
-        doubles = ->
-          yield for i in [1..3]
-            i * 2
-        six = ->
-          yield
-            2 * 3
-        ```
-
-    *   The JavaScript output is a bit nicer, with unnecessary parentheses and spaces, double indentation and double semicolons around `yield` no longer present.
-*   `&&=`, `||=`, `and=` and `or=` no longer accidentally allow a space before the equals sign.
-*   Improved several error messages.
-*   Just like `undefined` compiles to `void 0`, `NaN` now compiles into `0/0` and `Infinity` into `2e308`.
-*   Bugfix for renamed destructured parameters with defaults. `({a: b = 1}) ->` no longer crashes the compiler.
-*   Improved the internal representation of a CoffeeScript program. This is only noticeable to tools that use `CoffeeScript.tokens` or `CoffeeScript.nodes`. Such tools need to update to take account for changed or added tokens and nodes.
-*   Several minor bug fixes, including:
-
-    *   The caught error in `catch` blocks is no longer declared unnecessarily, and no longer mistakenly named `undefined` for `catch`-less `try` blocks.
-    *   Unassignable parameter destructuring no longer crashes the compiler.
-    *   Source maps are now used correctly for errors thrown from .coffee.md files.
-    *   `coffee -e 'throw null'` no longer crashes.
-    *   The REPL no longer crashes when using `.exit` to exit it.
-    *   Invalid JavaScript is no longer output when lots of `for` loops are used in the same scope.
-    *   A unicode issue when using stdin with the CLI.
-
-```
-releaseHeader('2015-09-03', '1.10.0', '1.9.3')
-```
-
-*   CoffeeScript now supports ES2015-style destructuring defaults.
-*   `(offsetHeight: height) ->` no longer compiles. That syntax was accidental and partly broken. Use `({offsetHeight: height}) ->` instead. Object destructuring always requires braces.
-*   Several minor bug fixes, including:
-
-    *   A bug where the REPL would sometimes report valid code as invalid, based on what you had typed earlier.
-    *   A problem with multiple JS contexts in the jest test framework.
-    *   An error in io.js where strict mode is set on internal modules.
-    *   A variable name clash for the caught error in `catch` blocks.
-
-```
-releaseHeader('2015-05-27', '1.9.3', '1.9.2')
-```
-
-*   Bugfix for interpolation in the first key of an object literal in an implicit call.
-*   Fixed broken error messages in the REPL, as well as a few minor bugs with the REPL.
-*   Fixed source mappings for tokens at the beginning of lines when compiling with the `--bare` option. This has the nice side effect of generating smaller source maps.
-*   Slight formatting improvement of compiled block comments.
-*   Better error messages for `on`, `off`, `yes` and `no`.
-
-```
-releaseHeader('2015-04-15', '1.9.2', '1.9.1')
-```
-
-*   Fixed a **watch** mode error introduced in 1.9.1 when compiling multiple files with the same filename.
-*   Bugfix for `yield` around expressions containing `this`.
-*   Added a Ruby-style `-r` option to the REPL, which allows requiring a module before execution with `--eval` or `--interactive`.
-*   In `<script type="text/coffeescript">` tags, to avoid possible duplicate browser requests for .coffee files, you can now use the `data-src` attribute instead of `src`.
-*   Minor bug fixes for IE8, strict ES5 regular expressions and Browserify.
-
-```
-releaseHeader('2015-02-18', '1.9.1', '1.9.0')
-```
-
-*   Interpolation now works in object literal keys (again). You can use this to dynamically name properties.
-*   Internal compiler variable names no longer start with underscores. This makes the generated JavaScript a bit prettier, and also fixes an issue with the completely broken and ungodly way that AngularJS “parses” function arguments.
-*   Fixed a few `yield`-related edge cases with `yield return` and `yield throw`.
-*   Minor bug fixes and various improvements to compiler error messages.
-
-```
-releaseHeader('2015-01-29', '1.9.0', '1.8.0')
-```
-
-*   CoffeeScript now supports ES2015 generators. A generator is simply a function that `yield`s.
-*   More robust parsing and improved error messages for strings and regexes — especially with respect to interpolation.
-*   Changed strategy for the generation of internal compiler variable names. Note that this means that `@example` function parameters are no longer available as naked `example` variables within the function body.
-*   Fixed REPL compatibility with latest versions of Node and Io.js.
-*   Various minor bug fixes.
-
-```
-releaseHeader('2014-08-26', '1.8.0', '1.7.1')
-```
-
-*   The `--join` option of the CLI is now deprecated.
-*   Source maps now use `.js.map` as file extension, instead of just `.map`.
-*   The CLI now exits with the exit code 1 when it fails to write a file to disk.
-*   The compiler no longer crashes on unterminated, single-quoted strings.
-*   Fixed location data for string interpolations, which made source maps out of sync.
-*   The error marker in error messages is now correctly positioned if the code is indented with tabs.
-*   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'`.
-*   Fixes for the REPL in Node 0.11.
-
-```
-releaseHeader('2014-01-29', '1.7.1', '1.7.0')
-```
-
-*   Fixed a typo that broke node module lookup when running a script directly with the `coffee` binary.
-
-```
-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**.
-*   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.
-*   Several breaking compilation fixes. Non-callable literals (strings, numbers etc.) don’t compile in a call now and multiple postfix conditionals compile properly. Postfix conditionals and loops always bind object literals. Conditional assignment compiles properly in subexpressions. `super` is disallowed outside of methods and works correctly inside `for` loops.
-*   Formatting of compiled block comments has been improved.
-*   No more `-p` folders on Windows.
-*   The `options` object passed to CoffeeScript is no longer mutated.
-
-```
-releaseHeader('2013-06-02', '1.6.3', '1.6.2')
-```
-
-*   The CoffeeScript REPL now remembers your history between sessions. Just like a proper REPL should.
-*   You can now use `require` in Node to load `.coffee.md` Literate CoffeeScript files. In the browser, `text/literate-coffeescript` script tags.
-*   The old `coffee --lint` command has been removed. It was useful while originally working on the compiler, but has been surpassed by JSHint. You may now use `-l` to pass literate files in over **stdio**.
-*   Bugfixes for Windows path separators, `catch` without naming the error, and executable-class-bodies-with- prototypal-property-attachment.
-
-```
-releaseHeader('2013-03-18', '1.6.2', '1.6.1')
-```
-
-*   Source maps have been used to provide automatic line-mapping when running CoffeeScript directly via the `coffee` command, and for automatic line-mapping when running CoffeeScript directly in the browser. Also, to provide better error messages for semantic errors thrown by the compiler — [with colors, even](http://cl.ly/NdOA).
-*   Improved support for mixed literate/vanilla-style CoffeeScript projects, and generating source maps for both at the same time.
-*   Fixes for **1.6.x** regressions with overriding inherited bound functions, and for Windows file path management.
-*   The `coffee` command can now correctly `fork()` both `.coffee` and `.js` files. (Requires Node.js 0.9+)
-
-```
-releaseHeader('2013-03-05', '1.6.1', '1.5.0')
-```
-
-*   First release of [source maps](#source-maps). Pass the `--map` flag to the compiler, and off you go. Direct all your thanks over to [Jason Walton](https://github.com/jwalton).
-*   Fixed a 1.5.0 regression with multiple implicit calls against an indented implicit object. Combinations of implicit function calls and implicit objects should generally be parsed better now — but it still isn’t good _style_ to nest them too heavily.
-*   `.coffee.md` is now also supported as a Literate CoffeeScript file extension, for existing tooling. `.litcoffee` remains the canonical one.
-*   Several minor fixes surrounding member properties, bound methods and `super` in class declarations.
-
-```
-releaseHeader('2013-02-25', '1.5.0', '1.4.0')
-```
-
-*   First release of [Literate CoffeeScript](#literate).
-*   The CoffeeScript REPL is now based on the Node.js REPL, and should work better and more familiarly.
-*   Returning explicit values from constructors is now forbidden. If you want to return an arbitrary value, use a function, not a constructor.
-*   You can now loop over an array backwards, without having to manually deal with the indexes: `for item in list by -1`
-*   Source locations are now preserved in the CoffeeScript AST, although source maps are not yet being emitted.
-
-```
-releaseHeader('2012-10-23', '1.4.0', '1.3.3')
-```
-
-*   The CoffeeScript compiler now strips Microsoft’s UTF-8 BOM if it exists, allowing you to compile BOM-borked source files.
-*   Fix Node/compiler deprecation warnings by removing `registerExtension`, and moving from `path.exists` to `fs.exists`.
-*   Small tweaks to splat compilation, backticks, slicing, and the error for duplicate keys in object literals.
-
-```
-releaseHeader('2012-05-15', '1.3.3', '1.3.1')
-```
-
-*   Due to the new semantics of JavaScript’s strict mode, CoffeeScript no longer guarantees that constructor functions have names in all runtimes. See [#2052](https://github.com/jashkenas/coffeescript/issues/2052) for discussion.
-*   Inside of a nested function inside of an instance method, it’s now possible to call `super` more reliably (walks recursively up).
-*   Named loop variables no longer have different scoping heuristics than other local variables. (Reverts #643)
-*   Fix for splats nested within the LHS of destructuring assignment.
-*   Corrections to our compile time strict mode forbidding of octal literals.
-
-```
-releaseHeader('2012-04-10', '1.3.1', '1.2.0')
-```
-
-*   CoffeeScript now enforces all of JavaScript’s **Strict Mode** early syntax errors at compile time. This includes old-style octal literals, duplicate property names in object literals, duplicate parameters in a function definition, deleting naked variables, setting the value of `eval` or `arguments`, and more. See a full discussion at [#1547](https://github.com/jashkenas/coffeescript/issues/1547).
-*   The REPL now has a handy new multi-line mode for entering large blocks of code. It’s useful when copy-and-pasting examples into the REPL. Enter multi-line mode with `Ctrl-V`. You may also now pipe input directly into the REPL.
-*   CoffeeScript now prints a `Generated by CoffeeScript VERSION` header at the top of each compiled file.
-*   Conditional assignment of previously undefined variables `a or= b` is now considered a syntax error.
-*   A tweak to the semantics of `do`, which can now be used to more easily simulate a namespace: `do (x = 1, y = 2) -> …`
-*   Loop indices are now mutable within a loop iteration, and immutable between them.
-*   Both endpoints of a slice are now allowed to be omitted for consistency, effectively creating a shallow copy of the list.
-*   Additional tweaks and improvements to `coffee --watch` under Node’s “new” file watching API. Watch will now beep by default if you introduce a syntax error into a watched script. We also now ignore hidden directories by default when watching recursively.
-
-```
-releaseHeader('2011-12-18', '1.2.0', '1.1.3')
-```
-
-*   Multiple improvements to `coffee --watch` and `--join`. You may now use both together, as well as add and remove files and directories within a `--watch`’d folder.
-*   The `throw` statement can now be used as part of an expression.
-*   Block comments at the top of the file will now appear outside of the safety closure wrapper.
-*   Fixed a number of minor 1.1.3 regressions having to do with trailing operators and unfinished lines, and a more major 1.1.3 regression that caused bound functions _within_ bound class functions to have the incorrect `this`.
-
-```
-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')`
-*   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)**.
-
-```
-releaseHeader('2011-08-04', '1.1.2', '1.1.1')
-```
-
-Fixes for block comment formatting, `?=` compilation, implicit calls against control structures, implicit invocation of a try/catch block, variadic arguments leaking from local scope, line numbers in syntax errors following heregexes, property access on parenthesized number literals, bound class methods and super with reserved names, a REPL overhaul, consecutive compiled semicolons, block comments in implicitly called objects, and a Chrome bug.
-
-```
-releaseHeader('2011-05-10', '1.1.1', '1.1.0')
-```
-
-Bugfix release for classes with external constructor functions, see issue #1182.
-
-```
-releaseHeader('2011-05-01', '1.1.0', '1.0.1')
-```
-
-When running via the `coffee` executable, `process.argv` and friends now report `coffee` instead of `node`. Better compatibility with **Node.js 0.4.x** module lookup changes. The output in the REPL is now colorized, like Node’s is. Giving your concatenated CoffeeScripts a name when using `--join` is now mandatory. Fix for lexing compound division `/=` as a regex accidentally. All `text/coffeescript` tags should now execute in the order they’re included. Fixed an issue with extended subclasses using external constructor functions. Fixed an edge-case infinite loop in `addImplicitParentheses`. Fixed exponential slowdown with long chains of function calls. Globals no longer leak into the CoffeeScript REPL. Splatted parameters are declared local to the function.
-
-```
-releaseHeader('2011-01-31', '1.0.1', '1.0.0')
-```
-
-Fixed a lexer bug with Unicode identifiers. Updated REPL for compatibility with Node.js 0.3.7\. Fixed requiring relative paths in the REPL. Trailing `return` and `return undefined` are now optimized away. Stopped requiring the core Node.js `util` module for back-compatibility with Node.js 0.2.5\. Fixed a case where a conditional `return` would cause fallthrough in a `switch` statement. Optimized empty objects in destructuring assignment.
-
-```
-releaseHeader('2010-12-24', '1.0.0', '0.9.6')
-```
-
-CoffeeScript loops no longer try to preserve block scope when functions are being generated within the loop body. Instead, you can use the `do` keyword to create a convenient closure wrapper. Added a `--nodejs` flag for passing through options directly to the `node` executable. Better behavior around the use of pure statements within expressions. Fixed inclusive slicing through `-1`, for all browsers, and splicing with arbitrary expressions as endpoints.
-
-```
-releaseHeader('2010-12-06', '0.9.6', '0.9.5')
-```
-
-The REPL now properly formats stacktraces, and stays alive through asynchronous exceptions. Using `--watch` now prints timestamps as files are compiled. Fixed some accidentally-leaking variables within plucked closure-loops. Constructors now maintain their declaration location within a class body. Dynamic object keys were removed. Nested classes are now supported. Fixes execution context for naked splatted functions. Bugfix for inversion of chained comparisons. Chained class instantiation now works properly with splats.
-
-```
-releaseHeader('2010-11-21', '0.9.5', '0.9.4')
-```
-
-0.9.5 should be considered the first release candidate for CoffeeScript 1.0. There have been a large number of internal changes since the previous release, many contributed from **satyr**’s [Coco](https://github.com/satyr/coco) dialect of CoffeeScript. Heregexes (extended regexes) were added. Functions can now have default arguments. Class bodies are now executable code. Improved syntax errors for invalid CoffeeScript. `undefined` now works like `null`, and cannot be assigned a new value. There was a precedence change with respect to single-line comprehensions: `result = i for i in list`
-used to parse as `result = (i for i in list)` by default … it now parses as
-`(result = i) for i in list`.
-
-```
-releaseHeader('2010-09-21', '0.9.4', '0.9.3')
-```
-
-CoffeeScript now uses appropriately-named temporary variables, and recycles their references after use. Added `require.extensions` support for **Node.js 0.3**. Loading CoffeeScript in the browser now adds just a single `CoffeeScript` object to global scope. Fixes for implicit object and block comment edge cases.
-
-```
-releaseHeader('2010-09-16', '0.9.3', '0.9.2')
-```
-
-CoffeeScript `switch` statements now compile into JS `switch` statements — they previously compiled into `if/else` chains for JavaScript 1.3 compatibility. Soaking a function invocation is now supported. Users of the RubyMine editor should now be able to use `--watch` mode.
-
-```
-releaseHeader('2010-08-23', '0.9.2', '0.9.1')
-```
-
-Specifying the start and end of a range literal is now optional, eg. `array[3..]`. You can now say `a not instanceof b`. Fixed important bugs with nested significant and non-significant indentation (Issue #637). Added a `--require` flag that allows you to hook into the `coffee` command. Added a custom `jsl.conf` file for our preferred JavaScriptLint setup. Sped up Jison grammar compilation time by flattening rules for operations. Block comments can now be used with JavaScript-minifier-friendly syntax. Added JavaScript’s compound assignment bitwise operators. Bugfixes to implicit object literals with leading number and string keys, as the subject of implicit calls, and as part of compound assignment.
-
-```
-releaseHeader('2010-08-11', '0.9.1', '0.9.0')
-```
-
-Bugfix release for **0.9.1**. Greatly improves the handling of mixed implicit objects, implicit function calls, and implicit indentation. String and regex interpolation is now strictly `#{ … }` (Ruby style). The compiler now takes a `--require` flag, which specifies scripts to run before compilation.
-
-```
-releaseHeader('2010-08-04', '0.9.0', '0.7.2')
-```
-
-The CoffeeScript **0.9** series is considered to be a release candidate for **1.0**; let’s give her a shakedown cruise. **0.9.0** introduces a massive backwards-incompatible change: Assignment now uses `=`, and object literals use `:`, as in JavaScript. This allows us to have implicit object literals, and YAML-style object definitions. Half assignments are removed, in favor of `+=`, `or=`, and friends. Interpolation now uses a hash mark `#` instead of the dollar sign `$` — because dollar signs may be part of a valid JS identifier. Downwards range comprehensions are now safe again, and are optimized to straight for loops when created with integer endpoints. A fast, unguarded form of object comprehension was added: `for all key, value of object`. Mentioning the `super` keyword with no arguments now forwards all arguments passed to the function, as in Ruby. If you extend class `B` from parent class `A`, if `A` has an `extended` method defined, it will be called, passing in `B` — this enables static inheritance, among other things. Cleaner output for functions bound with the fat arrow. `@variables` can now be used in parameter lists, with the parameter being automatically set as a property on the object — useful in constructors and setter functions. Constructor functions can now take splats.
-
-```
-releaseHeader('2010-07-12', '0.7.2', '0.7.1')
-```
-
-Quick bugfix (right after 0.7.1) for a problem that prevented `coffee` command-line options from being parsed in some circumstances.
-
-```
-releaseHeader('2010-07-11', '0.7.1', '0.7.0')
-```
-
-Block-style comments are now passed through and printed as JavaScript block comments – making them useful for licenses and copyright headers. Better support for running coffee scripts standalone via hashbangs. Improved syntax errors for tokens that are not in the grammar.
-
-```
-releaseHeader('2010-06-28', '0.7.0', '0.6.2')
-```
-
-Official CoffeeScript variable style is now camelCase, as in JavaScript. Reserved words are now allowed as object keys, and will be quoted for you. Range comprehensions now generate cleaner code, but you have to specify `by -1` if you’d like to iterate downward. Reporting of syntax errors is greatly improved from the previous release. Running `coffee` with no arguments now launches the REPL, with Readline support. The `<-` bind operator has been removed from CoffeeScript. The `loop` keyword was added, which is equivalent to a `while true` loop. Comprehensions that contain closures will now close over their variables, like the semantics of a `forEach`. You can now use bound function in class definitions (bound to the instance). For consistency, `a in b` is now an array presence check, and `a of b` is an object-key check. Comments are no longer passed through to the generated JavaScript.
-
-```
-releaseHeader('2010-05-15', '0.6.2', '0.6.1')
-```
-
-The `coffee` command will now preserve directory structure when compiling a directory full of scripts. Fixed two omissions that were preventing the CoffeeScript compiler from running live within Internet Explorer. There’s now a syntax for block comments, similar in spirit to CoffeeScript’s heredocs. ECMA Harmony DRY-style pattern matching is now supported, where the name of the property is the same as the name of the value: `{name, length}: func`. Pattern matching is now allowed within comprehension variables. `unless` is now allowed in block form. `until` loops were added, as the inverse of `while` loops. `switch` statements are now allowed without switch object clauses. Compatible with Node.js **v0.1.95**.
-
-```
-releaseHeader('2010-04-12', '0.6.1', '0.6.0')
-```
-
-Upgraded CoffeeScript for compatibility with the new Node.js **v0.1.90** series.
-
-```
-releaseHeader('2010-04-03', '0.6.0', '0.5.6')
-```
-
-Trailing commas are now allowed, a-la Python. Static properties may be assigned directly within class definitions, using `@property` notation.
-
-```
-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.
-
-```
-releaseHeader('2010-03-08', '0.5.5', '0.5.4')
-```
-
-String interpolation, contributed by [Stan Angeloff](https://github.com/StanAngeloff). Since `--run` has been the default since **0.5.3**, updating `--stdio` and `--eval` to run by default, pass `--compile` as well if you’d like to print the result.
-
-```
-releaseHeader('2010-03-03', '0.5.4', '0.5.3')
-```
-
-Bugfix that corrects the Node.js global constants `__filename` and `__dirname`. Tweaks for more flexible parsing of nested function literals and improperly-indented comments. Updates for the latest Node.js API.
-
-```
-releaseHeader('2010-02-27', '0.5.3', '0.5.2')
-```
-
-CoffeeScript now has a syntax for defining classes. Many of the core components (Nodes, Lexer, Rewriter, Scope, Optparse) are using them. Cakefiles can use `optparse.coffee` to define options for tasks. `--run` is now the default flag for the `coffee` command, use `--compile` to save JavaScripts. Bugfix for an ambiguity between RegExp literals and chained divisions.
-
-```
-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.
-
-```
-releaseHeader('2010-02-24', '0.5.1', '0.5.0')
-```
-
-Improvements to null soaking with the existential operator, including soaks on indexed properties. Added conditions to `while` loops, so you can use them as filters with `when`, in the same manner as comprehensions.
-
-```
-releaseHeader('2010-02-21', '0.5.0', '0.3.2')
-```
-
-CoffeeScript 0.5.0 is a major release, While there are no language changes, the Ruby compiler has been removed in favor of a self-hosting compiler written in pure CoffeeScript.
-
-```
-releaseHeader('2010-02-08', '0.3.2', '0.3.0')
-```
-
-`@property` is now a shorthand for `this.property`.
-Switched the default JavaScript engine from Narwhal to Node.js. Pass the `--narwhal` flag if you’d like to continue using it.
-
-```
-releaseHeader('2010-01-26', '0.3.0', '0.2.6')
-```
-
-CoffeeScript 0.3 includes major syntax changes:
-The function symbol was changed to `->`, and the bound function symbol is now `=>`.
-Parameter lists in function definitions must now be wrapped in parentheses.
-Added property soaking, with the `?.` operator.
-Made parentheses optional, when invoking functions with arguments.
-Removed the obsolete block literal syntax.
-
-```
-releaseHeader('2010-01-17', '0.2.6', '0.2.5')
-```
-
-Added Python-style chained comparisons, the conditional existence operator `?=`, and some examples from _Beautiful Code_. Bugfixes relating to statement-to-expression conversion, arguments-to-array conversion, and the TextMate syntax highlighter.
-
-```
-releaseHeader('2010-01-13', '0.2.5', '0.2.4')
-```
-
-The conditions in switch statements can now take multiple values at once — If any of them are true, the case will run. Added the long arrow `==>`, which defines and immediately binds a function to `this`. While loops can now be used as expressions, in the same way that comprehensions can. Splats can be used within pattern matches to soak up the rest of an array.
-
-```
-releaseHeader('2010-01-12', '0.2.4', '0.2.3')
-```
-
-Added ECMAScript Harmony style destructuring assignment, for dealing with extracting values from nested arrays and objects. Added indentation-sensitive heredocs for nicely formatted strings or chunks of code.
-
-```
-releaseHeader('2010-01-11', '0.2.3', '0.2.2')
-```
-
-Axed the unsatisfactory `ino` keyword, replacing it with `of` for object comprehensions. They now look like: `for prop, value of object`.
-
-```
-releaseHeader('2010-01-10', '0.2.2', '0.2.1')
-```
-
-When performing a comprehension over an object, use `ino`, instead of `in`, which helps us generate smaller, more efficient code at compile time.
-Added `::` as a shorthand for saying `.prototype.`
-The “splat” symbol has been changed from a prefix asterisk `*`, to a postfix ellipsis `...`
-Added JavaScript’s `in` operator, empty `return` statements, and empty `while` loops.
-Constructor functions that start with capital letters now include a safety check to make sure that the new instance of the object is returned.
-The `extends` keyword now functions identically to `goog.inherits` in Google’s Closure Library.
-
-```
-releaseHeader('2010-01-05', '0.2.1', '0.2.0')
-```
-
-Arguments objects are now converted into real arrays when referenced.
-
-```
-releaseHeader('2010-01-05', '0.2.0', '0.1.6')
-```
-
-Major release. Significant whitespace. Better statement-to-expression conversion. Splats. Splice literals. Object comprehensions. Blocks. The existential operator. Many thanks to all the folks who posted issues, with special thanks to [Liam O’Connor-Davis](https://github.com/liamoc) for whitespace and expression help.
-
-```
-releaseHeader('2009-12-27', '0.1.6', '0.1.5')
-```
-
-Bugfix for running `coffee --interactive` and `--run` from outside of the CoffeeScript directory. Bugfix for nested function/if-statements.
-
-```
-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`.
-
-```
-releaseHeader('2009-12-25', '0.1.4', '0.1.3')
-```
-
-The official CoffeeScript extension is now `.coffee` instead of `.cs`, which properly belongs to [C#](https://en.wikipedia.org/wiki/C_Sharp_(programming_language)). Due to popular demand, you can now also use `=` to assign. Unlike JavaScript, `=` can also be used within object literals, interchangeably with `:`. Made a grammatical fix for chained function calls like `func(1)(2)(3)(4)`. Inheritance and super no longer use `__proto__`, so they should be IE-compatible now.
-
-```
-releaseHeader('2009-12-25', '0.1.3', '0.1.2')
-```
-
-The `coffee` command now includes `--interactive`, which launches an interactive CoffeeScript session, and `--run`, which directly compiles and executes a script. Both options depend on a working installation of Narwhal. The `aint` keyword has been replaced by `isnt`, which goes together a little smoother with `is`. Quoted strings are now allowed as identifiers within object literals: eg. `{"5+5": 10}`. All assignment operators now use a colon: `+:`, `-:`, `*:`, etc.
-
-```
-releaseHeader('2009-12-24', '0.1.2', '0.1.1')
-```
-
-Fixed a bug with calling `super()` through more than one level of inheritance, with the re-addition of the `extends` keyword. Added experimental [Narwhal](http://narwhaljs.org/) support (as a Tusk package), contributed by [Tom Robinson](http://blog.tlrobinson.net/), including **bin/cs** as a CoffeeScript REPL and interpreter. New `--no-wrap` option to suppress the safety function wrapper.
-
-```
-releaseHeader('2009-12-24', '0.1.1', '0.1.0')
-```
-
-Added `instanceof` and `typeof` as operators.
-
-```
-releaseHeader('2009-12-24', '0.1.0', '8e9d637985d2dc9b44922076ad54ffef7fa8e9c2')
-```
-
-Initial CoffeeScript release.
+## Changelog

documentation/sections/changelog/0.1.0.md

@@ -0,0 +1,5 @@
+```
+releaseHeader('2009-12-24', '0.1.0', '8e9d637985d2dc9b44922076ad54ffef7fa8e9c2')
+```
+
+Initial CoffeeScript release.

documentation/sections/changelog/0.1.1.md

@@ -0,0 +1,5 @@
+```
+releaseHeader('2009-12-24', '0.1.1', '0.1.0')
+```
+
+Added `instanceof` and `typeof` as operators.

documentation/sections/changelog/0.1.2.md

@@ -0,0 +1,5 @@
+```
+releaseHeader('2009-12-24', '0.1.2', '0.1.1')
+```
+
+Fixed a bug with calling `super()` through more than one level of inheritance, with the re-addition of the `extends` keyword. Added experimental [Narwhal](http://narwhaljs.org/) support (as a Tusk package), contributed by [Tom Robinson](http://blog.tlrobinson.net/), including **bin/cs** as a CoffeeScript REPL and interpreter. New `--no-wrap` option to suppress the safety function wrapper.

documentation/sections/changelog/0.1.3.md

@@ -0,0 +1,5 @@
+```
+releaseHeader('2009-12-25', '0.1.3', '0.1.2')
+```
+
+The `coffee` command now includes `--interactive`, which launches an interactive CoffeeScript session, and `--run`, which directly compiles and executes a script. Both options depend on a working installation of Narwhal. The `aint` keyword has been replaced by `isnt`, which goes together a little smoother with `is`. Quoted strings are now allowed as identifiers within object literals: eg. `{"5+5": 10}`. All assignment operators now use a colon: `+:`, `-:`, `*:`, etc.

documentation/sections/changelog/0.1.4.md

@@ -0,0 +1,5 @@
+```
+releaseHeader('2009-12-25', '0.1.4', '0.1.3')
+```
+
+The official CoffeeScript extension is now `.coffee` instead of `.cs`, which properly belongs to [C#](https://en.wikipedia.org/wiki/C_Sharp_(programming_language)). Due to popular demand, you can now also use `=` to assign. Unlike JavaScript, `=` can also be used within object literals, interchangeably with `:`. Made a grammatical fix for chained function calls like `func(1)(2)(3)(4)`. Inheritance and super no longer use `__proto__`, so they should be IE-compatible now.

documentation/sections/changelog/0.1.5.md

@@ -0,0 +1,5 @@
+```
+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 `coffeescript` command is now called `coffee`.

documentation/sections/changelog/0.1.6.md

@@ -0,0 +1,5 @@
+```
+releaseHeader('2009-12-27', '0.1.6', '0.1.5')
+```
+
+Bugfix for running `coffee --interactive` and `--run` from outside of the CoffeeScript directory. Bugfix for nested function/if-statements.

documentation/sections/changelog/0.2.0.md

@@ -0,0 +1,5 @@
+```
+releaseHeader('2010-01-05', '0.2.0', '0.1.6')
+```
+
+Major release. Significant whitespace. Better statement-to-expression conversion. Splats. Splice literals. Object comprehensions. Blocks. The existential operator. Many thanks to all the folks who posted issues, with special thanks to [Liam O’Connor-Davis](https://github.com/liamoc) for whitespace and expression help.

documentation/sections/changelog/0.2.1.md

@@ -0,0 +1,5 @@
+```
+releaseHeader('2010-01-05', '0.2.1', '0.2.0')
+```
+
+Arguments objects are now converted into real arrays when referenced.

documentation/sections/changelog/0.2.2.md

@@ -0,0 +1,10 @@
+```
+releaseHeader('2010-01-10', '0.2.2', '0.2.1')
+```
+
+When performing a comprehension over an object, use `ino`, instead of `in`, which helps us generate smaller, more efficient code at compile time.
+Added `::` as a shorthand for saying `.prototype.`
+The “splat” symbol has been changed from a prefix asterisk `*`, to a postfix ellipsis `...`
+Added JavaScript’s `in` operator, empty `return` statements, and empty `while` loops.
+Constructor functions that start with capital letters now include a safety check to make sure that the new instance of the object is returned.
+The `extends` keyword now functions identically to `goog.inherits` in Google’s Closure Library.

documentation/sections/changelog/0.2.3.md

@@ -0,0 +1,5 @@
+```
+releaseHeader('2010-01-11', '0.2.3', '0.2.2')
+```
+
+Axed the unsatisfactory `ino` keyword, replacing it with `of` for object comprehensions. They now look like: `for prop, value of object`.

documentation/sections/changelog/0.2.4.md

@@ -0,0 +1,5 @@
+```
+releaseHeader('2010-01-12', '0.2.4', '0.2.3')
+```
+
+Added ECMAScript Harmony style destructuring assignment, for dealing with extracting values from nested arrays and objects. Added indentation-sensitive heredocs for nicely formatted strings or chunks of code.