[Extensibility] Hooking into the Command Line Compiler

What is this page about? In this article you will learn how you can listen for various events at compile time. Using the information here you can build scripts that connect CoffeeScript in watch mode with utilities such as Growl.

Compatibility

Since version 0.9.1 the compiler takes a --require flag, which specifies files to include before compilation.

Example

Let's create a simple script that would prepend a license header when code is compiled successfully (either via the command-line, stdin or a file):

$ cd ~
$ vim ext.coffee

Paste the following contents into ext.coffee:

# This is the file that gets required by the compiler
CoffeeScript = require 'coffee-script'
CoffeeScript.on 'success', (task) ->
  task.output = """
    // The MIT License
    // Copyright (c) #{ new Date().getFullYear() } Your Name\n
   """ + task.output

Events

CoffeeScript emits three events during compilation: compile, success and failure. Each event receives a task parameter -- in the case of failure it is the second parameter where the first one is the exception that was thrown. The task object is a collection of properties: file, input and options -- after compilation, output is also available:

In the script above we modify the output property before it is printed to stdout or a file.

Usage

Let's invoke the command-line compiler and require our script:

$ cd ~
$ coffee -ep --require ./ext.coffee '1 + 1'
// The MIT License
// Copyright (c) 2010 Your Name
(function() {
  1 + 1;
})();

and sure enough we can see our header merged to the output. In case you are wondering what -ep is, it is a shorthand for --eval --print. You can also short-type --require:

$ coffee -epr ./ext.coffee '1 + 1'

Caveats

The path to ext.coffee is resolved using node.js hence the need to prepend it with ./. If you want to avoid that, you can:

• create all extensions under ~/.node_libraries/

• create a new directory under your profile coffee_libraries and add it to your NODE_PATH:

  export NODE_PATH="/home/your_username/.coffee_libraries:$NODE_PATH"
  

If you do any of the above, you can omit the .coffee extension as well:

$ coffee -epr ext '1 + 1'