kotovalexarian-likes-github/jashkenas--coffeescript
1
0
Fork 0
mirror of https://github.com/jashkenas/coffeescript.git synced 2022-11-09 12:23:24 -05:00
Code Releases Activity

Update output

Browse source
This commit is contained in:
Geoffrey Booth 2022-04-19 09:03:13 -07:00
parent 8d32c713c5
commit 4f365524d7
6 changed files with 351 additions and 377 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

479
docs/v2/annotated-source/coffeescript.html
View file

@ -174,7 +174,9 @@ evaluated from <code>lib/coffeescript</code>.</p>
</div>
<div class="content"><div class='highlight'><pre><span class="hljs-built_in">exports</span>.helpers = helpers</pre></div></div>
<div class="content"><div class='highlight'><pre><span class="hljs-built_in">exports</span>.helpers = helpers
{getSourceMap, registerCompiled} = SourceMap</pre></div></div>
</li>
@ -185,6 +187,23 @@ evaluated from <code>lib/coffeescript</code>.</p>
<div class="sswrap ">
<a class="ss" href="#section-5">&#x00a7;</a>
</div>
<p>This is exported to enable an external module to implement caching of
sourcemaps. This is used only when <code>patchStackTrace</code> has been called to adjust
stack traces for files with cached source maps.</p>
</div>
<div class="content"><div class='highlight'><pre><span class="hljs-built_in">exports</span>.registerCompiled = registerCompiled</pre></div></div>
</li>
<li id="section-6">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-6">&#x00a7;</a>
</div>
<p>Function that allows for btoa in both nodejs and the browser.</p>
</div>
@ -197,11 +216,11 @@ evaluated from <code>lib/coffeescript</code>.</p>
</li>
<li id="section-6">
<li id="section-7">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-6">&#x00a7;</a>
<a class="ss" href="#section-7">&#x00a7;</a>
</div>
<p>The contents of a <code>&lt;script&gt;</code> block are encoded via UTF-16, so if any extended
characters are used in the block, btoa will fail as it maxes out at UTF-8.
@ -218,11 +237,11 @@ for the gory details, and for the solution implemented here.</p>
</li>
<li id="section-7">
<li id="section-8">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-7">&#x00a7;</a>
<a class="ss" href="#section-8">&#x00a7;</a>
</div>
<p>Function wrapper to add source file information to SyntaxErrors thrown by the
lexer/parser/compiler.</p>
@ -240,74 +259,12 @@ lexer/parser/compiler.</p>
</li>
<li id="section-8">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-8">&#x00a7;</a>
</div>
<p>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 <code>filename</code>: [<code>(source)</code>]</p>
</div>
<div class="content"><div class='highlight'><pre>sources = {}</pre></div></div>
</li>
<li id="section-9">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-9">&#x00a7;</a>
</div>
<p>Also save source maps if generated, in form of <code>(source)</code>: [<code>(source map)</code>].</p>
</div>
<div class="content"><div class='highlight'><pre>sourceMaps = {}</pre></div></div>
</li>
<li id="section-10">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-10">&#x00a7;</a>
</div>
<p>This is exported to enable an external module to implement caching of
compilation results. When the compiled js source is loaded from cache, the
original coffee code should be added with this method in order to enable the
Error.prepareStackTrace below to correctly adjust the stack trace for the
corresponding file (the source map will be generated on demand).</p>
</div>
<div class="content"><div class='highlight'><pre><span class="hljs-built_in">exports</span>.registerCompiled = registerCompiled = <span class="hljs-function"><span class="hljs-params">(filename, source, sourcemap)</span> -&gt;</span>
sources[filename] ?= []
sources[filename].push source
<span class="hljs-keyword">if</span> sourcemap?
sourceMaps[filename] ?= []
sourceMaps[filename].push sourcemap</pre></div></div>
</li>
<li id="section-11">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-11">&#x00a7;</a>
</div>
<p>Compile CoffeeScript code to JavaScript, using the Coffee/Jison compiler.</p>
<p>If <code>options.sourceMap</code> is specified, then <code>options.filename</code> must also be
specified. All options that can be passed to <code>SourceMap#generate</code> may also
@ -324,35 +281,20 @@ doing programmatic lookups.</p>
</li>
<li id="section-12">
<li id="section-10">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-12">&#x00a7;</a>
<a class="ss" href="#section-10">&#x00a7;</a>
</div>
<p>Clone <code>options</code>, to avoid mutating the <code>options</code> object passed in.</p>
</div>
<div class="content"><div class='highlight'><pre> options = <span class="hljs-built_in">Object</span>.assign {}, options</pre></div></div>
<div class="content"><div class='highlight'><pre> options = <span class="hljs-built_in">Object</span>.assign {}, options
</li>
<li id="section-13">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-13">&#x00a7;</a>
</div>
<p>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 <code>prepareStackTrace</code>.</p>
</div>
<div class="content"><div class='highlight'><pre> generateSourceMap = options.sourceMap <span class="hljs-keyword">or</span> options.inlineMap <span class="hljs-keyword">or</span> <span class="hljs-keyword">not</span> options.filename?
filename = options.filename <span class="hljs-keyword">or</span> <span class="hljs-string">&#x27;&lt;anonymous&gt;&#x27;</span>
generateSourceMap = options.sourceMap <span class="hljs-keyword">or</span> options.inlineMap <span class="hljs-keyword">or</span> <span class="hljs-keyword">not</span> options.filename?
filename = options.filename <span class="hljs-keyword">or</span> helpers.anonymousFileName()
checkShebangLine filename, code
@ -363,11 +305,11 @@ we need to recompile it to get a source map for <code>prepareStackTrace</code>.<
</li>
<li id="section-14">
<li id="section-11">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-14">&#x00a7;</a>
<a class="ss" href="#section-11">&#x00a7;</a>
</div>
<p>Pass a list of referenced variables, so that generated variables won’t get
the same name.</p>
@ -381,11 +323,11 @@ the same name.</p>
</li>
<li id="section-15">
<li id="section-12">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-15">&#x00a7;</a>
<a class="ss" href="#section-12">&#x00a7;</a>
</div>
<p>Check for import or export; if found, force bare mode.</p>
@ -402,11 +344,11 @@ the same name.</p>
</li>
<li id="section-16">
<li id="section-13">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-16">&#x00a7;</a>
<a class="ss" href="#section-13">&#x00a7;</a>
</div>
<p>If all that was requested was a POJO representation of the nodes, e.g.
the abstract syntax tree (AST), we can stop now and just return that
@ -443,11 +385,11 @@ which might’ve gotten misaligned from the original source due to the
</li>
<li id="section-17">
<li id="section-14">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-17">&#x00a7;</a>
<a class="ss" href="#section-14">&#x00a7;</a>
</div>
<p>Update the sourcemap with data from each fragment.</p>
@ -458,11 +400,11 @@ which might’ve gotten misaligned from the original source due to the
</li>
<li id="section-18">
<li id="section-15">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-18">&#x00a7;</a>
<a class="ss" href="#section-15">&#x00a7;</a>
</div>
<p>Do not include empty, whitespace, or semicolon-only fragments.</p>
@ -483,11 +425,11 @@ which might’ve gotten misaligned from the original source due to the
</li>
<li id="section-19">
<li id="section-16">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-19">&#x00a7;</a>
<a class="ss" href="#section-16">&#x00a7;</a>
</div>
<p>Copy the code from each fragment into the final JavaScript.</p>
@ -508,11 +450,11 @@ which might’ve gotten misaligned from the original source due to the
</li>
<li id="section-20">
<li id="section-17">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-20">&#x00a7;</a>
<a class="ss" href="#section-17">&#x00a7;</a>
</div>
<p>This only happens if run via the Node API and <code>transpile</code> is set to
something other than an object.</p>
@ -524,11 +466,11 @@ something other than an object.</p>
</li>
<li id="section-21">
<li id="section-18">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-21">&#x00a7;</a>
<a class="ss" href="#section-18">&#x00a7;</a>
</div>
<p>Get the reference to Babel that we have been passed if this compiler
is run via the CLI or Node API.</p>
@ -543,11 +485,11 @@ is run via the CLI or Node API.</p>
</li>
<li id="section-22">
<li id="section-19">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-22">&#x00a7;</a>
<a class="ss" href="#section-19">&#x00a7;</a>
</div>
<p>See <a href="https://github.com/babel/babel/issues/827#issuecomment-77573107">https://github.com/babel/babel/issues/827#issuecomment-77573107</a>:
Babel can take a v3 source map object as input in <code>inputSourceMap</code>
@ -565,7 +507,7 @@ and it will return an <em>updated</em> v3 source map object in its output.</p>
<span class="hljs-keyword">if</span> options.inlineMap
encoded = base64encode <span class="hljs-built_in">JSON</span>.stringify v3SourceMap
sourceMapDataURI = <span class="hljs-string">&quot;//# sourceMappingURL=data:application/json;base64,<span class="hljs-subst">#{encoded}</span>&quot;</span>
sourceURL = <span class="hljs-string">&quot;//# sourceURL=<span class="hljs-subst">#{options.filename ? <span class="hljs-string">&#x27;coffeescript&#x27;</span>}</span>&quot;</span>
sourceURL = <span class="hljs-string">&quot;//# sourceURL=<span class="hljs-subst">#{filename}</span>&quot;</span>
js = <span class="hljs-string">&quot;<span class="hljs-subst">#{js}</span>\n<span class="hljs-subst">#{sourceMapDataURI}</span>\n<span class="hljs-subst">#{sourceURL}</span>&quot;</span>
registerCompiled filename, code, map
@ -582,11 +524,11 @@ and it will return an <em>updated</em> v3 source map object in its output.</p>
</li>
<li id="section-23">
<li id="section-20">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-23">&#x00a7;</a>
<a class="ss" href="#section-20">&#x00a7;</a>
</div>
<p>Tokenize a string of CoffeeScript code, and return the array of tokens.</p>
@ -598,11 +540,11 @@ and it will return an <em>updated</em> v3 source map object in its output.</p>
</li>
<li id="section-24">
<li id="section-21">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-24">&#x00a7;</a>
<a class="ss" href="#section-21">&#x00a7;</a>
</div>
<p>Parse a string of CoffeeScript code or an array of lexed tokens, and
return the AST. You can then compile it by calling <code>.compile()</code> on the root,
@ -617,11 +559,11 @@ or traverse it by using <code>.traverseChildren()</code> with a callback.</p>
</li>
<li id="section-25">
<li id="section-22">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-25">&#x00a7;</a>
<a class="ss" href="#section-22">&#x00a7;</a>
</div>
<p>This file used to export these methods; leave stubs that throw warnings
instead. These methods have been moved into <code>index.coffee</code> to provide
@ -637,11 +579,11 @@ environment.</p>
</li>
<li id="section-26">
<li id="section-23">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-26">&#x00a7;</a>
<a class="ss" href="#section-23">&#x00a7;</a>
</div>
<p>Instantiate a Lexer for our use here.</p>
@ -652,11 +594,11 @@ environment.</p>
</li>
<li id="section-27">
<li id="section-24">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-27">&#x00a7;</a>
<a class="ss" href="#section-24">&#x00a7;</a>
</div>
<p>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
@ -686,11 +628,11 @@ directly as a “Jison lexer.”</p>
</li>
<li id="section-28">
<li id="section-25">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-28">&#x00a7;</a>
<a class="ss" href="#section-25">&#x00a7;</a>
</div>
<p>Make all the AST nodes visible to the parser.</p>
@ -701,11 +643,11 @@ directly as a “Jison lexer.”</p>
</li>
<li id="section-29">
<li id="section-26">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-29">&#x00a7;</a>
<a class="ss" href="#section-26">&#x00a7;</a>
</div>
<p>Override Jison’s default error handling function.</p>
@ -716,11 +658,11 @@ directly as a “Jison lexer.”</p>
</li>
<li id="section-30">
<li id="section-27">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-30">&#x00a7;</a>
<a class="ss" href="#section-27">&#x00a7;</a>
</div>
<p>Disregard Jison’s message, it contains redundant line number information.
Disregard the token, we take its value directly from the lexer in case
@ -744,11 +686,11 @@ the error is caused by a generated token which might refer to its origin.</p>
</li>
<li id="section-31">
<li id="section-28">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-31">&#x00a7;</a>
<a class="ss" href="#section-28">&#x00a7;</a>
</div>
<p>The second argument has a <code>loc</code> property, which should have the location
data for this token. Unfortunately, Jison seems to send an outdated <code>loc</code>
@ -757,7 +699,111 @@ from the lexer.</p>
</div>
<div class="content"><div class='highlight'><pre> helpers.throwSyntaxError <span class="hljs-string">&quot;unexpected <span class="hljs-subst">#{errorText}</span>&quot;</span>, errorLoc</pre></div></div>
<div class="content"><div class='highlight'><pre> helpers.throwSyntaxError <span class="hljs-string">&quot;unexpected <span class="hljs-subst">#{errorText}</span>&quot;</span>, errorLoc
<span class="hljs-built_in">exports</span>.patchStackTrace = <span class="hljs-function">-&gt;</span></pre></div></div>
</li>
<li id="section-29">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-29">&#x00a7;</a>
</div>
<p>Based on <a href="http://v8.googlecode.com/svn/branches/bleeding_edge/src/messages.js">http://v8.googlecode.com/svn/branches/bleeding_edge/src/messages.js</a>
Modified to handle sourceMap</p>
</div>
<div class="content"><div class='highlight'><pre><span class="hljs-function"> <span class="hljs-title">formatSourcePosition</span> = <span class="hljs-params">(frame, getSourceMapping)</span> -&gt;</span>
filename = <span class="hljs-literal">undefined</span>
fileLocation = <span class="hljs-string">&#x27;&#x27;</span>
<span class="hljs-keyword">if</span> frame.isNative()
fileLocation = <span class="hljs-string">&quot;native&quot;</span>
<span class="hljs-keyword">else</span>
<span class="hljs-keyword">if</span> frame.isEval()
filename = frame.getScriptNameOrSourceURL()
fileLocation = <span class="hljs-string">&quot;<span class="hljs-subst">#{frame.getEvalOrigin()}</span>, &quot;</span> <span class="hljs-keyword">unless</span> filename
<span class="hljs-keyword">else</span>
filename = frame.getFileName()
filename <span class="hljs-keyword">or</span>= <span class="hljs-string">&quot;&lt;anonymous&gt;&quot;</span>
line = frame.getLineNumber()
column = frame.getColumnNumber()</pre></div></div>
</li>
<li id="section-30">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-30">&#x00a7;</a>
</div>
<p>Check for a sourceMap position</p>
</div>
<div class="content"><div class='highlight'><pre> source = getSourceMapping filename, line, column
fileLocation =
<span class="hljs-keyword">if</span> source
<span class="hljs-string">&quot;<span class="hljs-subst">#{filename}</span>:<span class="hljs-subst">#{source[<span class="hljs-number">0</span>]}</span>:<span class="hljs-subst">#{source[<span class="hljs-number">1</span>]}</span>&quot;</span>
<span class="hljs-keyword">else</span>
<span class="hljs-string">&quot;<span class="hljs-subst">#{filename}</span>:<span class="hljs-subst">#{line}</span>:<span class="hljs-subst">#{column}</span>&quot;</span>
functionName = frame.getFunctionName()
isConstructor = frame.isConstructor()
isMethodCall = <span class="hljs-keyword">not</span> (frame.isToplevel() <span class="hljs-keyword">or</span> isConstructor)
<span class="hljs-keyword">if</span> isMethodCall
methodName = frame.getMethodName()
typeName = frame.getTypeName()
<span class="hljs-keyword">if</span> functionName
tp = <span class="hljs-keyword">as</span> = <span class="hljs-string">&#x27;&#x27;</span>
<span class="hljs-keyword">if</span> typeName <span class="hljs-keyword">and</span> functionName.indexOf typeName
tp = <span class="hljs-string">&quot;<span class="hljs-subst">#{typeName}</span>.&quot;</span>
<span class="hljs-keyword">if</span> methodName <span class="hljs-keyword">and</span> functionName.indexOf(<span class="hljs-string">&quot;.<span class="hljs-subst">#{methodName}</span>&quot;</span>) <span class="hljs-keyword">isnt</span> functionName.length - methodName.length - <span class="hljs-number">1</span>
<span class="hljs-keyword">as</span> = <span class="hljs-string">&quot; [as <span class="hljs-subst">#{methodName}</span>]&quot;</span>
<span class="hljs-string">&quot;<span class="hljs-subst">#{tp}</span><span class="hljs-subst">#{functionName}</span><span class="hljs-subst">#{<span class="hljs-keyword">as</span>}</span> (<span class="hljs-subst">#{fileLocation}</span>)&quot;</span>
<span class="hljs-keyword">else</span>
<span class="hljs-string">&quot;<span class="hljs-subst">#{typeName}</span>.<span class="hljs-subst">#{methodName <span class="hljs-keyword">or</span> <span class="hljs-string">&#x27;&lt;anonymous&gt;&#x27;</span>}</span> (<span class="hljs-subst">#{fileLocation}</span>)&quot;</span>
<span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> isConstructor
<span class="hljs-string">&quot;new <span class="hljs-subst">#{functionName <span class="hljs-keyword">or</span> <span class="hljs-string">&#x27;&lt;anonymous&gt;&#x27;</span>}</span> (<span class="hljs-subst">#{fileLocation}</span>)&quot;</span>
<span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> functionName
<span class="hljs-string">&quot;<span class="hljs-subst">#{functionName}</span> (<span class="hljs-subst">#{fileLocation}</span>)&quot;</span>
<span class="hljs-keyword">else</span>
fileLocation
<span class="hljs-function">
<span class="hljs-title">getSourceMapping</span> = <span class="hljs-params">(filename, line, column)</span> -&gt;</span>
sourceMap = getSourceMap filename, line, column
answer = sourceMap.sourceLocation [line - <span class="hljs-number">1</span>, column - <span class="hljs-number">1</span>] <span class="hljs-keyword">if</span> sourceMap?
<span class="hljs-keyword">if</span> answer? <span class="hljs-keyword">then</span> [answer[<span class="hljs-number">0</span>] + <span class="hljs-number">1</span>, answer[<span class="hljs-number">1</span>] + <span class="hljs-number">1</span>] <span class="hljs-keyword">else</span> <span class="hljs-literal">null</span></pre></div></div>
</li>
<li id="section-31">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-31">&#x00a7;</a>
</div>
<p>Based on <a href="http://goo.gl/ZTx1p">michaelficarra/CoffeeScriptRedux</a>
NodeJS / V8 have no support for transforming positions in stack traces using
sourceMap, so we must monkey-patch Error to display CoffeeScript source
positions.</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-built_in">Error</span>.prepareStackTrace = <span class="hljs-function"><span class="hljs-params">(err, stack)</span> -&gt;</span>
frames = <span class="hljs-keyword">for</span> frame <span class="hljs-keyword">in</span> stack</pre></div></div>
</li>
@ -768,189 +814,14 @@ from the lexer.</p>
<div class="sswrap ">
<a class="ss" href="#section-32">&#x00a7;</a>
</div>
<p>Based on <a href="http://v8.googlecode.com/svn/branches/bleeding_edge/src/messages.js">http://v8.googlecode.com/svn/branches/bleeding_edge/src/messages.js</a>
Modified to handle sourceMap</p>
<p>Don’t display stack frames deeper than <code>CoffeeScript.run</code>.</p>
</div>
<div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">formatSourcePosition</span> = <span class="hljs-params">(frame, getSourceMapping)</span> -&gt;</span>
filename = <span class="hljs-literal">undefined</span>
fileLocation = <span class="hljs-string">&#x27;&#x27;</span>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">break</span> <span class="hljs-keyword">if</span> frame.getFunction() <span class="hljs-keyword">is</span> <span class="hljs-built_in">exports</span>.run
<span class="hljs-string">&quot; at <span class="hljs-subst">#{formatSourcePosition frame, getSourceMapping}</span>&quot;</span>
<span class="hljs-keyword">if</span> frame.isNative()
fileLocation = <span class="hljs-string">&quot;native&quot;</span>
<span class="hljs-keyword">else</span>
<span class="hljs-keyword">if</span> frame.isEval()
filename = frame.getScriptNameOrSourceURL()
fileLocation = <span class="hljs-string">&quot;<span class="hljs-subst">#{frame.getEvalOrigin()}</span>, &quot;</span> <span class="hljs-keyword">unless</span> filename
<span class="hljs-keyword">else</span>
filename = frame.getFileName()
filename <span class="hljs-keyword">or</span>= <span class="hljs-string">&quot;&lt;anonymous&gt;&quot;</span>
line = frame.getLineNumber()
column = frame.getColumnNumber()</pre></div></div>
</li>
<li id="section-33">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-33">&#x00a7;</a>
</div>
<p>Check for a sourceMap position</p>
</div>
<div class="content"><div class='highlight'><pre> source = getSourceMapping filename, line, column
fileLocation =
<span class="hljs-keyword">if</span> source
<span class="hljs-string">&quot;<span class="hljs-subst">#{filename}</span>:<span class="hljs-subst">#{source[<span class="hljs-number">0</span>]}</span>:<span class="hljs-subst">#{source[<span class="hljs-number">1</span>]}</span>&quot;</span>
<span class="hljs-keyword">else</span>
<span class="hljs-string">&quot;<span class="hljs-subst">#{filename}</span>:<span class="hljs-subst">#{line}</span>:<span class="hljs-subst">#{column}</span>&quot;</span>
functionName = frame.getFunctionName()
isConstructor = frame.isConstructor()
isMethodCall = <span class="hljs-keyword">not</span> (frame.isToplevel() <span class="hljs-keyword">or</span> isConstructor)
<span class="hljs-keyword">if</span> isMethodCall
methodName = frame.getMethodName()
typeName = frame.getTypeName()
<span class="hljs-keyword">if</span> functionName
tp = <span class="hljs-keyword">as</span> = <span class="hljs-string">&#x27;&#x27;</span>
<span class="hljs-keyword">if</span> typeName <span class="hljs-keyword">and</span> functionName.indexOf typeName
tp = <span class="hljs-string">&quot;<span class="hljs-subst">#{typeName}</span>.&quot;</span>
<span class="hljs-keyword">if</span> methodName <span class="hljs-keyword">and</span> functionName.indexOf(<span class="hljs-string">&quot;.<span class="hljs-subst">#{methodName}</span>&quot;</span>) <span class="hljs-keyword">isnt</span> functionName.length - methodName.length - <span class="hljs-number">1</span>
<span class="hljs-keyword">as</span> = <span class="hljs-string">&quot; [as <span class="hljs-subst">#{methodName}</span>]&quot;</span>
<span class="hljs-string">&quot;<span class="hljs-subst">#{tp}</span><span class="hljs-subst">#{functionName}</span><span class="hljs-subst">#{<span class="hljs-keyword">as</span>}</span> (<span class="hljs-subst">#{fileLocation}</span>)&quot;</span>
<span class="hljs-keyword">else</span>
<span class="hljs-string">&quot;<span class="hljs-subst">#{typeName}</span>.<span class="hljs-subst">#{methodName <span class="hljs-keyword">or</span> <span class="hljs-string">&#x27;&lt;anonymous&gt;&#x27;</span>}</span> (<span class="hljs-subst">#{fileLocation}</span>)&quot;</span>
<span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> isConstructor
<span class="hljs-string">&quot;new <span class="hljs-subst">#{functionName <span class="hljs-keyword">or</span> <span class="hljs-string">&#x27;&lt;anonymous&gt;&#x27;</span>}</span> (<span class="hljs-subst">#{fileLocation}</span>)&quot;</span>
<span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> functionName
<span class="hljs-string">&quot;<span class="hljs-subst">#{functionName}</span> (<span class="hljs-subst">#{fileLocation}</span>)&quot;</span>
<span class="hljs-keyword">else</span>
fileLocation
<span class="hljs-function">
<span class="hljs-title">getSourceMap</span> = <span class="hljs-params">(filename, line, column)</span> -&gt;</span></pre></div></div>
</li>
<li id="section-34">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-34">&#x00a7;</a>
</div>
<p>Skip files that we didn’t compile, like Node system files that appear in
the stack trace, as they never have source maps.</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">return</span> <span class="hljs-literal">null</span> <span class="hljs-keyword">unless</span> filename <span class="hljs-keyword">is</span> <span class="hljs-string">&#x27;&lt;anonymous&gt;&#x27;</span> <span class="hljs-keyword">or</span> filename.slice(filename.lastIndexOf(<span class="hljs-string">&#x27;.&#x27;</span>)) <span class="hljs-keyword">in</span> FILE_EXTENSIONS
<span class="hljs-keyword">if</span> filename <span class="hljs-keyword">isnt</span> <span class="hljs-string">&#x27;&lt;anonymous&gt;&#x27;</span> <span class="hljs-keyword">and</span> sourceMaps[filename]?
<span class="hljs-keyword">return</span> sourceMaps[filename][sourceMaps[filename].length - <span class="hljs-number">1</span>]</pre></div></div>
</li>
<li id="section-35">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-35">&#x00a7;</a>
</div>
<p>CoffeeScript compiled in a browser or via <code>CoffeeScript.compile</code> or <code>.run</code>
may get compiled with <code>options.filename</code> that’s missing, which becomes
<code>&lt;anonymous&gt;</code>; but the runtime might request the stack trace with the
filename of the script file. See if we have a source map cached under
<code>&lt;anonymous&gt;</code> that matches the error.</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> sourceMaps[<span class="hljs-string">&#x27;&lt;anonymous&gt;&#x27;</span>]?</pre></div></div>
</li>
<li id="section-36">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-36">&#x00a7;</a>
</div>
<p>Work backwards from the most recent anonymous source maps, until we find
one that works. This isn’t foolproof; there is a chance that multiple
source maps will have line/column pairs that match. But we have no other
way to match them. <code>frame.getFunction().toString()</code> doesn’t always work,
and it’s not foolproof either.</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">for</span> map <span class="hljs-keyword">in</span> sourceMaps[<span class="hljs-string">&#x27;&lt;anonymous&gt;&#x27;</span>] <span class="hljs-keyword">by</span> <span class="hljs-number">-1</span>
sourceLocation = map.sourceLocation [line - <span class="hljs-number">1</span>, column - <span class="hljs-number">1</span>]
<span class="hljs-keyword">return</span> map <span class="hljs-keyword">if</span> sourceLocation?[<span class="hljs-number">0</span>]? <span class="hljs-keyword">and</span> sourceLocation[<span class="hljs-number">1</span>]?</pre></div></div>
</li>
<li id="section-37">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-37">&#x00a7;</a>
</div>
<p>If all else fails, recompile this source to get a source map. We need the
previous section (for <code>&lt;anonymous&gt;</code>) despite this option, because after it
gets compiled we will still need to look it up from
<code>sourceMaps[&#39;&lt;anonymous&gt;&#39;]</code> in order to find and return it. That’s why we
start searching from the end in the previous block, because most of the
time the source map we want is the last one.</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">if</span> sources[filename]?
answer = compile sources[filename][sources[filename].length - <span class="hljs-number">1</span>],
filename: filename
sourceMap: <span class="hljs-literal">yes</span>
literate: helpers.isLiterate filename
answer.sourceMap
<span class="hljs-keyword">else</span>
<span class="hljs-literal">null</span></pre></div></div>
</li>
<li id="section-38">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-38">&#x00a7;</a>
</div>
<p>Based on <a href="http://goo.gl/ZTx1p">michaelficarra/CoffeeScriptRedux</a>
NodeJS / V8 have no support for transforming positions in stack traces using
sourceMap, so we must monkey-patch Error to display CoffeeScript source
positions.</p>
</div>
<div class="content"><div class='highlight'><pre><span class="hljs-built_in">Error</span>.prepareStackTrace = <span class="hljs-function"><span class="hljs-params">(err, stack)</span> -&gt;</span>
<span class="hljs-function"> <span class="hljs-title">getSourceMapping</span> = <span class="hljs-params">(filename, line, column)</span> -&gt;</span>
sourceMap = getSourceMap filename, line, column
answer = sourceMap.sourceLocation [line - <span class="hljs-number">1</span>, column - <span class="hljs-number">1</span>] <span class="hljs-keyword">if</span> sourceMap?
<span class="hljs-keyword">if</span> answer? <span class="hljs-keyword">then</span> [answer[<span class="hljs-number">0</span>] + <span class="hljs-number">1</span>, answer[<span class="hljs-number">1</span>] + <span class="hljs-number">1</span>] <span class="hljs-keyword">else</span> <span class="hljs-literal">null</span>
frames = <span class="hljs-keyword">for</span> frame <span class="hljs-keyword">in</span> stack
<span class="hljs-keyword">break</span> <span class="hljs-keyword">if</span> frame.getFunction() <span class="hljs-keyword">is</span> <span class="hljs-built_in">exports</span>.run
<span class="hljs-string">&quot; at <span class="hljs-subst">#{formatSourcePosition frame, getSourceMapping}</span>&quot;</span>
<span class="hljs-string">&quot;<span class="hljs-subst">#{err.toString()}</span>\n<span class="hljs-subst">#{frames.join <span class="hljs-string">&#x27;\n&#x27;</span>}</span>\n&quot;</span>
<span class="hljs-string">&quot;<span class="hljs-subst">#{err.toString()}</span>\n<span class="hljs-subst">#{frames.join <span class="hljs-string">&#x27;\n&#x27;</span>}</span>\n&quot;</span>
<span class="hljs-function">
<span class="hljs-title">checkShebangLine</span> = <span class="hljs-params">(file, input)</span> -&gt;</span>
firstLine = input.split(<span class="hljs-regexp">/$/m</span>)[<span class="hljs-number">0</span>]

2
docs/v2/annotated-source/command.html
View file

@ -973,7 +973,7 @@ along.</p>
jsDir = path.dirname jsPath
answer = helpers.merge answer, {
jsPath
sourceRoot: path.relative jsDir, cwd
sourceRoot: path.relative(jsDir, cwd) + path.sep
sourceFiles: [path.relative cwd, filename]
generatedFile: helpers.baseFileName(jsPath, <span class="hljs-literal">no</span>, useWinPathSep)
}

65
docs/v2/annotated-source/helpers.html
View file

@ -584,6 +584,25 @@ built yet.</p>
<div class="sswrap ">
<a class="ss" href="#section-24">&#x00a7;</a>
</div>
<p>Generate a unique anonymous file name so we can distinguish source map cache
entries for any number of anonymous scripts.</p>
</div>
<div class="content"><div class='highlight'><pre><span class="hljs-built_in">exports</span>.anonymousFileName = <span class="hljs-keyword">do</span> -&gt;
n = <span class="hljs-number">0</span>
-&gt;
<span class="hljs-string">&quot;&lt;anonymous-<span class="hljs-subst">#{n++}</span>&gt;&quot;</span></pre></div></div>
</li>
<li id="section-25">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-25">&#x00a7;</a>
</div>
<p>A <code>.coffee.md</code> compatible version of <code>basename</code>, that returns the file sans-extension.</p>
</div>
@ -601,11 +620,11 @@ built yet.</p>
</li>
<li id="section-25">
<li id="section-26">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-25">&#x00a7;</a>
<a class="ss" href="#section-26">&#x00a7;</a>
</div>
<p>Determine if a filename represents a CoffeeScript file.</p>
@ -616,11 +635,11 @@ built yet.</p>
</li>
<li id="section-26">
<li id="section-27">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-26">&#x00a7;</a>
<a class="ss" href="#section-27">&#x00a7;</a>
</div>
<p>Determine if a filename represents a Literate CoffeeScript file.</p>
@ -631,11 +650,11 @@ built yet.</p>
</li>
<li id="section-27">
<li id="section-28">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-27">&#x00a7;</a>
<a class="ss" href="#section-28">&#x00a7;</a>
</div>
<p>Throws a SyntaxError from a given location.
The error’s <code>toString</code> will return an error message following the “standard”
@ -652,11 +671,11 @@ marker showing where the error is.</p>
</li>
<li id="section-28">
<li id="section-29">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-28">&#x00a7;</a>
<a class="ss" href="#section-29">&#x00a7;</a>
</div>
<p>Instead of showing the compiler’s stacktrace, show our custom error message
(this is useful when the error bubbles up in Node.js applications that
@ -671,11 +690,11 @@ compile CoffeeScript for example).</p>
</li>
<li id="section-29">
<li id="section-30">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-29">&#x00a7;</a>
<a class="ss" href="#section-30">&#x00a7;</a>
</div>
<p>Update a compiler SyntaxError with source code information if it didn’t have
it already.</p>
@ -687,11 +706,11 @@ it already.</p>
</li>
<li id="section-30">
<li id="section-31">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-30">&#x00a7;</a>
<a class="ss" href="#section-31">&#x00a7;</a>
</div>
<p>Avoid screwing up the <code>stack</code> property of other errors (i.e. possible bugs).</p>
@ -710,18 +729,22 @@ it already.</p>
last_line ?= first_line
last_column ?= first_column
filename = @filename <span class="hljs-keyword">or</span> <span class="hljs-string">&#x27;[stdin]&#x27;</span>
<span class="hljs-keyword">if</span> @filename?.startsWith <span class="hljs-string">&#x27;&lt;anonymous&#x27;</span>
filename = <span class="hljs-string">&#x27;[stdin]&#x27;</span>
<span class="hljs-keyword">else</span>
filename = @filename <span class="hljs-keyword">or</span> <span class="hljs-string">&#x27;[stdin]&#x27;</span>
codeLine = @code.split(<span class="hljs-string">&#x27;\n&#x27;</span>)[first_line]
start = first_column</pre></div></div>
</li>
<li id="section-31">
<li id="section-32">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-31">&#x00a7;</a>
<a class="ss" href="#section-32">&#x00a7;</a>
</div>
<p>Show only the first line on multi-line errors.</p>
@ -733,11 +756,11 @@ it already.</p>
</li>
<li id="section-32">
<li id="section-33">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-32">&#x00a7;</a>
<a class="ss" href="#section-33">&#x00a7;</a>
</div>
<p>Check to see if we’re running on a color-enabled TTY.</p>
@ -794,11 +817,11 @@ it already.</p>
</li>
<li id="section-33">
<li id="section-34">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-33">&#x00a7;</a>
<a class="ss" href="#section-34">&#x00a7;</a>
</div>
<p>surrogate pair</p>
@ -811,11 +834,11 @@ it already.</p>
</li>
<li id="section-34">
<li id="section-35">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-34">&#x00a7;</a>
<a class="ss" href="#section-35">&#x00a7;</a>
</div>
<p>Replace <code>\u{...}</code> with <code>\uxxxx[\uxxxx]</code> in regexes without <code>u</code> flag</p>

13
docs/v2/annotated-source/index.html
View file

@ -232,7 +232,7 @@ setting <code>__filename</code>, <code>__dirname</code>, and relative <code>requ
</div>
<div class="content"><div class='highlight'><pre> mainModule.filename = process.argv[<span class="hljs-number">1</span>] =
<span class="hljs-keyword">if</span> options.filename <span class="hljs-keyword">then</span> fs.realpathSync(options.filename) <span class="hljs-keyword">else</span> <span class="hljs-string">&#x27;&lt;anonymous&gt;&#x27;</span></pre></div></div>
<span class="hljs-keyword">if</span> options.filename <span class="hljs-keyword">then</span> fs.realpathSync(options.filename) <span class="hljs-keyword">else</span> helpers.anonymousFileName()</pre></div></div>
</li>
@ -281,7 +281,10 @@ setting <code>__filename</code>, <code>__dirname</code>, and relative <code>requ
</div>
<div class="content"><div class='highlight'><pre> mainModule.options = options</pre></div></div>
<div class="content"><div class='highlight'><pre> mainModule.options = options
options.filename = mainModule.filename
options.inlineMap = <span class="hljs-literal">true</span></pre></div></div>
</li>
@ -296,9 +299,8 @@ setting <code>__filename</code>, <code>__dirname</code>, and relative <code>requ
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> helpers.isCoffee(mainModule.filename) <span class="hljs-keyword">or</span> <span class="hljs-built_in">require</span>.extensions
answer = CoffeeScript.compile code, options
code = answer.js ? answer
<div class="content"><div class='highlight'><pre> answer = CoffeeScript.compile code, options
code = answer.js ? answer
mainModule._compile code, mainModule.filename</pre></div></div>
@ -424,7 +426,6 @@ CoffeeScript._compileRawFileContent = <span class="hljs-function"><span class="h
filename: filename
literate: helpers.isLiterate filename
sourceFiles: [filename]
inlineMap: <span class="hljs-literal">yes</span> <span class="hljs-comment"># Always generate a source map, so that stack traces line up.</span>
<span class="hljs-keyword">try</span>
answer = CoffeeScript.compile stripped, options

74
docs/v2/annotated-source/register.html
View file

@ -121,7 +121,9 @@
<div class="content"><div class='highlight'><pre>CoffeeScript = <span class="hljs-built_in">require</span> <span class="hljs-string">&#x27;./&#x27;</span>
child_process = <span class="hljs-built_in">require</span> <span class="hljs-string">&#x27;child_process&#x27;</span>
helpers = <span class="hljs-built_in">require</span> <span class="hljs-string">&#x27;./helpers&#x27;</span>
path = <span class="hljs-built_in">require</span> <span class="hljs-string">&#x27;path&#x27;</span></pre></div></div>
path = <span class="hljs-built_in">require</span> <span class="hljs-string">&#x27;path&#x27;</span>
{patchStackTrace} = CoffeeScript</pre></div></div>
</li>
@ -132,14 +134,18 @@ path = <span class="hljs-built_in">require</span> <span class="hljs-str
<div class="sswrap ">
<a class="ss" href="#section-2">&#x00a7;</a>
</div>
<p>Load and run a CoffeeScript file for Node, stripping any <code>BOM</code>s.</p>
<p>Check if Node’s built-in source map stack trace transformations are enabled.</p>
</div>
<div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">loadFile</span> = <span class="hljs-params">(module, filename)</span> -&gt;</span>
options = module.options <span class="hljs-keyword">or</span> getRootModule(module).options
answer = CoffeeScript._compileFile filename, options
module._compile answer, filename</pre></div></div>
<div class="content"><div class='highlight'><pre>nodeSourceMapsSupportEnabled = process? <span class="hljs-keyword">and</span> (
process.execArgv.includes(<span class="hljs-string">&#x27;--enable-source-maps&#x27;</span>) <span class="hljs-keyword">or</span>
process.env.NODE_OPTIONS?.includes(<span class="hljs-string">&#x27;--enable-source-maps&#x27;</span>)
)
<span class="hljs-keyword">unless</span> <span class="hljs-built_in">Error</span>.prepareStackTrace <span class="hljs-keyword">or</span> nodeSourceMapsSupportEnabled
cacheSourceMaps = <span class="hljs-literal">true</span>
patchStackTrace()</pre></div></div>
</li>
@ -150,6 +156,42 @@ path = <span class="hljs-built_in">require</span> <span class="hljs-str
<div class="sswrap ">
<a class="ss" href="#section-3">&#x00a7;</a>
</div>
<p>Load and run a CoffeeScript file for Node, stripping any <code>BOM</code>s.</p>
</div>
<div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">loadFile</span> = <span class="hljs-params">(module, filename)</span> -&gt;</span>
options = module.options <span class="hljs-keyword">or</span> getRootModule(module).options <span class="hljs-keyword">or</span> {}</pre></div></div>
</li>
<li id="section-4">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-4">&#x00a7;</a>
</div>
<p>Currently <code>CoffeeScript.compile</code> caches all source maps if present. They
are available in <code>getSourceMap</code> retrieved by <code>filename</code>.</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">if</span> cacheSourceMaps <span class="hljs-keyword">or</span> nodeSourceMapsSupportEnabled
options.inlineMap = <span class="hljs-literal">true</span>
js = CoffeeScript._compileFile filename, options
module._compile js, filename</pre></div></div>
</li>
<li id="section-5">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-5">&#x00a7;</a>
</div>
<p>If the installed version of Node supports <code>require.extensions</code>, register
CoffeeScript as an extension.</p>
@ -162,11 +204,11 @@ CoffeeScript as an extension.</p>
</li>
<li id="section-4">
<li id="section-6">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-4">&#x00a7;</a>
<a class="ss" href="#section-6">&#x00a7;</a>
</div>
<p>Patch Node’s module loader to be able to handle multi-dot extensions.
This is a horrible thing that should not be required.</p>
@ -181,11 +223,11 @@ This is a horrible thing that should not be required.</p>
</li>
<li id="section-5">
<li id="section-7">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-5">&#x00a7;</a>
<a class="ss" href="#section-7">&#x00a7;</a>
</div>
<p>Remove the initial dot from dotfiles.</p>
@ -196,11 +238,11 @@ This is a horrible thing that should not be required.</p>
</li>
<li id="section-6">
<li id="section-8">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-6">&#x00a7;</a>
<a class="ss" href="#section-8">&#x00a7;</a>
</div>
<p>Start with the longest possible extension and work our way shortwards.</p>
@ -221,11 +263,11 @@ This is a horrible thing that should not be required.</p>
</li>
<li id="section-7">
<li id="section-9">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-7">&#x00a7;</a>
<a class="ss" href="#section-9">&#x00a7;</a>
</div>
<p>If we’re on Node, patch <code>child_process.fork</code> so that Coffee scripts are able
to fork both CoffeeScript files, and JavaScript files, directly.</p>
@ -247,11 +289,11 @@ to fork both CoffeeScript files, and JavaScript files, directly.</p>
</li>
<li id="section-8">
<li id="section-10">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-8">&#x00a7;</a>
<a class="ss" href="#section-10">&#x00a7;</a>
</div>
<p>Utility function to find the <code>options</code> object attached to the topmost module.</p>

95
docs/v2/annotated-source/sourcemap.html
View file

@ -237,7 +237,7 @@ code.</p>
<div class="sswrap ">
<a class="ss" href="#section-7">&#x00a7;</a>
</div>
<h2 id="v3-sourcemap-generation">V3 SourceMap Generation</h2>
<h2 id="caching">Caching</h2>
</div>
@ -250,6 +250,43 @@ code.</p>
<div class="sswrap ">
<a class="ss" href="#section-8">&#x00a7;</a>
</div>
<p>A static source maps cache <code>filename</code>: <code>map</code>. These are used for transforming
stack traces and are currently set in <code>CoffeeScript.compile</code> for all files
compiled with the source maps option.</p>
</div>
<div class="content"><div class='highlight'><pre> @sourceMaps: <span class="hljs-built_in">Object</span>.create <span class="hljs-literal">null</span>
@registerCompiled: <span class="hljs-function"><span class="hljs-params">(filename, source, sourcemap)</span> =&gt;</span>
<span class="hljs-keyword">if</span> sourcemap?
@sourceMaps[filename] = sourcemap
@getSourceMap: <span class="hljs-function"><span class="hljs-params">(filename)</span> =&gt;</span>
@sourceMaps[filename]</pre></div></div>
</li>
<li id="section-9">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-9">&#x00a7;</a>
</div>
<h2 id="v3-sourcemap-generation">V3 SourceMap Generation</h2>
</div>
</li>
<li id="section-10">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-10">&#x00a7;</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
map. Also, <code>options.sourceFiles</code> and <code>options.generatedFile</code> may be passed to
@ -276,11 +313,11 @@ set “sources” and “file”, respectively.</p>
</li>
<li id="section-9">
<li id="section-11">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-9">&#x00a7;</a>
<a class="ss" href="#section-11">&#x00a7;</a>
</div>
<p>Write a comma if we’ve already written a segment on this line.</p>
@ -293,11 +330,11 @@ set “sources” and “file”, respectively.</p>
</li>
<li id="section-10">
<li id="section-12">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-10">&#x00a7;</a>
<a class="ss" href="#section-12">&#x00a7;</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.</p>
@ -312,11 +349,11 @@ column for the current line:</p>
</li>
<li id="section-11">
<li id="section-13">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-11">&#x00a7;</a>
<a class="ss" href="#section-13">&#x00a7;</a>
</div>
<p>The index into the list of sources:</p>
@ -327,11 +364,11 @@ column for the current line:</p>
</li>
<li id="section-12">
<li id="section-14">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-12">&#x00a7;</a>
<a class="ss" href="#section-14">&#x00a7;</a>
</div>
<p>The starting line in the original source, relative to the previous source line.</p>
@ -343,11 +380,11 @@ column for the current line:</p>
</li>
<li id="section-13">
<li id="section-15">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-13">&#x00a7;</a>
<a class="ss" href="#section-15">&#x00a7;</a>
</div>
<p>The starting column in the original source, relative to the previous column.</p>
@ -360,11 +397,11 @@ column for the current line:</p>
</li>
<li id="section-14">
<li id="section-16">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-14">&#x00a7;</a>
<a class="ss" href="#section-16">&#x00a7;</a>
</div>
<p>Produce the canonical JSON object format for a “v3” source map.</p>
@ -392,11 +429,11 @@ column for the current line:</p>
</li>
<li id="section-15">
<li id="section-17">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-15">&#x00a7;</a>
<a class="ss" href="#section-17">&#x00a7;</a>
</div>
<h2 id="base64-vlq-encoding">Base64 VLQ Encoding</h2>
@ -405,11 +442,11 @@ column for the current line:</p>
</li>
<li id="section-16">
<li id="section-18">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-16">&#x00a7;</a>
<a class="ss" href="#section-18">&#x00a7;</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
@ -429,11 +466,11 @@ bits of the original value encoded into the first byte of the VLQ encoded value.
</li>
<li id="section-17">
<li id="section-19">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-17">&#x00a7;</a>
<a class="ss" href="#section-19">&#x00a7;</a>
</div>
<p>Least significant bit represents the sign.</p>
@ -444,11 +481,11 @@ bits of the original value encoded into the first byte of the VLQ encoded value.
</li>
<li id="section-18">
<li id="section-20">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-18">&#x00a7;</a>
<a class="ss" href="#section-20">&#x00a7;</a>
</div>
<p>The next bits are the actual value.</p>
@ -459,11 +496,11 @@ bits of the original value encoded into the first byte of the VLQ encoded value.
</li>
<li id="section-19">
<li id="section-21">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-19">&#x00a7;</a>
<a class="ss" href="#section-21">&#x00a7;</a>
</div>
<p>Make sure we encode at least one character, even if valueToEncode is 0.</p>
@ -480,11 +517,11 @@ bits of the original value encoded into the first byte of the VLQ encoded value.
</li>
<li id="section-20">
<li id="section-22">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-20">&#x00a7;</a>
<a class="ss" href="#section-22">&#x00a7;</a>
</div>
<h2 id="regular-base64-encoding">Regular Base64 Encoding</h2>
@ -493,11 +530,11 @@ bits of the original value encoded into the first byte of the VLQ encoded value.
</li>
<li id="section-21">
<li id="section-23">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-21">&#x00a7;</a>
<a class="ss" href="#section-23">&#x00a7;</a>
</div>
</div>
@ -510,11 +547,11 @@ bits of the original value encoded into the first byte of the VLQ encoded value.
</li>
<li id="section-22">
<li id="section-24">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-22">&#x00a7;</a>
<a class="ss" href="#section-24">&#x00a7;</a>
</div>
<p>Our API for source maps is just the <code>SourceMap</code> class.</p>