PageRenderTime 171ms CodeModel.GetById 20ms RepoModel.GetById 28ms app.codeStats 0ms

/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. <html>
  3. <head>
  4. <title>cake.coffee</title>
  5. <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  6. <meta name="viewport" content="width=device-width, target-densitydpi=160dpi, initial-scale=1.0; maximum-scale=1.0; user-scalable=0;">
  7. <link rel="stylesheet" media="all" href="docco.css" />
  8. </head>
  9. <body>
  10. <div id="container">
  11. <div id="background"></div>
  12. <ul id="jump_to">
  13. <li>
  14. <a class="large" href="javascript:void(0);">Jump To &hellip;</a>
  15. <a class="small" href="javascript:void(0);">+</a>
  16. <div id="jump_wrapper">
  17. <div id="jump_page_wrapper">
  18. <div id="jump_page">
  19. <a class="source" href="browser.html">
  20. browser.coffee
  21. </a>
  22. <a class="source" href="cake.html">
  23. cake.coffee
  24. </a>
  25. <a class="source" href="coffee-script.html">
  26. coffee-script.coffee
  27. </a>
  28. <a class="source" href="command.html">
  29. command.coffee
  30. </a>
  31. <a class="source" href="grammar.html">
  32. grammar.coffee
  33. </a>
  34. <a class="source" href="helpers.html">
  35. helpers.coffee
  36. </a>
  37. <a class="source" href="index.html">
  38. index.coffee
  39. </a>
  40. <a class="source" href="lexer.html">
  41. lexer.coffee
  42. </a>
  43. <a class="source" href="nodes.html">
  44. nodes.coffee
  45. </a>
  46. <a class="source" href="optparse.html">
  47. optparse.coffee
  48. </a>
  49. <a class="source" href="register.html">
  50. register.coffee
  51. </a>
  52. <a class="source" href="repl.html">
  53. repl.coffee
  54. </a>
  55. <a class="source" href="rewriter.html">
  56. rewriter.coffee
  57. </a>
  58. <a class="source" href="scope.html">
  59. scope.litcoffee
  60. </a>
  61. <a class="source" href="sourcemap.html">
  62. sourcemap.litcoffee
  63. </a>
  64. </div>
  65. </div>
  66. </li>
  67. </ul>
  68. <ul class="sections">
  69. <li id="title">
  70. <div class="annotation">
  71. <h1>cake.coffee</h1>
  72. </div>
  73. </li>
  74. <li id="section-1">
  75. <div class="annotation">
  76. <div class="pilwrap ">
  77. <a class="pilcrow" href="#section-1">&#182;</a>
  78. </div>
  79. <p><code>cake</code> is a simplified version of <a href="http://www.gnu.org/software/make/">Make</a>
  80. (<a href="http://rake.rubyforge.org/">Rake</a>, <a href="http://github.com/280north/jake">Jake</a>)
  81. for CoffeeScript. You define tasks with names and descriptions in a Cakefile,
  82. and can call them from the command line, or invoke them from other tasks.</p>
  83. <p>Running <code>cake</code> with no arguments will print out a list of all the tasks in the
  84. current directorys Cakefile.</p>
  85. </div>
  86. </li>
  87. <li id="section-2">
  88. <div class="annotation">
  89. <div class="pilwrap ">
  90. <a class="pilcrow" href="#section-2">&#182;</a>
  91. </div>
  92. <p>External dependencies.</p>
  93. </div>
  94. <div class="content"><div class='highlight'><pre>fs = <span class="hljs-built_in">require</span> <span class="hljs-string">'fs'</span>
  95. path = <span class="hljs-built_in">require</span> <span class="hljs-string">'path'</span>
  96. helpers = <span class="hljs-built_in">require</span> <span class="hljs-string">'./helpers'</span>
  97. optparse = <span class="hljs-built_in">require</span> <span class="hljs-string">'./optparse'</span>
  98. CoffeeScript = <span class="hljs-built_in">require</span> <span class="hljs-string">'./coffee-script'</span></pre></div></div>
  99. </li>
  100. <li id="section-3">
  101. <div class="annotation">
  102. <div class="pilwrap ">
  103. <a class="pilcrow" href="#section-3">&#182;</a>
  104. </div>
  105. <p>Register .coffee extension</p>
  106. </div>
  107. <div class="content"><div class='highlight'><pre>CoffeeScript.register()</pre></div></div>
  108. </li>
  109. <li id="section-4">
  110. <div class="annotation">
  111. <div class="pilwrap ">
  112. <a class="pilcrow" href="#section-4">&#182;</a>
  113. </div>
  114. <p>Keep track of the list of defined tasks, the accepted options, and so on.</p>
  115. </div>
  116. <div class="content"><div class='highlight'><pre>tasks = {}
  117. options = {}
  118. switches = []
  119. oparse = <span class="hljs-literal">null</span></pre></div></div>
  120. </li>
  121. <li id="section-5">
  122. <div class="annotation">
  123. <div class="pilwrap ">
  124. <a class="pilcrow" href="#section-5">&#182;</a>
  125. </div>
  126. <p>Mixin the top-level Cake functions for Cakefiles to use directly.</p>
  127. </div>
  128. <div class="content"><div class='highlight'><pre>helpers.extend <span class="hljs-built_in">global</span>,</pre></div></div>
  129. </li>
  130. <li id="section-6">
  131. <div class="annotation">
  132. <div class="pilwrap ">
  133. <a class="pilcrow" href="#section-6">&#182;</a>
  134. </div>
  135. <p>Define a Cake task with a short name, an optional sentence description,
  136. and the function to run as the action itself.</p>
  137. </div>
  138. <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>
  139. [action, description] = [description, action] <span class="hljs-keyword">unless</span> action
  140. tasks[name] = {name, description, action}</pre></div></div>
  141. </li>
  142. <li id="section-7">
  143. <div class="annotation">
  144. <div class="pilwrap ">
  145. <a class="pilcrow" href="#section-7">&#182;</a>
  146. </div>
  147. <p>Define an option that the Cakefile accepts. The parsed options hash,
  148. containing all of the command-line options passed, will be made available
  149. as the first argument to the action.</p>
  150. </div>
  151. <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>
  152. switches.push [letter, flag, description]</pre></div></div>
  153. </li>
  154. <li id="section-8">
  155. <div class="annotation">
  156. <div class="pilwrap ">
  157. <a class="pilcrow" href="#section-8">&#182;</a>
  158. </div>
  159. <p>Invoke another task in the current Cakefile.</p>
  160. </div>
  161. <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>
  162. missingTask name <span class="hljs-keyword">unless</span> tasks[name]
  163. tasks[name].action options</pre></div></div>
  164. </li>
  165. <li id="section-9">
  166. <div class="annotation">
  167. <div class="pilwrap ">
  168. <a class="pilcrow" href="#section-9">&#182;</a>
  169. </div>
  170. <p>Run <code>cake</code>. Executes all of the tasks you pass, in order. Note that Nodes
  171. asynchrony may cause tasks to execute in a different order than youd expect.
  172. If no tasks are passed, print the help screen. Keep a reference to the
  173. original directory name, when running Cake tasks from subdirectories.</p>
  174. </div>
  175. <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>
  176. <span class="hljs-built_in">global</span>.__originalDirname = fs.realpathSync <span class="hljs-string">'.'</span>
  177. process.chdir cakefileDirectory __originalDirname
  178. args = process.argv[<span class="hljs-number">2.</span>.]
  179. CoffeeScript.run fs.readFileSync(<span class="hljs-string">'Cakefile'</span>).toString(), <span class="hljs-attribute">filename</span>: <span class="hljs-string">'Cakefile'</span>
  180. oparse = <span class="hljs-keyword">new</span> optparse.OptionParser switches
  181. <span class="hljs-keyword">return</span> printTasks() <span class="hljs-keyword">unless</span> args.length
  182. <span class="hljs-keyword">try</span>
  183. options = oparse.parse(args)
  184. <span class="hljs-keyword">catch</span> e
  185. <span class="hljs-keyword">return</span> fatalError <span class="hljs-string">"<span class="hljs-subst">#{e}</span>"</span>
  186. invoke arg <span class="hljs-keyword">for</span> arg <span class="hljs-keyword">in</span> options.arguments</pre></div></div>
  187. </li>
  188. <li id="section-10">
  189. <div class="annotation">
  190. <div class="pilwrap ">
  191. <a class="pilcrow" href="#section-10">&#182;</a>
  192. </div>
  193. <p>Display the list of Cake tasks in a format similar to <code>rake -T</code></p>
  194. </div>
  195. <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">printTasks</span> = -&gt;</span>
  196. relative = path.relative <span class="hljs-keyword">or</span> path.resolve
  197. cakefilePath = path.join relative(__originalDirname, process.cwd()), <span class="hljs-string">'Cakefile'</span>
  198. <span class="hljs-built_in">console</span>.log <span class="hljs-string">"<span class="hljs-subst">#{cakefilePath}</span> defines the following tasks:\n"</span>
  199. <span class="hljs-keyword">for</span> name, task <span class="hljs-keyword">of</span> tasks
  200. spaces = <span class="hljs-number">20</span> - name.length
  201. 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>
  202. 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>
  203. <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>
  204. <span class="hljs-built_in">console</span>.log oparse.help() <span class="hljs-keyword">if</span> switches.length</pre></div></div>
  205. </li>
  206. <li id="section-11">
  207. <div class="annotation">
  208. <div class="pilwrap ">
  209. <a class="pilcrow" href="#section-11">&#182;</a>
  210. </div>
  211. <p>Print an error and exit when attempting to use an invalid task/option.</p>
  212. </div>
  213. <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>
  214. <span class="hljs-built_in">console</span>.error message + <span class="hljs-string">'\n'</span>
  215. <span class="hljs-built_in">console</span>.log <span class="hljs-string">'To see a list of all tasks/options, run "cake"'</span>
  216. process.exit <span class="hljs-number">1</span>
  217. <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>
  218. </li>
  219. <li id="section-12">
  220. <div class="annotation">
  221. <div class="pilwrap ">
  222. <a class="pilcrow" href="#section-12">&#182;</a>
  223. </div>
  224. <p>When <code>cake</code> is invoked, search in the current and all parent directories
  225. to find the relevant Cakefile.</p>
  226. </div>
  227. <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>
  228. <span class="hljs-keyword">return</span> dir <span class="hljs-keyword">if</span> fs.existsSync path.join dir, <span class="hljs-string">'Cakefile'</span>
  229. parent = path.normalize path.join dir, <span class="hljs-string">'..'</span>
  230. <span class="hljs-keyword">return</span> cakefileDirectory parent <span class="hljs-keyword">unless</span> parent <span class="hljs-keyword">is</span> dir
  231. <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>
  232. </li>
  233. </ul>
  234. </div>
  235. </body>
  236. </html>