kotovalexarian-likes-github
/
jashkenas--coffeescript
mirror of https://github.com/jashkenas/coffeescript.git
1
0
Fork 0
Code Releases Activity

better docs for source maps

This commit is contained in:
Jeremy Ashkenas 2013-03-18 19:46:19 +08:00
parent c8b8beb500
commit 194baa0bd7
3 changed files with 68 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

119
documentation/docs/sourcemap.html
View File

@ -109,42 +109,35 @@
<a class="pilcrow" href="#section-1">&#182;</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&#39;re concerned with mapping pretty-printed
JavaScript back to CoffeeScript.
</p>
<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.
</p>
<h2>LineMap</h2>
</div>
<div class="content"><div class='highlight'><pre>{merge} = require <span class="string">'./helpers'</span></pre></div></div>
</li>
<li id="section-2">
<div class="annotation">
<div class="pilwrap for-h2">
<div class="pilwrap ">
<a class="pilcrow" href="#section-2">&#182;</a>
</div>
<h2>LineMap</h2>
</div>
</li>
<li id="section-3">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-3">&#182;</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">&#182;</a>
<a class="pilcrow" href="#section-3">&#182;</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">&#182;</a>
<a class="pilcrow" href="#section-4">&#182;</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">&#182;</a>
<a class="pilcrow" href="#section-5">&#182;</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">&#182;</a>
<a class="pilcrow" href="#section-6">&#182;</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">&#182;</a>
<a class="pilcrow" href="#section-7">&#182;</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">&#182;</a>
<a class="pilcrow" href="#section-8">&#182;</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 &quot;sources&quot; and &quot;file&quot;, respectively.
</li>
<li id="section-10">
<li id="section-9">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-10">&#182;</a>
<a class="pilcrow" href="#section-9">&#182;</a>
</div>
<p>Write a comma if we&#39;ve already written a segment on this line.
@ -312,11 +305,11 @@ set &quot;sources&quot; and &quot;file&quot;, respectively.
</li>
<li id="section-11">
<li id="section-10">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-11">&#182;</a>
<a class="pilcrow" href="#section-10">&#182;</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&#39;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">&#182;</a>
<a class="pilcrow" href="#section-11">&#182;</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">&#182;</a>
<a class="pilcrow" href="#section-12">&#182;</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">&#182;</a>
<a class="pilcrow" href="#section-13">&#182;</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">&#182;</a>
<a class="pilcrow" href="#section-14">&#182;</a>
</div>
<p>Produce the canonical JSON object format for a &quot;v3&quot; 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">&#182;</a>
<a class="pilcrow" href="#section-15">&#182;</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">&#182;</a>
<a class="pilcrow" href="#section-16">&#182;</a>
</div>
<p>Note that SourceMap VLQ encoding is &quot;backwards&quot;. 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">&#182;</a>
<a class="pilcrow" href="#section-17">&#182;</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">&#182;</a>
<a class="pilcrow" href="#section-18">&#182;</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">&#182;</a>
<a class="pilcrow" href="#section-19">&#182;</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">&#182;</a>
<a class="pilcrow" href="#section-20">&#182;</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">&#182;</a>
<a class="pilcrow" href="#section-21">&#182;</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">&#182;</a>
<a class="pilcrow" href="#section-22">&#182;</a>
</div>
<p>Our API for source maps is just the <code>SourceMap</code> class.

4
lib/coffee-script/sourcemap.js
View File

@ -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) {

19
src/sourcemap.litcoffee
View File

@ -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) ->