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