From 194baa0bd729c880dc48e7ca7c8d3e0dcc02f754 Mon Sep 17 00:00:00 2001 From: Jeremy Ashkenas Date: Mon, 18 Mar 2013 19:46:19 +0800 Subject: [PATCH] better docs for source maps --- documentation/docs/sourcemap.html | 119 ++++++++++++++---------------- lib/coffee-script/sourcemap.js | 4 +- src/sourcemap.litcoffee | 19 +++-- 3 files changed, 68 insertions(+), 74 deletions(-) diff --git a/documentation/docs/sourcemap.html b/documentation/docs/sourcemap.html index 97420185..5d00f0db 100644 --- a/documentation/docs/sourcemap.html +++ b/documentation/docs/sourcemap.html @@ -109,42 +109,35 @@

Source maps allow JavaScript runtimes to match running JavaScript back to -the original CoffeeScript source code that corresponds to it. In order to -produce maps, we must keep track of positions (line number, column number) -for every construct in the syntax tree, and be able to generate a map file --- which is a compact, VLQ-encoded representation of the JSON serialization -of this information -- to write out alongside the generated JavaScript. +the original source code that corresponds to it. This can be minified +JavaScript, but in our case, we're concerned with mapping pretty-printed +JavaScript back to CoffeeScript.

+

In order to produce maps, we must keep track of positions (line number, column number) +that originated every node in the syntax tree, and be able to generate a +map file +— which is a compact, VLQ-encoded representation of the JSON serialization +of this information — to write out alongside the generated JavaScript. + + +

+

LineMap

- 
{merge} = require './helpers'
-
  • -
    +
    -

    LineMap

    - -
    - -
    • - - -
  • -
    - -
    - -
    -

    Keeps track of information about column positions within a single line of -output JavaScript code. SourceMaps are implemented in terms of LineMaps. +

    A LineMap object keeps track of information about original line and column +positions for a single line of output JavaScript code. +SourceMaps are implemented in terms of LineMaps.

    @@ -165,11 +158,11 @@ output JavaScript code. SourceMaps are implemented in terms of
    • -
  • +
  • - +

    SourceMap

    @@ -178,11 +171,11 @@ output JavaScript code. SourceMaps are implemented in terms of
    • -
  • +
  • - +

    Maps locations in for a single generated JavaScript file back to locations in the original CoffeeScript source file. @@ -203,11 +196,11 @@ through the arrays of line and column buffer to produce it.

    • -
  • +
  • - +

    Adds a mapping to this SourceMap. sourceLocation and generatedLocation are both [line, column] arrays. If options.noReplace is true, then if there @@ -226,11 +219,11 @@ effect.

    • -
  • +
  • - +

    Look up the original position of a given line and column in the generated code. @@ -246,11 +239,11 @@ code.

    • -
  • +
  • - +

    V3 SourceMap Generation

    @@ -259,11 +252,11 @@ code.
    • -
  • +
  • - +

    Builds up a V3 source map, returning the generated JSON as a string. options.sourceRoot may be used to specify the sourceRoot written to the source @@ -293,11 +286,11 @@ set "sources" and "file", respectively.

    • -
  • +
  • - +

    Write a comma if we've already written a segment on this line. @@ -312,11 +305,11 @@ set "sources" and "file", respectively.

    • -
  • +
  • - +

    Write the next segment. Segments can be 1, 4, or 5 values. If just one, then it is a generated column which doesn't match anything in the source code. @@ -335,11 +328,11 @@ column for the current line:

    • -
  • +
  • - +

    The index into the list of sources: @@ -352,11 +345,11 @@ column for the current line:

    • -
  • +
  • - +

    The starting line in the original source, relative to the previous source line. @@ -372,11 +365,11 @@ column for the current line:

    • -
  • +
  • - +

    The starting column in the original source, relative to the previous column. @@ -391,11 +384,11 @@ column for the current line:

    • -
  • +
  • - +

    Produce the canonical JSON object format for a "v3" source map. @@ -418,11 +411,11 @@ column for the current line:

    • -
  • +
  • - +

    Base64 VLQ Encoding

    @@ -431,11 +424,11 @@ column for the current line:
    • -
  • +
  • - +

    Note that SourceMap VLQ encoding is "backwards". MIDI-style VLQ encoding puts the most-significant-bit (MSB) from the original value into the MSB of the VLQ @@ -457,11 +450,11 @@ bits of the original value encoded into the first byte of the VLQ encoded value.

    • -
  • +
  • - +

    Least significant bit represents the sign.

    @@ -473,11 +466,11 @@ bits of the original value encoded into the first byte of the VLQ encoded value.
    • -
  • +
  • - +

    The next bits are the actual value.

    @@ -489,11 +482,11 @@ bits of the original value encoded into the first byte of the VLQ encoded value.
    • -
  • +
  • - +

    Make sure we encode at least one character, even if valueToEncode is 0.

    @@ -511,11 +504,11 @@ bits of the original value encoded into the first byte of the VLQ encoded value.
    • -
  • +
  • - +

    Regular Base64 Encoding

    @@ -524,11 +517,11 @@ bits of the original value encoded into the first byte of the VLQ encoded value.
    • -
  • +
  • - +
    @@ -541,11 +534,11 @@ bits of the original value encoded into the first byte of the VLQ encoded value.
    • -
  • +
  • - +

    Our API for source maps is just the SourceMap class. diff --git a/lib/coffee-script/sourcemap.js b/lib/coffee-script/sourcemap.js index 4775ce68..4c1e2025 100644 --- a/lib/coffee-script/sourcemap.js +++ b/lib/coffee-script/sourcemap.js @@ -1,8 +1,6 @@ // Generated by CoffeeScript 1.6.2 (function() { - var LineMap, SourceMap, merge; - - merge = require('./helpers').merge; + var LineMap, SourceMap; LineMap = (function() { function LineMap(line) { diff --git a/src/sourcemap.litcoffee b/src/sourcemap.litcoffee index 3981f70e..e8154600 100644 --- a/src/sourcemap.litcoffee +++ b/src/sourcemap.litcoffee @@ -1,18 +1,21 @@ Source maps allow JavaScript runtimes to match running JavaScript back to -the original CoffeeScript source code that corresponds to it. In order to -produce maps, we must keep track of positions (line number, column number) -for every construct in the syntax tree, and be able to generate a map file --- which is a compact, VLQ-encoded representation of the JSON serialization -of this information -- to write out alongside the generated JavaScript. +the original source code that corresponds to it. This can be minified +JavaScript, but in our case, we're concerned with mapping pretty-printed +JavaScript back to CoffeeScript. - {merge} = require './helpers' +In order to produce maps, we must keep track of positions (line number, column number) +that originated every node in the syntax tree, and be able to generate a +[map file](https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit) +— which is a compact, VLQ-encoded representation of the JSON serialization +of this information — to write out alongside the generated JavaScript. LineMap ------- -Keeps track of information about column positions within a single line of -output JavaScript code. **SourceMap**s are implemented in terms of **LineMap**s. +A **LineMap** object keeps track of information about original line and column +positions for a single line of output JavaScript code. +**SourceMaps** are implemented in terms of **LineMaps**. class LineMap constructor: (@line) ->