/documentation/docs/cake.html

http://github.com/jashkenas/coffee-script · HTML · 345 lines · 236 code · 109 blank · 0 comment · 0 complexity · eb5069a6be1dbbb53346480e541dd843 MD5 · raw file 

    

  1. <!DOCTYPE html>
    2. 

  2. 

  3. <html>
    4. 

  4. <head>
    5. 

  5.   <title>cake.coffee</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>cake.coffee</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><code>cake</code> is a simplified version of <a href="http://www.gnu.org/software/make/">Make</a>
    119. 

  119. (<a href="http://rake.rubyforge.org/">Rake</a>, <a href="http://github.com/280north/jake">Jake</a>)
    120. 

  120. for CoffeeScript. You define tasks with names and descriptions in a Cakefile,
    121. 

  121. and can call them from the command line, or invoke them from other tasks.</p>
    122. 

  122. <p>Running <code>cake</code> with no arguments will print out a list of all the tasks in the
    123. 

  123. current directory’s Cakefile.</p>
    124. 

  124. 

  125.             </div>
    126. 

  126.             
    127. 

  127.         </li>
    128. 

  128.         
    129. 

  129.         
    130. 

  130.         <li id="section-2">
    131. 

  131.             <div class="annotation">
    132. 

  132.               
    133. 

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

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

  135.               </div>
    136. 

  136.               <p>External dependencies.</p>
    137. 

  137. 

  138.             </div>
    139. 

  139.             
    140. 

  140.             <div class="content"><div class='highlight'><pre>fs           = <span class="hljs-built_in">require</span> <span class="hljs-string">'fs'</span>
    141. 

  141. path         = <span class="hljs-built_in">require</span> <span class="hljs-string">'path'</span>
    142. 

  142. helpers      = <span class="hljs-built_in">require</span> <span class="hljs-string">'./helpers'</span>
    143. 

  143. optparse     = <span class="hljs-built_in">require</span> <span class="hljs-string">'./optparse'</span>
    144. 

  144. CoffeeScript = <span class="hljs-built_in">require</span> <span class="hljs-string">'./coffee-script'</span></pre></div></div>
    145. 

  145.             
    146. 

  146.         </li>
    147. 

  147.         
    148. 

  148.         
    149. 

  149.         <li id="section-3">
    150. 

  150.             <div class="annotation">
    151. 

  151.               
    152. 

  152.               <div class="pilwrap ">
    153. 

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

  154.               </div>
    155. 

  155.               <p>Register .coffee extension</p>
    156. 

  156. 

  157.             </div>
    158. 

  158.             
    159. 

  159.             <div class="content"><div class='highlight'><pre>CoffeeScript.register()</pre></div></div>
    160. 

  160.             
    161. 

  161.         </li>
    162. 

  162.         
    163. 

  163.         
    164. 

  164.         <li id="section-4">
    165. 

  165.             <div class="annotation">
    166. 

  166.               
    167. 

  167.               <div class="pilwrap ">
    168. 

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

  169.               </div>
    170. 

  170.               <p>Keep track of the list of defined tasks, the accepted options, and so on.</p>
    171. 

  171. 

  172.             </div>
    173. 

  173.             
    174. 

  174.             <div class="content"><div class='highlight'><pre>tasks     = {}
    175. 

  175. options   = {}
    176. 

  176. switches  = []
    177. 

  177. oparse    = <span class="hljs-literal">null</span></pre></div></div>
    178. 

  178.             
    179. 

  179.         </li>
    180. 

  180.         
    181. 

  181.         
    182. 

  182.         <li id="section-5">
    183. 

  183.             <div class="annotation">
    184. 

  184.               
    185. 

  185.               <div class="pilwrap ">
    186. 

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

  187.               </div>
    188. 

  188.               <p>Mixin the top-level Cake functions for Cakefiles to use directly.</p>
    189. 

  189. 

  190.             </div>
    191. 

  191.             
    192. 

  192.             <div class="content"><div class='highlight'><pre>helpers.extend <span class="hljs-built_in">global</span>,</pre></div></div>
    193. 

  193.             
    194. 

  194.         </li>
    195. 

  195.         
    196. 

  196.         
    197. 

  197.         <li id="section-6">
    198. 

  198.             <div class="annotation">
    199. 

  199.               
    200. 

  200.               <div class="pilwrap ">
    201. 

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

  202.               </div>
    203. 

  203.               <p>Define a Cake task with a short name, an optional sentence description,
    204. 

  204. and the function to run as the action itself.</p>
    205. 

  205. 

  206.             </div>
    207. 

  207.             
    208. 

  208.             <div class="content"><div class='highlight'><pre>  <span class="hljs-attribute">task</span>: <span class="hljs-function"><span class="hljs-params">(name, description, action)</span> -&gt;</span>
    209. 

  209.     [action, description] = [description, action] <span class="hljs-keyword">unless</span> action
    210. 

  210.     tasks[name] = {name, description, action}</pre></div></div>
    211. 

  211.             
    212. 

  212.         </li>
    213. 

  213.         
    214. 

  214.         
    215. 

  215.         <li id="section-7">
    216. 

  216.             <div class="annotation">
    217. 

  217.               
    218. 

  218.               <div class="pilwrap ">
    219. 

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

  220.               </div>
    221. 

  221.               <p>Define an option that the Cakefile accepts. The parsed options hash,
    222. 

  222. containing all of the command-line options passed, will be made available
    223. 

  223. as the first argument to the action.</p>
    224. 

  224. 

  225.             </div>
    226. 

  226.             
    227. 

  227.             <div class="content"><div class='highlight'><pre>  <span class="hljs-attribute">option</span>: <span class="hljs-function"><span class="hljs-params">(letter, flag, description)</span> -&gt;</span>
    228. 

  228.     switches.push [letter, flag, description]</pre></div></div>
    229. 

  229.             
    230. 

  230.         </li>
    231. 

  231.         
    232. 

  232.         
    233. 

  233.         <li id="section-8">
    234. 

  234.             <div class="annotation">
    235. 

  235.               
    236. 

  236.               <div class="pilwrap ">
    237. 

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

  238.               </div>
    239. 

  239.               <p>Invoke another task in the current Cakefile.</p>
    240. 

  240. 

  241.             </div>
    242. 

  242.             
    243. 

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

  244.     missingTask name <span class="hljs-keyword">unless</span> tasks[name]
    245. 

  245.     tasks[name].action options</pre></div></div>
    246. 

  246.             
    247. 

  247.         </li>
    248. 

  248.         
    249. 

  249.         
    250. 

  250.         <li id="section-9">
    251. 

  251.             <div class="annotation">
    252. 

  252.               
    253. 

  253.               <div class="pilwrap ">
    254. 

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

  255.               </div>
    256. 

  256.               <p>Run <code>cake</code>. Executes all of the tasks you pass, in order. Note that Node’s
    257. 

  257. asynchrony may cause tasks to execute in a different order than you’d expect.
    258. 

  258. If no tasks are passed, print the help screen. Keep a reference to the
    259. 

  259. original directory name, when running Cake tasks from subdirectories.</p>
    260. 

  260. 

  261.             </div>
    262. 

  262.             
    263. 

  263.             <div class="content"><div class='highlight'><pre><span class="hljs-built_in">exports</span>.<span class="hljs-function"><span class="hljs-title">run</span> = -&gt;</span>
    264. 

  264.   <span class="hljs-built_in">global</span>.__originalDirname = fs.realpathSync <span class="hljs-string">'.'</span>
    265. 

  265.   process.chdir cakefileDirectory __originalDirname
    266. 

  266.   args = process.argv[<span class="hljs-number">2.</span>.]
    267. 

  267.   CoffeeScript.run fs.readFileSync(<span class="hljs-string">'Cakefile'</span>).toString(), <span class="hljs-attribute">filename</span>: <span class="hljs-string">'Cakefile'</span>
    268. 

  268.   oparse = <span class="hljs-keyword">new</span> optparse.OptionParser switches
    269. 

  269.   <span class="hljs-keyword">return</span> printTasks() <span class="hljs-keyword">unless</span> args.length
    270. 

  270.   <span class="hljs-keyword">try</span>
    271. 

  271.     options = oparse.parse(args)
    272. 

  272.   <span class="hljs-keyword">catch</span> e
    273. 

  273.     <span class="hljs-keyword">return</span> fatalError <span class="hljs-string">"<span class="hljs-subst">#{e}</span>"</span>
    274. 

  274.   invoke arg <span class="hljs-keyword">for</span> arg <span class="hljs-keyword">in</span> options.arguments</pre></div></div>
    275. 

  275.             
    276. 

  276.         </li>
    277. 

  277.         
    278. 

  278.         
    279. 

  279.         <li id="section-10">
    280. 

  280.             <div class="annotation">
    281. 

  281.               
    282. 

  282.               <div class="pilwrap ">
    283. 

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

  284.               </div>
    285. 

  285.               <p>Display the list of Cake tasks in a format similar to <code>rake -T</code></p>
    286. 

  286. 

  287.             </div>
    288. 

  288.             
    289. 

  289.             <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">printTasks</span> = -&gt;</span>
    290. 

  290.   relative = path.relative <span class="hljs-keyword">or</span> path.resolve
    291. 

  291.   cakefilePath = path.join relative(__originalDirname, process.cwd()), <span class="hljs-string">'Cakefile'</span>
    292. 

  292.   <span class="hljs-built_in">console</span>.log <span class="hljs-string">"<span class="hljs-subst">#{cakefilePath}</span> defines the following tasks:\n"</span>
    293. 

  293.   <span class="hljs-keyword">for</span> name, task <span class="hljs-keyword">of</span> tasks
    294. 

  294.     spaces = <span class="hljs-number">20</span> - name.length
    295. 

  295.     spaces = <span class="hljs-keyword">if</span> spaces &gt; <span class="hljs-number">0</span> <span class="hljs-keyword">then</span> Array(spaces + <span class="hljs-number">1</span>).join(<span class="hljs-string">' '</span>) <span class="hljs-keyword">else</span> <span class="hljs-string">''</span>
    296. 

  296.     desc   = <span class="hljs-keyword">if</span> task.description <span class="hljs-keyword">then</span> <span class="hljs-string">"# <span class="hljs-subst">#{task.description}</span>"</span> <span class="hljs-keyword">else</span> <span class="hljs-string">''</span>
    297. 

  297.     <span class="hljs-built_in">console</span>.log <span class="hljs-string">"cake <span class="hljs-subst">#{name}</span><span class="hljs-subst">#{spaces}</span> <span class="hljs-subst">#{desc}</span>"</span>
    298. 

  298.   <span class="hljs-built_in">console</span>.log oparse.help() <span class="hljs-keyword">if</span> switches.length</pre></div></div>
    299. 

  299.             
    300. 

  300.         </li>
    301. 

  301.         
    302. 

  302.         
    303. 

  303.         <li id="section-11">
    304. 

  304.             <div class="annotation">
    305. 

  305.               
    306. 

  306.               <div class="pilwrap ">
    307. 

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

  308.               </div>
    309. 

  309.               <p>Print an error and exit when attempting to use an invalid task/option.</p>
    310. 

  310. 

  311.             </div>
    312. 

  312.             
    313. 

  313.             <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">fatalError</span> = <span class="hljs-params">(message)</span> -&gt;</span>
    314. 

  314.   <span class="hljs-built_in">console</span>.error message + <span class="hljs-string">'\n'</span>
    315. 

  315.   <span class="hljs-built_in">console</span>.log <span class="hljs-string">'To see a list of all tasks/options, run "cake"'</span>
    316. 

  316.   process.exit <span class="hljs-number">1</span>
    317. 

  317. 

  318. <span class="hljs-function"><span class="hljs-title">missingTask</span> = <span class="hljs-params">(task)</span> -&gt;</span> fatalError <span class="hljs-string">"No such task: <span class="hljs-subst">#{task}</span>"</span></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>When <code>cake</code> is invoked, search in the current and all parent directories
    330. 

  330. to find the relevant Cakefile.</p>
    331. 

  331. 

  332.             </div>
    333. 

  333.             
    334. 

  334.             <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">cakefileDirectory</span> = <span class="hljs-params">(dir)</span> -&gt;</span>
    335. 

  335.   <span class="hljs-keyword">return</span> dir <span class="hljs-keyword">if</span> fs.existsSync path.join dir, <span class="hljs-string">'Cakefile'</span>
    336. 

  336.   parent = path.normalize path.join dir, <span class="hljs-string">'..'</span>
    337. 

  337.   <span class="hljs-keyword">return</span> cakefileDirectory parent <span class="hljs-keyword">unless</span> parent <span class="hljs-keyword">is</span> dir
    338. 

  338.   <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> Error <span class="hljs-string">"Cakefile not found in <span class="hljs-subst">#{process.cwd()}</span>"</span></pre></div></div>
    339. 

  339.             
    340. 

  340.         </li>
    341. 

  341.         
    342. 

  342.     </ul>
    343. 

  343.   </div>
    344. 

  344. </body>
    345. 

  345. </html>
    346.