github/coffeescript
1
1
Fork 0
mirror of https://github.com/jashkenas/coffeescript.git synced 2026-01-13 00:37:54 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
coffeescript/docs/v2/annotated-source/index.html

498 lines
20 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html>
<head>
<title>index.coffee</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta name="viewport" content="width=device-width, target-densitydpi=160dpi, initial-scale=1.0; maximum-scale=1.0; user-scalable=0;">
<link rel="stylesheet" media="all" href="docco.css" />
</head>
<body>
<div id="container">
<div id="background"></div>
<ul id="jump_to">
<li>
<a class="large" href="javascript:void(0);">Jump To &hellip;</a>
<a class="small" href="javascript:void(0);">+</a>
<div id="jump_wrapper">
<div id="jump_page_wrapper">
<div id="jump_page">
<a class="source" href="browser.html">
browser.coffee
</a>
<a class="source" href="cake.html">
cake.coffee
</a>
<a class="source" href="coffeescript.html">
coffeescript.coffee
</a>
<a class="source" href="command.html">
command.coffee
</a>
<a class="source" href="grammar.html">
grammar.coffee
</a>
<a class="source" href="helpers.html">
helpers.coffee
</a>
<a class="source" href="index.html">
index.coffee
</a>
<a class="source" href="lexer.html">
lexer.coffee
</a>
<a class="source" href="nodes.html">
nodes.coffee
</a>
<a class="source" href="optparse.html">
optparse.coffee
</a>
<a class="source" href="register.html">
register.coffee
</a>
<a class="source" href="repl.html">
repl.coffee
</a>
<a class="source" href="rewriter.html">
rewriter.coffee
</a>
<a class="source" href="scope.html">
scope.litcoffee
</a>
<a class="source" href="sourcemap.html">
sourcemap.litcoffee
</a>
</div>
</div>
</li>
</ul>
<ul class="sections">
<li id="title">
<div class="annotation">
<h1>index.coffee</h1>
</div>
</li>
<li id="section-1">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-1">&#x00a7;</a>
</div>
<p>Node.js Implementation</p>
</div>
<div class="content"><div class='highlight'><pre>CoffeeScript = <span class="hljs-built_in">require</span> <span class="hljs-string">&#x27;./coffeescript&#x27;</span>
fs = <span class="hljs-built_in">require</span> <span class="hljs-string">&#x27;fs&#x27;</span>
vm = <span class="hljs-built_in">require</span> <span class="hljs-string">&#x27;vm&#x27;</span>
path = <span class="hljs-built_in">require</span> <span class="hljs-string">&#x27;path&#x27;</span>
helpers = CoffeeScript.helpers
CoffeeScript.transpile = <span class="hljs-function"><span class="hljs-params">(js, options)</span> -&gt;</span>
<span class="hljs-keyword">try</span>
babel = <span class="hljs-built_in">require</span> <span class="hljs-string">&#x27;@babel/core&#x27;</span>
<span class="hljs-keyword">catch</span>
<span class="hljs-keyword">try</span>
babel = <span class="hljs-built_in">require</span> <span class="hljs-string">&#x27;babel-core&#x27;</span>
<span class="hljs-keyword">catch</span></pre></div></div>
</li>
<li id="section-2">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-2">&#x00a7;</a>
</div>
<p>This error is only for Node, as CLI users will see a different error
earlier if they don’t have Babel installed.</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Error</span> <span class="hljs-string">&#x27;To use the transpile option, you must have the \&#x27;@babel/core\&#x27; module installed&#x27;</span>
babel.transform js, options</pre></div></div>
</li>
<li id="section-3">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-3">&#x00a7;</a>
</div>
<p>The <code>compile</code> method shared by the CLI, Node and browser APIs.</p>
</div>
<div class="content"><div class='highlight'><pre>universalCompile = CoffeeScript.compile</pre></div></div>
</li>
<li id="section-4">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-4">&#x00a7;</a>
</div>
<p>The <code>compile</code> method particular to the Node API.</p>
</div>
<div class="content"><div class='highlight'><pre>CoffeeScript.compile = <span class="hljs-function"><span class="hljs-params">(code, options)</span> -&gt;</span></pre></div></div>
</li>
<li id="section-5">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-5">&#x00a7;</a>
</div>
<p>Pass a reference to Babel into the compiler, so that the transpile option
is available in the Node API. We need to do this so that tools like Webpack
can <code>require(&#39;coffeescript&#39;)</code> and build correctly, without trying to
require Babel.</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">if</span> options?.transpile
options.transpile.transpile = CoffeeScript.transpile
universalCompile.call CoffeeScript, code, options</pre></div></div>
</li>
<li id="section-6">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-6">&#x00a7;</a>
</div>
<p>Compile and execute a string of CoffeeScript (on the server), correctly
setting <code>__filename</code>, <code>__dirname</code>, and relative <code>require()</code>.</p>
</div>
<div class="content"><div class='highlight'><pre>CoffeeScript.run = <span class="hljs-function"><span class="hljs-params">(code, options = {})</span> -&gt;</span>
mainModule = <span class="hljs-built_in">require</span>.main</pre></div></div>
</li>
<li id="section-7">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-7">&#x00a7;</a>
</div>
<p>Set the filename.</p>
</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> helpers.anonymousFileName()</pre></div></div>
</li>
<li id="section-8">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-8">&#x00a7;</a>
</div>
<p>Clear the module cache.</p>
</div>
<div class="content"><div class='highlight'><pre> mainModule.moduleCache <span class="hljs-keyword">and</span>= {}</pre></div></div>
</li>
<li id="section-9">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-9">&#x00a7;</a>
</div>
<p>Assign paths for node_modules loading</p>
</div>
<div class="content"><div class='highlight'><pre> dir = <span class="hljs-keyword">if</span> options.filename?
path.dirname fs.realpathSync options.filename
<span class="hljs-keyword">else</span>
fs.realpathSync <span class="hljs-string">&#x27;.&#x27;</span>
mainModule.paths = <span class="hljs-built_in">require</span>(<span class="hljs-string">&#x27;module&#x27;</span>)._nodeModulePaths dir</pre></div></div>
</li>
<li id="section-10">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-10">&#x00a7;</a>
</div>
<p>Save the options for compiling child imports.</p>
</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>
<li id="section-11">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-11">&#x00a7;</a>
</div>
<p>Compile.</p>
</div>
<div class="content"><div class='highlight'><pre> answer = CoffeeScript.compile code, options
code = answer.js ? answer
mainModule._compile code, mainModule.filename</pre></div></div>
</li>
<li id="section-12">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-12">&#x00a7;</a>
</div>
<p>Compile and evaluate a string of CoffeeScript (in a Node.js-like environment).
The CoffeeScript REPL uses this to run the input.</p>
</div>
<div class="content"><div class='highlight'><pre>CoffeeScript.<span class="hljs-built_in">eval</span> = <span class="hljs-function"><span class="hljs-params">(code, options = {})</span> -&gt;</span>
<span class="hljs-keyword">return</span> <span class="hljs-keyword">unless</span> code = code.trim()
createContext = vm.Script.createContext ? vm.createContext
isContext = vm.isContext ? (ctx) -&gt;
options.sandbox <span class="hljs-keyword">instanceof</span> createContext().constructor
<span class="hljs-keyword">if</span> createContext
<span class="hljs-keyword">if</span> options.sandbox?
<span class="hljs-keyword">if</span> isContext options.sandbox
sandbox = options.sandbox
<span class="hljs-keyword">else</span>
sandbox = createContext()
sandbox[k] = v <span class="hljs-keyword">for</span> own k, v <span class="hljs-keyword">of</span> options.sandbox
sandbox.global = sandbox.root = sandbox.GLOBAL = sandbox
<span class="hljs-keyword">else</span>
sandbox = global
sandbox.__filename = options.filename || <span class="hljs-string">&#x27;eval&#x27;</span>
sandbox.__dirname = path.dirname sandbox.__filename</pre></div></div>
</li>
<li id="section-13">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-13">&#x00a7;</a>
</div>
<p>define module/require only if they chose not to specify their own</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">unless</span> sandbox <span class="hljs-keyword">isnt</span> global <span class="hljs-keyword">or</span> sandbox.module <span class="hljs-keyword">or</span> sandbox.<span class="hljs-built_in">require</span>
Module = <span class="hljs-built_in">require</span> <span class="hljs-string">&#x27;module&#x27;</span>
sandbox.module = _module = <span class="hljs-keyword">new</span> Module(options.modulename || <span class="hljs-string">&#x27;eval&#x27;</span>)
sandbox.<span class="hljs-built_in">require</span> = _require = <span class="hljs-function"><span class="hljs-params">(path)</span> -&gt;</span> Module._load path, _module, <span class="hljs-literal">true</span>
_module.filename = sandbox.__filename
<span class="hljs-keyword">for</span> r <span class="hljs-keyword">in</span> <span class="hljs-built_in">Object</span>.getOwnPropertyNames <span class="hljs-built_in">require</span> <span class="hljs-keyword">when</span> r <span class="hljs-keyword">not</span> <span class="hljs-keyword">in</span> [<span class="hljs-string">&#x27;paths&#x27;</span>, <span class="hljs-string">&#x27;arguments&#x27;</span>, <span class="hljs-string">&#x27;caller&#x27;</span>]
_require[r] = <span class="hljs-built_in">require</span>[r]</pre></div></div>
</li>
<li id="section-14">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-14">&#x00a7;</a>
</div>
<p>use the same hack node currently uses for their own REPL</p>
</div>
<div class="content"><div class='highlight'><pre> _require.paths = _module.paths = Module._nodeModulePaths process.cwd()
_require.resolve = <span class="hljs-function"><span class="hljs-params">(request)</span> -&gt;</span> Module._resolveFilename request, _module
o = {}
o[k] = v <span class="hljs-keyword">for</span> own k, v <span class="hljs-keyword">of</span> options
o.bare = <span class="hljs-literal">on</span> <span class="hljs-comment"># ensure return value</span>
js = CoffeeScript.compile code, o
<span class="hljs-keyword">if</span> sandbox <span class="hljs-keyword">is</span> global
vm.runInThisContext js
<span class="hljs-keyword">else</span>
vm.runInContext js, sandbox
CoffeeScript.register = <span class="hljs-function">-&gt;</span> <span class="hljs-built_in">require</span> <span class="hljs-string">&#x27;./register&#x27;</span></pre></div></div>
</li>
<li id="section-15">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-15">&#x00a7;</a>
</div>
<p>Throw error with deprecation warning when depending upon implicit <code>require.extensions</code> registration</p>
</div>
<div class="content"><div class='highlight'><pre><span class="hljs-keyword">if</span> <span class="hljs-built_in">require</span>.extensions
<span class="hljs-keyword">for</span> ext <span class="hljs-keyword">in</span> CoffeeScript.FILE_EXTENSIONS <span class="hljs-keyword">then</span> <span class="hljs-keyword">do</span> (ext) -&gt;
<span class="hljs-built_in">require</span>.extensions[ext] ?= <span class="hljs-function">-&gt;</span>
<span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Error</span> <span class="hljs-string">&quot;&quot;&quot;
Use CoffeeScript.register() or require the coffeescript/register module to require <span class="hljs-subst">#{ext}</span> files.
&quot;&quot;&quot;</span>
CoffeeScript._compileRawFileContent = <span class="hljs-function"><span class="hljs-params">(raw, filename, options = {})</span> -&gt;</span></pre></div></div>
</li>
<li id="section-16">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-16">&#x00a7;</a>
</div>
<p>Strip the Unicode byte order mark, if this file begins with one.</p>
</div>
<div class="content"><div class='highlight'><pre> stripped = <span class="hljs-keyword">if</span> raw.charCodeAt(<span class="hljs-number">0</span>) <span class="hljs-keyword">is</span> <span class="hljs-number">0xFEFF</span> <span class="hljs-keyword">then</span> raw.substring <span class="hljs-number">1</span> <span class="hljs-keyword">else</span> raw
options = <span class="hljs-built_in">Object</span>.assign {}, options,
filename: filename
literate: helpers.isLiterate filename
sourceFiles: [filename]
<span class="hljs-keyword">try</span>
answer = CoffeeScript.compile stripped, options
<span class="hljs-keyword">catch</span> err</pre></div></div>
</li>
<li id="section-17">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-17">&#x00a7;</a>
</div>
<p>As the filename and code of a dynamically loaded file will be different
from the original file compiled with CoffeeScript.run, add that
information to error so it can be pretty-printed later.</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">throw</span> helpers.updateSyntaxError err, stripped, filename
answer
CoffeeScript._compileFile = <span class="hljs-function"><span class="hljs-params">(filename, options = {})</span> -&gt;</span>
raw = fs.readFileSync filename, <span class="hljs-string">&#x27;utf8&#x27;</span>
CoffeeScript._compileRawFileContent raw, filename, options
module.<span class="hljs-built_in">exports</span> = CoffeeScript</pre></div></div>
</li>
<li id="section-18">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-18">&#x00a7;</a>
</div>
<p>Explicitly define all named exports so that Node’s automatic detection of
named exports from CommonJS packages finds all of them. This enables consuming
packages to write code like <code>import { compile } from &#39;coffeescript&#39;</code>.
Don’t simplify this into a loop or similar; the <code>module.exports.name</code> part is
essential for Node’s algorithm to successfully detect the name.</p>
</div>
<div class="content"><div class='highlight'><pre>module.<span class="hljs-built_in">exports</span>.VERSION = CoffeeScript.VERSION
module.<span class="hljs-built_in">exports</span>.FILE_EXTENSIONS = CoffeeScript.FILE_EXTENSIONS
module.<span class="hljs-built_in">exports</span>.helpers = CoffeeScript.helpers
module.<span class="hljs-built_in">exports</span>.registerCompiled = CoffeeScript.registerCompiled
module.<span class="hljs-built_in">exports</span>.compile = CoffeeScript.compile
module.<span class="hljs-built_in">exports</span>.tokens = CoffeeScript.tokens
module.<span class="hljs-built_in">exports</span>.nodes = CoffeeScript.nodes
module.<span class="hljs-built_in">exports</span>.register = CoffeeScript.register
module.<span class="hljs-built_in">exports</span>.<span class="hljs-built_in">eval</span> = CoffeeScript.<span class="hljs-built_in">eval</span>
module.<span class="hljs-built_in">exports</span>.run = CoffeeScript.run
module.<span class="hljs-built_in">exports</span>.transpile = CoffeeScript.transpile
module.<span class="hljs-built_in">exports</span>.patchStackTrace = CoffeeScript.patchStackTrace
module.<span class="hljs-built_in">exports</span>._compileRawFileContent = CoffeeScript._compileRawFileContent
module.<span class="hljs-built_in">exports</span>._compileFile = CoffeeScript._compileFile</pre></div></div>
</li>
</ul>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink