coffeescript

<!DOCTYPE html> <html> <head> <meta http-equiv="content-type" content="text/html;charset=UTF-8" /> <title>CoffeeScript</title> <link rel="stylesheet" type="text/css" href="documentation/css/docs.css" /> <link rel="stylesheet" type="text/css" href="documentation/css/idle.css" /> <link rel="shortcut icon" href="documentation/images/favicon.ico" /> </head> <body class="minimized"> <div id="fadeout"></div> <div id="flybar"> <a id="logo" href="#top"> </a> <div class="navigation toc"> <div class="button"> Table of Contents </div> <div class="contents"> <a href="#overview">Mini Overview</a> <a href="#installation">Installation and Usage</a> <a href="#language">Language Reference</a> <a href="#whitespace">Significant Whitespace</a> <a href="#functions">Functions and Invocation</a> <a href="#objects_and_arrays">Objects and Arrays</a> <a href="#lexical_scope">Lexical Scoping and Variable Safety</a> <a href="#conditionals">If, Else, Unless, and Conditional Assignment</a> <a href="#aliases">Aliases</a> <a href="#splats">Splats...</a> <a href="#while">While, Until, and Loop</a> <a href="#comprehensions">Comprehensions (Arrays, Objects, and Ranges)</a> <a href="#slice_splice">Array Slicing and Splicing with Ranges</a> <a href="#expressions">Everything is an Expression</a> <a href="#existence">The Existential Operator</a> <a href="#classes">Classes, Inheritance, and Super</a> <a href="#pattern_matching">Pattern Matching</a> <a href="#fat_arrow">Function Binding</a> <a href="#embedded">Embedded JavaScript</a> <a href="#switch">Switch/When/Else</a> <a href="#try">Try/Catch/Finally</a> <a href="#comparisons">Chained Comparisons</a> <a href="#interpolation">String and RegExp Interpolation</a> <a href="#heredocs">Multiline Strings, Heredocs, and Block Comments</a> <a href="#cake">Cake, and Cakefiles</a> <a href="#scripts">"text/coffeescript" Script Tags</a> <a href="#resources">Resources</a> <a href="#webchat">Web Chat (IRC)</a> <a href="#change_log">Change Log</a> </div> </div> <div class="navigation try"> <div class="button"> Try CoffeeScript </div> <div class="contents repl_wrapper"> <div class="code"> <div id="repl_source_wrap"><textarea id="repl_source">reverse = (string) -> string.split('').reverse().join '' alert reverse '.eeffoC yrT'</textarea></div> <pre id="repl_results"></pre> <button class="full_screen">go full screen</button> <button class="minimize">minimize</button> <button class="run">run</button> </div> </div> </div> <div class="navigation annotated"> <div class="button"> Annotated Source </div> <div class="contents"> <a href="documentation/docs/grammar.html">Grammar Rules — src/grammar</a> <a href="documentation/docs/lexer.html">Lexing Tokens — src/lexer</a> <a href="documentation/docs/rewriter.html">The Rewriter — src/rewriter</a> <a href="documentation/docs/nodes.html">The Syntax Tree — src/nodes</a> <a href="documentation/docs/scope.html">Lexical Scope — src/scope</a> <a href="documentation/docs/helpers.html">Helpers & Utility Functions — src/helpers</a> <a href="documentation/docs/coffee-script.html">The CoffeeScript Module — src/coffee-script</a> <a href="documentation/docs/cake.html">Cake & Cakefiles — src/cake</a> <a href="documentation/docs/command.html">"coffee" Command-Line Utility — src/command</a> <a href="documentation/docs/optparse.html">Option Parsing — src/optparse</a> <a href="documentation/docs/repl.html">Interactive REPL — src/repl</a> </div> </div> <div id="error" style="display:none;"></div> </div> <div class="container"> CoffeeScript is a little language that compiles into JavaScript. Think of it as JavaScript's less ostentatious kid brother — the same genes, roughly the same height, but a different sense of style. Apart from a handful of bonus goodies, statements in CoffeeScript correspond one-to-one with their equivalent in JavaScript, it's just another way of saying it. Disclaimer: CoffeeScript is just for fun. Until it reaches 1.0, there are no guarantees that the syntax won't change between versions. That said, it compiles into clean JavaScript (the good parts) that can use existing JavaScript libraries seamlessly, and passes through <a href="http://www.jslint.com/">JSLint</a> without warnings. The compiled output is pretty-printed and quite readable. Latest Version: <a href="http://github.com/jashkenas/coffee-script/tarball/0.9.0">0.9.0</a> <h2> Mini Overview </h2> CoffeeScript on the left, compiled JavaScript output on the right. <div class='code'><pre class="idle"># Assignment: number = 42 opposite = true # Conditions: number = -42 if opposite # Functions: square = (x) -> x * x # Arrays: list = [1, 2, 3, 4, 5] # Objects: math = root: Math.sqrt square: square cube: (x) -> x * square x # Splats: race = (winner, runners...) -> print winner, runners # Existence: alert "I knew it!" if elvis? # Array comprehensions: cubes = math.cube num for num in list </pre><pre class="idle">var _a, _b, _c, _d, cubes, list, math, num, number, opposite, race, square; var __slice = Array.prototype.slice; number = 42; opposite = true; if (opposite) { number = -42; } square = function(x) { return x * x; }; list = [1, 2, 3, 4, 5]; math = { root: Math.sqrt, square: square, cube: function(x) { return x * square(x); } }; race = function(winner) { var runners; runners = __slice.call(arguments, 1); return print(winner, runners); }; if (typeof elvis !== "undefined" && elvis !== null) { alert("I knew it!"); } cubes = (function() { _a = []; _c = list; for (_b = 0, _d = _c.length; _b < _d; _b++) { num = _c[_b]; _a.push(math.cube(num)); } return _a; })(); </pre><button onclick='javascript: var _a, _b, _c, _d, cubes, list, math, num, number, opposite, race, square; var __slice = Array.prototype.slice; number = 42; opposite = true; if (opposite) { number = -42; } square = function(x) { return x * x; }; list = [1, 2, 3, 4, 5]; math = { root: Math.sqrt, square: square, cube: function(x) { return x * square(x); } }; race = function(winner) { var runners; runners = __slice.call(arguments, 1); return print(winner, runners); }; if (typeof elvis !== "undefined" && elvis !== null) { alert("I knew it!"); } cubes = (function() { _a = []; _c = list; for (_b = 0, _d = _c.length; _b < _d; _b++) { num = _c[_b]; _a.push(math.cube(num)); } return _a; })();;alert(cubes);'>run: cubes</button> </div> For a longer CoffeeScript example, check out <a href="documentation/docs/underscore.html">Underscore.coffee</a>, a port of the <a href="http://documentcloud.github.com/underscore/">Underscore.js</a> library of helper functions. Underscore.coffee can pass the entire Underscore.js test suite. The CoffeeScript version is faster than the original for a number of methods (in general, due to the speed of CoffeeScript's array comprehensions), and after being minified and gzipped, is only 241 bytes larger than the original JavaScript version. Additional examples are included in the source repository, inside the <a href="http://github.com/jashkenas/coffee-script/tree/master/examples/">examples</a> folder. <h2> Installation and Usage </h2> The CoffeeScript compiler is written in pure CoffeeScript, using a <a href="documentation/docs/grammar.html">small DSL</a> on top of the <a href="http://github.com/zaach/jison">Jison parser generator</a>, and is available as a <a href="http://nodejs.org/">Node.js</a> utility. The core compiler however, does not depend on Node, and can be run in other server-side-JavaScript environments, or in the browser (see "Try CoffeeScript", above). To install, first make sure you have a working copy of the latest tagged version of <a href="http://nodejs.org/">Node.js</a>, currently 0.1.102 or higher. Then clone the CoffeeScript <a href="http://github.com/jashkenas/coffee-script">source repository</a> from GitHub, or download the latest release: <a href="http://github.com/jashkenas/coffee-script/tarball/0.9.0">0.9.0</a>. To install the CoffeeScript compiler system-wide under <tt>/usr/local</tt>, open the directory and run: <pre> sudo bin/cake install</pre> Alternatively, if you already have the <a href="http://npmjs.org/">Node Package Manager</a> installed, you can use that to grab the latest CoffeeScript: <pre> sudo npm install coffee-script</pre> Both of these provide the <tt>coffee</tt> command, which will execute CoffeeScripts under Node.js by default, but is also used to compile CoffeeScript <tt>.coffee</tt> files into JavaScript, or to run an an interactive REPL. When compiling to JavaScript, <tt>coffee</tt> writes the output as <tt>.js</tt> files in the same directory by default, but output can be customized with the following options: <table> <tr> <td><code>-c, --compile</code></td> <td> Compile a <tt>.coffee</tt> script into a <tt>.js</tt> JavaScript file of the same name. </td> </tr> <tr> <td width="25%"><code>-i, --interactive</code></td> <td> Launch an interactive CoffeeScript session to try short snippets. More pleasant if wrapped with <a href="http://utopia.knoware.nl/~hlub/uck/rlwrap/rlwrap.html">rlwrap</a>. </td> </tr> <tr> <td><code>-o, --output [DIR]</code></td> <td> Write out all compiled JavaScript files into the specified directory. Use in conjunction with <tt>--compile</tt> or <tt>--watch</tt>. </td> </tr> <tr> <td><code>-w, --watch</code></td> <td> Watch the modification times of the coffee-scripts, recompiling as soon as a change occurs. </td> </tr> <tr> <td><code>-p, --print</code></td> <td> Instead of writing out the JavaScript as a file, print it directly to stdout. </td> </tr> <tr> <td><code>-l, --lint</code></td> <td> If the <tt>jsl</tt> (<a href="http://www.javascriptlint.com/">JavaScript Lint</a>) command is installed, use it to check the compilation of a CoffeeScript file. (Handy in conjunction with <tt>--watch</tt>) </td> </tr> <tr> <td><code>-s, --stdio</code></td> <td> Pipe in CoffeeScript to STDIN and get back JavaScript over STDOUT. Good for use with processes written in other languages. An example: <tt>cat src/cake.coffee | coffee -sc</tt> </td> </tr> <tr> <td><code>-e, --eval</code></td> <td> Compile and print a little snippet of CoffeeScript directly from the command line. For example: <tt>coffee -e "puts num for num in [10..1]"</tt> </td> </tr> <tr> <td><code>--no-wrap</code></td> <td> Compile the JavaScript without the top-level function safety wrapper. (Used for CoffeeScript as a Node.js module.) </td> </tr> <tr> <td><code>-t, --tokens</code></td> <td> Instead of parsing the CoffeeScript, just lex it, and print out the token stream: <tt>[IDENTIFIER square] [ASSIGN =] [PARAM_START (]</tt> ... </td> </tr> <tr> <td><code>-n, --nodes</code></td> <td> Instead of compiling the CoffeeScript, just lex and parse it, and print out the parse tree: <pre class="no_bar"> Expressions Assign Value "square" Code "x" Op * Value "x" Value "x"</pre> </td> </tr> </table> Examples: <pre> coffee -c path/to/script.coffee coffee --interactive coffee --watch --lint experimental.coffee coffee --print app/scripts/*.coffee > concatenation.js</pre> <h2> Language Reference </h2> This reference is structured so that it can be read from top to bottom, if you like. Later sections use ideas and syntax previously introduced. Familiarity with JavaScript is assumed. In all of the following examples, the source CoffeeScript is provided on the left, and the direct compilation into JavaScript is on the right. Many of the examples can be run (where it makes sense) by pressing the "run" button towards the bottom right. You can also paste examples into "Try CoffeeScript" in the toolbar, and play with them from there. Significant Whitespace CoffeeScript uses Python-style significant whitespace: You don't need to use semicolons <tt>;</tt> to terminate expressions, ending the line will do just as well. Semicolons can still be used to fit multiple expressions onto a single line. Instead of using curly braces <tt>{ }</tt> to delimit blocks of code (like <a href="#functions">functions</a>, <a href="#conditionals">if-statements</a>, <a href="#switch">switch</a>, and <a href="#try">try/catch</a>), use indentation. You don't need to use parentheses to invoke a function if you're passing arguments: <tt>print "coffee"</tt>. Implicit parentheses wrap forwards to the end of the line, or block expression. You can use newlines to break up your expression into smaller pieces, as long as CoffeeScript can determine that the line hasn't finished yet, because it ends with an operator or a dot ... seen most commonly in jQuery-chaining style JavaScript. Functions and Invocation Functions are defined by a list of parameters, an arrow, and the function body. The empty function looks like this: <tt>-></tt> <div class='code'><pre class="idle">square = (x) -> x * x cube = (x) -> square(x) * x </pre><pre class="idle">var cube, square; square = function(x) { return x * x; }; cube = function(x) { return square(x) * x; }; </pre><button onclick='javascript: var cube, square; square = function(x) { return x * x; }; cube = function(x) { return square(x) * x; };;alert(cube(5));'>run: cube(5)</button> </div> Objects and Arrays Object and Array literals look very similar to their JavaScript cousins. When you spread out each property on a separate line, the commas are optional. Implicit objects may be created with indentation instead of brackets, winding up looking quite similar to YAML. <div class='code'><pre class="idle">song = ["do", "re", "mi", "fa", "so"] singers = {Jagger: "Rock", Elvis: "Roll"} matrix = [ 1, 0, 1 0, 0, 1 1, 1, 0 ] kids = brother: name: "Max" age: 11 sister: name: "Ida" age: 9 </pre><pre class="idle">var kids, matrix, singers, song; song = ["do", "re", "mi", "fa", "so"]; singers = { Jagger: "Rock", Elvis: "Roll" }; matrix = [1, 0, 1, 0, 0, 1, 1, 1, 0]; kids = { brother: { name: "Max", age: 11 }, sister: { name: "Ida", age: 9 } }; </pre><button onclick='javascript: var kids, matrix, singers, song; song = ["do", "re", "mi", "fa", "so"]; singers = { Jagger: "Rock", Elvis: "Roll" }; matrix = [1, 0, 1, 0, 0, 1, 1, 1, 0]; kids = { brother: { name: "Max", age: 11 }, sister: { name: "Ida", age: 9 } };;alert(song.join(","));'>run: song.join(",")</button> </div> In JavaScript, you can't use reserved words, like <tt>class</tt>, as properties of an object, without quoting them as strings. CoffeeScript notices and quotes them for you, so you don't have to worry about it (say, when using jQuery). <div class='code'><pre class="idle">$('.account').css class: 'active' </pre><pre class="idle">$('.account').css({ "class": 'active' }); </pre> </div> Lexical Scoping and Variable Safety The CoffeeScript compiler takes care to make sure that all of your variables are properly declared within lexical scope — you never need to write <tt>var</tt> yourself. <div class='code'><pre class="idle">outer = 1 changeNumbers = -> inner = -1 outer = 10 inner = changeNumbers() </pre><pre class="idle">var changeNumbers, inner, outer; outer = 1; changeNumbers = function() { var inner; inner = -1; return (outer = 10); }; inner = changeNumbers(); </pre><button onclick='javascript: var changeNumbers, inner, outer; outer = 1; changeNumbers = function() { var inner; inner = -1; return (outer = 10); }; inner = changeNumbers();;alert(inner);'>run: inner</button> </div> Notice how all of the variable declarations have been pushed up to the top of the closest scope, the first time they appear. outer is not redeclared within the inner function, because it's already in scope; inner within the function, on the other hand, should not be able to change the value of the external variable of the same name, and therefore has a declaration of its own. This behavior is effectively identical to Ruby's scope for local variables. Because you don't have direct access to the <tt>var</tt> keyword, it's impossible to shadow an outer variable on purpose, you may only refer to it. So be careful that you're not reusing the name of an external variable accidentally, if you're writing a deeply nested function. Although suppressed within this documentation for clarity, all CoffeeScript output is wrapped in an anonymous function: <tt>(function(){ ... })();</tt> This safety wrapper, combined with the automatic generation of the <tt>var</tt> keyword, make it exceedingly difficult to pollute the global namespace by accident. If you'd like to create top-level variables for other scripts to use, attach them as properties on window, or on the exports object in CommonJS. The existential operator (covered below), gives you a reliable way to figure out where to add them, if you're targeting both CommonJS and the browser: <tt>root = exports ? this</tt> If, Else, Unless, and Conditional Assignment If/else statements can be written without the use of parentheses and curly brackets. As with functions and other block expressions, multi-line conditionals are delimited by indentation. There's also a handy postfix form, with the <tt>if</tt> or <tt>unless</tt> at the end. CoffeeScript can compile if statements into JavaScript expressions, using the ternary operator when possible, and closure wrapping otherwise. There is no explicit ternary statement in CoffeeScript — you simply use a regular if statement inline. <div class='code'><pre class="idle">mood = greatlyImproved if singing if happy and knowsIt clapsHands() chaChaCha() else showIt() date = if friday then sue else jill options or= defaults </pre><pre class="idle">var date, mood, options; if (singing) { mood = greatlyImproved; } if (happy && knowsIt) { clapsHands(); chaChaCha(); } else { showIt(); } date = friday ? sue : jill; options = options || defaults; </pre> </div> Aliases Because the <tt>==</tt> operator frequently causes undesirable coercion, is intransitive, and has a different meaning than in other languages, CoffeeScript compiles <tt>==</tt> into <tt>===</tt>, and <tt>!=</tt> into <tt>!==</tt>. In addition, <tt>is</tt> compiles into <tt>===</tt>, and <tt>isnt</tt> into <tt>!==</tt>. You can use <tt>not</tt> as an alias for <tt>!</tt>. For logic, <tt>and</tt> compiles to <tt>&&</tt>, and <tt>or</tt> into <tt>||</tt>. Instead of a newline or semicolon, <tt>then</tt> can be used to separate conditions from expressions, in while, if/else, and switch/when statements. As in <a href="http://yaml.org/">YAML</a>, <tt>on</tt> and <tt>yes</tt> are the same as boolean <tt>true</tt>, while <tt>off</tt> and <tt>no</tt> are boolean <tt>false</tt>. For single-line statements, <tt>unless</tt> can be used as the inverse of <tt>if</tt>. As a shortcut for <tt>this.property</tt>, you can use <tt>@property</tt>. You can use <tt>in</tt> to test for array presence, and <tt>of</tt> to test for JavaScript object-key presence. <div class='code'><pre class="idle">launch() if ignition is on volume = 10 if band isnt SpinalTap letTheWildRumpusBegin() unless answer is no if car.speed < limit then accelerate() winner = yes if pick in [47, 92, 13] print inspect "My name is " + @name </pre><pre class="idle">var volume, winner; if (ignition === true) { launch(); } if (band !== SpinalTap) { volume = 10; } if (!(answer === false)) { letTheWildRumpusBegin(); } car.speed < limit ? accelerate() : null; if (47 === pick || 92 === pick || 13 === pick) { winner = true; } print(inspect("My name is " + this.name)); </pre> </div> Splats... The JavaScript arguments object is a useful way to work with functions that accept variable numbers of arguments. CoffeeScript provides splats <tt>...</tt>, both for function definition as well as invocation, making variable numbers of arguments a little bit more palatable. <div class='code'><pre class="idle">gold = silver = rest = "unknown" awardMedals = (first, second, others...) -> gold = first silver = second rest = others contenders = [ "Michael Phelps" "Liu Xiang" "Yao Ming" "Allyson Felix" "Shawn Johnson" "Roman Sebrle" "Guo Jingjing" "Tyson Gay" "Asafa Powell" "Usain Bolt" ] awardMedals contenders... alert "Gold: " + gold alert "Silver: " + silver alert "The Field: " + rest </pre><pre class="idle">var awardMedals, contenders, gold, rest, silver; var __slice = Array.prototype.slice; gold = (silver = (rest = "unknown")); awardMedals = function(first, second) { var others; others = __slice.call(arguments, 2); gold = first; silver = second; return (rest = others); }; contenders = ["Michael Phelps", "Liu Xiang", "Yao Ming", "Allyson Felix", "Shawn Johnson", "Roman Sebrle", "Guo Jingjing", "Tyson Gay", "Asafa Powell", "Usain Bolt"]; awardMedals.apply(this, contenders); alert("Gold: " + gold); alert("Silver: " + silver); alert("The Field: " + rest); </pre><button onclick='javascript: var awardMedals, contenders, gold, rest, silver; var __slice = Array.prototype.slice; gold = (silver = (rest = "unknown")); awardMedals = function(first, second) { var others; others = __slice.call(arguments, 2); gold = first; silver = second; return (rest = others); }; contenders = ["Michael Phelps", "Liu Xiang", "Yao Ming", "Allyson Felix", "Shawn Johnson", "Roman Sebrle", "Guo Jingjing", "Tyson Gay", "Asafa Powell", "Usain Bolt"]; awardMedals.apply(this, contenders); alert("Gold: " + gold); alert("Silver: " + silver); alert("The Field: " + rest);;'>run</button> </div> While, Until, and Loop The only low-level loop that CoffeeScript provides is the while loop. The main difference from JavaScript is that the while loop can be used as an expression, returning an array containing the result of each iteration through the loop. <div class='code'><pre class="idle"># Econ 101 if this.studyingEconomics buy() while supply > demand sell() until supply > demand # Nursery Rhyme num = 6 lyrics = while num -= 1 num + " little monkeys, jumping on the bed. One fell out and bumped his head." </pre><pre class="idle">var _a, lyrics, num; if (this.studyingEconomics) { while (supply > demand) { buy(); } while (!(supply > demand)) { sell(); } } num = 6; lyrics = (function() { _a = []; while (num -= 1) { _a.push(num + " little monkeys, jumping on the bed. \ One fell out and bumped his head."); } return _a; })(); </pre><button onclick='javascript: var _a, lyrics, num; if (this.studyingEconomics) { while (supply > demand) { buy(); } while (!(supply > demand)) { sell(); } } num = 6; lyrics = (function() { _a = []; while (num -= 1) { _a.push(num + " little monkeys, jumping on the bed. \ One fell out and bumped his head."); } return _a; })();;alert(lyrics.join("\n"));'>run: lyrics.join("\n")</button> </div> For readability, the until keyword is equivalent to <tt>while not</tt>, and the loop keyword is equivalent to <tt>while true</tt>. Other JavaScript loops, such as for loops and do-while loops can be mimicked by variations on loop, but the hope is that you won't need to do that with CoffeeScript, either because you're using each (forEach) style iterators, or... Comprehensions (Arrays, Objects, and Ranges) For your looping needs, CoffeeScript provides array comprehensions similar to Python's. They replace (and compile into) for loops, with optional guard clauses and the value of the current array index. Unlike for loops, array comprehensions are expressions, and can be returned and assigned. They should be able to handle most places where you otherwise would use a loop, each/forEach, map, or select/filter. <div class='code'><pre class="idle"># Eat lunch. lunch = eat food for food in ['toast', 'cheese', 'wine'] # Naive collision detection. for roid in asteroids for roid2 in asteroids when roid isnt roid2 roid.explode() if roid.overlaps roid2 </pre><pre class="idle">var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, food, lunch, roid, roid2; lunch = (function() { _a = []; _c = ['toast', 'cheese', 'wine']; for (_b = 0, _d = _c.length; _b < _d; _b++) { food = _c[_b]; _a.push(eat(food)); } return _a; })(); _f = asteroids; for (_e = 0, _g = _f.length; _e < _g; _e++) { roid = _f[_e]; _i = asteroids; for (_h = 0, _j = _i.length; _h < _j; _h++) { roid2 = _i[_h]; if (roid !== roid2) { if (roid.overlaps(roid2)) { roid.explode(); } } } } </pre> </div> If you know the start and end of your loop, or would like to step through in fixed-size increments, you can use a range to specify the start and end of your comprehension. <div class='code'><pre class="idle">countdown = num for num in [10..1] deliverEggs = -> for i in [0...eggs.length] by 12 dozen = eggs[i...i+12] deliver new eggCarton dozen </pre><pre class="idle">var _a, countdown, deliverEggs, num; countdown = (function() { _a = []; for (num = 10; num >= 1; num--) { _a.push(num); } return _a; })(); deliverEggs = function() { var _b, _c, dozen, i; _b = []; _c = eggs.length; for (i = 0; (0 <= _c ? i < _c : i > _c); i += 12) { _b.push((function() { dozen = eggs.slice(i, i + 12); return deliver(new eggCarton(dozen)); })()); } return _b; }; </pre><button onclick='javascript: var _a, countdown, deliverEggs, num; countdo