coffeescript 1.8.0 documents

CoffeeScript is a little language that compiles into javaScript. Underneath that awkward Java-esque patina, Javascript has always had a gorgeous heart. CoffeeScript is an attempt to expose the good parts of JavaScript in a simple way.

The golden rule of CoffeeScript is: "It's just JavaScript". The code compiles one-to-one into the equivalent JS, and there is no interPRetation at runtime. You can use any existing JavaScript library seamlessly from CoffeeScript (and vice-versa). The compiled output is readable and pretty-printed, will work in every JavaScript runtime, and tends to run as fast or faster than the equivalent handwritten JavaScript.

Latest Version: 1.8.0

npm install -g coffee-script

Overview

CoffeeScript on the left, compiled JavaScript output on the right.

# Assignment:number   = 42opposite = 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)

var cubes, list, math, num, number, opposite, race, square,  __slice = [].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() {  var runners, winner;  winner = arguments[0], runners = 2 <= arguments.length ? __slice.call(arguments, 1) : [];  return print(winner, runners);};if (typeof elvis !== "undefined" && elvis !== null) {  alert("I knew it!");}cubes = (function() {  var _i, _len, _results;  _results = [];  for (_i = 0, _len = list.length; _i < _len; _i++) {    num = list[_i];    _results.push(math.cube(num));  }  return _results;})();

Installation

The CoffeeScript compiler is itself written in CoffeeScript, using the Jison parser generator. The command-line version of coffee is available as a Node.js utility. The core compiler however, does not depend on Node, and can be run in any JavaScript environment, or in the browser (see "Try CoffeeScript", above).

To install, first make sure you have a working copy of the latest stable version of Node.js, and npm (the Node Package Manager). You can then install CoffeeScript globally with npm:

npm install -g coffee-script

When you need CoffeeScript as a dependency, install it locally:

npm install --save coffee-script

If you'd prefer to install the latest master version of CoffeeScript, you can clone the CoffeeScript source repository from GitHub, or download the source directly. To install the latest master CoffeeScript compiler with npm:

npm install -g jashkenas/coffeescript

Or, if you want to install to /usr/local, and don't want to use npm to manage it, open the coffee-script directory and run:

sudo bin/cake install

Usage

Once installed, you should have access to the coffee command, which can execute scripts, compile .coffee files into .js, and provide an interactive REPL. The coffee command takes the following options:

Expressions  Assign    Value "square"    Code "x"      Op *        Value "x"        Value "x"

Examples:

• Compile a directory tree of .coffee files in src into a parallel tree of .js files in lib: coffee --compile --output lib/ src/
• Watch a file for changes, and recompile it every time the file is saved: coffee --watch --compile experimental.coffee
• Concatenate a list of files into a single script: coffee --join project.js --compile src/*.coffee
• Print out the compiled JS from a one-liner: coffee -bpe "alert i for i in [0..10]"
• All together now, watch and recompile an entire project as you work on it: coffee -o lib/ -cw src/
• Start the CoffeeScript REPL (Ctrl-D to exit, Ctrl-Vfor multi-line): coffee

Literate CoffeeScript

Besides being used as an ordinary programming language, CoffeeScript may also be written in "literate" mode. If you name your file with a .litcoffee extension, you can write it as a Markdown document — a document that also happens to be executable CoffeeScript code. The compiler will treat any indented blocks (Markdown's way of indicating source code) as code, and ignore the rest as comments.

Just for kicks, a little bit of the compiler is currently implemented in this fashion: See it as a document, raw, and properly highlighted in a text edit