Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 194baa0

Browse files
jashkenasjashkenas
committed
better docs for source maps
1 parent c8b8beb commit 194baa0

3 files changed

Lines changed: 68 additions & 74 deletions

File tree

‎documentation/docs/sourcemap.html‎

Lines changed: 56 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -109,42 +109,35 @@ <h1>sourcemap.litcoffee</h1>
109109
<a class="pilcrow" href="#section-1">&#182;</a>
110110
</div>
111111
<p>Source maps allow JavaScript runtimes to match running JavaScript back to
112-
the original CoffeeScript source code that corresponds to it. In order to
113-
produce maps, we must keep track of positions (line number, column number)
114-
for every construct in the syntax tree, and be able to generate a map file
115-
-- which is a compact, VLQ-encoded representation of the JSON serialization
116-
of this information -- to write out alongside the generated JavaScript.
112+
the original source code that corresponds to it. This can be minified
113+
JavaScript, but in our case, we&#39;re concerned with mapping pretty-printed
114+
JavaScript back to CoffeeScript.
117115

118116
</p>
117+
<p>In order to produce maps, we must keep track of positions (line number, column number)
118+
that originated every node in the syntax tree, and be able to generate a
119+
<a href="https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit">map file</a>
120+
— which is a compact, VLQ-encoded representation of the JSON serialization
121+
of this information — to write out alongside the generated JavaScript.
119122

120-
</div>
121-
122-
<div class="content"><div class='highlight'><pre>{merge} = require <span class="string">'./helpers'</span></pre></div></div>
123-
124-
</li>
125-
126-
127-
<li id="section-2">
128-
<div class="annotation">
129-
130-
<div class="pilwrap for-h2">
131-
<a class="pilcrow" href="#section-2">&#182;</a>
132-
</div>
133-
<h2>LineMap</h2>
123+
124+
</p>
125+
<h2>LineMap</h2>
134126

135127
</div>
136128

137129
</li>
138130

139131

140-
<li id="section-3">
132+
<li id="section-2">
141133
<div class="annotation">
142134

143135
<div class="pilwrap ">
144-
<a class="pilcrow" href="#section-3">&#182;</a>
136+
<a class="pilcrow" href="#section-2">&#182;</a>
145137
</div>
146-
<p>Keeps track of information about column positions within a single line of
147-
output JavaScript code. <strong>SourceMap</strong>s are implemented in terms of <strong>LineMap</strong>s.
138+
<p>A <strong>LineMap</strong> object keeps track of information about original line and column
139+
positions for a single line of output JavaScript code.
140+
<strong>SourceMaps</strong> are implemented in terms of <strong>LineMaps</strong>.
148141

149142
</p>
150143

@@ -165,11 +158,11 @@ <h2>LineMap</h2>
165158
</li>
166159

167160

168-
<li id="section-4">
161+
<li id="section-3">
169162
<div class="annotation">
170163

171164
<div class="pilwrap for-h2">
172-
<a class="pilcrow" href="#section-4">&#182;</a>
165+
<a class="pilcrow" href="#section-3">&#182;</a>
173166
</div>
174167
<h2>SourceMap</h2>
175168

@@ -178,11 +171,11 @@ <h2>SourceMap</h2>
178171
</li>
179172

180173

181-
<li id="section-5">
174+
<li id="section-4">
182175
<div class="annotation">
183176

184177
<div class="pilwrap ">
185-
<a class="pilcrow" href="#section-5">&#182;</a>
178+
<a class="pilcrow" href="#section-4">&#182;</a>
186179
</div>
187180
<p>Maps locations in for a single generated JavaScript file back to locations in
188181
the original CoffeeScript source file.
@@ -203,11 +196,11 @@ <h2>SourceMap</h2>
203196
</li>
204197

205198

206-
<li id="section-6">
199+
<li id="section-5">
207200
<div class="annotation">
208201

209202
<div class="pilwrap ">
210-
<a class="pilcrow" href="#section-6">&#182;</a>
203+
<a class="pilcrow" href="#section-5">&#182;</a>
211204
</div>
212205
<p>Adds a mapping to this SourceMap. <code>sourceLocation</code> and <code>generatedLocation</code>
213206
are both <code>[line, column]</code> arrays. If <code>options.noReplace</code> is true, then if there
@@ -226,11 +219,11 @@ <h2>SourceMap</h2>
226219
</li>
227220

228221

229-
<li id="section-7">
222+
<li id="section-6">
230223
<div class="annotation">
231224

232225
<div class="pilwrap ">
233-
<a class="pilcrow" href="#section-7">&#182;</a>
226+
<a class="pilcrow" href="#section-6">&#182;</a>
234227
</div>
235228
<p>Look up the original position of a given <code>line</code> and <code>column</code> in the generated
236229
code.
@@ -246,11 +239,11 @@ <h2>SourceMap</h2>
246239
</li>
247240

248241

249-
<li id="section-8">
242+
<li id="section-7">
250243
<div class="annotation">
251244

252245
<div class="pilwrap for-h2">
253-
<a class="pilcrow" href="#section-8">&#182;</a>
246+
<a class="pilcrow" href="#section-7">&#182;</a>
254247
</div>
255248
<h2>V3 SourceMap Generation</h2>
256249

@@ -259,11 +252,11 @@ <h2>V3 SourceMap Generation</h2>
259252
</li>
260253

261254

262-
<li id="section-9">
255+
<li id="section-8">
263256
<div class="annotation">
264257

265258
<div class="pilwrap ">
266-
<a class="pilcrow" href="#section-9">&#182;</a>
259+
<a class="pilcrow" href="#section-8">&#182;</a>
267260
</div>
268261
<p>Builds up a V3 source map, returning the generated JSON as a string.
269262
<code>options.sourceRoot</code> may be used to specify the sourceRoot written to the source
@@ -293,11 +286,11 @@ <h2>V3 SourceMap Generation</h2>
293286
</li>
294287

295288

296-
<li id="section-10">
289+
<li id="section-9">
297290
<div class="annotation">
298291

299292
<div class="pilwrap ">
300-
<a class="pilcrow" href="#section-10">&#182;</a>
293+
<a class="pilcrow" href="#section-9">&#182;</a>
301294
</div>
302295
<p>Write a comma if we&#39;ve already written a segment on this line.
303296

@@ -312,11 +305,11 @@ <h2>V3 SourceMap Generation</h2>
312305
</li>
313306

314307

315-
<li id="section-11">
308+
<li id="section-10">
316309
<div class="annotation">
317310

318311
<div class="pilwrap ">
319-
<a class="pilcrow" href="#section-11">&#182;</a>
312+
<a class="pilcrow" href="#section-10">&#182;</a>
320313
</div>
321314
<p>Write the next segment. Segments can be 1, 4, or 5 values. If just one, then it
322315
is a generated column which doesn&#39;t match anything in the source code.
@@ -335,11 +328,11 @@ <h2>V3 SourceMap Generation</h2>
335328
</li>
336329

337330

338-
<li id="section-12">
331+
<li id="section-11">
339332
<div class="annotation">
340333

341334
<div class="pilwrap ">
342-
<a class="pilcrow" href="#section-12">&#182;</a>
335+
<a class="pilcrow" href="#section-11">&#182;</a>
343336
</div>
344337
<p>The index into the list of sources:
345338

@@ -352,11 +345,11 @@ <h2>V3 SourceMap Generation</h2>
352345
</li>
353346

354347

355-
<li id="section-13">
348+
<li id="section-12">
356349
<div class="annotation">
357350

358351
<div class="pilwrap ">
359-
<a class="pilcrow" href="#section-13">&#182;</a>
352+
<a class="pilcrow" href="#section-12">&#182;</a>
360353
</div>
361354
<p>The starting line in the original source, relative to the previous source line.
362355

@@ -372,11 +365,11 @@ <h2>V3 SourceMap Generation</h2>
372365
</li>
373366

374367

375-
<li id="section-14">
368+
<li id="section-13">
376369
<div class="annotation">
377370

378371
<div class="pilwrap ">
379-
<a class="pilcrow" href="#section-14">&#182;</a>
372+
<a class="pilcrow" href="#section-13">&#182;</a>
380373
</div>
381374
<p>The starting column in the original source, relative to the previous column.
382375

@@ -391,11 +384,11 @@ <h2>V3 SourceMap Generation</h2>
391384
</li>
392385

393386

394-
<li id="section-15">
387+
<li id="section-14">
395388
<div class="annotation">
396389

397390
<div class="pilwrap ">
398-
<a class="pilcrow" href="#section-15">&#182;</a>
391+
<a class="pilcrow" href="#section-14">&#182;</a>
399392
</div>
400393
<p>Produce the canonical JSON object format for a &quot;v3&quot; source map.
401394

@@ -418,11 +411,11 @@ <h2>V3 SourceMap Generation</h2>
418411
</li>
419412

420413

421-
<li id="section-16">
414+
<li id="section-15">
422415
<div class="annotation">
423416

424417
<div class="pilwrap for-h2">
425-
<a class="pilcrow" href="#section-16">&#182;</a>
418+
<a class="pilcrow" href="#section-15">&#182;</a>
426419
</div>
427420
<h2>Base64 VLQ Encoding</h2>
428421

@@ -431,11 +424,11 @@ <h2>Base64 VLQ Encoding</h2>
431424
</li>
432425

433426

434-
<li id="section-17">
427+
<li id="section-16">
435428
<div class="annotation">
436429

437430
<div class="pilwrap ">
438-
<a class="pilcrow" href="#section-17">&#182;</a>
431+
<a class="pilcrow" href="#section-16">&#182;</a>
439432
</div>
440433
<p>Note that SourceMap VLQ encoding is &quot;backwards&quot;. MIDI-style VLQ encoding puts
441434
the most-significant-bit (MSB) from the original value into the MSB of the VLQ
@@ -457,11 +450,11 @@ <h2>Base64 VLQ Encoding</h2>
457450
</li>
458451

459452

460-
<li id="section-18">
453+
<li id="section-17">
461454
<div class="annotation">
462455

463456
<div class="pilwrap ">
464-
<a class="pilcrow" href="#section-18">&#182;</a>
457+
<a class="pilcrow" href="#section-17">&#182;</a>
465458
</div>
466459
<p>Least significant bit represents the sign.
467460
</p>
@@ -473,11 +466,11 @@ <h2>Base64 VLQ Encoding</h2>
473466
</li>
474467

475468

476-
<li id="section-19">
469+
<li id="section-18">
477470
<div class="annotation">
478471

479472
<div class="pilwrap ">
480-
<a class="pilcrow" href="#section-19">&#182;</a>
473+
<a class="pilcrow" href="#section-18">&#182;</a>
481474
</div>
482475
<p>The next bits are the actual value.
483476
</p>
@@ -489,11 +482,11 @@ <h2>Base64 VLQ Encoding</h2>
489482
</li>
490483

491484

492-
<li id="section-20">
485+
<li id="section-19">
493486
<div class="annotation">
494487

495488
<div class="pilwrap ">
496-
<a class="pilcrow" href="#section-20">&#182;</a>
489+
<a class="pilcrow" href="#section-19">&#182;</a>
497490
</div>
498491
<p>Make sure we encode at least one character, even if valueToEncode is 0.
499492
</p>
@@ -511,11 +504,11 @@ <h2>Base64 VLQ Encoding</h2>
511504
</li>
512505

513506

514-
<li id="section-21">
507+
<li id="section-20">
515508
<div class="annotation">
516509

517510
<div class="pilwrap for-h2">
518-
<a class="pilcrow" href="#section-21">&#182;</a>
511+
<a class="pilcrow" href="#section-20">&#182;</a>
519512
</div>
520513
<h2>Regular Base64 Encoding</h2>
521514

@@ -524,11 +517,11 @@ <h2>Regular Base64 Encoding</h2>
524517
</li>
525518

526519

527-
<li id="section-22">
520+
<li id="section-21">
528521
<div class="annotation">
529522

530523
<div class="pilwrap ">
531-
<a class="pilcrow" href="#section-22">&#182;</a>
524+
<a class="pilcrow" href="#section-21">&#182;</a>
532525
</div>
533526

534527
</div>
@@ -541,11 +534,11 @@ <h2>Regular Base64 Encoding</h2>
541534
</li>
542535

543536

544-
<li id="section-23">
537+
<li id="section-22">
545538
<div class="annotation">
546539

547540
<div class="pilwrap ">
548-
<a class="pilcrow" href="#section-23">&#182;</a>
541+
<a class="pilcrow" href="#section-22">&#182;</a>
549542
</div>
550543
<p>Our API for source maps is just the <code>SourceMap</code> class.
551544

‎lib/coffee-script/sourcemap.js‎

Lines changed: 1 addition & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎src/sourcemap.litcoffee‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,21 @@
11
Source maps allow JavaScript runtimes to match running JavaScript back to
2-
the original CoffeeScript source code that corresponds to it. In order to
3-
produce maps, we must keep track of positions (line number, column number)
4-
for every construct in the syntax tree, and be able to generate a map file
5-
-- which is a compact, VLQ-encoded representation of the JSON serialization
6-
of this information -- to write out alongside the generated JavaScript.
2+
the original source code that corresponds to it. This can be minified
3+
JavaScript, but in our case, we're concerned with mapping pretty-printed
4+
JavaScript back to CoffeeScript.
75

8-
{merge} = require './helpers'
6+
In order to produce maps, we must keep track of positions (line number, column number)
7+
that originated every node in the syntax tree, and be able to generate a
8+
[map file](https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit)
9+
— which is a compact, VLQ-encoded representation of the JSON serialization
10+
of this information — to write out alongside the generated JavaScript.
911

1012

1113
LineMap
1214
-------
1315

14-
Keeps track of information about column positions within a single line of
15-
output JavaScript code. **SourceMap**s are implemented in terms of **LineMap**s.
16+
A **LineMap** object keeps track of information about original line and column
17+
positions for a single line of output JavaScript code.
18+
**SourceMaps** are implemented in terms of **LineMaps**.
1619

1720
class LineMap
1821
constructor: (@line) ->

0 commit comments

Comments
 (0)