guard 1.0.3 → 1.1.0.alpha

data/CHANGELOG.md

@@ -1,9 +1,3 @@
-## 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

@@ -34,7 +34,8 @@ Contents
   * [notification](#guardfile-dsl-notification)
   * [interactor](#guardfile-dsl-interactor)
   * [callback](#guardfile-dsl-callback)
-  * [ignore_paths](#guardfile-dsl-ignore-paths)
+  * [ignore](#guardfile-dsl-ignore)
+  * [filter](#guardfile-dsl-filter)
   * [Example](#guardfile-dsl-example)
 * [Shared configurations](#shared-configurations)
 * [Advanced Linux system configuration](#advanced-linux-system-configuration)
@@ -47,13 +48,9 @@ Contents
 Features
 --------
 
-* [FSEvent](http://en.wikipedia.org/wiki/FSEvents) support on Mac OS X.
-* [Inotify](http://en.wikipedia.org/wiki/Inotify) support on Linux.
-* [Directory Change Notification](http://msdn.microsoft.com/en-us/library/aa365261\(VS.85\).aspx) support on Windows.
-* Polling on the other operating systems.
-* Automatic and super fast file modification detection when polling is not used.
-  Even new and deleted files are detected.
+* File system changes handled by our awesome [Listen](https://github.com/guard/listen) gem.
 * Support for visual system notifications.
+* 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" />
@@ -358,40 +355,40 @@ $ guard --guardfile ~/.your_global_guardfile
 $ guard -G ~/.your_global_guardfile # shortcut
 ```
 
-#### `-A`/`--watch-all-modifications` option
+#### `-i`/`--no-interactions` option
 
-Guard can optionally watch all file modifications like moves or deletions with:
+Turn off completely any Guard terminal interactions with:
 
 ```bash
-$ guard start -A
-$ guard start --watch-all-modifications
+$ guard start -i
+$ guard start --no-interactions
 ```
 
-#### `-i`/`--no-interactions` option
+#### `-B`/`--no-bundler-warning` option
 
-Turn off completely any Guard terminal interactions with:
+Skip Bundler warning when a Gemfile exists in the project directory but Guard is not run with Bundler.
 
 ```bash
-$ guard start -i
-$ guard start --no-interactions
+$ guard start -B
+$ guard start --no-bundler-warning
 ```
 
-#### `-I`/`--no-vendor` option
+#### `-l`/`--latency` option
 
-Ignore the use of vendored gems with:
+Overwrite Listen default latency, usefull when your harddrive/system is slow.
 
 ```bash
-$ guard start -I
-$ guard start --no-vendor
+$ guard start -l 1.5
+$ guard start --latency 1.5
 ```
 
-#### `-B`/`--no-bundler-warning` option
+#### `-p`/`--force-polling` option
 
-Skip Bundler warning when a Gemfile exists in the project directory but Guard is not run with Bundler.
+Force Listen polling listener usage.
 
 ```bash
-$ guard start -B
-$ guard start --no-bundler-warning
+$ guard start -p
+$ guard start --force-polling
 ```
 
 <a name="usage-list" />
@@ -682,22 +679,33 @@ 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-paths" />
-### ignore_paths
+<a name="guardfile-dsl-ignore" />
+### ignore
+
+The `ignore` method allows you to ignore specific paths. This comes is handy when you have large
+amounts of non-source data in you project. By default [`.rbx`, `.bundle`, `.git`, `.svn`, `log`, `tmp`, `vendor`](https://github.com/guard/listen/blob/master/lib/listen/directory_record.rb#L14) are ignored.
+Please note that method only accept regexps. More on the [Listen README](https://github.com/guard/listen#the-patterns-for-filtering-and-ignoring-paths).
+
+```ruby
+ignore %r{^ignored/path/}, /public/
+```
+
+<a name="guardfile-dsl-filter" />
+### filter
 
-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.
+The `filter` method allows you to filter specific paths.
+Please note that method only accept regexps. More on the [Listen README](https://github.com/guard/listen#the-patterns-for-filtering-and-ignoring-paths).
 
 ```ruby
-ignore_paths 'public'
+filter /\.txt$/, /.*\.zip/
 ```
 
 <a name="guardfile-dsl-example" />
 ### Example
 
 ```ruby
-ignore_paths 'foo', 'bar'
+ignore %r{^ignored/path/}, /public/
+filter /\.txt$/, /.*\.zip/
 
 notification :growl_notify
 notification :gntp, :host => '192.168.1.5'

data/lib/guard.rb

@@ -1,4 +1,5 @@
 require 'thread'
+require 'listen'
 
 # Guard is the main module for all Guard related modules and classes.
 # Also other Guard implementation should use this namespace.
@@ -6,13 +7,14 @@ require 'thread'
 module Guard
 
   autoload :UI,           'guard/ui'
+  autoload :Guardfile,    'guard/guardfile'
   autoload :Dsl,          'guard/dsl'
   autoload :DslDescriber, 'guard/dsl_describer'
   autoload :Group,        'guard/group'
   autoload :Interactor,   'guard/interactor'
-  autoload :Listener,     'guard/listener'
   autoload :Watcher,      'guard/watcher'
   autoload :Notifier,     'guard/notifier'
+  autoload :Runner,       'guard/runner'
   autoload :Hook,         'guard/hook'
 
   # The Guardfile template for `guard init`
@@ -21,63 +23,7 @@ module Guard
   HOME_TEMPLATES = File.expand_path('~/.guard/templates')
 
   class << self
-    attr_accessor :options, :interactor, :listener, :lock
-
-    # Creates the initial Guardfile template when it does not
-    # already exist.
-    #
-    # @see Guard::CLI.init
-    #
-    # @param [Hash] options The options for creating a Guardfile
-    # @option options [Boolean] :abort_on_existence Whether to abort or not when a Guardfile already exists
-    #
-    def create_guardfile(options = {})
-      if !File.exist?('Guardfile')
-        ::Guard::UI.info "Writing new Guardfile to #{ Dir.pwd }/Guardfile"
-        FileUtils.cp(GUARDFILE_TEMPLATE, 'Guardfile')
-      elsif options[:abort_on_existence]
-        ::Guard::UI.error "Guardfile already exists at #{ Dir.pwd }/Guardfile"
-        abort
-      end
-    end
-
-    # Adds the Guardfile template of a Guard implementation
-    # to an existing Guardfile.
-    #
-    # @see Guard::CLI.init
-    #
-    # @param [String] guard_name the name of the Guard or template to initialize
-    #
-    def initialize_template(guard_name)
-      guard_class = ::Guard.get_guard_class(guard_name, true)
-
-      if guard_class
-        guard_class.init(guard_name)
-      elsif File.exist?(File.join(HOME_TEMPLATES, guard_name))
-        content  = File.read('Guardfile')
-        template = File.read(File.join(HOME_TEMPLATES, guard_name))
-
-        File.open('Guardfile', 'wb') do |f|
-          f.puts(content)
-          f.puts("")
-          f.puts(template)
-        end
-
-        ::Guard::UI.info "#{ guard_name } template added to Guardfile, feel free to edit it"
-      else
-        const_name  = guard_name.downcase.gsub('-', '')
-        UI.error "Could not load 'guard/#{ guard_name.downcase }' or '~/.guard/templates/#{ guard_name.downcase }' or find class Guard::#{ const_name.capitalize }"
-      end
-    end
-
-    # Adds the templates of all installed Guard implementations
-    # to an existing Guardfile.
-    #
-    # @see Guard::CLI.init
-    #
-    def initialize_all_templates
-      guard_gem_names.each {|g| initialize_template(g) }
-    end
+    attr_accessor :options, :interactor, :runner, :listener, :lock
 
     # Initialize the Guard singleton:
     #
@@ -91,98 +37,97 @@ module Guard
     # @option options [Array<String>] group the list of groups to start
     # @option options [String] watchdir the director to watch
     # @option options [String] guardfile the path to the Guardfile
-    # @option options [Boolean] watch_all_modifications watches all file modifications if true
+    # @deprecated @option options [Boolean] watch_all_modifications watches all file modifications if true
+    # @deprecated @option options [Boolean] no_vendor ignore vendored dependencies
     #
     def setup(options = {})
       @lock       = Mutex.new
       @options    = options
-      @guards     = []
-      self.reset_groups
-      @listener   = Listener.select_and_init(options)
+      @watchdir   = (options[:watchdir] && File.expand_path(options[:watchdir])) || Dir.pwd
+      @runner     = Runner.new
 
-      if Signal.list.keys.include?('USR1')
-        Signal.trap('USR1') { ::Guard.pause unless @listener.paused? }
-      end
+      UI.clear
+      deprecated_options_warning
 
-      if Signal.list.keys.include?('USR2')
-        Signal.trap('USR2') { ::Guard.pause if @listener.paused? }
-      end
+      setup_groups
+      setup_guards
+      setup_listener
+      setup_signal_traps
 
-      UI.clear if @options[:clear]
       debug_command_execution if @options[:verbose]
 
+      Dsl.evaluate_guardfile(options)
+      UI.error 'No guards found in Guardfile, please add at least one.' if @guards.empty?
+
+      runner.deprecation_warning # Guard deprecation go here
+
+      setup_notifier
+      setup_interactor
+
       self
     end
 
-    # Smart accessor for retrieving a specific guard or several guards at once.
+    # Initialize the groups array with the `:default` group.
     #
     # @see Guard.groups
     #
-    # @example Filter Guards by String or Symbol
-    #   Guard.guards('rspec')
-    #   Guard.guards(:rspec)
+    def setup_groups
+      @groups = [Group.new(:default)]
+    end
+
+    # Initialize the guards array to an empty array.
     #
-    # @example Filter Guards by Regexp
-    #   Guard.guards(/rsp.+/)
+    # @see Guard.guards
     #
-    # @example Filter Guards by Hash
-    #   Guard.guards({ :name => 'rspec', :group => 'backend' })
+    def setup_guards
+      @guards = []
+    end
+
+    # Sets up traps to catch signlas used to control Guard.
     #
-    # @param [String, Symbol, Regexp, Hash] filter the filter to apply to the Guards
-    # @return [Array<Guard>] the filtered Guards
+    # Currently two signals are cought:
+    # - `USR1` which pauses listening to changes.
+    # - `USR2` which resumes listening to changes.
     #
-    def guards(filter = nil)
-      @guards ||= []
+    def setup_signal_traps
+      if Signal.list.keys.include?('USR1')
+        Signal.trap('USR1') { ::Guard.pause unless @listener.paused? }
+      end
 
-      case filter
-      when String, Symbol
-        @guards.find { |guard| guard.class.to_s.downcase.sub('guard::', '') == filter.to_s.downcase.gsub('-', '') }
-      when Regexp
-        @guards.find_all { |guard| guard.class.to_s.downcase.sub('guard::', '') =~ filter }
-      when Hash
-        filter.inject(@guards) do |matches, (k, v)|
-          if k.to_sym == :name
-            matches.find_all { |guard| guard.class.to_s.downcase.sub('guard::', '') == v.to_s.downcase.gsub('-', '') }
-          else
-            matches.find_all { |guard| guard.send(k).to_sym == v.to_sym }
-          end
-        end
-      else
-        @guards
+      if Signal.list.keys.include?('USR2')
+        Signal.trap('USR2') { ::Guard.pause if @listener.paused? }
       end
     end
 
-    # Smart accessor for retrieving a specific group or several groups at once.
-    #
-    # @see Guard.guards
+    # Initializes the listener and registers a callback for changes.
     #
-    # @example Filter groups by String or Symbol
-    #   Guard.groups('backend')
-    #   Guard.groups(:backend)
-    #
-    # @example Filter groups by Regexp
-    #   Guard.groups(/(back|front)end/)
-    #
-    # @param [String, Symbol, Regexp] filter the filter to apply to the Groups
-    # @return [Array<Group>] the filtered groups
-    #
-    def groups(filter = nil)
-      case filter
-      when String, Symbol
-        @groups.find { |group| group.name == filter.to_sym }
-      when Regexp
-        @groups.find_all { |group| group.name.to_s =~ filter }
-      else
-        @groups
+    def setup_listener
+      listener_callback = lambda do |modified, added, removed|
+        Dsl.reevaluate_guardfile if Watcher.match_guardfile?(modified)
+        runner.run_on_changes(modified, added, removed)
       end
+
+      listener_options = { :relative_paths => true }
+      %w[latency force_polling].each do |option|
+        listener_options[option.to_sym] = options[option] if options.key?(option)
+      end
+
+      @listener = Listen.to(@watchdir, listener_options).change(&listener_callback)
     end
 
-    # Initialize the groups array with the `:default` group.
+    # Enables or disables the notifier based on user's configurations.
     #
-    # @see Guard.groups
+    def setup_notifier
+      options[:notify] && ENV['GUARD_NOTIFY'] != 'false' ? Notifier.turn_on : Notifier.turn_off
+    end
+
+    # Initializes the interactor unless the user has specified not to.
     #
-    def reset_groups
-      @groups = [Group.new(:default)]
+    def setup_interactor
+      unless options[:no_interactions]
+        @interactor = Interactor.fabricate
+        @interactor.start if @interactor
+      end
     end
 
     # Start Guard by evaluate the `Guardfile`, initialize the declared Guards
@@ -204,40 +149,20 @@ module Guard
     #
     def start(options = {})
       setup(options)
+      UI.info "Guard is now watching at '#{ @watchdir }'"
 
-      Dsl.evaluate_guardfile(options)
-      UI.error 'No guards found in Guardfile, please add at least one.' if ::Guard.guards.empty?
-
-      options[:notify] && ENV['GUARD_NOTIFY'] != 'false' ? Notifier.turn_on : Notifier.turn_off
-
-      listener.on_change do |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 }'"
-
-      run_on_guards do |guard|
-        run_supervised_task(guard, :start)
-      end
-
-      unless options[:no_interactions]
-        @interactor = Interactor.fabricate
-        @interactor.start if @interactor
-      end
+      interactor.start if interactor
 
+      runner.run(:start)
       listener.start
     end
 
     # Stop Guard listening to file changes
     #
     def stop
-      run_on_guards do |guard|
-        run_supervised_task(guard, :stop)
-      end
-
       interactor.stop if interactor
       listener.stop
+      runner.run(:stop)
 
       UI.info 'Bye bye...', :reset => true
     end
@@ -247,11 +172,8 @@ module Guard
     # @param [Hash] scopes an hash with a guard or a group scope
     #
     def reload(scopes)
-      run do
-        run_on_guards(scopes) do |guard|
-          run_supervised_task(guard, :reload)
-        end
-      end
+      UI.clear
+      runner.run(:reload, scopes)
     end
 
     # Trigger `run_all` on all Guards currently enabled.
@@ -259,11 +181,8 @@ module Guard
     # @param [Hash] scopes an hash with a guard or a group scope
     #
     def run_all(scopes)
-      run do
-        run_on_guards(scopes) do |guard|
-          run_supervised_task(guard, :run_all)
-        end
-      end
+      UI.clear
+      runner.run(:run_all, scopes)
     end
 
     # Pause Guard listening to file changes.
@@ -271,159 +190,73 @@ module Guard
     def pause
       if listener.paused?
         UI.info 'Un-paused files modification listening', :reset => true
-        listener.clear_changed_files
-        listener.run
+        listener.unpause
       else
         UI.info 'Paused files modification listening', :reset => true
         listener.pause
       end
     end
 
-    # Trigger `run_on_change` on all Guards currently enabled.
+    # Smart accessor for retrieving a specific guard or several guards at once.
     #
-    def run_on_change(files)
-      run do
-        run_on_guards do |guard|
-          run_on_change_task(files, guard)
-        end
-      end
-    end
-
-    # Run a block where the listener and the interactor is
-    # blocked.
+    # @see Guard.groups
     #
-    # @yield the block to run
+    # @example Filter Guards by String or Symbol
+    #   Guard.guards('rspec')
+    #   Guard.guards(:rspec)
     #
-    def run
-      UI.clear if options[:clear]
-
-      lock.synchronize do
-        begin
-          interactor.stop if interactor
-          yield
-        rescue Interrupt
-        end
-
-        interactor.start if interactor
-      end
-    end
-
-    # Loop through all groups and run the given task for each Guard.
+    # @example Filter Guards by Regexp
+    #   Guard.guards(/rsp.+/)
     #
-    # Stop the task run for the all Guards within a group if one Guard
-    # throws `:task_has_failed`.
+    # @example Filter Guards by Hash
+    #   Guard.guards({ :name => 'rspec', :group => 'backend' })
     #
-    # @param [Hash] scopes an hash with a guard or a group scope
-    # @yield the task to run
+    # @param [String, Symbol, Regexp, Hash] filter the filter to apply to the Guards
+    # @return [Array<Guard>] the filtered Guards
     #
-    def run_on_guards(scopes = {})
-      if scope_guard = scopes[:guard]
-        yield(scope_guard)
-      else
-        groups = scopes[:group] ? [scopes[:group]] : @groups
-        groups.each do |group|
-          catch :task_has_failed do
-            guards(:group => group.name).each do |guard|
-              yield(guard)
-            end
+    def guards(filter = nil)
+      @guards ||= []
+
+      case filter
+      when String, Symbol
+        @guards.find { |guard| guard.class.to_s.downcase.sub('guard::', '') == filter.to_s.downcase.gsub('-', '') }
+      when Regexp
+        @guards.find_all { |guard| guard.class.to_s.downcase.sub('guard::', '') =~ filter }
+      when Hash
+        filter.inject(@guards) do |matches, (k, v)|
+          if k.to_sym == :name
+            matches.find_all { |guard| guard.class.to_s.downcase.sub('guard::', '') == v.to_s.downcase.gsub('-', '') }
+          else
+            matches.find_all { |guard| guard.send(k).to_sym == v.to_sym }
           end
         end
+      else
+        @guards
       end
     end
 
-    # Run the `:run_on_change` task. When the option `:watch_all_modifications` is set,
-    # the task is split to run changed paths on {Guard::Guard#run_on_change}, whereas
-    # deleted paths run on {Guard::Guard#run_on_deletion}.
-    #
-    # @param [Array<String>] files the list of files to pass to the task
-    # @param [Guard::Guard] guard the guard to run
-    # @raise [:task_has_failed] when task has failed
-    #
-    def run_on_change_task(files, guard)
-      paths = Watcher.match_files(guard, files)
-      changes = changed_paths(paths)
-      deletions = deleted_paths(paths)
-
-      unless changes.empty?
-        UI.debug "#{ guard.class.name }#run_on_change with #{ changes.inspect }"
-        run_supervised_task(guard, :run_on_change, changes)
-      end
-
-      unless deletions.empty?
-        UI.debug "#{ guard.class.name }#run_on_deletion with #{ deletions.inspect }"
-        run_supervised_task(guard, :run_on_deletion, deletions)
-      end
-    end
-
-    # Detects the paths that have changed.
-    #
-    # Deleted paths are prefixed by an exclamation point.
-    # @see Guard::Listener#modified_files
-    #
-    # @param [Array<String>] paths the watched paths
-    # @return [Array<String>] the changed paths
-    #
-    def changed_paths(paths)
-      paths.select { |f| !f.respond_to?(:start_with?) || !f.start_with?('!') }
-    end
-
-    # Detects the paths that have been deleted.
-    #
-    # Deleted paths are prefixed by an exclamation point.
-    # @see Guard::Listener#modified_files
-    #
-    # @param [Array<String>] paths the watched paths
-    # @return [Array<String>] the deleted paths
-    #
-    def deleted_paths(paths)
-      paths.select { |f| f.respond_to?(:start_with?) && f.start_with?('!') }.map { |f| f.slice(1..-1) }
-    end
-
-    # Run a Guard task, but remove the Guard when his work leads to a system failure.
-    #
-    # When the Group has `:halt_on_fail` disabled, we've to catch `:task_has_failed`
-    # here in order to avoid an uncaught throw error.
+    # Smart accessor for retrieving a specific group or several groups at once.
     #
-    # @param [Guard::Guard] guard the Guard to execute
-    # @param [Symbol] task the task to run
-    # @param [Array] args the arguments for the task
-    # @raise [:task_has_failed] when task has failed
+    # @see Guard.guards
     #
-    def run_supervised_task(guard, task, *args)
-      catch guard_symbol(guard) do
-        guard.hook("#{ task }_begin", *args)
-        result = guard.send(task, *args)
-        guard.hook("#{ task }_end", result)
-
-        result
-      end
-
-    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") }")
-
-      guards.delete guard
-      UI.info("\n#{ guard.class.name } has just been fired")
-
-      ex
-    end
-
-    # Get the symbol we have to catch when running a supervised task.
-    # If we are within a Guard group that has the `:halt_on_fail`
-    # option set, we do NOT catch it here, it will be catched at the
-    # group level.
+    # @example Filter groups by String or Symbol
+    #   Guard.groups('backend')
+    #   Guard.groups(:backend)
     #
-    # @see .run_on_guards
+    # @example Filter groups by Regexp
+    #   Guard.groups(/(back|front)end/)
     #
-    # @param [Guard::Guard] guard the Guard to execute
-    # @return [Symbol] the symbol to catch
+    # @param [String, Symbol, Regexp] filter the filter to apply to the Groups
+    # @return [Array<Group>] the filtered groups
     #
-    def guard_symbol(guard)
-      if guard.group.class == Symbol
-        group = groups(guard.group)
-        group.options[:halt_on_fail] ? :no_catch : :task_has_failed
+    def groups(filter = nil)
+      case filter
+      when String, Symbol
+        @groups.find { |group| group.name == filter.to_sym }
+      when Regexp
+        @groups.find_all { |group| group.name.to_s =~ filter }
       else
-        :task_has_failed
+        @groups
       end
     end
 
@@ -463,6 +296,25 @@ module Guard
       group
     end
 
+    # Runs a block where the interactor is
+    # blocked and execution is synchronized
+    # to avoid state inconsistency.
+    #
+    # @yield the block to run
+    #
+    def within_preserved_state
+      lock.synchronize do
+        begin
+          interactor.stop if interactor
+          @result = yield
+        rescue Interrupt
+        end
+
+        interactor.start if interactor
+      end
+      @result
+    end
+
     # Tries to load the Guard main class. This transforms the supplied Guard
     # name into a class name:
     #
@@ -545,5 +397,26 @@ module Guard
       end
     end
 
+    # Deprecation message for the `watch_all_modifications` start option
+    WATCH_ALL_MODIFICATIONS_DEPRECATION = <<-EOS.gsub(/^\s*/, '')
+      Starting with Guard v1.1 the 'watch_all_modifications' option is removed and is now always on.
+    EOS
+
+    # 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.
+
+      You can specify a custom version of any monitoring gem directly in your Gemfile
+      if you want to overwrite Listen's default monitoring gems.
+    EOS
+
+    # Displays a warning for each deprecated options used.
+    #
+    def deprecated_options_warning
+      ::Guard::UI.deprecation(WATCH_ALL_MODIFICATIONS_DEPRECATION) if options[:watch_all_modifications]
+      ::Guard::UI.deprecation(NO_VENDOR_DEPRECATION) if options[:no_vendor]
+    end
+
   end
 end