guard 2.6.1 → 2.7.0

data/lib/guard/runner.rb.orig

@@ -0,0 +1,200 @@
+require "lumberjack"
+
+require "guard/ui"
+require "guard/watcher"
+
+module Guard
+  # The runner is responsible for running all methods defined on each plugin.
+  #
+  class Runner
+    # Runs a Guard-task on all registered plugins.
+    #
+    # @param [Symbol] task the task to run
+    #
+    # @param [Hash] scopes either the Guard plugin or the group to run the task
+    # on
+    #
+    # @see self.run_supervised_task
+    #
+    def run(task, scope = {})
+      Lumberjack.unit_of_work do
+        _scoped_plugins(scope) do |guard|
+          run_supervised_task(guard, task) if guard.respond_to?(task)
+        end
+      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 plugins
+    # 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)
+      types = {
+        MODIFICATION_TASKS => modified,
+        ADDITION_TASKS => added,
+        REMOVAL_TASKS => removed
+      }
+
+      ::Guard::UI.clearable
+
+      _scoped_plugins do |guard|
+        ::Guard::UI.clear
+
+        types.each do |tasks, unmatched_paths|
+          paths = ::Guard::Watcher.match_files(guard, unmatched_paths)
+          next if paths.empty?
+
+          next unless (task = tasks.detect { |meth| guard.respond_to?(meth) })
+          run_supervised_task(guard, task, paths)
+        end
+      end
+    end
+
+    # Run a Guard plugin task, but remove the Guard plugin 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::Plugin] 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)
+      catch self.class.stopping_symbol_for(guard) do
+        guard.hook("#{ task }_begin", *args)
+        begin
+          result = guard.send(task, *args)
+        rescue Interrupt
+          throw(:task_has_failed)
+        end
+        guard.hook("#{ task }_end", result)
+        result
+      end
+    rescue ScriptError, StandardError, RuntimeError
+      ::Guard::UI.error("#{ guard.class.name } failed to achieve its"\
+                        " <#{ task }>, exception was:" \
+                        "\n#{ $!.class }: #{ $!.message }" \
+                        "\n#{ $!.backtrace.join("\n") }")
+      ::Guard.plugins.delete guard
+      ::Guard::UI.info("\n#{ guard.class.name } has just been fired")
+      $!
+    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_plugins
+    #
+    # @param [Guard::Plugin] guard the Guard plugin to execute
+    # @return [Symbol] the symbol to catch
+    #
+    def self.stopping_symbol_for(guard)
+      guard.group.options[:halt_on_fail] ? :no_catch : :task_has_failed
+    end
+
+    private
+
+    # Loop through all groups and run the given task for each Guard plugin.
+    #
+    # If no scope is supplied, the global Guard scope is taken into account.
+    # If both a plugin and a group scope is given, then only the plugin scope
+    # is used.
+    #
+    # Stop the task run for the all Guard plugins within a group if one Guard
+    # throws `:task_has_failed`.
+    #
+    # @param [Hash] scopes hash with plugins or a groups scope
+    # @yield the task to run
+    #
+    def _scoped_plugins(scopes = {})
+      if plugins = _current_plugins_scope(scopes)
+        plugins.each do |guard|
+          yield(guard)
+        end
+      else
+        _current_groups_scope(scopes).each do |group|
+          current_plugin = nil
+          block_return = catch :task_has_failed do
+            ::Guard.plugins(group: group.name).each do |guard|
+              current_plugin = guard
+              yield(guard)
+            end
+          end
+
+          next unless block_return.nil?
+
+          ::Guard::UI.info "#{ current_plugin.class.name } has failed,"\
+            " other group's plugins execution has been halted."
+        end
+      end
+    end
+
+    # Returns the current plugins scope.
+    # Local plugins scope wins over global plugins scope.
+    # If no plugins scope is found, then NO plugins are returned.
+    #
+    # @param [Hash] scopes hash with a local plugins or a groups scope
+    # @return [Array<Guard::Plugin>] the plugins to scope to
+    #
+    def _current_plugins_scope(scope)
+      if plugins = _find_non_empty_plugins_scope(scope)
+        Array(plugins).map do |plugin|
+          plugin.is_a?(Symbol) ? ::Guard.plugin(plugin) : plugin
+        end
+      else
+        nil
+      end
+    end
+
+    # Returns the current groups scope.
+    # Local groups scope wins over global groups scope.
+    # If no groups scope is found, then ALL groups are returned.
+    #
+    # @param [Hash] scopes hash with a local plugins or a groups scope
+    # @return [Array<Guard::Group>] the groups to scope to
+    #
+    def _current_groups_scope(scope)
+      Array(_find_non_empty_groups_scope(scope)).map do |group|
+        group.is_a?(Symbol) ? ::Guard.group(group) : group
+      end
+    end
+
+    # Find the first non empty element in the given possibilities
+    #
+    def _find_non_empty_scope(type, local_scope, *additional_possibilities)
+      found = [
+        local_scope[:"#{type}s"],
+        local_scope[type.to_sym],
+        ::Guard.scope[:"#{type}s"],
+        additional_possibilities.flatten
+      ].compact.detect { |a| !Array(a).empty? }
+      found ? [::Guard.group(:common)] + Array(found) : found
+    end
+
+    # Find the first non empty plugins scope
+    #
+    def _find_non_empty_plugins_scope(scope)
+      _find_non_empty_scope(:plugin, scope)
+    end
+
+    # Find the first non empty groups scope
+    #
+    def _find_non_empty_groups_scope(scope)
+      _find_non_empty_scope(:group, scope, ::Guard.groups)
+    end
+  end
+end

data/lib/guard/setuper.rb

@@ -1,11 +1,10 @@
-require 'thread'
-require 'listen'
-require 'guard/options'
+require "thread"
+require "listen"
+require "guard/options"
 
 module Guard
-
+  # Sets up initial variables and options
   module Setuper
-
     DEFAULT_OPTIONS = {
       clear: false,
       notify: true,
@@ -22,12 +21,12 @@ module Guard
       wait_for_delay: nil,
       listen_on: nil
     }
-    DEFAULT_GROUPS = [:default]
+    DEFAULT_GROUPS = [:default, :common]
 
     # Initializes the Guard singleton:
     #
     # * Initialize the internal Guard state;
-    # * Create the interactor when necessary for user interaction;
+    # * Create the interactor
     # * Select and initialize the file change listener.
     #
     # @option options [Boolean] clear if auto clear the UI should be done
@@ -39,59 +38,33 @@ module Guard
     #
     # @return [Guard] the Guard singleton
     #
+
+    # TODO: this method has too many instance variables
+    # and some are mock and leak between tests,
+    # so ideally there should be a guard "instance"
+    # object that can be created anew between tests
     def setup(opts = {})
-      _reset_lazy_accessors
-      @running   = true
-      @lock      = Mutex.new
-      @opts      = opts
-      @watchdirs = [Dir.pwd]
-      @runner    = ::Guard::Runner.new
-
-      if options[:watchdir]
-        # Ensure we have an array
-        @watchdirs = Array(options[:watchdir]).map { |dir| File.expand_path dir }
-      end
+      reset_options(opts)
+      reset_evaluator(opts)
+
+      @queue = Queue.new
+      @runner = ::Guard::Runner.new
+      @watchdirs = _setup_watchdirs
 
       ::Guard::UI.clear(force: true)
+
       _setup_debug if options[:debug]
-      _setup_listener
+      @listener = _setup_listener
       _setup_signal_traps
 
-      reset_groups
-      reset_plugins
-      reset_scope
-
-      evaluate_guardfile
-
-      setup_scope(groups: options[:group], plugins: options[:plugin])
-
-      _setup_notifier
-
+      _load_guardfile
+      @interactor = _setup_interactor
       self
     end
 
-    # Lazy initializer for Guard's options hash
-    #
-    def options
-      @options ||= ::Guard::Options.new(@opts, DEFAULT_OPTIONS)
-    end
-
-    # Lazy initializer for Guardfile evaluator
-    #
-    def evaluator
-      @evaluator ||= ::Guard::Guardfile::Evaluator.new(@opts || {})
-    end
-
-    # Lazy initializer the interactor unless the user has specified not to.
-    #
-    def interactor
-      return if options[:no_interactions] || !::Guard::Interactor.enabled
-
-      @interactor ||= ::Guard::Interactor.new
-    end
+    attr_reader :options, :evaluator, :interactor
 
-    # Clear Guard's options hash
-    #
+    # Used only by tests (for all I know...)
     def clear_options
       @options = nil
     end
@@ -117,25 +90,48 @@ module Guard
     # @see Guard.setup_scope
     #
     def reset_scope
-      @scope = { groups: [], plugins: [] }
+      # calls Guard.scope=() to set the instance variable directly, as opposed
+      # to Guard.scope()
+      ::Guard.scope = { groups: [], plugins: [] }
+    end
+
+    # Used to merge CLI options with Setuper defaults
+    def reset_options(new_options)
+      @options = ::Guard::Options.new(new_options, DEFAULT_OPTIONS)
+    end
+
+    # TODO: code smell - too many reset_* methods
+    def reset_evaluator(new_options)
+      @evaluator = ::Guard::Guardfile::Evaluator.new(new_options)
+    end
+
+    def save_scope
+      # This actually replaces scope from command line,
+      # so scope set by 'scope' Pry command will be reset
+      @saved_scope = _prepare_scope(::Guard.scope)
+    end
+
+    def restore_scope
+      ::Guard.setup_scope(@saved_scope)
     end
 
     attr_reader :watchdirs
 
-    # Stores the scopes defined by the user via the `--group` / `-g` option (to run
-    # only a specific group) or the `--plugin` / `-P` option (to run only a
+    # Stores the scopes defined by the user via the `--group` / `-g` option (to
+    # run only a specific group) or the `--plugin` / `-P` option (to run only a
     # specific plugin).
     #
     # @see CLI#start
     # @see Dsl#scope
     #
-    def setup_scope(new_scope)
-      if new_scope[:groups] && new_scope[:groups].any?
-        scope[:groups]  = new_scope[:groups].map { |group| ::Guard.add_group(group) }
-      end
-
-      if new_scope[:plugins] && new_scope[:plugins].any?
-        scope[:plugins] = new_scope[:plugins].map { |plugin| ::Guard.plugin(plugin) }
+    def setup_scope(scope = {})
+      # TODO: there should be a special Scope class instead
+      scope = _prepare_scope(scope)
+      { groups: :add_group, plugins: :plugin }.each do |type, meth|
+        next unless scope[type].any?
+        ::Guard.scope[type] = scope[type].map do |item|
+          ::Guard.send(meth, item)
+        end
       end
     end
 
@@ -146,17 +142,40 @@ module Guard
     #
     def evaluate_guardfile
       evaluator.evaluate_guardfile
-      ::Guard::UI.error 'No plugins found in Guardfile, please add at least one.' if plugins.empty?
+      msg = "No plugins found in Guardfile, please add at least one."
+      ::Guard::UI.error msg unless _non_builtin_plugins?
     end
 
-    private
+    # Asynchronously trigger changes
+    #
+    # Currently supported args:
+    #
+    #   old style hash: {modified: ['foo'], added: ['bar'], removed: []}
+    #
+    #   new style signals with args: [:guard_pause, :unpaused ]
+    #
+    def async_queue_add(changes)
+      @queue << changes
 
-    def _reset_lazy_accessors
-      @options    = nil
-      @evaluator  = nil
-      @interactor = nil
+      # Putting interactor in background puts guard into foreground
+      # so it can handle change notifications
+      Thread.new { interactor.background }
     end
 
+    def pending_changes?
+      ! @queue.empty?
+    end
+
+    def add_builtin_plugins(guardfile)
+      return unless guardfile
+
+      pattern = _relative_pathname(guardfile).to_s
+      watcher = ::Guard::Watcher.new(pattern)
+      ::Guard.add_plugin(:reevaluator, watchers: [watcher], group: :common)
+    end
+
+    private
+
     # Sets up various debug behaviors:
     #
     # * Abort threads on exception;
@@ -175,15 +194,31 @@ module Guard
     #
     def _setup_listener
       if options[:listen_on]
-        @listener = Listen.on(options[:listen_on], &_listener_callback)
+        Listen.on(options[:listen_on], &_listener_callback)
       else
         listener_options = {}
         [:latency, :force_polling, :wait_for_delay].each do |option|
           listener_options[option] = options[option] if options[option]
         end
         listen_args = watchdirs + [listener_options]
-        @listener = Listen.to(*listen_args, &_listener_callback)
+        Listen.to(*listen_args, &_listener_callback)
+      end
+    end
+
+    # Process the change queue, running tasks within the main Guard thread
+    def _process_queue
+      actions, changes = [], { modified: [], added: [], removed: [] }
+
+      while pending_changes?
+        if (item = @queue.pop).first.is_a?(Symbol)
+          actions << item
+        else
+          item.each { |key, value| changes[key] += value }
+        end
       end
+
+      _run_actions(actions)
+      runner.run_on_changes(*changes.values)
     end
 
     # Sets up traps to catch signals used to control Guard.
@@ -194,39 +229,24 @@ module Guard
     # - 'INT' which is delegated to Pry if active, otherwise stops Guard.
     #
     def _setup_signal_traps
-      unless defined?(JRUBY_VERSION)
-        if Signal.list.keys.include?('USR1')
-          Signal.trap('USR1') do
-            unless listener.paused?
-              Thread.new { within_preserved_state { ::Guard.pause } }
-            end
-          end
-        end
+      return if defined?(JRUBY_VERSION)
 
-        if Signal.list.keys.include?('USR2')
-          Signal.trap('USR2') do
-            if listener.paused?
-              Thread.new { within_preserved_state { ::Guard.pause } }
-            end
-          end
-        end
+      if Signal.list.keys.include?("USR1")
+        Signal.trap("USR1") { async_queue_add([:guard_pause, :paused]) }
+      end
 
-        if Signal.list.keys.include?('INT')
-          Signal.trap('INT') do
-            if interactor && interactor.thread
-              interactor.thread.raise(Interrupt)
-            else
-              ::Guard.stop
-            end
-          end
-        end
+      if Signal.list.keys.include?("USR2")
+        Signal.trap("USR2") { async_queue_add([:guard_pause, :unpaused]) }
       end
+
+      return unless Signal.list.keys.include?("INT")
+      Signal.trap("INT") { interactor.handle_interrupt }
     end
 
     # Enables or disables the notifier based on user's configurations.
     #
     def _setup_notifier
-      if options[:notify] && ENV['GUARD_NOTIFY'] != 'false'
+      if options[:notify] && ENV["GUARD_NOTIFY"] != "false"
         ::Guard::Notifier.turn_on
       else
         ::Guard::Notifier.turn_off
@@ -239,7 +259,7 @@ module Guard
     def _debug_command_execution
       Kernel.send(:alias_method, :original_system, :system)
       Kernel.send(:define_method, :system) do |command, *args|
-        ::Guard::UI.debug "Command execution: #{ command } #{ args.join(' ') }"
+        ::Guard::UI.debug "Command execution: #{ command } #{ args.join(" ") }"
         Kernel.send :original_system, command, *args
       end
 
@@ -250,53 +270,102 @@ module Guard
       end
     end
 
+    # TODO: Guard::Watch or Guard::Scope should provide this
+    def _scoped_watchers
+      watchers = []
+      runner.send(:_scoped_plugins) { |guard| watchers += guard.watchers }
+      watchers
+    end
+
     # Check if any of the changes are actually watched for
-    #
-    # NOTE: this is called from the listen thread - be careful to not
-    # modify any state
-    #
-    # TODO: move this to watcher class?
-    #
     def _relevant_changes?(changes)
-      # TODO: make a Guardfile reloader "plugin" instead of a special case
-      return true if ::Guard::Watcher.match_guardfile?(changes[:modified])
+      files = changes.values.flatten(1)
+      watchers = _scoped_watchers
+      watchers.any? { |watcher| files.any? { |file| watcher.match(file) } }
+    end
 
-      # TODO: ignoring irrelevant files should be Listen's responsibility
-      all_files = changes.values.flatten(1)
-      runner.send(:_scoped_plugins) do |guard|
-        return true if ::Guard::Watcher.match_files?([guard], all_files)
-      end
-      false
-    end
-
-    def _relative_paths(changes)
-      # Convert to relative paths (respective to the watchdir it came from)
-      watchdirs.each do |watchdir|
-        changes.each do |type, paths|
-          paths.each do |path|
-            if path.start_with? watchdir
-              path.sub! "#{watchdir}#{File::SEPARATOR}", ''
-            end
-          end
+    def _relative_pathname(path)
+      full_path = Pathname(path)
+      full_path.relative_path_from(Pathname.pwd)
+    rescue ArgumentError
+      full_path
+    end
+
+    def _relative_pathnames(paths)
+      paths.map { |path| _relative_pathname(path) }
+    end
+
+    def _run_actions(actions)
+      actions.each do |action_args|
+        args = action_args.dup
+        namespaced_action = args.shift
+        action = namespaced_action.to_s.sub(/^guard_/, "")
+        if ::Guard.respond_to?(action)
+          ::Guard.send(action, *args)
+        else
+          fail "Unknown action: #{action.inspect}"
         end
       end
     end
 
+    def _setup_watchdirs
+      dirs = Array(options[:watchdir])
+      dirs.empty? ? [Dir.pwd] : dirs.map { |dir| File.expand_path dir }
+    end
+
     def _listener_callback
       lambda do |modified, added, removed|
-        all_changes = { modified: modified.dup,
-                        added: added.dup,
-                        removed: removed.dup }
-
-        # TODO: this should be Listen's responsibility
-        _relative_paths(all_changes)
+        relative_paths = {
+          modified: _relative_pathnames(modified),
+          added: _relative_pathnames(added),
+          removed: _relative_pathnames(removed)
+        }
 
-        if _relevant_changes?(all_changes)
-          within_preserved_state do
-            runner.run_on_changes(*all_changes.values)
-          end
-        end
+        async_queue_add(relative_paths) if _relevant_changes?(relative_paths)
       end
     end
+
+    def _reset_all
+      reset_groups
+      reset_plugins
+      reset_scope
+    end
+
+    def _setup_interactor
+      ::Guard::Interactor.new(options[:no_interactions])
+    end
+
+    def _load_guardfile
+      _reset_all
+      evaluate_guardfile
+      setup_scope
+      _setup_notifier
+    end
+
+    def _prepare_scope(scope)
+      plugins = Array(options[:plugin])
+      plugins = Array(scope[:plugins] || scope[:plugin]) if plugins.empty?
+
+      groups = Array(options[:group])
+      groups = Array(scope[:groups] || scope[:group]) if groups.empty?
+
+      { plugins: plugins, groups: groups }
+    end
+
+    def _non_builtin_plugins?
+      plugins.map(&:name) != ["reevaluator"]
+    end
+
+    def _reset_for_tests
+      @options = nil
+      @queue = nil
+      @runner = nil
+      @evaluator = nil
+      @watchdirs = nil
+      @watchdirs = nil
+      @listener = nil
+      @interactor = nil
+      ::Guard.scope = nil
+    end
   end
 end