From 8ce7c30c4929031c3bc1b2daf41a6db8de891f2e Mon Sep 17 00:00:00 2001 From: Geoffrey Booth Date: Sun, 22 Jan 2017 13:30:38 -0800 Subject: [PATCH] Update generated docs for 1.12.3 --- docs/v1/annotated-source/coffee-script.html | 335 ++++++++++++++++---- docs/v1/annotated-source/nodes.html | 7 +- docs/v1/index.html | 21 +- 3 files changed, 290 insertions(+), 73 deletions(-) diff --git a/docs/v1/annotated-source/coffee-script.html b/docs/v1/annotated-source/coffee-script.html index 9c498ae5..99a4d22a 100644 --- a/docs/v1/annotated-source/coffee-script.html +++ b/docs/v1/annotated-source/coffee-script.html @@ -249,25 +249,17 @@ lexer/parser/compiler.

-

Compile CoffeeScript code to JavaScript, using the Coffee/Jison compiler.

-

If options.sourceMap is specified, then options.filename must also be specified. All -options that can be passed to SourceMap#generate may also be passed here.

-

This returns a javascript string, unless options.sourceMap is passed, -in which case this returns a {js, v3SourceMap, sourceMap} -object, where sourceMap is a sourcemap.coffee#SourceMap object, handy for doing programatic -lookups.

+

For each compiled file, save its source in memory in case we need to +recompile it later. We might need to recompile if the first compilation +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 filename: (source)

- 
exports.compile = compile = withPrettyErrors (code, options) ->
-  {merge, extend} = helpers
-  options = extend {}, options
-  generateSourceMap = options.sourceMap or options.inlineMap
-
-  if generateSourceMap
-    map = new SourceMap
-
-  tokens = lexer.tokenize code, options
+ 
sources = {}
@@ -278,6 +270,68 @@ lookups.

+

Also save source maps if generated, in form of filename: (source map).

+ + + + 
sourceMaps = {}
+ + + + +
  • +
    + +
    + +
    +

    Compile CoffeeScript code to JavaScript, using the Coffee/Jison compiler.

    +

    If options.sourceMap is specified, then options.filename must also be +specified. All options that can be passed to SourceMap#generate may also +be passed here.

    +

    This returns a javascript string, unless options.sourceMap is passed, +in which case this returns a {js, v3SourceMap, sourceMap} +object, where sourceMap is a sourcemap.coffee#SourceMap object, handy for +doing programmatic lookups.

    + +
    + + 
    exports.compile = compile = withPrettyErrors (code, options) ->
+  {merge, extend} = helpers
+  options = extend {}, options
    + +
    • + + +
  • +
    + +
    + +
    +

    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 +we need to recompile it to get a source map for prepareStackTrace.

    + +
    + + 
      generateSourceMap = options.sourceMap or options.inlineMap or not options.filename?
+  filename = options.filename or '<anonymous>'
+
+  sources[filename] = code
+  map = new SourceMap if generateSourceMap
+
+  tokens = lexer.tokenize code, options
    + +
    • + + +
  • +
    + +
    + +

    Pass a list of referenced variables, so that generated variables won’t get the same name.

    @@ -290,13 +344,13 @@ the same name.

    • -
  • +
  • - +
    -

    Check for import or export; if found, force bare mode

    +

    Check for import or export; if found, force bare mode.

    @@ -318,13 +372,13 @@ the same name.

    • -
  • +
  • - +
    -

    Update the sourcemap with data from each fragment

    +

    Update the sourcemap with data from each fragment.

    @@ -333,11 +387,11 @@ the same name.

    • -
  • +
  • - +

    Do not include empty, whitespace, or semicolon-only fragments.

    @@ -358,11 +412,11 @@ the same name.

    • -
  • +
  • - +

    Copy the code from each fragment into the final JavaScript.

    @@ -376,6 +430,7 @@ the same name.

    if generateSourceMap v3SourceMap = map.generate(options, code) + sourceMaps[filename] = map if options.inlineMap encoded = base64encode JSON.stringify v3SourceMap @@ -395,11 +450,11 @@ the same name.

    • -
  • +
  • - +

    Tokenize a string of CoffeeScript code, and return the array of tokens.

    @@ -411,11 +466,11 @@ the same name.

    • -
  • +
  • - +

    Parse a string of CoffeeScript code or an array of lexed tokens, and return the AST. You can then compile it by calling .compile() on the root, @@ -432,11 +487,11 @@ or traverse it by using .traverseChildren() with a callback.

    • -
  • +
  • - +

    Compile and execute a string of CoffeeScript (on the server), correctly setting __filename, __dirname, and relative require().

    @@ -449,27 +504,27 @@ setting __filename, __dirname, and relative requ
    • -
  • +
  • - +

    Set the filename.

      mainModule.filename = process.argv[1] =
-    if options.filename then fs.realpathSync(options.filename) else '.'
    + if options.filename then fs.realpathSync(options.filename) else '<anonymous>'
    • -
  • +
  • - +

    Clear the module cache.

    @@ -480,17 +535,17 @@ setting __filename, __dirname, and relative requ
    • -
  • +
  • - +

    Assign paths for node_modules loading

    - 
      dir = if options.filename
+            
      dir = if options.filename?
     path.dirname fs.realpathSync options.filename
   else
     fs.realpathSync '.'
@@ -499,11 +554,11 @@ setting __filename, __dirname, and relative requ
    • -
  • +
  • - +

    Compile.

    @@ -518,11 +573,11 @@ setting __filename, __dirname, and relative requ
    • -
  • +
  • - +

    Compile and evaluate a string of CoffeeScript (in a Node.js-like environment). The CoffeeScript REPL uses this to run the input.

    @@ -552,11 +607,11 @@ The CoffeeScript REPL uses this to run the input.

    • -
  • +
  • - +

    define module/require only if they chose not to specify their own

    @@ -573,11 +628,11 @@ The CoffeeScript REPL uses this to run the input.

    • -
  • +
  • - +

    use the same hack node currently uses for their own REPL

    @@ -599,11 +654,11 @@ exports.register = -> +
  • - +

    Throw error with deprecation warning when depending upon implicit require.extensions registration

    @@ -617,8 +672,22 @@ exports.register = -> exports._compileFile = (filename, sourceMap = no, inlineMap = no) -> - raw = fs.readFileSync filename, 'utf8' - stripped = if raw.charCodeAt(0) is 0xFEFF then raw.substring 1 else raw + raw = fs.readFileSync filename, 'utf8'
    + +
    • + + +
  • +
    + +
    + +
    +

    Strip the Unicode byte order mark, if this file begins with one.

    + +
    + + 
      stripped = if raw.charCodeAt(0) is 0xFEFF then raw.substring 1 else raw
 
   try
     answer = compile stripped, {
@@ -631,11 +700,11 @@ exports._compileFile = (fi
    • -
  • +
  • - +

    As the filename and code of a dynamically loaded file will be different from the original file compiled with CoffeeScript.run, add that @@ -650,11 +719,11 @@ information to error so it can be pretty-printed later.

    • -
  • +
  • - +

    Instantiate a Lexer for our use here.

    @@ -665,11 +734,11 @@ information to error so it can be pretty-printed later.

    • -
  • +
  • - +

    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 @@ -697,11 +766,11 @@ directly as a “Jison lexer”.

    • -
  • +
  • - +

    Make all the AST nodes visible to the parser.

    @@ -712,11 +781,11 @@ directly as a “Jison lexer”.

    • -
  • +
  • - +

    Override Jison’s default error handling function.

    @@ -727,11 +796,11 @@ directly as a “Jison lexer”.

    • -
  • +
  • - +

    Disregard Jison’s message, it contains redundant line number information. Disregard the token, we take its value directly from the lexer in case @@ -755,11 +824,11 @@ the error is caused by a generated token which might refer to its origin.

    • -
  • +
  • - +

    The second argument has a loc property, which should have the location data for this token. Unfortunately, Jison seems to send an outdated loc @@ -772,6 +841,140 @@ from the lexer.

    • + +
  • +
    + +
    + +
    +

    Based on http://v8.googlecode.com/svn/branches/bleeding_edge/src/messages.js +Modified to handle sourceMap

    + +
    + + 
    formatSourcePosition = (frame, getSourceMapping) ->
+  filename = undefined
+  fileLocation = ''
+
+  if frame.isNative()
+    fileLocation = "native"
+  else
+    if frame.isEval()
+      filename = frame.getScriptNameOrSourceURL()
+      fileLocation = "#{frame.getEvalOrigin()}, " unless filename
+    else
+      filename = frame.getFileName()
+
+    filename or= "<anonymous>"
+
+    line = frame.getLineNumber()
+    column = frame.getColumnNumber()
    + +
    • + + +
  • +
    + +
    + +
    +

    Check for a sourceMap position

    + +
    + + 
        source = getSourceMapping filename, line, column
+    fileLocation =
+      if source
+        "#{filename}:#{source[0]}:#{source[1]}"
+      else
+        "#{filename}:#{line}:#{column}"
+
+  functionName = frame.getFunctionName()
+  isConstructor = frame.isConstructor()
+  isMethodCall = not (frame.isToplevel() or isConstructor)
+
+  if isMethodCall
+    methodName = frame.getMethodName()
+    typeName = frame.getTypeName()
+
+    if functionName
+      tp = as = ''
+      if typeName and functionName.indexOf typeName
+        tp = "#{typeName}."
+      if methodName and functionName.indexOf(".#{methodName}") isnt functionName.length - methodName.length - 1
+        as = " [as #{methodName}]"
+
+      "#{tp}#{functionName}#{as} (#{fileLocation})"
+    else
+      "#{typeName}.#{methodName or '<anonymous>'} (#{fileLocation})"
+  else if isConstructor
+    "new #{functionName or '<anonymous>'} (#{fileLocation})"
+  else if functionName
+    "#{functionName} (#{fileLocation})"
+  else
+    fileLocation
+
+getSourceMap = (filename) ->
+  if sourceMaps[filename]?
+    sourceMaps[filename]
    + +
    • + + +
  • +
    + +
    + +
    +

    CoffeeScript compiled in a browser may get compiled with options.filename +of <anonymous>, but the browser may request the stack trace with the +filename of the script file.

    + +
    + + 
      else if sourceMaps['<anonymous>']?
+    sourceMaps['<anonymous>']
+  else if sources[filename]?
+    answer = compile sources[filename],
+      filename: filename
+      sourceMap: yes
+    answer.sourceMap
+  else
+    null
    + +
    • + + +
  • +
    + +
    + +
    +

    Based on michaelficarra/CoffeeScriptRedux +NodeJS / V8 have no support for transforming positions in stack traces using +sourceMap, so we must monkey-patch Error to display CoffeeScript source +positions.

    + +
    + + 
    Error.prepareStackTrace = (err, stack) ->
+  getSourceMapping = (filename, line, column) ->
+    sourceMap = getSourceMap filename
+    answer = sourceMap.sourceLocation [line - 1, column - 1] if sourceMap?
+    if answer? then [answer[0] + 1, answer[1] + 1] else null
+
+  frames = for frame in stack
+    break if frame.getFunction() is exports.run
+    "    at #{formatSourcePosition frame, getSourceMapping}"
+
+  "#{err.toString()}\n#{frames.join '\n'}\n"
    + +
    • + diff --git a/docs/v1/annotated-source/nodes.html b/docs/v1/annotated-source/nodes.html index 8d1c78bc..2b60c5a4 100644 --- a/docs/v1/annotated-source/nodes.html +++ b/docs/v1/annotated-source/nodes.html @@ -4114,7 +4114,8 @@ used sequentially. For example:

    compileFloorDivision: (o) -> floor = new Value new IdentifierLiteral('Math'), [new Access new PropertyName 'floor'] - div = new Op '/', @first, @second + second = if @second.isComplex() then new Parens @second else @second + div = new Op '/', @first, second new Call(floor, [div]).compileToFragments o compileModulo: (o) -> @@ -4591,7 +4592,7 @@ you can map and filter in a single pass.

    @index.error 'cannot use index with for-from' if @from and @index source.ownTag.error "cannot use own with for-#{if @from then 'from' else 'in'}" if @own and not @object [@name, @index] = [@index, @name] if @object - @index.error 'index cannot be a pattern matching expression' if @index instanceof Value + @index.error 'index cannot be a pattern matching expression' if @index instanceof Value and not @index.isAssignable() @range = @source instanceof Value and @source.base instanceof Range and not @source.properties.length and not @from @pattern = @name instanceof Value @index.error 'indexes do not apply to range loops' if @range and @index @@ -4625,7 +4626,7 @@ some cannot.

    name = @name and (@name.compile o, LEVEL_LIST) if not @pattern index = @index and (@index.compile o, LEVEL_LIST) scope.find(name) if name and not @pattern - scope.find(index) if index + scope.find(index) if index and @index not instanceof Value rvar = scope.freeVariable 'results' if @returns if @from ivar = scope.freeVariable 'x', single: true if @pattern diff --git a/docs/v1/index.html b/docs/v1/index.html index 83654de4..983dc44d 100644 --- a/docs/v1/index.html +++ b/docs/v1/index.html @@ -607,7 +607,7 @@ pre .xml .cdata {

    CoffeeScript is a little language that compiles into JavaScript. Underneath that awkward Java-esque patina, JavaScript has always had a gorgeous heart. CoffeeScript is an attempt to expose the good parts of JavaScript in a simple way.

    The golden rule of CoffeeScript is: “It’s just JavaScript”. The code compiles one-to-one into the equivalent JS, and there is no interpretation at runtime. You can use any existing JavaScript library seamlessly from CoffeeScript (and vice-versa). The compiled output is readable, pretty-printed, and tends to run as fast or faster than the equivalent handwritten JavaScript.

    The CoffeeScript compiler goes to great lengths to generate output JavaScript that runs in every JavaScript runtime, but there are exceptions. Use generator functions, for…from, or tagged template literals only if you know that your target runtimes can support them. If you use modules, you will need to use an additional tool to resolve them.

    -

    Latest Version: 1.12.2

    +

    Latest Version: 1.12.3

    npm install -g coffee-script
    @@ -1936,8 +1936,10 @@ ref = weatherReport("Berkeley, CA"), city = ref[0], temp = ref[1], for "Bellagio, Italy 22021" ] +{sculptor} = futurists + {poet: {name, address: [street, city]}} = futurists -
    var city, futurists, name, ref, ref1, street;
+
    var city, futurists, name, ref, ref1, sculptor, street;
 
 futurists = {
   sculptor: "Umberto Boccioni",
@@ -1948,8 +1950,10 @@ futurists = {
   }
 };
 
+sculptor = futurists.sculptor;
+
 ref = futurists.poet, name = ref.name, (ref1 = ref.address, street = ref1[0], city = ref1[1]);
-
    load
    load
    run: name + "-" + street

    Destructuring assignment can even be combined with splats.

    tag = "<impossible>"
@@ -2603,7 +2609,14 @@ The CoffeeScript logo is available in SVG for use in presentations.
 
 
   
-    
    Change Log
    
+    
    Change Log
    
+
    
+  1.12.3
+   — 
+
      
+
    • 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.
      • 
+
    
+
    
 
    
   1.12.2
    —