guard 1.0.3 → 1.1.0.alpha

data/lib/guard/cli.rb

@@ -47,17 +47,19 @@ module Guard
                   :aliases => '-G',
                   :banner  => 'Specify a Guardfile'
 
+    # DEPRECATED
     method_option :no_vendor,
                   :type    => :boolean,
                   :default => false,
                   :aliases => '-I',
-                  :banner  => 'Ignore vendored dependencies'
+                  :banner  => 'DEPRECATED: Ignore vendored dependencies'
 
+    # DEPRECATED
     method_option :watch_all_modifications,
                   :type => :boolean,
                   :default => false,
                   :aliases => '-A',
-                  :banner => 'Watch for all file modifications including moves and deletions'
+                  :banner => 'DEPRECATED: Watch for all file modifications including moves and deletions'
 
     method_option :no_interactions,
                   :type => :boolean,
@@ -71,6 +73,18 @@ module Guard
                   :aliases => '-B',
                   :banner => 'Turn off warning when Bundler is not present'
 
+    # Listen options
+    method_option :latency,
+                  :type    => :numeric,
+                  :aliases => '-l',
+                  :banner  => 'Overwrite Listen default latency'
+    
+    method_option :force_polling,
+                  :type    => :boolean,
+                  :default => false,
+                  :aliases => '-p',
+                  :banner  => 'Force Listen polling listener usage'
+
     # 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/dsl.rb

@@ -6,8 +6,8 @@ module Guard
   # The main keywords of the DSL are `guard` and `watch`. These are necessary to define
   # the used Guards and the file changes they are watching.
   #
-  # You can optionally group the Guards with the `group` keyword and ignore certain paths
-  # with the `ignore_paths` keyword.
+  # You can optionally group the Guards with the `group` keyword and ignore and filter certain paths
+  # with the `ignore` and `filter` keywords.
   #
   # You can set your preferred system notification library with `notification` and pass
   # some optional configuration options for the library. If you don't configure a library,
@@ -82,6 +82,15 @@ module Guard
   #   end
   #
   class Dsl
+
+    # Deprecation message for the `ignore_paths` method
+    IGNORE_PATHS_DEPRECATION = <<-EOS.gsub(/^\s*/, '')
+      Starting with Guard v1.1 the use of the 'ignore_paths' Guardfile dsl method is deprecated.
+
+      Please replace that method with the better 'ignore' or/and 'filter' methods.
+      Documentation on the README: https://github.com/guard/guard#guardfile-dsl-ignore
+    EOS
+
     class << self
 
       @@options = nil
@@ -105,23 +114,18 @@ module Guard
       # Re-evaluate the `Guardfile` to update the current Guard configuration.
       #
       def reevaluate_guardfile
-        ::Guard.run do
-          before_reevaluate_guardfile
-          Dsl.evaluate_guardfile(@@options)
-          after_reevaluate_guardfile
-        end
+        before_reevaluate_guardfile
+        Dsl.evaluate_guardfile(@@options)
+        after_reevaluate_guardfile
       end
 
       # Stop Guards and clear internal state
       # before the Guardfile will be re-evaluated.
       #
       def before_reevaluate_guardfile
-        ::Guard.run_on_guards do |guard|
-          ::Guard.run_supervised_task(guard, :stop)
-        end
-
+        ::Guard.runner.run(:stop)
         ::Guard.guards.clear
-        ::Guard.reset_groups
+        ::Guard.setup_groups
         ::Guard::Notifier.clear_notifications
 
         @@options.delete(:guardfile_contents)
@@ -140,9 +144,7 @@ module Guard
           ::Guard::UI.info(msg)
           ::Guard::Notifier.notify(msg, :title => 'Guard re-evaluate')
 
-          ::Guard.run_on_guards do |guard|
-            ::Guard.run_supervised_task(guard, :start)
-          end
+          ::Guard.runner.run(:start)
         end
       end
 
@@ -421,18 +423,37 @@ module Guard
       @callbacks << { :events => events, :listener => listener }
     end
 
-    # Ignore certain paths globally.
+    # @deprecated Ignore certain paths globally.
     #
     # @example Ignore some paths
     #   ignore_paths ".git", ".svn"
     #
     # @param [Array] paths the list of paths to ignore
     #
-    # @see Guard::Listener
-    #
     def ignore_paths(*paths)
-      UI.info "Ignoring paths: #{ paths.join(', ') }"
-      ::Guard.listener.ignore_paths.push(*paths)
+      UI.deprecation(IGNORE_PATHS_DEPRECATION)
+    end
+
+    # Ignore certain patterns paths globally.
+    #
+    # @example Ignore some paths
+    #   ignore %r{^ignored/path/}, /man/
+    #
+    # @param [Regexp] regexp a pattern for ignoring paths
+    #
+    def ignore(*regexps)
+      ::Guard.listener = ::Guard.listener.ignore(*regexps)
+    end
+
+    # Filter certain patterns paths globally.
+    #
+    # @example Filter some files
+    #   ignore /\.txt$/, /.*\.zip/
+    #
+    # @param [Regexp] regexp a pattern for filtering paths
+    #
+    def filter(*regexps)
+      ::Guard.listener = ::Guard.listener.filter(*regexps)
     end
 
   end

data/lib/guard/dsl_describer.rb

@@ -2,7 +2,7 @@ require 'guard/dsl'
 
 module Guard
 
-  autoload :UI,    'guard/ui'
+  autoload :UI, 'guard/ui'
 
   # The DslDescriber overrides methods to create an internal structure
   # of the Guardfile that is used in some inspection utility methods

data/lib/guard/group.rb

@@ -20,7 +20,7 @@ module Guard
 
     attr_accessor :name, :options
 
-    # Initialize a Group.
+    # Initializes a Group.
     #
     # @param [String] name the name of the group
     # @param [Hash] options the group options

data/lib/guard/guard.rb

@@ -38,7 +38,7 @@ module Guard
 
     attr_accessor :watchers, :options, :group
 
-    # Initialize a Guard.
+    # Initializes a Guard.
     #
     # @param [Array<Guard::Watcher>] watchers the Guard file watchers
     # @param [Hash] options the custom Guard options
@@ -106,24 +106,58 @@ module Guard
     def run_all
     end
 
+    # Default behavious 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
+
+    # Called on file(s) additions 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_addtions(paths)
+      run_on_changes(paths)
+    end
+
     # Called on file(s) modifications 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_change(paths)
+    def run_on_modifications(paths)
+      run_on_changes(paths)
     end
 
-    # Called on file(s) deletions that the Guard watches.
+    # Called on file(s) removals that the Guard watches.
     #
-    # @param [Array<String>] paths the deleted files or paths
+    # @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_deletion(paths)
+    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
+    # end
+
   end
 
 end

data/lib/guard/guardfile.rb

@@ -0,0 +1,70 @@
+module Guard
+
+  # The Guardfile is responsible for generating the Guardfile
+  # and adding guards' template into it.
+  #
+  # @see Guard::CLI
+  #
+  class Guardfile
+
+    class << self
+
+      # 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.guard_gem_names.each { |g| initialize_template(g) }
+      end
+
+    end
+  end
+end

data/lib/guard/runner.rb

@@ -0,0 +1,179 @@
+module Guard
+
+  # The runner is responsible for running all methods defined on each guards.
+  #
+  class Runner
+
+    # Deprecation message for the `run_on_change` method
+    RUN_ON_CHANGE_DEPRECATION = <<-EOS.gsub(/^\s*/, '')
+      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'
+      based on the type of the changes you want to handle.
+
+      For more information on how to update existing guards, please head over to:
+      https://github.com/guard/guard/wiki/Upgrade-guide-for-existing-guards-to-Guard-v1.1
+    EOS
+
+    # Deprecation message for the `run_on_deletion` method
+    RUN_ON_DELETION_DEPRECATION = <<-EOS.gsub(/^\s*/, '')
+      Starting with Guard v1.1 the use of the 'run_on_deletion' method in the '%s' guard is deprecated.
+
+      Please consider replacing that method-call with 'run_on_removals' for future proofing your code.
+
+      For more information on how to update existing guards, please head over to:
+      https://github.com/guard/guard/wiki/Upgrade-guide-for-existing-guards-to-Guard-v1.1
+    EOS
+
+    # Displays a warning for each deprecated-method used is any registered guard.
+    #
+    def deprecation_warning
+      ::Guard.guards.each do |guard|
+        UI.deprecation(RUN_ON_CHANGE_DEPRECATION % guard.class.name)   if guard.respond_to?(:run_on_change)
+        UI.deprecation(RUN_ON_DELETION_DEPRECATION % guard.class.name) if guard.respond_to?(:run_on_deletion)
+      end
+    end
+
+    # Runs a Guard-task on all registered guards.
+    #
+    # @param [Symbol] task the task to run
+    # @param [Hash] scope either the guard or the group to run the task on
+    #
+    # @see self.run_supervised_task
+    #
+    def run(task, scopes = {})
+      scoped_guards(scopes) do |guard|
+        run_supervised_task(guard, task)
+      end
+    end
+
+    # Runs the appropriate tasks on all registered guards
+    # based on the passed changes.
+    #
+    # @param [Array<String>] modified the modified paths.
+    # @param [Array<String>] added the added paths.
+    # @param [Array<String>] removed the removed paths.
+    #
+    def run_on_changes(modified, added, removed)
+      scoped_guards do |guard|
+        modified_paths = Watcher.match_files(guard, modified)
+        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
+
+          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
+      end
+    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.
+    #
+    # @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
+    #
+    def run_supervised_task(guard, task, *args)
+      ::Guard.within_preserved_state do
+        begin
+          catch Runner.stopping_symbol_for(guard) do
+            guard.hook("#{ task }_begin", *args)
+            result = guard.send(task, *args)
+            guard.hook("#{ task }_end", result)
+            result
+          end
+
+        rescue NotImplementedError => ex
+          raise ex
+        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") }")
+
+          ::Guard.guards.delete guard
+          UI.info("\n#{ guard.class.name } has just been fired")
+
+          ex
+        end
+      end
+    end
+
+    # Returns the symbol that has to be caught when running a supervised task.
+    #
+    # @note If a Guard group is being run and it has the `:halt_on_fail`
+    #   option set, this method returns :no_catch as it will be caught at the
+    #   group level.
+    # @see .scoped_guards
+    #
+    # @param [Guard::Guard] guard the Guard to execute
+    #
+    # @return [Symbol] the symbol to catch
+    #
+    def self.stopping_symbol_for(guard)
+      return :task_has_failed if guard.group.class != Symbol
+
+      group = ::Guard.groups(guard.group)
+      group.options[:halt_on_fail] ? :no_catch : :task_has_failed
+    end
+
+    private
+
+    # Tries to run the first implemented task by a given guard
+    # from a collection of tasks.
+    #
+    # @param [Guard::Guard] guard the guard to run the found task on
+    # @param [Array<Symbol>] tasks the tasks to run the first among
+    # @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
+      end
+    end
+
+    # Loop through all groups and run the given task for each Guard.
+    #
+    # Stop the task run for the all Guards within a group if one Guard
+    # throws `:task_has_failed`.
+    #
+    # @param [Hash] scope an hash with a guard or a group scope
+    # @yield the task to run
+    #
+    def scoped_guards(scopes = {})
+      if guard = scopes[:guard]
+        yield(guard)
+      else
+        groups = scopes[:group] ? [scopes[:group]] : ::Guard.groups
+        groups.each do |group|
+          catch :task_has_failed do
+            ::Guard.guards(:group => group.name).each do |guard|
+              yield(guard)
+            end
+          end
+        end
+      end
+    end
+
+  end
+end