guard 1.1.0.alpha.2 → 1.1.0.beta

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+## 1.1.0 - Unreleased
+
+### Improvements
+
+- Listening is now handled by the [Listen gem](https://github.com/guard/listen).
+- New `--latency`/`-l` option to overwrite Listen's default latency.
+- New `--force-polling`/`-p` option to force usage of the Listen polling listener.
+- `--watch-all-modifications`/`-A` option is removed and is now always on.
+- `--no-vendor`/`-I` option is removed because the monitoring gems are now part of the [Listen gem](https://github.com/guard/listen). You can specify a custom version of any monitoring gem directly in your Gemfile if you want to overwrite Listen's default monitoring gems.
+- Guards implementations must now implement `run_on_additions`, `run_on_modifications`, `run_on_removals` and / or `run_on_changes`. The `run_on_change` and `run_on_deletion` methods are deprecated and should be removed as soon as possible. See the [Upgrade guide for existing guards to Guard v1.1](https://github.com/guard/guard/wiki/Upgrade-guide-for-existing-guards-to-Guard-v1.1) for more info.
+
+The Listen integration has been supervised by [@thibaudgg][] and executed by [@Maher4Ever][], [@rymai][] and [@thibaudgg][].
+
+## 1.0.3 - 14 May, 2012
+
+### Improvement
+
+- Improve Thor dependency '~> 0.14.6' => '>= 0.14.6'. ([@thibaudgg][])
+
 ## 1.0.2 - 30 April, 2012
 
 ### Improvements

data/README.md

@@ -7,44 +7,9 @@ This document contains a lot of information, please take your time and read thes
 any questions, ask them in our [Google group](http://groups.google.com/group/guard-dev) or on `#guard`
 (irc.freenode.net).
 
-Before you file an issue, make sure you have read the [file an issue](#file-an-issue) section that contains some
+Before you file an issue, make sure you have read the file an issue section that contains some
 important information.
 
-Contents
---------
-
-* [Features](#features)
-* [Screencast](#screencast)
-* [Installation](#installation)
-  * [System notifications](#installation-system-notifications)
-* [Add more Guards](#add-more-guards)
-* [Usage](#usage)
-  * [Help](#usage-help)
-  * [Init](#usage-init)
-  * [Start](#usage-start)
-  * [List](#usage-list)
-  * [Show](#usage-show)
-* [Interactions](#interactions)
-  * [Readline support](#interactions-readline-support)
-  * [Signals](#interactions-signal)
-* [Guardfile DSL](#guardfile-dsl)
-  * [guard](#guardfile-dsl-guard)
-  * [watch](#guardfile-dsl-watch)
-  * [group](#guardfile-dsl-group)
-  * [notification](#guardfile-dsl-notification)
-  * [interactor](#guardfile-dsl-interactor)
-  * [callback](#guardfile-dsl-callback)
-  * [ignore](#guardfile-dsl-ignore)
-  * [filter](#guardfile-dsl-filter)
-  * [Example](#guardfile-dsl-example)
-* [Shared configurations](#shared-configurations)
-* [Advanced Linux system configuration](#advanced-linux-system-configuration)
-* [Create a Guard](#create-a-guard)
-* [Programmatic use of Guard](#programmatic-use-of-guard)
-* [File an issue](#file-an-issue)
-* [Development](#development)
-
-<a name="features" />
 Features
 --------
 
@@ -53,14 +18,12 @@ Features
 * Huge ([more than 120](https://rubygems.org/search?query=guard-)) guard extensions eco-system.
 * Tested against Ruby 1.8.7, 1.9.2, 1.9.3, REE and the latest versions of JRuby & Rubinius.
 
-<a name="screencast" />
 Screencast
 ----------
 
 Ryan Bates made an excellent [RailsCast about Guard](http://railscasts.com/episodes/264-guard) and you should definitely
 watch it for a nice introduction to Guard.
 
-<a name="installation" />
 Installation
 ------------
 
@@ -98,7 +61,6 @@ end
 **It's important that you always run Guard through Bundler to avoid errors.** If you're getting sick of typing `bundle exec` all
 the time, try the [Rubygems Bundler](https://github.com/mpapis/rubygems-bundler).
 
-<a name="installation-system-notifications" />
 ### System notifications
 
 You can configure Guard to make use of the following system notification libraries, but it's strongly recommended
@@ -206,7 +168,6 @@ group :development do
 end
 ```
 
-<a name="add-more-guards" />
 Add more Guards
 ---------------
 
@@ -225,13 +186,11 @@ end
 See the init section of the Guard usage below to see how to install the supplied Guard template that you can install and
 to suit your needs.
 
-<a name="usage" />
 Usage
 -----
 
 Guard is run from the command line. Please open your terminal and go to your project work directory.
 
-<a name="usage-help" />
 ### Help
 
 You can always get help on the available tasks with the `help` task:
@@ -247,7 +206,6 @@ For example, to get help for the `start` task, simply run:
 $ guard help start
 ```
 
-<a name="usage-init" />
 ### Init
 
 You can generate a Guardfile and have all installed guards be automatically added into
@@ -285,7 +243,6 @@ $ guard init --bare
 $ guard init -b # shortcut
 ```
 
-<a name="usage-start" />
 ### Start
 
 Just launch Guard inside your Ruby or Rails project with:
@@ -375,7 +332,7 @@ $ guard start --no-bundler-warning
 
 #### `-l`/`--latency` option
 
-Overwrite Listen default latency, usefull when your harddrive/system is slow.
+Overwrite Listen's default latency, useful when your hard-drive / system is slow.
 
 ```bash
 $ guard start -l 1.5
@@ -391,7 +348,6 @@ $ guard start -p
 $ guard start --force-polling
 ```
 
-<a name="usage-list" />
 ### List
 
 You can list the available Guards with the `list` task:
@@ -412,7 +368,6 @@ See also https://github.com/guard/guard/wiki/List-of-available-Guards
 * denotes ones already in your Guardfile
 ```
 
-<a name="usage-show" />
 ### Show
 
 You can show the structure of the groups and their Guards with the `show` task:
@@ -433,7 +388,6 @@ Group frontend:
 This shows the internal structure of the evaluated `Guardfile` or `.Guardfile`, with the `.guard.rb` file. You can
 read more about these files in the shared configuration section below.
 
-<a name="interactions" />
 Interactions
 ------------
 
@@ -471,7 +425,6 @@ This will reload only the Ronn Guard. You can also reload all Guards within a gr
 > backend reload
 ```
 
-<a name="interactions-readline-support" />
 ### Readline support
 
 With Readline enabled, you'll see a command prompt `>` when Guard is ready to accept a command. The command line
@@ -489,7 +442,6 @@ end
 Guard will automatically enable Readline support if your environment supports it, but you can disable Readline with the
 `interactor` DSL method or turn off completely with the `--no-interactions` option.
 
-<a name="interactions-signal" />
 ### Signals
 
 You can also interact with Guard by sending POSIX signals to the Guard process (all but Windows).
@@ -506,14 +458,12 @@ $ kill -USR1 <guard_pid>
 $ kill -USR2 <guard_pid>
 ```
 
-<a name="guardfile-dsl" />
 Guardfile DSL
 -------------
 
 The Guardfile DSL is evaluated as plain Ruby, so you can use normal Ruby code in your `Guardfile`.
 Guard itself provides the following DSL methods that can be used for configuration:
 
-<a name="guardfile-dsl-guard" />
 ### guard
 
 The `guard` method allows you to add a Guard to your toolchain and configure it by passing the
@@ -530,7 +480,6 @@ guard :coffeescript, :input => 'coffeescripts', :output => 'javascripts'
 guard :coffeescript, :input => 'specs', :output => 'specs'
 ```
 
-<a name="guardfile-dsl-watch" />
 ### watch
 
 The `watch` method allows you to define which files are watched by a Guard:
@@ -576,7 +525,6 @@ guard :shell do
 end
 ```
 
-<a name="guardfile-dsl-group" />
 ### group
 
 The `group` method allows you to group several Guards together. This comes in handy especially when you
@@ -604,7 +552,6 @@ $ guard -g specs
 
 Guards that don't belong to a group are considered global and are always run.
 
-<a name="guardfile-dsl-notification" />
 ### notification
 
 If you don't specify any notification configuration in your `Guardfile`, Guard goes through the list of available
@@ -641,7 +588,6 @@ or using the cli switch `-n`:
 notification :off
 ```
 
-<a name="guardfile-dsl-interactor" />
 ### interactor
 
 You can disable the interactor auto detection and for a specific implementation:
@@ -662,7 +608,6 @@ If you do not need the keyboard interactions with Guard at all, you can turn the
 interactor :off
 ```
 
-<a name="guardfile-dsl-callback" />
 ### callback
 
 The `callback` method allows you to execute arbitrary code before or after any of the `start`, `stop`, `reload`,
@@ -679,7 +624,6 @@ end
 Please see the [hooks and callbacks](https://github.com/guard/guard/wiki/Hooks-and-callbacks) page in the Guard wiki for
 more details.
 
-<a name="guardfile-dsl-ignore" />
 ### ignore
 
 The `ignore` method allows you to ignore specific paths. This comes is handy when you have large
@@ -690,7 +634,6 @@ Please note that method only accept regexps. More on the [Listen README](https:/
 ignore %r{^ignored/path/}, /public/
 ```
 
-<a name="guardfile-dsl-filter" />
 ### filter
 
 The `filter` method allows you to filter specific paths.
@@ -700,7 +643,6 @@ Please note that method only accept regexps. More on the [Listen README](https:/
 filter /\.txt$/, /.*\.zip/
 ```
 
-<a name="guardfile-dsl-example" />
 ### Example
 
 ```ruby
@@ -735,7 +677,6 @@ group :frontend do
 end
 ```
 
-<a name="shared-configurations" />
 Shared configurations
 ---------------------
 
@@ -753,7 +694,6 @@ guard :shell do
 end
 ```
 
-<a name="advanced-linux-system-configuration" />
 Advanced Linux system configuration
 -----------------------------------
 
@@ -782,7 +722,6 @@ sudo sysctl -p
 
 You may also need to pay attention to the values of `max_queued_events` and `max_user_instances`.
 
-<a name="create-a-guard" />
 Create a Guard
 --------------
 
@@ -814,8 +753,9 @@ README.md
 ```
 
 Your Guard main class `Guard::Yoyo` in `lib/guard/guard-yoyo.rb` must inherit from
-[Guard::Guard](http://rubydoc.info/github/guard/guard/master/Guard/Guard) and should overwrite at least the
-`#run_on_change` task methods.
+[Guard::Guard](http://rubydoc.info/github/guard/guard/master/Guard/Guard) and should implement at least the
+`#run_on_changes` task method. `#run_on_additions`, `#run_on_modifications` and `#run_on_removals` task methods
+could be use instead of `#run_on_changes` task method for more control about how changes are handled.
 
 Here is an example scaffold for `lib/guard/yoyo.rb`:
 
@@ -855,18 +795,11 @@ module Guard
     def run_all
     end
 
-    # Called on file(s) modifications that the Guard watches.
+    # Default behaviour on file(s) changes that the Guard watches.
     # @param [Array<String>] paths the changes files or paths
     # @raise [:task_has_failed] when run_on_change has failed
-    def run_on_change(paths)
-    end
-
-    # Called on file(s) deletions that the Guard watches.
-    # @param [Array<String>] paths the deleted files or paths
-    # @raise [:task_has_failed] when run_on_change has failed
-    def run_on_deletion(paths)
+    def run_on_changes(paths)
     end
-
   end
 end
 ```
@@ -884,7 +817,7 @@ module ::Guard
     def run_all
     end
 
-    def run_on_change(paths)
+    def run_on_changes(paths)
     end
   end
 end
@@ -893,7 +826,6 @@ end
 [@avdi](https://github.com/avdi) has a very cool inline Guard example in his blog post
 [A Guardfile for Redis](http://avdi.org/devblog/2011/06/15/a-guardfile-for-redis).
 
-<a name="programmatic-use-of-guard" />
 Programmatic use of Guard
 -------------------------
 
@@ -933,7 +865,6 @@ EOF
 Guard.start(:guardfile_contents => guardfile)
 ```
 
-<a name="file-an-issue" />
 File an issue
 -------------
 
@@ -954,7 +885,6 @@ When you file a bug, please try to follow these simple rules if applicable:
 
 **It's most likely that your bug gets resolved faster if you provide as much information as possible!**
 
-<a name="development" />
 Development [![Dependency Status](https://gemnasium.com/guard/guard.png?branch=master)](https://gemnasium.com/guard/guard)
 -----------
 

data/lib/guard.rb

@@ -406,8 +406,8 @@ module Guard
 
     # Deprecation message for the `no_vendor` start option
     NO_VENDOR_DEPRECATION = <<-EOS.gsub(/^\s*/, '')
-      Starting with Guard v1.1 the 'no_vendor' option is removed because the monitoring gems are now
-      a part of a new gem called Listen.
+      Starting with Guard v1.1 the 'no_vendor' option is removed because the monitoring
+      gems are now part of a new gem called Listen. (https://github.com/guard/listen)
 
       You can specify a custom version of any monitoring gem directly in your Gemfile
       if you want to overwrite Listen's default monitoring gems.

data/lib/guard/cli.rb

@@ -77,13 +77,13 @@ module Guard
     method_option :latency,
                   :type    => :numeric,
                   :aliases => '-l',
-                  :banner  => 'Overwrite Listen default latency'
+                  :banner  => 'Overwrite Listen\'s default latency'
     
     method_option :force_polling,
                   :type    => :boolean,
                   :default => false,
                   :aliases => '-p',
-                  :banner  => 'Force Listen polling listener usage'
+                  :banner  => 'Force usage of the Listen polling listener'
 
     # Start Guard by initialize the defined Guards and watch the file system.
     # This is the default task, so calling `guard` is the same as calling `guard start`.

data/lib/guard/guard.rb

@@ -2,8 +2,13 @@ module Guard
 
   # Base class that every Guard implementation must inherit from.
   #
-  # Guard will trigger the `start`, `stop`, `reload`, `run_all`, `run_on_change` and
-  # `run_on_deletion` task methods depending on user interaction and file modification.
+  # Guard will trigger the `start`, `stop`, `reload`, `run_all` and `run_on_changes`
+  # (`run_on_additions`, `run_on_modifications` and `run_on_removals`) task methods
+  # depending on user interaction and file modification.
+  #
+  # `run_on_changes` could be implemented to handle all the changes task case (additions,
+  # modifications, removals) in once, or each task can be implemented separatly with a
+  # specific behavior.
   #
   # In each of these Guard task methods you have to implement some work when you want to
   # support this kind of task. The return value of each Guard task method is not evaluated
@@ -81,16 +86,16 @@ module Guard
     # @raise [:task_has_failed] when start has failed
     # @return [Object] the task result
     #
-    def start
-    end
+    # def start
+    # end
 
     # Called when `stop|quit|exit|s|q|e + enter` is pressed (when Guard quits).
     #
     # @raise [:task_has_failed] when stop has failed
     # @return [Object] the task result
     #
-    def stop
-    end
+    # def stop
+    # end
 
     # Called when `reload|r|z + enter` is pressed.
     # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
@@ -98,8 +103,8 @@ module Guard
     # @raise [:task_has_failed] when reload has failed
     # @return [Object] the task result
     #
-    def reload
-    end
+    # def reload
+    # end
 
     # Called when just `enter` is pressed
     # This method should be principally used for long action like running all specs/tests/...
@@ -107,18 +112,17 @@ module Guard
     # @raise [:task_has_failed] when run_all has failed
     # @return [Object] the task result
     #
-    def run_all
-    end
+    # def run_all
+    # end
 
-    # Default behavious on file(s) changes that the Guard watches.
+    # Default behaviour on file(s) changes that the Guard watches.
     #
     # @param [Array<String>] paths the changes files or paths
     # @raise [:task_has_failed] when run_on_change has failed
     # @return [Object] the task result
     #
-    def run_on_changes(paths)
-      raise NotImplementedError
-    end
+    # def run_on_changes(paths)
+    # end
 
     # Called on file(s) additions that the Guard watches.
     #
@@ -126,9 +130,8 @@ module Guard
     # @raise [:task_has_failed] when run_on_change has failed
     # @return [Object] the task result
     #
-    def run_on_addtions(paths)
-      run_on_changes(paths)
-    end
+    # def run_on_additions(paths)
+    # end
 
     # Called on file(s) modifications that the Guard watches.
     #
@@ -136,9 +139,8 @@ module Guard
     # @raise [:task_has_failed] when run_on_change has failed
     # @return [Object] the task result
     #
-    def run_on_modifications(paths)
-      run_on_changes(paths)
-    end
+    # def run_on_modifications(paths)
+    # end
 
     # Called on file(s) removals that the Guard watches.
     #
@@ -146,20 +148,7 @@ module Guard
     # @raise [:task_has_failed] when run_on_change has failed
     # @return [Object] the task result
     #
-    def run_on_removals(paths)
-      run_on_changes(paths)
-    end
-
-    # @deprecated Use #run_on_modifications or #run_on_addtions instead
-    #
-    # def run_on_change(paths)
-    #   raise NotImplementedError
-    # end
-
-    # @deprecated Use #run_on_removals instead
-    #
-    # def run_on_deletion(paths)
-    #   raise NotImplementedError
+    # def run_on_removals(paths)
     # end
 
   end

data/lib/guard/notifiers/notifysend.rb

@@ -14,7 +14,8 @@ module Guard
 
       # Default options for the notify-send program
       DEFAULTS = {
-        :t => 3000 # Default timeout is 3000ms
+        :t => 3000, # Default timeout is 3000ms
+        :h => 'int:transient:1' # Automatically close the notification
       }
 
       # Full list of options supported by notify-send

data/lib/guard/runner.rb

@@ -9,7 +9,7 @@ module Guard
       Starting with Guard v1.1 the use of the 'run_on_change' method in the '%s' guard is deprecated.
 
       Please consider replacing that method-call with 'run_on_changes' if the type of change
-      is not important for your usecase or using either 'run_on_modifications' or 'run_on_addtions'
+      is not important for your usecase or using either 'run_on_modifications' or 'run_on_additions'
       based on the type of the changes you want to handle.
 
       For more information on how to update existing guards, please head over to:
@@ -48,6 +48,10 @@ module Guard
       end
     end
 
+    MODIFICATION_TASKS = [:run_on_modifications, :run_on_changes, :run_on_change]
+    ADDITION_TASKS     = [:run_on_additions, :run_on_changes, :run_on_change]
+    REMOVAL_TASKS      = [:run_on_removals, :run_on_changes, :run_on_deletion]
+
     # Runs the appropriate tasks on all registered guards
     # based on the passed changes.
     #
@@ -61,19 +65,11 @@ module Guard
         added_paths    = Watcher.match_files(guard, added)
         removed_paths  = Watcher.match_files(guard, removed)
 
-        if !modified_paths.empty? || !added_paths.empty? || !removed_paths.empty?
-          UI.clear
+        UI.clear if clearable?(guard, modified_paths, added_paths, removed_paths)
 
-          unless modified_paths.empty?
-            run_first_task_found(guard, [:run_on_modifications, :run_on_change], modified_paths)
-          end
-          unless added_paths.empty?
-            run_first_task_found(guard, [:run_on_addtions, :run_on_change], added_paths)
-          end
-          unless removed_paths.empty?
-            run_first_task_found(guard, [:run_on_removals, :run_on_deletion], removed_paths)
-          end
-        end
+        run_first_task_found(guard, MODIFICATION_TASKS, modified_paths) unless modified_paths.empty?
+        run_first_task_found(guard, ADDITION_TASKS, added_paths) unless added_paths.empty?
+        run_first_task_found(guard, REMOVAL_TASKS, removed_paths) unless removed_paths.empty?
       end
     end
 
@@ -97,8 +93,8 @@ module Guard
             result
           end
 
-        rescue NotImplementedError => ex
-          raise ex
+        rescue NoMethodError
+          # Do nothing
         rescue Exception => ex
           UI.error("#{ guard.class.name } failed to achieve its <#{ task.to_s }>, exception was:" +
                    "\n#{ ex.class }: #{ ex.message }\n#{ ex.backtrace.join("\n") }")
@@ -129,7 +125,7 @@ module Guard
       group.options[:halt_on_fail] ? :no_catch : :task_has_failed
     end
 
-    private
+  private
 
     # Tries to run the first implemented task by a given guard
     # from a collection of tasks.
@@ -139,16 +135,13 @@ module Guard
     # @param [Object] task_param the param to pass to each task
     #
     def run_first_task_found(guard, tasks, task_param)
-      enum = tasks.to_enum
-
-      begin
-        task = enum.next
-        UI.debug "Trying to run #{ guard.class.name }##{ task.to_s } with #{ task_param.inspect }"
-        run_supervised_task(guard, task, task_param)
-      rescue StopIteration
-        # Do nothing
-      rescue NotImplementedError
-        retry
+      tasks.each do |task|
+        if guard.respond_to?(task)
+          run_supervised_task(guard, task, task_param)
+          break
+        else
+          UI.debug "Trying to run #{ guard.class.name }##{ task.to_s } with #{ task_param.inspect }"
+        end
       end
     end
 
@@ -175,5 +168,19 @@ module Guard
       end
     end
 
+    # Logic to know if the UI can be cleared or not in the run_on_changes method
+    # based on the guard and the changes.
+    #
+    # @param [Guard::Guard] guard the guard where run_on_changes is called
+    # @param [Array<String>] modified_paths the modified paths.
+    # @param [Array<String>] added_paths the added paths.
+    # @param [Array<String>] removed_paths the removed paths.
+    #
+    def clearable?(guard, modified_paths, added_paths, removed_paths)
+      (MODIFICATION_TASKS.any? { |task| guard.respond_to?(task) } && !modified_paths.empty?) ||
+      (ADDITION_TASKS.any? { |task| guard.respond_to?(task) } && !added_paths.empty?) ||
+      (REMOVAL_TASKS.any? { |task| guard.respond_to?(task) } && !removed_paths.empty?)
+    end
+
   end
 end

data/lib/guard/version.rb

@@ -1,4 +1,4 @@
 module Guard
   # The current gem version of Guard
-  VERSION = '1.1.0.alpha.2'
+  VERSION = '1.1.0.beta'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: guard
 version: !ruby/object:Gem::Version
-  version: 1.1.0.alpha.2
+  version: 1.1.0.beta
   prerelease: 6
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-14 00:00:00.000000000 Z
+date: 2012-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor