better docs for source maps
This commit is contained in:
parent
c8b8beb500
commit
194baa0bd7
|
@ -109,27 +109,19 @@
|
|||
<a class="pilcrow" href="#section-1">¶</a>
|
||||
</div>
|
||||
<p>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.
|
||||
|
||||
</p>
|
||||
|
||||
</div>
|
||||
|
||||
<div class="content"><div class='highlight'><pre>{merge} = require <span class="string">'./helpers'</span></pre></div></div>
|
||||
|
||||
</li>
|
||||
<p>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
|
||||
<a href="https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit">map file</a>
|
||||
— which is a compact, VLQ-encoded representation of the JSON serialization
|
||||
of this information — to write out alongside the generated JavaScript.
|
||||
|
||||
|
||||
<li id="section-2">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap for-h2">
|
||||
<a class="pilcrow" href="#section-2">¶</a>
|
||||
</div>
|
||||
</p>
|
||||
<h2>LineMap</h2>
|
||||
|
||||
</div>
|
||||
|
@ -137,14 +129,15 @@ of this information -- to write out alongside the generated JavaScript.
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-3">
|
||||
<li id="section-2">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap ">
|
||||
<a class="pilcrow" href="#section-3">¶</a>
|
||||
<a class="pilcrow" href="#section-2">¶</a>
|
||||
</div>
|
||||
<p>Keeps track of information about column positions within a single line of
|
||||
output JavaScript code. <strong>SourceMap</strong>s are implemented in terms of <strong>LineMap</strong>s.
|
||||
<p>A <strong>LineMap</strong> object keeps track of information about original line and column
|
||||
positions for a single line of output JavaScript code.
|
||||
<strong>SourceMaps</strong> are implemented in terms of <strong>LineMaps</strong>.
|
||||
|
||||
</p>
|
||||
|
||||
|
@ -165,11 +158,11 @@ output JavaScript code. <strong>SourceMap</strong>s are implemented in terms of
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-4">
|
||||
<li id="section-3">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap for-h2">
|
||||
<a class="pilcrow" href="#section-4">¶</a>
|
||||
<a class="pilcrow" href="#section-3">¶</a>
|
||||
</div>
|
||||
<h2>SourceMap</h2>
|
||||
|
||||
|
@ -178,11 +171,11 @@ output JavaScript code. <strong>SourceMap</strong>s are implemented in terms of
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-5">
|
||||
<li id="section-4">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap ">
|
||||
<a class="pilcrow" href="#section-5">¶</a>
|
||||
<a class="pilcrow" href="#section-4">¶</a>
|
||||
</div>
|
||||
<p>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.
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-6">
|
||||
<li id="section-5">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap ">
|
||||
<a class="pilcrow" href="#section-6">¶</a>
|
||||
<a class="pilcrow" href="#section-5">¶</a>
|
||||
</div>
|
||||
<p>Adds a mapping to this SourceMap. <code>sourceLocation</code> and <code>generatedLocation</code>
|
||||
are both <code>[line, column]</code> arrays. If <code>options.noReplace</code> is true, then if there
|
||||
|
@ -226,11 +219,11 @@ effect.
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-7">
|
||||
<li id="section-6">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap ">
|
||||
<a class="pilcrow" href="#section-7">¶</a>
|
||||
<a class="pilcrow" href="#section-6">¶</a>
|
||||
</div>
|
||||
<p>Look up the original position of a given <code>line</code> and <code>column</code> in the generated
|
||||
code.
|
||||
|
@ -246,11 +239,11 @@ code.
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-8">
|
||||
<li id="section-7">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap for-h2">
|
||||
<a class="pilcrow" href="#section-8">¶</a>
|
||||
<a class="pilcrow" href="#section-7">¶</a>
|
||||
</div>
|
||||
<h2>V3 SourceMap Generation</h2>
|
||||
|
||||
|
@ -259,11 +252,11 @@ code.
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-9">
|
||||
<li id="section-8">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap ">
|
||||
<a class="pilcrow" href="#section-9">¶</a>
|
||||
<a class="pilcrow" href="#section-8">¶</a>
|
||||
</div>
|
||||
<p>Builds up a V3 source map, returning the generated JSON as a string.
|
||||
<code>options.sourceRoot</code> may be used to specify the sourceRoot written to the source
|
||||
|
@ -293,11 +286,11 @@ set "sources" and "file", respectively.
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-10">
|
||||
<li id="section-9">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap ">
|
||||
<a class="pilcrow" href="#section-10">¶</a>
|
||||
<a class="pilcrow" href="#section-9">¶</a>
|
||||
</div>
|
||||
<p>Write a comma if we've already written a segment on this line.
|
||||
|
||||
|
@ -312,11 +305,11 @@ set "sources" and "file", respectively.
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-11">
|
||||
<li id="section-10">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap ">
|
||||
<a class="pilcrow" href="#section-11">¶</a>
|
||||
<a class="pilcrow" href="#section-10">¶</a>
|
||||
</div>
|
||||
<p>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:
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-12">
|
||||
<li id="section-11">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap ">
|
||||
<a class="pilcrow" href="#section-12">¶</a>
|
||||
<a class="pilcrow" href="#section-11">¶</a>
|
||||
</div>
|
||||
<p>The index into the list of sources:
|
||||
|
||||
|
@ -352,11 +345,11 @@ column for the current line:
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-13">
|
||||
<li id="section-12">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap ">
|
||||
<a class="pilcrow" href="#section-13">¶</a>
|
||||
<a class="pilcrow" href="#section-12">¶</a>
|
||||
</div>
|
||||
<p>The starting line in the original source, relative to the previous source line.
|
||||
|
||||
|
@ -372,11 +365,11 @@ column for the current line:
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-14">
|
||||
<li id="section-13">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap ">
|
||||
<a class="pilcrow" href="#section-14">¶</a>
|
||||
<a class="pilcrow" href="#section-13">¶</a>
|
||||
</div>
|
||||
<p>The starting column in the original source, relative to the previous column.
|
||||
|
||||
|
@ -391,11 +384,11 @@ column for the current line:
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-15">
|
||||
<li id="section-14">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap ">
|
||||
<a class="pilcrow" href="#section-15">¶</a>
|
||||
<a class="pilcrow" href="#section-14">¶</a>
|
||||
</div>
|
||||
<p>Produce the canonical JSON object format for a "v3" source map.
|
||||
|
||||
|
@ -418,11 +411,11 @@ column for the current line:
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-16">
|
||||
<li id="section-15">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap for-h2">
|
||||
<a class="pilcrow" href="#section-16">¶</a>
|
||||
<a class="pilcrow" href="#section-15">¶</a>
|
||||
</div>
|
||||
<h2>Base64 VLQ Encoding</h2>
|
||||
|
||||
|
@ -431,11 +424,11 @@ column for the current line:
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-17">
|
||||
<li id="section-16">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap ">
|
||||
<a class="pilcrow" href="#section-17">¶</a>
|
||||
<a class="pilcrow" href="#section-16">¶</a>
|
||||
</div>
|
||||
<p>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.
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-18">
|
||||
<li id="section-17">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap ">
|
||||
<a class="pilcrow" href="#section-18">¶</a>
|
||||
<a class="pilcrow" href="#section-17">¶</a>
|
||||
</div>
|
||||
<p>Least significant bit represents the sign.
|
||||
</p>
|
||||
|
@ -473,11 +466,11 @@ bits of the original value encoded into the first byte of the VLQ encoded value.
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-19">
|
||||
<li id="section-18">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap ">
|
||||
<a class="pilcrow" href="#section-19">¶</a>
|
||||
<a class="pilcrow" href="#section-18">¶</a>
|
||||
</div>
|
||||
<p>The next bits are the actual value.
|
||||
</p>
|
||||
|
@ -489,11 +482,11 @@ bits of the original value encoded into the first byte of the VLQ encoded value.
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-20">
|
||||
<li id="section-19">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap ">
|
||||
<a class="pilcrow" href="#section-20">¶</a>
|
||||
<a class="pilcrow" href="#section-19">¶</a>
|
||||
</div>
|
||||
<p>Make sure we encode at least one character, even if valueToEncode is 0.
|
||||
</p>
|
||||
|
@ -511,11 +504,11 @@ bits of the original value encoded into the first byte of the VLQ encoded value.
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-21">
|
||||
<li id="section-20">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap for-h2">
|
||||
<a class="pilcrow" href="#section-21">¶</a>
|
||||
<a class="pilcrow" href="#section-20">¶</a>
|
||||
</div>
|
||||
<h2>Regular Base64 Encoding</h2>
|
||||
|
||||
|
@ -524,11 +517,11 @@ bits of the original value encoded into the first byte of the VLQ encoded value.
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-22">
|
||||
<li id="section-21">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap ">
|
||||
<a class="pilcrow" href="#section-22">¶</a>
|
||||
<a class="pilcrow" href="#section-21">¶</a>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
@ -541,11 +534,11 @@ bits of the original value encoded into the first byte of the VLQ encoded value.
|
|||
</li>
|
||||
|
||||
|
||||
<li id="section-23">
|
||||
<li id="section-22">
|
||||
<div class="annotation">
|
||||
|
||||
<div class="pilwrap ">
|
||||
<a class="pilcrow" href="#section-23">¶</a>
|
||||
<a class="pilcrow" href="#section-22">¶</a>
|
||||
</div>
|
||||
<p>Our API for source maps is just the <code>SourceMap</code> class.
|
||||
|
||||
|
|
|
@ -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) {
|
||||
|
|
|
@ -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) ->
|
||||
|
|
Loading…
Reference in New Issue