guard 0.6.3 → 0.7.0.rc1

data/CHANGELOG.md

@@ -1,9 +1,25 @@
+## 0.7.0.rc1 - September 5, 2011
+
+### Major Changes
+
+- Posix Signals handlers (`Ctrl-C`, `Ctrl-\` and `Ctrl-Z`) are no more supported and replaced by `$stdin.gets`. Please refer to the "Interactions" section in the README for more information. ([@thibaudgg][])
+- JRuby & Rubinius support (beta). ([@thibaudgg][] and [@netzpirat][])
+
+### New feature:
+
+- Pull request [#42](https://github.com/guard/guard/pull/42): New DSL method: `callback` allows you to execute arbitrary code before or after any of the `start`, `stop`, `reload`, `run_all` and `run_on_change` guards' method. New [Wiki page](https://github.com/guard/guard/wiki/Hooks-and-callbacks) for documenting it. ([@monocle][] & [@rymai][])
+- Ability to 'pause' files modification listening. Please refer to the "Interactions" section in the README for more information. ([@thibaudgg][])
+
+### Improvement:
+
+- Remove the need to scan the whole directory after guard's `run_on_change` method. ([@thibaudgg][])
+
 ## 0.6.3 - September 1, 2011
 
 ### New features:
 
-- Pull request [#130](https://github.com/guard/guard/pull/130): Adds ignore_paths option to DSL. ([@ianwhite][])
-- Pull request [#128](https://github.com/guard/guard/pull/128): Users can add additional settings to ~/.guard.rb that augment the existing Guardfile. ([@tpope][])
+- Pull request [#130](https://github.com/guard/guard/pull/130): Adds `ignore_paths` method to DSL. ([@ianwhite][])
+- Pull request [#128](https://github.com/guard/guard/pull/128): Users can add additional settings to `~/.guard.rb` that augment the existing Guardfile. ([@tpope][])
 
 ## 0.6.2 - August 17, 2011
 
@@ -14,7 +30,7 @@
 
 ### New features:
 
-- Groups are now stored in a @groups variable (will be used for future features). ([@rymai][])
+- Groups are now stored in a `@groups` variable (will be used for future features). ([@rymai][])
 - Guards will now receive their group in the options hash at initialization (will be used for future features). ([@rymai][])
 
 ### Improvement:
@@ -25,15 +41,15 @@
 
 ### Bugs fixes:
 
-- Pull request [#120](https://github.com/guard/guard/pull/120): remove guardfile_contents when re-evaluating so that the Guardfile gets reloaded correctly. ([@mordaroso][])
-- Pull request [#119](https://github.com/guard/guard/pull/119): Dsl.evaluate_guardfile uses all groups if none specified. ([@ches][])
+- Pull request [#120](https://github.com/guard/guard/pull/120): remove `guardfile_contents` when re-evaluating so that the Guardfile gets reloaded correctly. ([@mordaroso][])
+- Pull request [#119](https://github.com/guard/guard/pull/119): `Dsl.evaluate_guardfile` uses all groups if none specified. ([@ches][])
 
 ## 0.6.0 - August 13, 2011
 
 ### Bugs fixes:
 
 - Pull request [#107](https://github.com/guard/guard/pull/107): Small spelling fix. ([@dnagir][])
-- Dir.glob now ignores files that don't need to be watched. ([@rymai][])
+- `Dir.glob` now ignores files that don't need to be watched. ([@rymai][])
 
 ### New features:
 
@@ -42,7 +58,7 @@
 ### Improvements:
 
 - Pull request [#99](https://github.com/guard/guard/pull/99): [OS X] Switch from growl gem to growl_notify gem. ([@johnbintz][])
-- Pull request [#115](https://github.com/guard/guard/pull/115): [Linux] Add ':transient => true' to default libnotify options. ([@zonque][])
+- Pull request [#115](https://github.com/guard/guard/pull/115): [Linux] Add `:transient => true` to default libnotify options. ([@zonque][])
 - Pull request [#95](https://github.com/guard/guard/pull/95): Output system commands and options to be executed when in debug mode. ([@uk-ar][] and [@netzpirat][])
 - `Guard::Dsl.revaluate_guardfile` has been renamed to `Guard::Dsl.reevaluate_guardfile`. ([@rymai][])
 - New CLI options: ([@nestegg][])
@@ -233,6 +249,7 @@
 [@Gazer]: https://github.com/Gazer
 [@gix]: https://github.com/gix
 [@hashrocketeer]: https://github.com/hashrocketeer
+[@ianwhite]: https://github.com/ianwhite
 [@indirect]: https://github.com/indirect
 [@jeffutter]: https://github.com/jeffutter
 [@johnbintz]: https://github.com/johnbintz
@@ -240,6 +257,7 @@
 [@koshigoe]: https://github.com/koshigoe
 [@mcmire]: https://github.com/mcmire
 [@mislav]: https://github.com/mislav
+[@monocle]: https://github.com/monocle
 [@mordaroso]: https://github.com/mordaroso
 [@nestegg]: https://github.com/nestegg
 [@netzpirat]: https://github.com/netzpirat

data/README.md

@@ -1,4 +1,4 @@
-Guard [![Build Status](https://travis-ci.org/guard/guard.png)](http://travis-ci.org/guard/guard)
+Guard [![Build Status](http://travis-ci.org/guard/guard.png)](http://travis-ci.org/guard/guard)
 =====
 
 Guard is a command line tool that easily handle events on files modifications.
@@ -13,14 +13,13 @@ Features
 * [Directory Change Notification](http://msdn.microsoft.com/en-us/library/aa365261\(VS.85\).aspx) support on Windows ([rb-fchange, >= 0.0.2](https://rubygems.org/gems/rb-fchange) required).
 * Polling on the other operating systems (help us to support more OS).
 * Automatic & Super fast (when polling is not used) files modifications detection (even new files are detected).
-* Growl notifications ([growl_notify gem](https://rubygems.org/gems/growl_notify) or [growlnotify](http://growl.info/documentation/growlnotify.php) & [growl gem](https://rubygems.org/gems/growl) required).
-* Libnotify notifications ([libnotify gem](https://rubygems.org/gems/libnotify) required).
-* Tested against Ruby 1.8.7, 1.9.2 and REE.
+* Visual notifications on Mac OSX ([Growl](http://growl.info)), Linux ([Libnotify](http://developer.gnome.org/libnotify)) and Windows ([Notifu](http://www.paralint.com/projects/notifu)).
+* Tested against Ruby 1.8.7, 1.9.2, REE and the latest versions of JRuby & Rubinius.
 
 Screencast
 ----------
 
-Ryan Bates made a screencast on Guard, you can view it here: http://railscasts.com/episodes/264-guard
+Ryan Bates made a Railscast on Guard, you can view it here: http://railscasts.com/episodes/264-guard
 
 Install
 -------
@@ -31,12 +30,18 @@ Install the gem:
 $ gem install guard
 ```
 
-Add it to your Gemfile (inside the `development` group):
+Or add it to your Gemfile (inside the `development` group):
 
 ``` ruby
 gem 'guard'
 ```
 
+and install it via Bundler:
+
+``` bash
+$ bundle install
+```
+
 Generate an empty Guardfile with:
 
 ``` bash
@@ -44,6 +49,7 @@ $ guard init
 ```
 
 You may optionally place a .Guardfile in your home directory to use it across multiple projects.
+Also note that if a `.guard.rb` is found in your home directory, it will be appended to the Guardfile.
 
 Add the guards you need to your Guardfile (see the existing guards below).
 
@@ -55,11 +61,18 @@ Install the rb-fsevent gem for [FSEvent](http://en.wikipedia.org/wiki/FSEvents)
 $ gem install rb-fsevent
 ```
 
-Install either the growl_notify or the growl gem if you want notification support:
+You have two possibilities:
+
+Use the [growl_notify gem](https://rubygems.org/gems/growl_notify) (recommended):
 
 ``` bash
 $ gem install growl_notify
-$ # or
+```
+
+Use the [growlnotify](http://growl.info/extras.php#growlnotify) (cli tool for growl) + the [growl gem](https://rubygems.org/gems/growl).
+
+``` bash
+$ brew install growlnotify
 $ gem install growl
 ```
 
@@ -67,22 +80,23 @@ And add them to your Gemfile:
 
 ``` ruby
 gem 'rb-fsevent'
-gem 'growl'
+gem 'growl_notify' # or gem 'growl'
 ```
 
-The difference between growl and growl_notify is that growl_notify uses AppleScript to 
+The difference between growl and growl_notify is that growl_notify uses AppleScript to
 display a message, whereas growl uses the `growlnotify` command. In general the AppleScript
-approach is preferred, but this is currently known to not work in conjunction with Spork.
+approach is preferred, but you may also use the older growl gem. Have a look at the
+[Guard Wiki](https://github.com/guard/guard/wiki/Use-growl_notify-or-growl-gem) for more information.
 
 ### On Linux
 
-Install the rb-inotify gem for [inotify](http://en.wikipedia.org/wiki/Inotify) support:
+Install the [rb-inotify gem](https://rubygems.org/gems/rb-inotify) for [inotify](http://en.wikipedia.org/wiki/Inotify) support:
 
 ``` bash
 $ gem install rb-inotify
 ```
 
-Install the Libnotify gem if you want notification support:
+Install the [libnotify gem](https://rubygems.org/gems/libnotify) if you want visual notification support:
 
 ``` bash
 $ gem install libnotify
@@ -97,19 +111,19 @@ gem 'libnotify'
 
 ### On Windows
 
-Install the rb-fchange gem for [Directory Change Notification](http://msdn.microsoft.com/en-us/library/aa365261\(VS.85\).aspx) support:
+Install the [rb-fchange gem](https://rubygems.org/gems/rb-fchange) for [Directory Change Notification](http://msdn.microsoft.com/en-us/library/aa365261\(VS.85\).aspx) support:
 
 ``` bash
 $ gem install rb-fchange
 ```
 
-Install the win32console gem if you want colors in your terminal:
+Install the [win32console gem](https://rubygems.org/gems/win32console) if you want colors in your terminal:
 
 ``` bash
 $ gem install win32console
 ```
 
-Install the Notifu gem if you want notification support:
+Install the [rb-notifu gem](https://rubygems.org/gems/rb-notifu) if you want visual notification support:
 
 ``` bash
 $ gem install rb-notifu
@@ -120,6 +134,7 @@ And add them to your Gemfile:
 ``` ruby
 gem 'rb-fchange'
 gem 'rb-notifu'
+gem 'win32console'
 ```
 
 Usage
@@ -204,16 +219,17 @@ An exhaustive list of options is available with:
 $ guard help [TASK]
 ```
 
-Signal handlers
----------------
+Interactions
+------------
 
-Signal handlers are used to interact with Guard:
+**From version >= 0.7.0 Posix Signal handlers are no more used to interact with Guard. If you're using a version < 0.7, please refer to the [README in the v0.6 branch](https://github.com/guard/guard/blob/v0.6/README.md).**
 
-* `Ctrl-C` - Calls each guard's `#stop` method, in the same order they are declared in the Guardfile, and then quits Guard itself.
-* `Ctrl-\` - Calls each guard's `#run_all` method, in the same order they are declared in the Guardfile.
-* `Ctrl-Z` - Calls each guard's `#reload` method, in the same order they are declared in the Guardfile.
+When Guard do nothing you can interact with by entering a command + hitting enter:
 
-You can read more about [configure the signal keyboard shortcuts](https://github.com/guard/guard/wiki/Configure-keyboard-shortcuts) in the wiki.
+* `stop|quit|exit|s|q|e + enter` - Calls each guard's `#stop` method, in the same order they are declared in the Guardfile, and then quits Guard itself.
+* `reload|r|z + enter` - Calls each guard's `#reload` method, in the same order they are declared in the Guardfile.
+* `pause|p + enter` - Toggle files modification listening. Useful when switching git branches.
+* `just enter (no commands)` - Calls each guard's `#run_all` method, in the same order they are declared in the Guardfile.
 
 Available Guards
 ----------------
@@ -245,17 +261,13 @@ You are good to go, or you can modify your guards' definition to suit your needs
 Guardfile DSL
 -------------
 
-The Guardfile DSL consists of just three simple methods: `#guard`, `#watch` & `#group`.
-
-Required:
-
-* The `#guard` method allows you to add a guard with an optional hash of options.
+The Guardfile DSL consists of the following methods:
 
-Optional:
-
-* The `#watch` method allows you to define which files are supervised by this guard. An optional block can be added to overwrite the paths sent to the guard's `#run_on_change` method or to launch any arbitrary command.
-* The `#group` method allows you to group several guards together. Groups to be run can be specified with the Guard DSL option `--group` (or `-g`). This comes in handy especially when you have a huge Guardfile and want to focus your development on a certain part. Guards that don't belong to a group are considered global and are always run.
-* The `#ignore_paths` method allows you to ignore top level directories altogether.  This comes is handy when you have large amounts of non-source data in you project.  By default .bundle, .git, log, tmp, and vendor are ignored.  Currently it is only possible to ignore the immediate descendants of the watched directory.
+* `#guard`: allows you to add a guard with an optional hash of options.
+* `#watch`: allows you to define which files are supervised by this guard. An optional block can be added to overwrite the paths sent to the guard's `#run_on_change` method or to launch any arbitrary command.
+* `#group`: allows you to group several guards together. Groups to be run can be specified with the Guard DSL option `--group` (or `-g`). This comes in handy especially when you have a huge Guardfile and want to focus your development on a certain part. Guards that don't belong to a group are considered global and are always run.
+* `#callback`: allows you to execute arbitrary code before or after any of the `start`, `stop`, `reload`, `run_all` and `run_on_change` guards' method. You can even insert more hooks inside these methods. Please [checkout the Wiki page](https://github.com/guard/guard/wiki/Hooks-and-callbacks) for more details.
+* `#ignore_paths`: allows you to ignore top level directories altogether.  This comes is handy when you have large amounts of non-source data in you project.  By default .bundle, .git, log, tmp, and vendor are ignored.  Currently it is only possible to ignore the immediate descendants of the watched directory.
 
 Example:
 
@@ -290,7 +302,8 @@ group 'frontend' do
 end
 ```
 
-### Using a Guardfile without the `guard` binary
+Using a Guardfile without the `guard` binary
+--------------------------------------------
 
 The Guardfile DSL can also be used in a programmatic fashion by calling directly `Guard::Dsl.evaluate_guardfile`.
 Available options are as follow:
@@ -337,7 +350,7 @@ Group frontend:
 User config file
 ----------------
 
-If a .guard.rb is found in your home directory, it will be appended to
+If a `.guard.rb` is found in your home directory, it will be appended to
 the Guardfile.  This can be used for tasks you want guard to handle but
 other users probably don't.  For example, indexing your source tree with
 [Ctags](http://ctags.sourceforge.net):
@@ -346,7 +359,6 @@ other users probably don't.  For example, indexing your source tree with
 guard 'shell' do
   watch(%r{^(?:app|lib)/.+\.rb$}) { `ctags -R` }
 end
-
 ```
 
 Create a new guard
@@ -454,7 +466,13 @@ Development
 * Source hosted at [GitHub](https://github.com/guard/guard).
 * Report issues and feature requests to [GitHub Issues](https://github.com/guard/guard/issues).
 
-Pull requests are very welcome! Make sure your patches are well tested. Please create a topic branch for every separate change you make. Please **do not change** the version in your pull-request.
+Pull requests are very welcome! Please try to follow these simple "rules", though:
+
+- Please create a topic branch for every separate change you make;
+- Make sure your patches are well tested;
+- Update the README (if applicable);
+- Update the CHANGELOG (maybe not for a typo but don't hesitate!);
+- 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).
 
@@ -464,6 +482,6 @@ Author
 [Thibaud Guillaume-Gentil](https://github.com/thibaudgg)
 
 Contributors
-------
+------------
 
 https://github.com/guard/guard/contributors

data/lib/guard.rb

@@ -7,16 +7,18 @@ module Guard
   autoload :Listener,     'guard/listener'
   autoload :Watcher,      'guard/watcher'
   autoload :Notifier,     'guard/notifier'
+  autoload :Hook,         'guard/hook'
 
   class << self
-    attr_accessor :options, :guards, :groups, :listener
+    attr_accessor :options, :guards, :groups, :interactor, :listener
 
     # initialize this singleton
     def setup(options = {})
-      @options  = options
-      @listener = Listener.select_and_init(@options[:watchdir] ? File.expand_path(@options[:watchdir]) : Dir.pwd)
-      @groups   = [:default]
-      @guards   = []
+      @options    = options
+      @guards     = []
+      @groups     = [:default]
+      @interactor = Interactor.new
+      @listener   = Listener.select_and_init(@options[:watchdir] ? File.expand_path(@options[:watchdir]) : Dir.pwd)
 
       @options[:notify] && ENV["GUARD_NOTIFY"] != 'false' ? Notifier.turn_on : Notifier.turn_off
 
@@ -27,43 +29,83 @@ module Guard
     end
 
     def start(options = {})
-      Interactor.init_signal_traps
-
       setup(options)
 
       Dsl.evaluate_guardfile(options)
 
       listener.on_change do |files|
-        Dsl.reevaluate_guardfile if Watcher.match_guardfile?(files)
-
-        run { run_on_change_for_all_guards(files) } if Watcher.match_files?(guards, files)
+        Dsl.reevaluate_guardfile        if Watcher.match_guardfile?(files)
+        listener.changed_files += files if Watcher.match_files?(guards, files)
       end
 
       UI.info "Guard is now watching at '#{listener.directory}'"
       guards.each { |guard| supervised_task(guard, :start) }
+
+      interactor.start
       listener.start
     end
 
-    def run_on_change_for_all_guards(files)
-      guards.each do |guard|
-        paths = Watcher.match_files(guard, files)
-        unless paths.empty?
-          UI.debug "#{guard.class.name}#run_on_change with #{paths.inspect}"
-          supervised_task(guard, :run_on_change, paths)
+    def stop
+      UI.info "Bye bye...", :reset => true
+      listener.stop
+      guards.each { |guard| supervised_task(guard, :stop) }
+      abort
+    end
+
+    def reload
+      run do
+        guards.each { |guard| supervised_task(guard, :reload) }
+      end
+    end
+
+    def run_all
+      run do
+        guards.each { |guard| supervised_task(guard, :run_all) }
+      end
+    end
+
+    def pause
+      if listener.locked
+        UI.info "Un-paused files modification listening", :reset => true
+        listener.clear_changed_files
+        listener.unlock
+      else
+        UI.info "Paused files modification listening", :reset => true
+        listener.lock
+      end
+    end
+
+    def run_on_change(files)
+      run do
+        guards.each do |guard|
+          paths = Watcher.match_files(guard, files)
+          unless paths.empty?
+            UI.debug "#{guard.class.name}#run_on_change with #{paths.inspect}"
+            supervised_task(guard, :run_on_change, paths)
+          end
         end
       end
+    end
 
-      # Reparse the whole directory to catch new files modified during the guards run
-      new_modified_files = listener.modified_files([listener.directory], :all => true)
-      if !new_modified_files.empty? && Watcher.match_files?(guards, new_modified_files)
-        run { run_on_change_for_all_guards(new_modified_files) }
+    def run
+      listener.lock
+      interactor.lock
+      UI.clear if options[:clear]
+      begin
+        yield
+      rescue Interrupt
       end
+      interactor.unlock
+      listener.unlock
     end
 
     # Let a guard execute its task but
     # fire it if his work leads to a system failure
     def supervised_task(guard, task_to_supervise, *args)
-      guard.send(task_to_supervise, *args)
+      guard.hook("#{task_to_supervise}_begin", *args)
+      result = guard.send(task_to_supervise, *args)
+      guard.hook("#{task_to_supervise}_end", result)
+      result
     rescue Exception => ex
       UI.error("#{guard.class.name} failed to achieve its <#{task_to_supervise.to_s}>, exception was:" +
       "\n#{ex.class}: #{ex.message}\n#{ex.backtrace.join("\n")}")
@@ -72,22 +114,13 @@ module Guard
       return ex
     end
 
-    def run
-      listener.stop
-      UI.clear if options[:clear]
-      begin
-        yield
-      rescue Interrupt
-      end
-      listener.start
-    end
-
-    def add_guard(name, watchers = [], options = {})
+    def add_guard(name, watchers = [], callbacks = [], options = {})
       if name.to_sym == :ego
         UI.deprecation("Guard::Ego is now part of Guard. You can remove it from your Guardfile.")
       else
-        guard = get_guard_class(name).new(watchers, options)
-        @guards << guard
+        guard_class = get_guard_class(name)
+        callbacks.each { |callback| Hook.add_callback(callback[:listener], guard_class, callback[:events]) }
+        @guards << guard_class.new(watchers, options)
       end
     end