guard 0.7.0 → 0.8.0

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+## 0.8.0 - September 28, 2011
+
+### Bugs fixes:
+
+- Pull request [#137](https://github.com/guard/guard/pull/137): Fix interacting with tools like ruby-debug. ([@hron][] & [@netzpirat][])
+- Pull request [#138](https://github.com/guard/guard/pull/138): Fixed comments in example scaffold to reference interactions. ([@rmm5t][] & [@netzpirat][])
+
+### New feature:
+
+- Pull request [#136](https://github.com/guard/guard/pull/136): New CLI `:watch_all_modifications`/`-A` option to watch for deleted and moved files too. ([@limeyd][] & [@netzpirat][])
+- Issue [#97](https://github.com/guard/guard/issues/97): Guard dependencies. Task execution can now be halted if a Guard throws `:task_has_failed` and `Guard::Dsl#group` options include `:halt_on_fail => true`. ([@rymai][])
+- Issue [#121](https://github.com/guard/guard/issues/121): `Guard.guards` and `Guard.groups` are now smart accessors. Filters can be passed to find a specific Guard/group or several Guards/groups that match (see YARDoc). ([@rymai][] & [@ches][])
+- New `Guard::Group` class to store groups defined in Guardfile (with `Guard::Dsl#group`). ([@rymai][])
+
+### Improvement:
+
+- Specs refactoring. ([@netzpirat][])
+- Full YARD documentation. ([@netzpirat][] & a little of [@rymai][])
+
 ## 0.7.0 - September 14, 2011
 
 ## 0.7.0.rc1 - September 5, 2011
@@ -5,7 +24,7 @@
 ### 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][])
+- JRuby & Rubinius support (beta). ([@thibaudgg][] & [@netzpirat][])
 
 ### New feature:
 
@@ -250,6 +269,7 @@
 [@fnichol]: https://github.com/fnichol
 [@Gazer]: https://github.com/Gazer
 [@gix]: https://github.com/gix
+[@hron]: https://github.com/hron
 [@hashrocketeer]: https://github.com/hashrocketeer
 [@ianwhite]: https://github.com/ianwhite
 [@indirect]: https://github.com/indirect
@@ -257,6 +277,7 @@
 [@johnbintz]: https://github.com/johnbintz
 [@jrsacks]: https://github.com/jrsacks
 [@koshigoe]: https://github.com/koshigoe
+[@limeyd]: https://github.com/limeyd
 [@mcmire]: https://github.com/mcmire
 [@mislav]: https://github.com/mislav
 [@monocle]: https://github.com/monocle
@@ -267,6 +288,7 @@
 [@niklas]: https://github.com/niklas
 [@oliamb]: https://github.com/oliamb
 [@pcreux]: https://github.com/pcreux
+[@rmm5t]: https://github.com/rmm5t
 [@rymai]: https://github.com/rymai
 [@stereobooster]: https://github.com/stereobooster
 [@stouset]: https://github.com/stouset

data/README.md

@@ -26,27 +26,19 @@ Install
 
 Install the gem:
 
-``` bash
-$ gem install guard
-```
+    $ gem install guard
 
 Or add it to your Gemfile (inside the `development` group):
 
-``` ruby
-gem 'guard'
-```
+    gem 'guard'
 
 and install it via Bundler:
 
-``` bash
-$ bundle install
-```
+    $ bundle install
 
 Generate an empty Guardfile with:
 
-``` bash
-$ guard init
-```
+    $ 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.
@@ -57,31 +49,23 @@ Add the guards you need to your Guardfile (see the existing guards below).
 
 Install the rb-fsevent gem for [FSEvent](http://en.wikipedia.org/wiki/FSEvents) support:
 
-``` bash
-$ gem install rb-fsevent
-```
+    $ gem install rb-fsevent
 
 You have two possibilities:
 
 Use the [growl_notify gem](https://rubygems.org/gems/growl_notify) (recommended):
 
-``` bash
-$ gem install growl_notify
-```
+    $ gem install growl_notify
 
 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
-```
+    $ brew install growlnotify
+    $ gem install growl
 
 And add them to your Gemfile:
 
-``` ruby
-gem 'rb-fsevent'
-gem 'growl_notify' # or gem 'growl'
-```
+    gem 'rb-fsevent'
+    gem 'growl_notify' # or gem 'growl'
 
 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
@@ -92,65 +76,47 @@ approach is preferred, but you may also use the older growl gem. Have a look at
 
 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
-```
+    $ gem install rb-inotify
 
 Install the [libnotify gem](https://rubygems.org/gems/libnotify) if you want visual notification support:
 
-``` bash
-$ gem install libnotify
-```
+    $ gem install libnotify
 
 And add them to your Gemfile:
 
-``` ruby
-gem 'rb-inotify'
-gem 'libnotify'
-```
+    gem 'rb-inotify'
+    gem 'libnotify'
 
 ### On Windows
 
 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
-```
+    $ gem install rb-fchange
 
 Install the [win32console gem](https://rubygems.org/gems/win32console) if you want colors in your terminal:
 
-``` bash
-$ gem install win32console
-```
+    $ gem install win32console
 
 Install the [rb-notifu gem](https://rubygems.org/gems/rb-notifu) if you want visual notification support:
 
-``` bash
-$ gem install rb-notifu
-```
+    $ gem install rb-notifu
 
 And add them to your Gemfile:
 
-``` ruby
-gem 'rb-fchange'
-gem 'rb-notifu'
-gem 'win32console'
-```
+    gem 'rb-fchange'
+    gem 'rb-notifu'
+    gem 'win32console'
 
 Usage
 -----
 
 Just launch Guard inside your Ruby / Rails project with:
 
-``` bash
-$ guard [start]
-```
+    $ guard [start]
 
 or if you use Bundler, to run the Guard executable specific to your bundle:
 
-``` bash
-$ bundle exec guard [start]
-```
+    $ bundle exec guard [start]
 
 Guard will look for a Guardfile in your current directory. If it does not find one, it will look in your `$HOME` directory for a .Guardfile.
 
@@ -161,19 +127,15 @@ Command line options
 
 Shell can be cleared after each change:
 
-``` bash
-$ guard --clear
-$ guard -c # shortcut
-```
+    $ guard --clear
+    $ guard -c # shortcut
 
 ### `-n`/`--notify` option
 
 Notifications (growl/libnotify) can be disabled:
 
-``` bash
-$ guard --notify false
-$ guard -n f # shortcut
-```
+    $ guard --notify false
+    $ guard -n f # shortcut
 
 Notifications can also be disabled globally by setting a `GUARD_NOTIFY` environment variable to `false`
 
@@ -181,43 +143,42 @@ Notifications can also be disabled globally by setting a `GUARD_NOTIFY` environm
 
 Only certain guards groups can be run (see the Guardfile DSL below for creating groups):
 
-``` bash
-$ guard --group group_name another_group_name
-$ guard -g group_name another_group_name # shortcut
-```
+    $ guard --group group_name another_group_name
+    $ guard -g group_name another_group_name # shortcut
 
 ### `-d`/`--debug` option
 
 Guard can be run in debug mode:
 
-``` bash
-$ guard --debug
-$ guard -d # shortcut
-```
+    $ guard --debug
+    $ guard -d # shortcut
 
 ### `-w`/`--watchdir` option
 
 Guard can watch in any directory (instead of the current directory):
 
-``` bash
-$ guard --watchdir ~/your/fancy/project
-$ guard -w ~/your/fancy/project # shortcut
-```
+    $ guard --watchdir ~/your/fancy/project
+    $ guard -w ~/your/fancy/project # shortcut
 
 ### `-G`/`--guardfile` option
 
 Guard can use a Guardfile not located in the current directory:
 
+    $ guard --guardfile ~/.your_global_guardfile
+    $ guard -G ~/.your_global_guardfile # shortcut
+
+### `-A`/`--watch-all-modifications` option
+
+Guard can optionally watch all file modifications like moves or deletions with:
+
 ``` bash
-$ guard --guardfile ~/.your_global_guardfile
-$ guard -G ~/.your_global_guardfile # shortcut
+$ guard start -A
+$ guard start --watch-all-modifications
 ```
 
 An exhaustive list of options is available with:
 
-``` bash
-$ guard help [TASK]
-```
+    $ guard help [TASK]
 
 Interactions
 ------------
@@ -240,21 +201,15 @@ A list of the available guards is present [in the wiki](https://github.com/guard
 
 Add it to your Gemfile (inside the `development` group):
 
-``` ruby
-gem '<guard-name>'
-```
+    gem '<guard-name>'
 
 You can list all guards installed on your system with:
 
-``` bash
-$ guard list
-```
+    $ guard list
 
 Insert default guard's definition to your Guardfile by running this command:
 
-``` bash
-$ guard init <guard-name>
-```
+    $ guard init <guard-name>
 
 You are good to go, or you can modify your guards' definition to suit your needs.
 
@@ -271,36 +226,34 @@ The Guardfile DSL consists of the following methods:
 
 Example:
 
-``` ruby
-ignore_paths 'foo', 'bar'
-
-group 'backend' do
-  guard 'bundler' do
-    watch('Gemfile')
-  end
-
-  guard 'rspec', :cli => '--color --format doc' do
-    # Regexp watch patterns are matched with Regexp#match
-    watch(%r{^spec/.+_spec\.rb$})
-    watch(%r{^lib/(.+)\.rb$})         { |m| "spec/lib/#{m[1]}_spec.rb" }
-    watch(%r{^spec/models/.+\.rb$})   { ["spec/models", "spec/acceptance"] }
-    watch(%r{^spec/.+\.rb$})          { `say hello` }
-
-    # String watch patterns are matched with simple '=='
-    watch('spec/spec_helper.rb') { "spec" }
-  end
-end
-
-group 'frontend' do
-  guard 'coffeescript', :output => 'public/javascripts/compiled' do
-    watch(%r{^app/coffeescripts/.+\.coffee$})
-  end
-
-  guard 'livereload' do
-    watch(%r{^app/.+\.(erb|haml)$})
-  end
-end
-```
+    ignore_paths 'foo', 'bar'
+
+    group 'backend' do
+      guard 'bundler' do
+        watch('Gemfile')
+      end
+
+      guard 'rspec', :cli => '--color --format doc' do
+        # Regexp watch patterns are matched with Regexp#match
+        watch(%r{^spec/.+_spec\.rb$})
+        watch(%r{^lib/(.+)\.rb$})         { |m| "spec/lib/#{m[1]}_spec.rb" }
+        watch(%r{^spec/models/.+\.rb$})   { ["spec/models", "spec/acceptance"] }
+        watch(%r{^spec/.+\.rb$})          { `say hello` }
+
+        # String watch patterns are matched with simple '=='
+        watch('spec/spec_helper.rb') { "spec" }
+      end
+    end
+
+    group 'frontend' do
+      guard 'coffeescript', :output => 'public/javascripts/compiled' do
+        watch(%r{^app/coffeescripts/.+\.coffee$})
+      end
+
+      guard 'livereload' do
+        watch(%r{^app/.+\.(erb|haml)$})
+      end
+    end
 
 Using a Guardfile without the `guard` binary
 --------------------------------------------
@@ -315,37 +268,33 @@ Remember, without any options given, Guard will look for a Guardfile in your cur
 
 For instance, you could use it as follow:
 
-``` ruby
-gem 'guard'
-require 'guard'
+    gem 'guard'
+    require 'guard'
 
-Guard.setup
+    Guard.setup
 
-Guard::Dsl.evaluate_guardfile(:guardfile => '/your/custom/path/to/a/valid/Guardfile')
-# or
-Guard::Dsl.evaluate_guardfile(:guardfile_contents => "
-  guard 'rspec' do
-    watch(%r{^spec/.+_spec\.rb$})
-  end
-")
-```
+    Guard::Dsl.evaluate_guardfile(:guardfile => '/your/custom/path/to/a/valid/Guardfile')
+    # or
+    Guard::Dsl.evaluate_guardfile(:guardfile_contents => "
+      guard 'rspec' do
+        watch(%r{^spec/.+_spec\.rb$})
+      end
+    ")
 
 ### Listing defined guards/groups for the current project
 
 You can list the defined groups and guards for the current Guardfile from the command line using `guard show` or `guard -T`:
 
-``` bash
-# guard -T
-
-(global):
-  shell
-Group backend:
-  bundler
-  rspec: cli => "--color --format doc"
-Group frontend:
-  coffeescript: output => "public/javascripts/compiled"
-  livereload
-```
+    $ guard -T
+
+    (global):
+      shell
+    Group backend:
+      bundler
+      rspec: cli => "--color --format doc"
+    Group frontend:
+      coffeescript: output => "public/javascripts/compiled"
+      livereload
 
 User config file
 ----------------
@@ -355,114 +304,112 @@ 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):
 
-``` ruby
-guard 'shell' do
-  watch(%r{^(?:app|lib)/.+\.rb$}) { `ctags -R` }
-end
-```
+    guard 'shell' do
+      watch(%r{^(?:app|lib)/.+\.rb$}) { `ctags -R` }
+    end
 
 Create a new guard
 ------------------
 
 Creating a new guard is very easy, just create a new gem (`bundle gem` if you use Bundler) with this basic structure:
 
-```
-.travis.yml  # bonus point!
-CHANGELOG.md # bonus point!
-Gemfile
-guard-name.gemspec
-Guardfile
-lib/
-  guard/
-    guard-name/
-      templates/
-        Guardfile # needed for `guard init <guard-name>`
-      version.rb
-    guard-name.rb
-test/ # or spec/
-README.md
-```
+    .travis.yml  # bonus point!
+    CHANGELOG.md # bonus point!
+    Gemfile
+    guard-name.gemspec
+    Guardfile
+    lib/
+      guard/
+        guard-name/
+          templates/
+            Guardfile # needed for `guard init <guard-name>`
+          version.rb
+        guard-name.rb
+    test/ # or spec/
+    README.md
 
 `Guard::GuardName` (in `lib/guard/guard-name.rb`) must inherit from `Guard::Guard` and should overwrite at least one of the five basic `Guard::Guard` instance methods.
 
 Here is an example scaffold for `lib/guard/guard-name.rb`:
 
-``` ruby
-require 'guard'
-require 'guard/guard'
-
-module Guard
-  class GuardName < Guard
-
-    def initialize(watchers=[], options={})
-      super
-      # init stuff here, thx!
-    end
-
-    # =================
-    # = Guard methods =
-    # =================
-
-    # If one of those methods raise an exception, the Guard::GuardName instance
-    # will be removed from the active guards.
-
-    # Called once when Guard starts
-    # Please override initialize method to init stuff
-    def start
-      true
-    end
-
-    # Called on Ctrl-C signal (when Guard quits)
-    def stop
-      true
+    require 'guard'
+    require 'guard/guard'
+
+    module Guard
+      class GuardName < Guard
+
+        def initialize(watchers = [], options = {})
+          super
+          # init stuff here, thx!
+        end
+
+        # =================
+        # = Guard methods =
+        # =================
+
+        # If one of those methods raise an exception, the Guard::GuardName instance
+        # will be removed from the active guards.
+
+        # Called once when Guard starts
+        # Please override initialize method to init stuff
+        def start
+          true
+        end
+
+        # Called when `stop|quit|exit|s|q|e + enter` is pressed (when Guard quits)
+        def stop
+          true
+        end
+
+        # Called when `reload|r|z + enter` is pressed
+        # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
+        def reload
+          true
+        end
+
+        # Called when just `enter` is pressed
+        # This method should be principally used for long action like running all specs/tests/...
+        def run_all
+          true
+        end
+
+        # Called on file(s) modifications
+        def run_on_change(paths)
+          true
+        end
+
+        # Called on file(s) deletions
+        def run_on_deletion(paths)
+          true
+        end
+
+      end
     end
 
-    # Called on Ctrl-Z signal
-    # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
-    def reload
-      true
-    end
-
-    # Called on Ctrl-\ signal
-    # This method should be principally used for long action like running all specs/tests/...
-    def run_all
-      true
-    end
-
-    # Called on file(s) modifications
-    def run_on_change(paths)
-      true
-    end
-
-  end
-end
-```
-
 Please take a look at the [existing guards' source code](https://github.com/guard/guard/wiki/List-of-available-Guards) for more concrete example and inspiration.
 
 Alternatively, a new guard can be added inline to a Guardfile with this basic structure:
 
-``` ruby
-require 'guard/guard'
+    require 'guard/guard'
 
-module ::Guard
-  class InlineGuard < ::Guard::Guard
-    def run_all
-      true
-    end
+    module ::Guard
+      class InlineGuard < ::Guard::Guard
+        def run_all
+          true
+        end
 
-    def run_on_change(paths)
-      true
+        def run_on_change(paths)
+          true
+        end
+      end
     end
-  end
-end
-```
 
 Here is a very cool example by [@avdi](https://github.com/avdi) : http://avdi.org/devblog/2011/06/15/a-guardfile-for-redis
 
 Development
 -----------
 
+* Documentation hosted at [RubyDoc](http://rubydoc.info/github/guard/guard/master/frames).
 * Source hosted at [GitHub](https://github.com/guard/guard).
 * Report issues and feature requests to [GitHub Issues](https://github.com/guard/guard/issues).