/documentation/docs/scope.html

http://github.com/jashkenas/coffee-script · HTML · 392 lines · 265 code · 127 blank · 0 comment · 0 complexity · db2b0b333c46bf2db8b59d105095c30f MD5 · raw file 

    

  1. <!DOCTYPE html>
    2. 

  2. 

  3. <html>
    4. 

  4. <head>
    5. 

  5.   <title>scope.litcoffee</title>
    6. 

  6.   <meta http-equiv="content-type" content="text/html; charset=UTF-8">
    7. 

  7.   <meta name="viewport" content="width=device-width, target-densitydpi=160dpi, initial-scale=1.0; maximum-scale=1.0; user-scalable=0;">
    8. 

  8.   <link rel="stylesheet" media="all" href="docco.css" />
    9. 

  9. </head>
    10. 

  10. <body>
    11. 

  11.   <div id="container">
    12. 

  12.     <div id="background"></div>
    13. 

  13.     
    14. 

  14.       <ul id="jump_to">
    15. 

  15.         <li>
    16. 

  16.           <a class="large" href="javascript:void(0);">Jump To &hellip;</a>
    17. 

  17.           <a class="small" href="javascript:void(0);">+</a>
    18. 

  18.           <div id="jump_wrapper">
    19. 

  19.           <div id="jump_page_wrapper">
    20. 

  20.             <div id="jump_page">
    21. 

  21.               
    22. 

  22.                 
    23. 

  23.                 <a class="source" href="browser.html">
    24. 

  24.                   browser.coffee
    25. 

  25.                 </a>
    26. 

  26.               
    27. 

  27.                 
    28. 

  28.                 <a class="source" href="cake.html">
    29. 

  29.                   cake.coffee
    30. 

  30.                 </a>
    31. 

  31.               
    32. 

  32.                 
    33. 

  33.                 <a class="source" href="coffee-script.html">
    34. 

  34.                   coffee-script.coffee
    35. 

  35.                 </a>
    36. 

  36.               
    37. 

  37.                 
    38. 

  38.                 <a class="source" href="command.html">
    39. 

  39.                   command.coffee
    40. 

  40.                 </a>
    41. 

  41.               
    42. 

  42.                 
    43. 

  43.                 <a class="source" href="grammar.html">
    44. 

  44.                   grammar.coffee
    45. 

  45.                 </a>
    46. 

  46.               
    47. 

  47.                 
    48. 

  48.                 <a class="source" href="helpers.html">
    49. 

  49.                   helpers.coffee
    50. 

  50.                 </a>
    51. 

  51.               
    52. 

  52.                 
    53. 

  53.                 <a class="source" href="index.html">
    54. 

  54.                   index.coffee
    55. 

  55.                 </a>
    56. 

  56.               
    57. 

  57.                 
    58. 

  58.                 <a class="source" href="lexer.html">
    59. 

  59.                   lexer.coffee
    60. 

  60.                 </a>
    61. 

  61.               
    62. 

  62.                 
    63. 

  63.                 <a class="source" href="nodes.html">
    64. 

  64.                   nodes.coffee
    65. 

  65.                 </a>
    66. 

  66.               
    67. 

  67.                 
    68. 

  68.                 <a class="source" href="optparse.html">
    69. 

  69.                   optparse.coffee
    70. 

  70.                 </a>
    71. 

  71.               
    72. 

  72.                 
    73. 

  73.                 <a class="source" href="register.html">
    74. 

  74.                   register.coffee
    75. 

  75.                 </a>
    76. 

  76.               
    77. 

  77.                 
    78. 

  78.                 <a class="source" href="repl.html">
    79. 

  79.                   repl.coffee
    80. 

  80.                 </a>
    81. 

  81.               
    82. 

  82.                 
    83. 

  83.                 <a class="source" href="rewriter.html">
    84. 

  84.                   rewriter.coffee
    85. 

  85.                 </a>
    86. 

  86.               
    87. 

  87.                 
    88. 

  88.                 <a class="source" href="scope.html">
    89. 

  89.                   scope.litcoffee
    90. 

  90.                 </a>
    91. 

  91.               
    92. 

  92.                 
    93. 

  93.                 <a class="source" href="sourcemap.html">
    94. 

  94.                   sourcemap.litcoffee
    95. 

  95.                 </a>
    96. 

  96.               
    97. 

  97.             </div>
    98. 

  98.           </div>
    99. 

  99.         </li>
    100. 

  100.       </ul>
    101. 

  101.     
    102. 

  102.     <ul class="sections">
    103. 

  103.         
    104. 

  104.           <li id="title">
    105. 

  105.               <div class="annotation">
    106. 

  106.                   <h1>scope.litcoffee</h1>
    107. 

  107.               </div>
    108. 

  108.           </li>
    109. 

  109.         
    110. 

  110.         
    111. 

  111.         
    112. 

  112.         <li id="section-1">
    113. 

  113.             <div class="annotation">
    114. 

  114.               
    115. 

  115.               <div class="pilwrap ">
    116. 

  116.                 <a class="pilcrow" href="#section-1">&#182;</a>
    117. 

  117.               </div>
    118. 

  118.               <p>The <strong>Scope</strong> class regulates lexical scoping within CoffeeScript. As you
    119. 

  119. generate code, you create a tree of scopes in the same shape as the nested
    120. 

  120. function bodies. Each scope knows about the variables declared within it,
    121. 

  121. and has a reference to its parent enclosing scope. In this way, we know which
    122. 

  122. variables are new and need to be declared with <code>var</code>, and which are shared
    123. 

  123. with external scopes.</p>
    124. 

  124. 

  125.             </div>
    126. 

  126.             
    127. 

  127.             <div class="content"><div class='highlight'><pre><span class="hljs-built_in">exports</span>.Scope = <span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">Scope</span></span></pre></div></div>
    128. 

  128.             
    129. 

  129.         </li>
    130. 

  130.         
    131. 

  131.         
    132. 

  132.         <li id="section-2">
    133. 

  133.             <div class="annotation">
    134. 

  134.               
    135. 

  135.               <div class="pilwrap ">
    136. 

  136.                 <a class="pilcrow" href="#section-2">&#182;</a>
    137. 

  137.               </div>
    138. 

  138.               <p>Initialize a scope with its parent, for lookups up the chain,
    139. 

  139. as well as a reference to the <strong>Block</strong> node it belongs to, which is
    140. 

  140. where it should declare its variables, a reference to the function that
    141. 

  141. it belongs to, and a list of variables referenced in the source code
    142. 

  142. and therefore should be avoided when generating variables.</p>
    143. 

  143. 

  144.             </div>
    145. 

  145.             
    146. 

  146.             <div class="content"><div class='highlight'><pre>  <span class="hljs-attribute">constructor</span>: <span class="hljs-function"><span class="hljs-params">(<span class="hljs-property">@parent</span>, <span class="hljs-property">@expressions</span>, <span class="hljs-property">@method</span>, <span class="hljs-property">@referencedVars</span>)</span> -&gt;</span>
    147. 

  147.     <span class="hljs-property">@variables</span> = [{<span class="hljs-attribute">name</span>: <span class="hljs-string">'arguments'</span>, <span class="hljs-attribute">type</span>: <span class="hljs-string">'arguments'</span>}]
    148. 

  148.     <span class="hljs-property">@positions</span> = {}
    149. 

  149.     <span class="hljs-property">@utilities</span> = {} <span class="hljs-keyword">unless</span> <span class="hljs-property">@parent</span></pre></div></div>
    150. 

  150.             
    151. 

  151.         </li>
    152. 

  152.         
    153. 

  153.         
    154. 

  154.         <li id="section-3">
    155. 

  155.             <div class="annotation">
    156. 

  156.               
    157. 

  157.               <div class="pilwrap ">
    158. 

  158.                 <a class="pilcrow" href="#section-3">&#182;</a>
    159. 

  159.               </div>
    160. 

  160.               <p>The <code>@root</code> is the top-level <strong>Scope</strong> object for a given file.</p>
    161. 

  161. 

  162.             </div>
    163. 

  163.             
    164. 

  164.             <div class="content"><div class='highlight'><pre>    <span class="hljs-property">@root</span> = <span class="hljs-property">@parent</span>?.root ? <span class="hljs-keyword">this</span></pre></div></div>
    165. 

  165.             
    166. 

  166.         </li>
    167. 

  167.         
    168. 

  168.         
    169. 

  169.         <li id="section-4">
    170. 

  170.             <div class="annotation">
    171. 

  171.               
    172. 

  172.               <div class="pilwrap ">
    173. 

  173.                 <a class="pilcrow" href="#section-4">&#182;</a>
    174. 

  174.               </div>
    175. 

  175.               <p>Adds a new variable or overrides an existing one.</p>
    176. 

  176. 

  177.             </div>
    178. 

  178.             
    179. 

  179.             <div class="content"><div class='highlight'><pre>  <span class="hljs-attribute">add</span>: <span class="hljs-function"><span class="hljs-params">(name, type, immediate)</span> -&gt;</span>
    180. 

  180.     <span class="hljs-keyword">return</span> <span class="hljs-property">@parent</span>.add name, type, immediate <span class="hljs-keyword">if</span> <span class="hljs-property">@shared</span> <span class="hljs-keyword">and</span> <span class="hljs-keyword">not</span> immediate
    181. 

  181.     <span class="hljs-keyword">if</span> <span class="hljs-attribute">Object</span>::hasOwnProperty.call <span class="hljs-property">@positions</span>, name
    182. 

  182.       <span class="hljs-property">@variables</span>[<span class="hljs-property">@positions</span>[name]].type = type
    183. 

  183.     <span class="hljs-keyword">else</span>
    184. 

  184.       <span class="hljs-property">@positions</span>[name] = <span class="hljs-property">@variables</span>.push({name, type}) - <span class="hljs-number">1</span></pre></div></div>
    185. 

  185.             
    186. 

  186.         </li>
    187. 

  187.         
    188. 

  188.         
    189. 

  189.         <li id="section-5">
    190. 

  190.             <div class="annotation">
    191. 

  191.               
    192. 

  192.               <div class="pilwrap ">
    193. 

  193.                 <a class="pilcrow" href="#section-5">&#182;</a>
    194. 

  194.               </div>
    195. 

  195.               <p>When <code>super</code> is called, we need to find the name of the current method we’re
    196. 

  196. in, so that we know how to invoke the same method of the parent class. This
    197. 

  197. can get complicated if super is being called from an inner function.
    198. 

  198. <code>namedMethod</code> will walk up the scope tree until it either finds the first
    199. 

  199. function object that has a name filled in, or bottoms out.</p>
    200. 

  200. 

  201.             </div>
    202. 

  202.             
    203. 

  203.             <div class="content"><div class='highlight'><pre>  <span class="hljs-attribute">namedMethod</span>:<span class="hljs-function"> -&gt;</span>
    204. 

  204.     <span class="hljs-keyword">return</span> <span class="hljs-property">@method</span> <span class="hljs-keyword">if</span> <span class="hljs-property">@method</span>?.name <span class="hljs-keyword">or</span> !<span class="hljs-property">@parent</span>
    205. 

  205.     <span class="hljs-property">@parent</span>.namedMethod()</pre></div></div>
    206. 

  206.             
    207. 

  207.         </li>
    208. 

  208.         
    209. 

  209.         
    210. 

  210.         <li id="section-6">
    211. 

  211.             <div class="annotation">
    212. 

  212.               
    213. 

  213.               <div class="pilwrap ">
    214. 

  214.                 <a class="pilcrow" href="#section-6">&#182;</a>
    215. 

  215.               </div>
    216. 

  216.               <p>Look up a variable name in lexical scope, and declare it if it does not
    217. 

  217. already exist.</p>
    218. 

  218. 

  219.             </div>
    220. 

  220.             
    221. 

  221.             <div class="content"><div class='highlight'><pre>  <span class="hljs-attribute">find</span>: <span class="hljs-function"><span class="hljs-params">(name)</span> -&gt;</span>
    222. 

  222.     <span class="hljs-keyword">return</span> <span class="hljs-literal">yes</span> <span class="hljs-keyword">if</span> <span class="hljs-property">@check</span> name
    223. 

  223.     <span class="hljs-property">@add</span> name, <span class="hljs-string">'var'</span>
    224. 

  224.     <span class="hljs-literal">no</span></pre></div></div>
    225. 

  225.             
    226. 

  226.         </li>
    227. 

  227.         
    228. 

  228.         
    229. 

  229.         <li id="section-7">
    230. 

  230.             <div class="annotation">
    231. 

  231.               
    232. 

  232.               <div class="pilwrap ">
    233. 

  233.                 <a class="pilcrow" href="#section-7">&#182;</a>
    234. 

  234.               </div>
    235. 

  235.               <p>Reserve a variable name as originating from a function parameter for this
    236. 

  236. scope. No <code>var</code> required for internal references.</p>
    237. 

  237. 

  238.             </div>
    239. 

  239.             
    240. 

  240.             <div class="content"><div class='highlight'><pre>  <span class="hljs-attribute">parameter</span>: <span class="hljs-function"><span class="hljs-params">(name)</span> -&gt;</span>
    241. 

  241.     <span class="hljs-keyword">return</span> <span class="hljs-keyword">if</span> <span class="hljs-property">@shared</span> <span class="hljs-keyword">and</span> <span class="hljs-property">@parent</span>.check name, <span class="hljs-literal">yes</span>
    242. 

  242.     <span class="hljs-property">@add</span> name, <span class="hljs-string">'param'</span></pre></div></div>
    243. 

  243.             
    244. 

  244.         </li>
    245. 

  245.         
    246. 

  246.         
    247. 

  247.         <li id="section-8">
    248. 

  248.             <div class="annotation">
    249. 

  249.               
    250. 

  250.               <div class="pilwrap ">
    251. 

  251.                 <a class="pilcrow" href="#section-8">&#182;</a>
    252. 

  252.               </div>
    253. 

  253.               <p>Just check to see if a variable has already been declared, without reserving,
    254. 

  254. walks up to the root scope.</p>
    255. 

  255. 

  256.             </div>
    257. 

  257.             
    258. 

  258.             <div class="content"><div class='highlight'><pre>  <span class="hljs-attribute">check</span>: <span class="hljs-function"><span class="hljs-params">(name)</span> -&gt;</span>
    259. 

  259.     !!(<span class="hljs-property">@type</span>(name) <span class="hljs-keyword">or</span> <span class="hljs-property">@parent</span>?.check(name))</pre></div></div>
    260. 

  260.             
    261. 

  261.         </li>
    262. 

  262.         
    263. 

  263.         
    264. 

  264.         <li id="section-9">
    265. 

  265.             <div class="annotation">
    266. 

  266.               
    267. 

  267.               <div class="pilwrap ">
    268. 

  268.                 <a class="pilcrow" href="#section-9">&#182;</a>
    269. 

  269.               </div>
    270. 

  270.               <p>Generate a temporary variable name at the given index.</p>
    271. 

  271. 

  272.             </div>
    273. 

  273.             
    274. 

  274.             <div class="content"><div class='highlight'><pre>  <span class="hljs-attribute">temporary</span>: <span class="hljs-function"><span class="hljs-params">(name, index, single=<span class="hljs-literal">false</span>)</span> -&gt;</span>
    275. 

  275.     <span class="hljs-keyword">if</span> single
    276. 

  276.       (index + parseInt name, <span class="hljs-number">36</span>).toString(<span class="hljs-number">36</span>).replace <span class="hljs-regexp">/\d/g</span>, <span class="hljs-string">'a'</span>
    277. 

  277.     <span class="hljs-keyword">else</span>
    278. 

  278.       name + (index <span class="hljs-keyword">or</span> <span class="hljs-string">''</span>)</pre></div></div>
    279. 

  279.             
    280. 

  280.         </li>
    281. 

  281.         
    282. 

  282.         
    283. 

  283.         <li id="section-10">
    284. 

  284.             <div class="annotation">
    285. 

  285.               
    286. 

  286.               <div class="pilwrap ">
    287. 

  287.                 <a class="pilcrow" href="#section-10">&#182;</a>
    288. 

  288.               </div>
    289. 

  289.               <p>Gets the type of a variable.</p>
    290. 

  290. 

  291.             </div>
    292. 

  292.             
    293. 

  293.             <div class="content"><div class='highlight'><pre>  <span class="hljs-attribute">type</span>: <span class="hljs-function"><span class="hljs-params">(name)</span> -&gt;</span>
    294. 

  294.     <span class="hljs-keyword">return</span> v.type <span class="hljs-keyword">for</span> v <span class="hljs-keyword">in</span> <span class="hljs-property">@variables</span> <span class="hljs-keyword">when</span> v.name <span class="hljs-keyword">is</span> name
    295. 

  295.     <span class="hljs-literal">null</span></pre></div></div>
    296. 

  296.             
    297. 

  297.         </li>
    298. 

  298.         
    299. 

  299.         
    300. 

  300.         <li id="section-11">
    301. 

  301.             <div class="annotation">
    302. 

  302.               
    303. 

  303.               <div class="pilwrap ">
    304. 

  304.                 <a class="pilcrow" href="#section-11">&#182;</a>
    305. 

  305.               </div>
    306. 

  306.               <p>If we need to store an intermediate result, find an available name for a
    307. 

  307. compiler-generated variable. <code>_var</code>, <code>_var2</code>, and so on…</p>
    308. 

  308. 

  309.             </div>
    310. 

  310.             
    311. 

  311.             <div class="content"><div class='highlight'><pre>  <span class="hljs-attribute">freeVariable</span>: <span class="hljs-function"><span class="hljs-params">(name, options={})</span> -&gt;</span>
    312. 

  312.     index = <span class="hljs-number">0</span>
    313. 

  313.     <span class="hljs-keyword">loop</span>
    314. 

  314.       temp = <span class="hljs-property">@temporary</span> name, index, options.single
    315. 

  315.       <span class="hljs-keyword">break</span> <span class="hljs-keyword">unless</span> <span class="hljs-property">@check</span>(temp) <span class="hljs-keyword">or</span> temp <span class="hljs-keyword">in</span> <span class="hljs-property">@root</span>.referencedVars
    316. 

  316.       index++
    317. 

  317.     <span class="hljs-property">@add</span> temp, <span class="hljs-string">'var'</span>, <span class="hljs-literal">yes</span> <span class="hljs-keyword">if</span> options.reserve ? <span class="hljs-literal">true</span>
    318. 

  318.     temp</pre></div></div>
    319. 

  319.             
    320. 

  320.         </li>
    321. 

  321.         
    322. 

  322.         
    323. 

  323.         <li id="section-12">
    324. 

  324.             <div class="annotation">
    325. 

  325.               
    326. 

  326.               <div class="pilwrap ">
    327. 

  327.                 <a class="pilcrow" href="#section-12">&#182;</a>
    328. 

  328.               </div>
    329. 

  329.               <p>Ensure that an assignment is made at the top of this scope
    330. 

  330. (or at the top-level scope, if requested).</p>
    331. 

  331. 

  332.             </div>
    333. 

  333.             
    334. 

  334.             <div class="content"><div class='highlight'><pre>  <span class="hljs-attribute">assign</span>: <span class="hljs-function"><span class="hljs-params">(name, value)</span> -&gt;</span>
    335. 

  335.     <span class="hljs-property">@add</span> name, {value, <span class="hljs-attribute">assigned</span>: <span class="hljs-literal">yes</span>}, <span class="hljs-literal">yes</span>
    336. 

  336.     <span class="hljs-property">@hasAssignments</span> = <span class="hljs-literal">yes</span></pre></div></div>
    337. 

  337.             
    338. 

  338.         </li>
    339. 

  339.         
    340. 

  340.         
    341. 

  341.         <li id="section-13">
    342. 

  342.             <div class="annotation">
    343. 

  343.               
    344. 

  344.               <div class="pilwrap ">
    345. 

  345.                 <a class="pilcrow" href="#section-13">&#182;</a>
    346. 

  346.               </div>
    347. 

  347.               <p>Does this scope have any declared variables?</p>
    348. 

  348. 

  349.             </div>
    350. 

  350.             
    351. 

  351.             <div class="content"><div class='highlight'><pre>  <span class="hljs-attribute">hasDeclarations</span>:<span class="hljs-function"> -&gt;</span>
    352. 

  352.     !!<span class="hljs-property">@declaredVariables</span>().length</pre></div></div>
    353. 

  353.             
    354. 

  354.         </li>
    355. 

  355.         
    356. 

  356.         
    357. 

  357.         <li id="section-14">
    358. 

  358.             <div class="annotation">
    359. 

  359.               
    360. 

  360.               <div class="pilwrap ">
    361. 

  361.                 <a class="pilcrow" href="#section-14">&#182;</a>
    362. 

  362.               </div>
    363. 

  363.               <p>Return the list of variables first declared in this scope.</p>
    364. 

  364. 

  365.             </div>
    366. 

  366.             
    367. 

  367.             <div class="content"><div class='highlight'><pre>  <span class="hljs-attribute">declaredVariables</span>:<span class="hljs-function"> -&gt;</span>
    368. 

  368.     (v.name <span class="hljs-keyword">for</span> v <span class="hljs-keyword">in</span> <span class="hljs-property">@variables</span> <span class="hljs-keyword">when</span> v.type <span class="hljs-keyword">is</span> <span class="hljs-string">'var'</span>).sort()</pre></div></div>
    369. 

  369.             
    370. 

  370.         </li>
    371. 

  371.         
    372. 

  372.         
    373. 

  373.         <li id="section-15">
    374. 

  374.             <div class="annotation">
    375. 

  375.               
    376. 

  376.               <div class="pilwrap ">
    377. 

  377.                 <a class="pilcrow" href="#section-15">&#182;</a>
    378. 

  378.               </div>
    379. 

  379.               <p>Return the list of assignments that are supposed to be made at the top
    380. 

  380. of this scope.</p>
    381. 

  381. 

  382.             </div>
    383. 

  383.             
    384. 

  384.             <div class="content"><div class='highlight'><pre>  <span class="hljs-attribute">assignedVariables</span>:<span class="hljs-function"> -&gt;</span>
    385. 

  385.     <span class="hljs-string">"<span class="hljs-subst">#{v.name}</span> = <span class="hljs-subst">#{v.type.value}</span>"</span> <span class="hljs-keyword">for</span> v <span class="hljs-keyword">in</span> <span class="hljs-property">@variables</span> <span class="hljs-keyword">when</span> v.type.assigned</pre></div></div>
    386. 

  386.             
    387. 

  387.         </li>
    388. 

  388.         
    389. 

  389.     </ul>
    390. 

  390.   </div>
    391. 

  391. </body>
    392. 

  392. </html>
    393.