guard-coffeescript 0.4.0 → 0.4.1

data/README.md

@@ -1,10 +1,8 @@
-# Guard::CoffeeScript
-
-![travis-ci](http://travis-ci.org/netzpirat/guard-coffeescript.png)
+# Guard::CoffeeScript [![Build Status](https://secure.travis-ci.org/netzpirat/guard-coffeescript.png)](http://travis-ci.org/netzpirat/guard-coffeescript)
 
 Guard::CoffeeScript compiles or validates your CoffeeScripts automatically when files are modified.
 
-Tested on MRI Ruby 1.8.7, 1.9.2 and the latest versions of JRuby & Rubinius.
+Tested on MRI Ruby 1.8.7, 1.9.2, REE and the latest versions of JRuby & Rubinius.
 
 If you have any questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard`
 (irc.freenode.net).
@@ -15,21 +13,15 @@ Please be sure to have [Guard](https://github.com/guard/guard) installed.
 
 Install the gem:
 
-```bash
-$ gem install guard-coffeescript
-```
+    $ gem install guard-coffeescript
 
 Add it to your `Gemfile`, preferably inside the development group:
 
-```ruby
-gem 'guard-coffeescript'
-```
+    gem 'guard-coffeescript'
 
 Add guard definition to your `Guardfile` by running this command:
 
-```bash
-$ guard init coffeescript
-```
+    $ guard init coffeescript
 
 ## JSON
 
@@ -41,59 +33,61 @@ to install the `json` or `json_pure` gem. On Ruby 1.9, JSON is included in the s
 Guard::CoffeeScript uses [Ruby CoffeeScript](https://github.com/josh/ruby-coffee-script/) to compile the CoffeeScripts,
 that in turn uses [ExecJS](https://github.com/sstephenson/execjs) to pick the best runtime to evaluate the JavaScript.
 
-## Choose a runtime
+* With CRuby you want to use a V8 JavaScript Engine or Mozilla SpiderMonkey.
+* With JRuby you want to use the Mozilla Rhino.
+* On Mac OS X you want to use Apple JavaScriptCore.
+* On Linux or as a node.js developer you want to use Node.js (V8).
+* On Windows you want to use Microsoft Windows Script Host.
+
+## JavaScript runtimes
+
+The following sections gives you a short overview of the available JavaScript runtimes and how to install it.
 
-### CoffeeScript executable on node.js
+### Node.js (V8)
 
-Please refer to the [CoffeeScript documentation](http://jashkenas.github.com/coffee-script/) for more information about
-how to install the latest CoffeeScript version on [node.js](http://nodejs.org/).
+You can install [node.js](http://nodejs.org/) and use its V8 engine. On OS X you may want to install it with
+[Homebrew](http://mxcl.github.com/homebrew/), on Linux with your package manager and on Windows you have to download and
+install the [executable](http://www.nodejs.org/#download).
 
 ### V8 JavaScript Engine
 
 To use the [V8 JavaScript Engine](http://code.google.com/p/v8/), simple add `therubyracer` to your `Gemfile`.
 The Ruby Racer acts as a bridge between Ruby and the V8 engine, that will be automatically installed by the Ruby Racer.
 
-```ruby
-group :development do
-  gem 'therubyracer'
-end
-```
+    group :development do
+      gem 'therubyracer'
+    end
 
 Another alternative is [Mustang](https://github.com/nu7hatch/mustang), a Ruby proxy library for the awesome Google V8
 JavaScript engine. Just add `mustang` to your `Gemfile`:
 
-```ruby
-group :development do
-  gem 'mustang'
-end
-```
+    group :development do
+      gem 'mustang'
+    end
 
 ### Mozilla SpiderMonkey
 
 To use [Mozilla SpiderMonkey](https://developer.mozilla.org/en/SpiderMonkey), simple add `johnson` to your `Gemfile`.
 Johnson embeds the Mozilla SpiderMonkey JavaScript runtime as a C extension.
 
-```ruby
-group :development do
-  gem 'johnson'
-end
-```
+    group :development do
+      gem 'johnson'
+    end
 
 ### Mozilla Rhino
 
 If you're using JRuby, you can embed the [Mozilla Rhino](http://www.mozilla.org/rhino/) runtime by adding `therubyrhino`
 to your `Gemfile`:
 
-```ruby
-group :development do
-  gem 'therubyrhino'
-end
-```
+    group :development do
+      gem 'therubyrhino'
+    end
 
 ### Apple JavaScriptCore
 
-JavaScriptCore is only available on Mac OS X. To use JavaScript Core you don't have to install anything, because
-JavaScriptCore is packaged with Mac OS X.
+[JavaScriptCore](http://developer.apple.com/library/mac/#documentation/Carbon/Reference/WebKit_JavaScriptCore_Ref/index.html)
+is Safari's Nitro JavaScript Engine and only usable on Mac OS X. You don't have to install anything, because
+JavaScriptCore is already packaged with Mac OS X.
 
 ### Microsoft Windows Script Host
 
@@ -109,71 +103,61 @@ Please read the [Guard usage documentation](https://github.com/guard/guard#readm
 Guard::CoffeeScript can be adapted to all kind of projects. Please read the
 [Guard documentation](https://github.com/guard/guard#readme) for more information about the Guardfile DSL.
 
-### Standard Ruby gem
+### Ruby project
 
-In a custom Ruby project you want to configure your `:input` and `:output` directories.
+In a Ruby project you want to configure your input and output directories.
 
-```ruby
-guard 'coffeescript', :input => 'coffeescripts', :output => 'javascripts'
-```
+    guard 'coffeescript', :input => 'coffeescripts', :output => 'javascripts'
 
 If your output directory is the same as the input directory, you can simply skip it:
 
-```ruby
-guard 'coffeescript', :input => 'javascripts'
-```
+    guard 'coffeescript', :input => 'javascripts'
 
 ### Rails app with the asset pipeline
 
 With the introduction of the [asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html) in Rails 3.1 there is
-no need to compile your CoffeeScripts with this Guard. However if you like to have instant validation feedback
-(preferably with a Growl notification) directly after you save a change, then you may want still use this Guard and just
-skip the generation of the output file:
+no need to compile your CoffeeScripts with this Guard.
 
-```ruby
-guard 'coffeescript', :input => 'app/assets/javascripts', :noop => true
-```
+However, if you would still like to have feedback on the validation of your CoffeeScripts
+(preferably with a Growl notification) directly after you save a change, then you can still
+use this Guard and simply skip generation of the output file:
+
+    guard 'coffeescript', :input => 'app/assets/javascripts', :noop => true
 
 This give you a faster compilation feedback compared to making a subsequent request to your Rails application. If you
 just want to be notified when an error occurs you can hide the success compilation message:
 
-```ruby
-guard 'coffeescript', :input => 'app/assets/javascripts', :noop => true, :hide_success => true
-```
+    guard 'coffeescript', :input => 'app/assets/javascripts', :noop => true, :hide_success => true
 
 ### Rails app without the asset pipeline
 
 Without the asset pipeline you just define an input and output directory like within a normal Ruby project:
 
-```ruby
-guard 'coffeescript', :input => 'app/coffeescripts', :output => 'public/javascripts',
-```
+    guard 'coffeescript', :input => 'app/coffeescripts', :output => 'public/javascripts'
 
 ## Options
 
 There following options can be passed to Guard::CoffeeScript:
 
-```ruby
-:input => 'coffeescripts'           # Relative path to the input directory.
-                                    # A suffix `/(.+\.coffee)` will be added to this option.
-                                    # default: nil
+    :input => 'coffeescripts'           # Relative path to the input directory.
+                                        # A suffix `/(.+\.coffee)` will be added to this option.
+                                        # default: nil
 
-:output => 'javascripts'            # Relative path to the output directory.
-                                    # default: the path given with the :input option
+    :output => 'javascripts'            # Relative path to the output directory.
+                                        # default: the path given with the :input option
 
-:noop => true                       # No operation: do not write an output file.
-                                    # default: false
+    :noop => true                       # No operation: do not write an output file.
+                                        # default: false
 
-:bare => true                       # Compile without the top-level function wrapper.
-                                    # Provide either a boolean value or an Array of filenames.
-                                    # default: false
+    :bare => true                       # Compile without the top-level function wrapper.
+                                        # Provide either a boolean value or an Array of filenames.
+                                        # default: false
 
-:shallow => true                    # Do not create nested output directories.
-                                    # default: false
+    :shallow => true                    # Do not create nested output directories.
+                                        # default: false
 
-:hide_success => true               # Disable successful compilation messages.
-                                    # default: false
-```
+    :hide_success => true               # Disable successful compilation messages.
+                                        # default: false
 
 ### Output short notation
 
@@ -181,25 +165,19 @@ In addition to the standard configuration, this Guard has a short notation for c
 and output directory. This notation creates a watcher from the `:input` parameter that matches all CoffeeScript files
 under the given directory and you don't have to specify a watch regular expression.
 
-```ruby
-guard 'coffeescript', :input => 'javascripts'
-```
+    guard 'coffeescript', :input => 'javascripts'
 
 ### Selective bare option
 
 The `:bare` option can take a boolean value that indicates if all scripts should be compiled without the top-level
 function wrapper.
 
-```ruby
-:bare => true
-```
+    :bare => true
 
 But you can also pass an Array of filenames that should be compiled without the top-level function wrapper. The path of
 the file to compile is ignored, so the list of filenames should not contain any path information:
 
-```ruby
-:bare => %w{ a.coffee b.coffee }
-```
+    :bare => %w{ a.coffee b.coffee }
 
 In the above example, all `a.coffee` and `b.coffee` files will be compiled with option `:bare => true` and all other
 files with option `:bare => false`.
@@ -211,27 +189,19 @@ the match of the watch regular expression:
 
 A file
 
-```bash
-/app/coffeescripts/ui/buttons/toggle_button.coffee
-```
+    /app/coffeescripts/ui/buttons/toggle_button.coffee
 
 that has been detected by the watch
 
-```ruby
-watch(%r{^app/coffeescripts/(.+\.coffee)$})
-```
+    watch(%r{^app/coffeescripts/(.+\.coffee)$})
 
 with an output directory of
 
-```ruby
-:output => 'public/javascripts/compiled'
-```
+    :output => 'public/javascripts/compiled'
 
 will be compiled to
 
-```bash
-public/javascripts/compiled/ui/buttons/toggle_button.js
-```
+    public/javascripts/compiled/ui/buttons/toggle_button.js
 
 Note the parenthesis around the `.+\.coffee`. This enables Guard::CoffeeScript to place the full path that was matched
 inside the parenthesis into the proper output directory.
@@ -243,42 +213,40 @@ compiled directly to the output directory.
 
 The Guard short notation
 
-```ruby
-guard 'coffeescript', :input => 'app/coffeescripts', :output => 'public/javascripts/compiled'
-```
+    guard 'coffeescript', :input => 'app/coffeescripts', :output => 'public/javascripts/compiled'
 
 will be internally converted into the standard notation by adding `/(.+\.coffee)` to the `input` option string and
 create a Watcher that is equivalent to:
 
-```ruby
-guard 'coffeescript', :output => 'public/javascripts/compiled' do
-  watch(%r{^app/coffeescripts/(.+\.coffee)$})
-end
-```
+    guard 'coffeescript', :output => 'public/javascripts/compiled' do
+      watch(%r{^app/coffeescripts/(.+\.coffee)$})
+    end
 
 To add a second source directory that will be compiled to the same output directory, just add another watcher:
 
-```ruby
-guard 'coffeescript', :input => 'app/coffeescripts', :output => 'public/javascripts/compiled' do
-  watch(%r{lib/coffeescripts/(.+\.coffee)})
-end
-```
+    guard 'coffeescript', :input => 'app/coffeescripts', :output => 'public/javascripts/compiled' do
+      watch(%r{lib/coffeescripts/(.+\.coffee)})
+    end
 
 which is equivalent to:
 
-```ruby
-guard 'coffeescript', :output => 'public/javascripts/compiled' do
-  watch(%r{app/coffeescripts/(.+\.coffee)})
-  watch(%r{lib/coffeescripts/(.+\.coffee)})
-end
-```
+    guard 'coffeescript', :output => 'public/javascripts/compiled' do
+      watch(%r{app/coffeescripts/(.+\.coffee)})
+      watch(%r{lib/coffeescripts/(.+\.coffee)})
+    end
 
 ## Development
 
-- Source hosted at [GitHub](https://github.com/netzpirat/guard-coffeescript)
-- Report issues and feature requests to [GitHub Issues](https://github.com/netzpirat/guard-coffeescript/issues)
+- Documentation hosted at [RubyDoc](http://rubydoc.info/gems/guard-coffeescript/frames).
+- Source hosted at [GitHub](https://github.com/netzpirat/guard-coffeescript).
+- Report issues and feature requests to [GitHub Issues](https://github.com/netzpirat/guard-coffeescript/issues).
+
+Pull requests are very welcome! Please try to follow these simple "rules", though:
 
-Pull requests are very welcome! Make sure your patches are well tested.
+- Please create a topic branch for every separate change you make.
+- Make sure your patches are well tested.
+- Update the README (if applicable).
+- Please **do not change** the version number.
 
 For questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard`
 (irc.freenode.net).
@@ -292,7 +260,10 @@ For questions please join us on our [Google group](http://groups.google.com/grou
 
 ## Acknowledgment
 
-The [Guard Team](https://github.com/guard/guard/contributors) for giving us such a nice pice of software
+[Jeremy Ashkenas][] for [CoffeeScript][], that little language that compiles into JavaScript and makes me enjoy the
+frontend.
+
+The [Guard Team](https://github.com/guard/guard/contributors) for giving us such a nice piece of software
 that is so easy to extend, one *has* to make a plugin for it!
 
 All the authors of the numerous [Guards](https://github.com/guard) available for making the Guard ecosystem

data/lib/guard/coffeescript.rb

@@ -3,19 +3,34 @@ require 'guard/guard'
 require 'guard/watcher'
 
 module Guard
+
+  # The CoffeeScript guard that gets notifications about the following
+  # Guard events: `start`, `stop`, `reload`, `run_all` and `run_on_change`.
+  #
   class CoffeeScript < Guard
 
     autoload :Formatter, 'guard/coffeescript/formatter'
     autoload :Inspector, 'guard/coffeescript/inspector'
     autoload :Runner, 'guard/coffeescript/runner'
 
-    def initialize(watchers = [], options = {})
+    # Initialize Guard::CoffeeScript.
+    #
+    # @param [Array<Guard::Watcher>] watchers the watchers in the Guard block
+    # @param [Hash] options the options for the Guard
+    # @option options [String] :input the input directory
+    # @option options [String] :output the output directory
+    # @option options [Boolean] :bare do not wrap the output in a top level function
+    # @option options [Boolean] :shallow do not create nested directories
+    # @option options [Boolean] :hide_success hide success message notification
+    # @option options [Boolean] :noop do not generate an output file
+    #
+    def initialize(watchers = [], options = { })
       watchers = [] if !watchers
       defaults = {
-          :bare => false,
-          :shallow => false,
+          :bare         => false,
+          :shallow      => false,
           :hide_success => false,
-          :noop => false
+          :noop         => false
       }
 
       if options[:input]
@@ -26,10 +41,19 @@ module Guard
       super(watchers, defaults.merge(options))
     end
 
+    # Gets called when all specs should be run.
+    #
+    # @return [Boolean] when running all specs was successful
+    #
     def run_all
       run_on_change(Watcher.match_files(self, Dir.glob(File.join('**', '*.coffee'))))
     end
 
+    # Gets called when watched paths and files have changes.
+    #
+    # @param [Array<String>] paths the changed paths and files
+    # @return [Boolean] when running the changed specs was successful
+    #
     def run_on_change(paths)
       changed_files, success = Runner.run(Inspector.clean(paths), watchers, options)
       notify changed_files
@@ -39,6 +63,11 @@ module Guard
 
     private
 
+    # Notify changed files back to Guard, so that other Guards can continue
+    # to work with the generated files.
+    #
+    # @param [Array<String>] changed_files the files that have been changed
+    #
     def notify(changed_files)
       ::Guard.guards.each do |guard|
         paths = Watcher.match_files(guard, changed_files)

data/lib/guard/coffeescript/formatter.rb

@@ -1,32 +1,73 @@
 module Guard
   class CoffeeScript
+
+    # The Guard::CoffeeScript formatter collects console and
+    # system notification methods and enhances them with
+    # some color information.
+    #
     module Formatter
       class << self
 
-        def info(message, options={ })
+        # Print an info message to the console.
+        #
+        # @param [String] message the message to print
+        # @param [Hash] options the output options
+        # @option options [Boolean] :reset reset the UI
+        #
+        def info(message, options = { })
           ::Guard::UI.info(message, options)
         end
 
-        def debug(message, options={})
+        # Print a debug message to the console.
+        #
+        # @param [String] message the message to print
+        # @param [Hash] options the output options
+        # @option options [Boolean] :reset reset the UI
+        #
+        def debug(message, options = { })
           ::Guard::UI.debug(message, options)
         end
 
-        def error(message, options={})
+        # Print a red error message to the console.
+        #
+        # @param [String] message the message to print
+        # @param [Hash] options the output options
+        # @option options [Boolean] :reset reset the UI
+        #
+        def error(message, options = { })
           ::Guard::UI.error(color(message, ';31'), options)
         end
 
-        def success(message, options={})
+        # Print a green success message to the console.
+        #
+        # @param [String] message the message to print
+        # @param [Hash] options the output options
+        # @option options [Boolean] :reset reset the UI
+        #
+        def success(message, options = { })
           ::Guard::UI.info(color(message, ';32'), options)
         end
 
-        def notify(message, options={})
+        # Outputs a system notification.
+        #
+        # @param [String] message the message to print
+        # @param [Hash] options the output options
+        # @option options [Symbol, String] :image the image to use, either :failed, :pending or :success, or an image path
+        # @option options [String] :title the title of the system notification
+        #
+        def notify(message, options = { })
           ::Guard::Notifier.notify(message, options)
         end
 
         private
 
+        # Print a info message to the console.
+        #
+        # @param [String] test the text to colorize
+        # @param [String] color_code the color code
+        #
         def color(text, color_code)
-          ::Guard::UI.send(:color_enabled?) ? "\e[0#{color_code}m#{text}\e[0m" : text
+          ::Guard::UI.send(:color_enabled?) ? "\e[0#{ color_code }m#{ text }\e[0m" : text
         end
 
       end