diff --git a/Cakefile b/Cakefile index 61d46227b1..d002ccb48b 100644 --- a/Cakefile +++ b/Cakefile @@ -24,65 +24,31 @@ header = """ */ """ -# Used in folder names like docs/v1 +# Used in folder names like `docs/v1`. majorVersion = parseInt CoffeeScript.VERSION.split('.')[0], 10 -# Build the CoffeeScript language from source. -build = (cb) -> - files = fs.readdirSync 'src' - files = ('src/' + file for file in files when file.match(/\.(lit)?coffee$/)) - run ['-c', '-o', 'lib/coffee-script'].concat(files), cb - -# Run a CoffeeScript through our node/coffee interpreter. -run = (args, cb) -> - proc = spawn 'node', ['bin/coffee'].concat(args) - proc.stderr.on 'data', (buffer) -> console.log buffer.toString() - proc.on 'exit', (status) -> - process.exit(1) if status isnt 0 - cb() if typeof cb is 'function' # Log a message with a color. log = (message, color, explanation) -> console.log color + message + reset + ' ' + (explanation or '') -option '-p', '--prefix [DIR]', 'set the installation prefix for `cake install`' - -task 'install', 'install CoffeeScript into /usr/local (or --prefix)', (options) -> - base = options.prefix or '/usr/local' - lib = "#{base}/lib/coffee-script" - bin = "#{base}/bin" - node = "~/.node_libraries/coffee-script" - console.log "Installing CoffeeScript to #{lib}" - console.log "Linking to #{node}" - console.log "Linking 'coffee' to #{bin}/coffee" - exec([ - "mkdir -p #{lib} #{bin}" - "cp -rf bin lib LICENSE README.md package.json src #{lib}" - "ln -sfn #{lib}/bin/coffee #{bin}/coffee" - "ln -sfn #{lib}/bin/cake #{bin}/cake" - "mkdir -p ~/.node_libraries" - "ln -sfn #{lib}/lib/coffee-script #{node}" - ].join(' && '), (err, stdout, stderr) -> - if err then console.log stderr.trim() else log 'done', green - ) - - -task 'build', 'build the CoffeeScript language from source', build - -task 'build:full', 'rebuild the source twice, and run the tests', -> - build -> - build -> - csPath = './lib/coffee-script' - csDir = path.dirname require.resolve csPath - for mod of require.cache when csDir is mod[0 ... csDir.length] - delete require.cache[mod] +spawnNodeProcess = (args, output = 'stderr', callback) -> + relayOutput = (buffer) -> console.log buffer.toString() + proc = spawn 'node', args + proc.stdout.on 'data', relayOutput if output is 'both' or output is 'stdout' + proc.stderr.on 'data', relayOutput if output is 'both' or output is 'stderr' + proc.on 'exit', (status) -> callback(status) if typeof callback is 'function' - unless runTests require csPath - process.exit 1 +# Run a CoffeeScript through our node/coffee interpreter. +run = (args, callback) -> + spawnNodeProcess ['bin/coffee'].concat(args), 'stderr', (status) -> + process.exit(1) if status isnt 0 + callback() if typeof callback is 'function' -task 'build:parser', 'rebuild the Jison parser (run build first)', -> +# Build the CoffeeScript language from source. +buildParser = -> helpers.extend global, require 'util' require 'jison' parser = require('./lib/coffee-script/grammar').parser.generate() @@ -95,8 +61,62 @@ task 'build:parser', 'rebuild the Jison parser (run build first)', -> source = fs""" fs.writeFileSync 'lib/coffee-script/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 + +build = (callback) -> + buildParser() + buildExceptParser callback + +testBuiltCode = (watch = no) -> + csPath = './lib/coffee-script' + csDir = path.dirname require.resolve csPath + + for mod of require.cache when csDir is mod[0 ... csDir.length] + delete require.cache[mod] + + testResults = runTests require csPath + unless watch + process.exit 1 unless testResults + +buildAndTest = (includingParser = yes, harmony = no) -> + process.stdout.write '\x1Bc' # Clear terminal screen. + execSync 'git checkout lib/*', stdio: [0,1,2] # Reset the generated compiler. + + buildArgs = ['bin/cake'] + buildArgs.push if includingParser then 'build' else 'build:except-parser' + log "building#{if includingParser then ', including parser' else ''}...", green + spawnNodeProcess buildArgs, 'both', -> + log 'testing...', green + testArgs = if harmony then ['--harmony'] else [] + testArgs = testArgs.concat ['bin/cake', 'test'] + spawnNodeProcess testArgs, 'both' -task 'build:browser', 'rebuild the merged script for inclusion in the browser', -> +watchAndBuildAndTest = (harmony = no) -> + buildAndTest yes, harmony + fs.watch 'src/', interval: 200, (eventType, filename) -> + if eventType is 'change' + log "src/#{filename} changed, rebuilding..." + buildAndTest (filename is 'grammar.coffee'), harmony + fs.watch 'test/', {interval: 200, recursive: yes}, (eventType, filename) -> + if eventType is 'change' + log "test/#{filename} changed, rebuilding..." + buildAndTest no, harmony + + +task 'build', 'build the CoffeeScript compiler from source', build + +task 'build:parser', 'build the Jison parser only', buildParser + +task 'build:except-parser', 'build the CoffeeScript compiler, except for the Jison parser', buildExceptParser + +task 'build:full', 'build the CoffeeScript compiler from source twice, and run the tests', -> + build -> + build testBuiltCode + +task 'build:browser', 'build the merged script for inclusion in the browser', -> code = """ require['../../package.json'] = (function() { return #{fs.readFileSync "./package.json"}; @@ -137,8 +157,14 @@ task 'build:browser', 'rebuild the merged script for inclusion in the browser', console.log "built ... running browser tests:" invoke 'test:browser' +task 'build:watch', 'watch and continually rebuild the CoffeeScript compiler, running tests on each build', -> + watchAndBuildAndTest() + +task 'build:watch:harmony', 'watch and continually rebuild the CoffeeScript compiler, running harmony tests on each build', -> + watchAndBuildAndTest yes + -task 'doc:site', 'watch and continually rebuild the documentation for the website', -> +buildDocs = (watch = no) -> # Constants indexFile = 'documentation/index.html' versionedSourceFolder = "documentation/v#{majorVersion}" @@ -211,12 +237,19 @@ task 'doc:site', 'watch and continually rebuild the documentation for the websit fs.symlinkSync "v#{majorVersion}/index.html", 'docs/index.html' catch exception - for target in [indexFile, versionedSourceFolder, examplesSourceFolder, sectionsSourceFolder] - fs.watch target, interval: 200, renderIndex - log 'watching...' , green + if watch + for target in [indexFile, versionedSourceFolder, examplesSourceFolder, sectionsSourceFolder] + fs.watch target, interval: 200, renderIndex + log 'watching...', green +task 'doc:site', 'build the documentation for the website', -> + buildDocs() -task 'doc:test', 'watch and continually rebuild the browser-based tests', -> +task 'doc:site:watch', 'watch and continually rebuild the documentation for the website', -> + buildDocs yes + + +buildDocTests = (watch = no) -> # Constants testFile = 'documentation/test.html' testsSourceFolder = 'test' @@ -254,14 +287,40 @@ task 'doc:test', 'watch and continually rebuild the browser-based tests', -> fs.writeFileSync "#{outputFolder}/test.html", output log 'compiled', green, "#{testFile} → #{outputFolder}/test.html" - for target in [testFile, testsSourceFolder] - fs.watch target, interval: 200, renderTest - log 'watching...' , green + if watch + for target in [testFile, testsSourceFolder] + fs.watch target, interval: 200, renderTest + log 'watching...', green + +task 'doc:test', 'build the browser-based tests', -> + buildDocTests() + +task 'doc:test:watch', 'watch and continually rebuild the browser-based tests', -> + buildDocTests yes + + +buildAnnotatedSource = (watch = no) -> + do generateAnnotatedSource = -> + exec "node_modules/docco/bin/docco src/*.*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 + fs.watch 'src/', interval: 200, generateAnnotatedSource + log 'watching...', green + +task 'doc:source', 'build the annotated source documentation', -> + buildAnnotatedSource() +task 'doc:source:watch', 'watch and continually rebuild the annotated source documentation', -> + buildAnnotatedSource yes -task 'doc:source', 'rebuild the annotated source documentation', -> - exec "node_modules/docco/bin/docco src/*.*coffee --output docs/v#{majorVersion}/annotated-source", (err) -> throw err if err +task 'release', 'build and test the CoffeeScript source, and build the documentation', -> + invoke 'build:full' + invoke 'build:browser' + invoke 'doc:site' + invoke 'doc:test' + invoke 'doc:source' task 'bench', 'quick benchmark of compilation time', -> {Rewriter} = require './lib/coffee-script/rewriter' diff --git a/README.md b/README.md index 486d7d26db..432c83ce2d 100644 --- a/README.md +++ b/README.md @@ -25,15 +25,10 @@ CoffeeScript is a little language that compiles into JavaScript. If you have the node package manager, npm, installed: ```shell -npm install -g coffee-script +npm install --global coffee-script ``` -Leave off the `-g` if you don't wish to install globally. If you don't wish to use npm: - -```shell -git clone https://github.com/jashkenas/coffeescript.git -sudo coffeescript/bin/cake install -``` +Leave off the `--global` if you don’t wish to install globally. ## Getting Started @@ -53,7 +48,7 @@ For documentation, usage, and examples, see: http://coffeescript.org/ To suggest a feature or report a bug: http://github.com/jashkenas/coffeescript/issues -If you'd like to chat, drop by #coffeescript on Freenode IRC. +If you’d like to chat, drop by #coffeescript on Freenode IRC. The source repository: https://github.com/jashkenas/coffeescript.git diff --git a/docs/v1/annotated-source/coffee-script.html b/docs/v1/annotated-source/coffee-script.html index 99a4d22ab0..634839ba53 100644 --- a/docs/v1/annotated-source/coffee-script.html +++ b/docs/v1/annotated-source/coffee-script.html @@ -941,6 +941,7 @@

coffee-script.coffee

answer = compile sources[filename], filename: filename sourceMap: yes + literate: helpers.isLiterate filename answer.sourceMap else null diff --git a/docs/v1/annotated-source/lexer.html b/docs/v1/annotated-source/lexer.html index b0cebbb9b2..1a34a1871b 100644 --- a/docs/v1/annotated-source/lexer.html +++ b/docs/v1/annotated-source/lexer.html @@ -710,10 +710,10 @@

Tokenizers

@token 'CALL_START', '(', 0, 0 @mergeInterpolationTokens tokens, {delimiter: '"', double: yes}, @formatHeregex if flags - @token ',', ',', index, 0 - @token 'STRING', '"' + flags + '"', index, flags.length - @token ')', ')', end, 0 - @token 'REGEX_END', ')', end, 0 + @token ',', ',', index - 1, 0 + @token 'STRING', '"' + flags + '"', index - 1, flags.length + @token ')', ')', end - 1, 0 + @token 'REGEX_END', ')', end - 1, 0 end diff --git a/docs/v1/annotated-source/nodes.html b/docs/v1/annotated-source/nodes.html index 2b60c5a455..22f350c244 100644 --- a/docs/v1/annotated-source/nodes.html +++ b/docs/v1/annotated-source/nodes.html @@ -1404,6 +1404,33 @@

Call

+

When setting the location, we sometimes need to update the start location to +account for a newly-discovered new operator to the left of us. This +expands the range on the left, but not the right.

+ + + + 
  updateLocationDataIfMissing: (locationData) ->
+    if @locationData and @needsUpdatedStartLocation
+      @locationData.first_line = locationData.first_line
+      @locationData.first_column = locationData.first_column
+      base = @variable?.base or @variable
+      if base.needsUpdatedStartLocation
+        @variable.locationData.first_line = locationData.first_line
+        @variable.locationData.first_column = locationData.first_column
+        base.updateLocationDataIfMissing locationData
+      delete @needsUpdatedStartLocation
+    super
+ + + + +
  • +
    + +
    + +

    Tag this invocation as creating a new instance.

    @@ -1414,16 +1441,17 @@

    Call

    base.newInstance() else @isNew = true + @needsUpdatedStartLocation = true this
    • -
  • +
  • - +

    Soaked chained invocations unfold into if/else ternary structures.

    @@ -1463,11 +1491,11 @@

    Call

    • -
  • +
  • - +

    Compile a vanilla function call.

    @@ -1499,11 +1527,11 @@

    Call

    • -
  • +
  • - +

    If you call a function with a splat, it’s converted into a JavaScript .apply() call to allow an array of arguments to be passed. @@ -1551,11 +1579,11 @@

    Call

    • -
  • +
  • - +

    Super

    @@ -1564,11 +1592,11 @@

    Super

    • -
  • +
  • - +

    Takes care of converting super() calls into calls against the prototype’s function of the same name.

    @@ -1582,11 +1610,11 @@

    Super

    • -
  • +
  • - +

    Allow to recognize a bare super call without parentheses and arguments.

    @@ -1597,11 +1625,11 @@

    Super

    • -
  • +
  • - +

    Grab the reference to the superclass’s implementation of the current method.

    @@ -1634,11 +1662,11 @@

    Super

    • -
  • +
  • - +

    The appropriate this value for a super call.

    @@ -1651,11 +1679,11 @@

    Super

    • -
  • +
  • - +

    RegexWithInterpolations

    @@ -1664,11 +1692,11 @@

    RegexWithInterpolations

    • -
  • +
  • - +

    Regexes with interpolations are in fact just a variation of a Call (a RegExp() call to be precise) with a StringWithInterpolations inside.

    @@ -1682,11 +1710,11 @@

    RegexWithInterpolations

    • -
  • +
  • - +

    TaggedTemplateCall

    @@ -1703,11 +1731,11 @@

    TaggedTemplateCall

    • -
  • +
  • - +

    Tell StringWithInterpolations whether to compile as ES2015 or not; will be removed in CoffeeScript 2.

    @@ -1719,11 +1747,11 @@

    TaggedTemplateCall

    • -
  • +
  • - +

    Extends

    @@ -1732,11 +1760,11 @@

    Extends

    • -
  • +
  • - +

    Node to extend an object’s prototype with an ancestor object. After goog.inherits from the @@ -1752,11 +1780,11 @@

    Extends

    • -
  • +
  • - +

    Hooks one constructor into another’s prototype chain.

    @@ -1768,11 +1796,11 @@

    Extends

    • -
  • +
  • - +

    Access

    @@ -1781,11 +1809,11 @@

    Access

    • -
  • +
  • - +

    A . access into a property of a value, or the :: shorthand for an access into the object’s prototype.

    @@ -1814,11 +1842,11 @@

    Access

    • -
  • +
  • - +

    Index

    @@ -1827,11 +1855,11 @@

    Index

    • -
  • +
  • - +

    A [ ... ] indexed access into an array or object.

    @@ -1851,11 +1879,11 @@

    Index

    • -
  • +
  • - +

    Range

    @@ -1864,11 +1892,11 @@

    Range

    • -
  • +
  • - +

    A range literal. Ranges can be used to extract portions (slices) of arrays, to specify a range for comprehensions, or as a value, to be expanded into the @@ -1887,11 +1915,11 @@

    Range

    • -
  • +
  • - +

    Compiles the range’s source variables – where it starts and where it ends. But only if they need to be cached to avoid double evaluation.

    @@ -1911,11 +1939,11 @@

    Range

    • -
  • +
  • - +

    When compiled normally, the range returns the contents of the for loop needed to iterate over the values in the range. Used by comprehensions.

    @@ -1929,11 +1957,11 @@

    Range

    • -
  • +
  • - +

    Set up endpoints.

    @@ -1951,11 +1979,11 @@

    Range

    • -
  • +
  • - +

    Generate the condition.

    @@ -1973,11 +2001,11 @@

    Range

    • -
  • +
  • - +

    Generate the step.

    @@ -2002,11 +2030,11 @@

    Range

    • -
  • +
  • - +

    The final loop body.

    @@ -2017,11 +2045,11 @@

    Range

    • -
  • +
  • - +

    When used as a value, expand the range into the equivalent array.

    @@ -2052,11 +2080,11 @@

    Range

    • -
  • +
  • - +

    Slice

    @@ -2065,11 +2093,11 @@

    Slice

    • -
  • +
  • - +

    An array slice literal. Unlike JavaScript’s Array#slice, the second parameter specifies the index of the end of the slice, just as the first parameter @@ -2087,11 +2115,11 @@

    Slice

    • -
  • +
  • - +

    We have to be careful when trying to slice through the end of the array, 9e9 is used because not all implementations respect undefined or 1/0. @@ -2106,11 +2134,11 @@

    Slice

    • -
  • +
  • - +

    TODO: jwalton - move this into the ‘if’?

    @@ -2132,11 +2160,11 @@

    Slice

    • -
  • +
  • - +

    Obj

    @@ -2145,11 +2173,11 @@

    Obj

    • -
  • +
  • - +

    An object literal, nothing fancy.

    @@ -2222,11 +2250,11 @@

    Obj

    • -
  • +
  • - +

    Arr

    @@ -2235,11 +2263,11 @@

    Arr

    • -
  • +
  • - +

    An array literal.

    @@ -2278,11 +2306,11 @@

    Arr

    • -
  • +
  • - +

    Class

    @@ -2291,11 +2319,11 @@

    Class

    • -
  • +
  • - +

    The CoffeeScript class definition. Initialize a Class with its name, an optional superclass, and a @@ -2315,11 +2343,11 @@

    Class

    • -
  • +
  • - +

    Figure out the appropriate name for the constructor function of this class.

    @@ -2343,11 +2371,11 @@

    Class

    • -
  • +
  • - +

    For all this-references and bound functions in the class definition, this is the Class being constructed.

    @@ -2365,11 +2393,11 @@

    Class

    • -
  • +
  • - +

    Ensure that all functions bound to the instance are proxied in the constructor.

    @@ -2385,11 +2413,11 @@

    Class

    • -
  • +
  • - +

    Merge the properties from a top-level object as prototypal properties on the class.

    @@ -2428,11 +2456,11 @@

    Class

    • -
  • +
  • - +

    Walk the body of the class, looking for prototype properties to be converted and tagging static assignments.

    @@ -2456,11 +2484,11 @@

    Class

    • -
  • +
  • - +

    use strict (and other directives) must be the first expression statement(s) of a function body. This method ensures the prologue is correctly positioned @@ -2478,11 +2506,11 @@

    Class

    • -
  • +
  • - +

    Make sure that a constructor is defined for the class, and properly configured.

    @@ -2505,11 +2533,11 @@

    Class

    • -
  • +
  • - +

    Instead of generating the JavaScript string directly, we build up the equivalent syntax tree and compile that, in pieces. You can see the @@ -2552,11 +2580,11 @@

    Class

    • -
  • +
  • - +

    Import and Export

    @@ -2628,11 +2656,11 @@

    Import and Export

    • -
  • +
  • - +

    Prevent exporting an anonymous class; all exported members must be named

    @@ -2644,11 +2672,11 @@

    Import and Export

    • -
  • +
  • - +

    When the ES2015 class keyword is supported, don’t add a var here

    @@ -2702,11 +2730,11 @@

    Import and Export

    • -
  • +
  • - +

    The name of the variable entering the local scope

    @@ -2717,7 +2745,7 @@

    Import and Export

    children: ['original', 'alias'] compileNode: (o) -> - o.scope.add @identifier, @moduleDeclarationType + o.scope.find @identifier, @moduleDeclarationType code = [] code.push @makeCode @original.value code.push @makeCode " as #{@alias.value}" if @alias? @@ -2732,11 +2760,11 @@

    Import and Export

    • -
  • +
  • - +

    Per the spec, symbols can’t be imported multiple times (e.g. import { foo, foo } from 'lib' is invalid)

    @@ -2760,11 +2788,11 @@

    Import and Export

    • -
  • +
  • - +

    Assign

    @@ -2773,11 +2801,11 @@

    Assign

    • -
  • +
  • - +

    The Assign is used to assign a local variable to value, or to set the property of an object – including within object literals.

    @@ -2807,11 +2835,11 @@

    Assign

    • -
  • +
  • - +

    Compile an assignment, delegating to compilePatternMatch or compileSplice if appropriate. Keep track of the name of the base object @@ -2846,11 +2874,11 @@

    Assign

    • -
  • +
  • - +

    moduleDeclaration can be 'import' or 'export'

    @@ -2881,11 +2909,11 @@

    Assign

    • -
  • +
  • - +

    Brief implementation of recursive pattern matching, when assigning array or object literals to a value. Peeks at their properties to assign inner names.

    @@ -2908,11 +2936,11 @@

    Assign

    • -
  • +
  • - +

    Pick the property straight off the value when there’s just one to pick (no need to cache the value into a variable).

    @@ -2925,11 +2953,11 @@

    Assign

    • -
  • +
  • - +

    A regular object pattern-match.

    @@ -2948,11 +2976,11 @@

    Assign

    • -
  • +
  • - +

    A shorthand {a, b, @c} = val pattern-match.

    @@ -2967,11 +2995,11 @@

    Assign

    • -
  • +
  • - +

    A regular array pattern-match.

    @@ -2993,11 +3021,11 @@

    Assign

    • -
  • +
  • - +

    Make vvar into a simple variable if it isn’t already.

    @@ -3039,11 +3067,11 @@

    Assign

    • -
  • +
  • - +

    A regular object pattern-match.

    @@ -3062,11 +3090,11 @@

    Assign

    • -
  • +
  • - +

    A shorthand {a, b, @c} = val pattern-match.

    @@ -3081,11 +3109,11 @@

    Assign

    • -
  • +
  • - +

    A regular array pattern-match.

    @@ -3107,11 +3135,11 @@

    Assign

    • -
  • +
  • - +

    When compiling a conditional assignment, take care to ensure that the operands are only evaluated once, even though we have to reference them @@ -3125,11 +3153,11 @@

    Assign

    • -
  • +
  • - +

    Disallow conditional assignment of undefined variables.

    @@ -3148,11 +3176,11 @@

    Assign

    • -
  • +
  • - +

    Convert special math assignment operators like a **= b to the equivalent extended form a = a ** b and then compiles that.

    @@ -3166,11 +3194,11 @@

    Assign

    • -
  • +
  • - +

    Compile the assignment from an array splice literal, using JavaScript’s Array#splice method.

    @@ -3200,11 +3228,11 @@

    Assign

    • -
  • +
  • - +

    Code

    @@ -3213,11 +3241,11 @@

    Code

    • -
  • +
  • - +

    A function definition. This is the only node that creates a new Scope. When for the purposes of walking the contents of a function body, the Code @@ -3244,11 +3272,11 @@

    Code

    • -
  • +
  • - +

    Compilation creates a new scope unless explicitly asked to share with the outer scope. Handles splat parameters in the parameter list by peeking at @@ -3266,11 +3294,11 @@

    Code

    • -
  • +
  • - +

    Handle bound functions early.

    @@ -3342,11 +3370,11 @@

    Code

    • -
  • +
  • - +

    Short-circuit traverseChildren method to prevent it from crossing scope boundaries unless crossScope is true.

    @@ -3359,11 +3387,11 @@

    Code

    • -
  • +
  • - +

    Param

    @@ -3372,11 +3400,11 @@

    Param

    • -
  • +
  • - +

    A parameter in a function definition. Beyond a typical JavaScript parameter, these parameters can also attach themselves to the context of the function, @@ -3417,11 +3445,11 @@

    Param

    • -
  • +
  • - +

    Iterates the name or names of a Param. In a sense, a destructured parameter represents multiple JS parameters. This @@ -3438,11 +3466,11 @@

    Param

    • -
  • +
  • - +