guard 1.8.3 → 2.0.0.pre

data/lib/guard/rake_task.rb

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+
+require 'rake'
+require 'rake/tasklib'
+
+require 'guard/cli'
+
+module Guard
+
+  # Provides a method to define a Rake task that
+  # runs the Guard plugins.
+  #
+  class RakeTask < ::Rake::TaskLib
+
+    # Name of the main, top level task
+    attr_accessor :name
+
+    # CLI options
+    attr_accessor :options
+
+    # Initialize the Rake task
+    #
+    # @param [Symbol] name the name of the Rake task
+    # @param [String] options the CLI options
+    # @yield [Guard::RakeTask] the task
+    #
+    def initialize(name = :guard, options = '')
+      @name = name
+      @options = options
+
+      yield self if block_given?
+
+      desc "Starts Guard with options: '#{options}'"
+      task name => ["#{name}:start"]
+
+      namespace(name) do
+
+        desc "Starts Guard with options: '#{options}'"
+        task(:start) do
+          ::Guard::CLI.start(options.split)
+        end
+
+      end
+    end
+
+  end
+end

data/lib/guard/runner.rb

@@ -1,56 +1,24 @@
+require 'lumberjack'
+
+require 'guard/ui'
+require 'guard/watcher'
+
 module Guard
 
-  # The runner is responsible for running all methods defined on each guards.
+  # The runner is responsible for running all methods defined on each plugin.
   #
   class Runner
 
-    require 'guard'
-    require 'guard/ui'
-    require 'guard/watcher'
-
-    require 'lumberjack'
-
-    # 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_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:
-      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|
-        ::Guard::UI.deprecation(RUN_ON_CHANGE_DEPRECATION % guard.class.name)   if guard.respond_to?(:run_on_change)
-        ::Guard::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.
+    # 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, scopes = {})
+    def run(task, scope = {})
       Lumberjack.unit_of_work do
-        scoped_guards(scopes) do |guard|
+        _scoped_plugins(scope) do |guard|
           run_supervised_task(guard, task) if guard.respond_to?(task)
         end
       end
@@ -60,7 +28,7 @@ module Guard
     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
+    # Runs the appropriate tasks on all registered plugins
     # based on the passed changes.
     #
     # @param [Array<String>] modified the modified paths.
@@ -69,16 +37,16 @@ module Guard
     #
     def run_on_changes(modified, added, removed)
       ::Guard::UI.clearable
-      scoped_guards do |guard|
+      _scoped_plugins do |guard|
         modified_paths = ::Guard::Watcher.match_files(guard, modified)
         added_paths    = ::Guard::Watcher.match_files(guard, added)
         removed_paths  = ::Guard::Watcher.match_files(guard, removed)
 
-        ::Guard::UI.clear if clearable?(guard, modified_paths, added_paths, removed_paths)
+        ::Guard::UI.clear if _clearable?(guard, modified_paths, added_paths, removed_paths)
 
-        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?
+        _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
 
@@ -87,14 +55,14 @@ module Guard
     # 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 [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)
       begin
-        catch Runner.stopping_symbol_for(guard) do
+        catch self.class.stopping_symbol_for(guard) do
           guard.hook("#{ task }_begin", *args)
           result = guard.send(task, *args)
           guard.hook("#{ task }_end", result)
@@ -105,7 +73,7 @@ module Guard
         ::Guard::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
+        ::Guard.plugins.delete guard
         ::Guard::UI.info("\n#{ guard.class.name } has just been fired")
 
         ex
@@ -117,28 +85,25 @@ module Guard
     # @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
+    # @see ._scoped_plugins
     #
-    # @param [Guard::Guard] guard the Guard plugin to execute
+    # @param [Guard::Plugin] guard the Guard plugin 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.fetch(:halt_on_fail, false) ? :no_catch : :task_has_failed
+      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.
     #
-    # @param [Guard::Guard] guard the Guard plugin to run the first found task on
+    # @param [Guard::Plugin] guard the Guard plugin to run the first 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)
+    def _run_first_task_found(guard, tasks, task_param)
       tasks.each do |task|
         if guard.respond_to?(task)
           run_supervised_task(guard, task, task_param)
@@ -161,16 +126,16 @@ module Guard
     # @param [Hash] scopes hash with plugins or a groups scope
     # @yield the task to run
     #
-    def scoped_guards(scopes = {})
-      if guards = current_plugins_scope(scopes)
-        guards.each do |guard|
+    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_groups_scope(scopes).each do |group|
           current_plugin = nil
           block_return = catch :task_has_failed do
-            ::Guard.guards(:group => group.name).each do |guard|
+            ::Guard.plugins(group: group.name).each do |guard|
               current_plugin = guard
               yield(guard)
             end
@@ -186,12 +151,12 @@ module Guard
     # 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 plugin where run_on_changes is called
+    # @param [Guard::Plugin] guard the Guard plugin 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)
+    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?)
@@ -202,15 +167,13 @@ module Guard
     # 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::Guard>] the plugins to scope to
+    # @return [Array<Guard::Plugin>] the plugins to scope to
     #
-    def current_plugins_scope(scopes)
-      if scopes[:plugins] && !scopes[:plugins].empty?
-        scopes[:plugins]
-
-      elsif !::Guard.scope[:plugins].empty?
-        ::Guard.scope[:plugins]
-
+    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
@@ -223,16 +186,33 @@ module Guard
     # @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(scopes)
-      if scopes[:groups] && !scopes[:groups].empty?
-        scopes[:groups]
+    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)
+      [
+        local_scope[:"#{type}s"],
+        local_scope[type.to_sym],
+        ::Guard.scope[:"#{type}s"],
+        additional_possibilities.flatten
+      ].compact.find { |a| !Array(a).empty? }
+    end
 
-      elsif !::Guard.scope[:groups].empty?
-        ::Guard.scope[:groups]
+    # Find the first non empty plugins scope
+    #
+    def _find_non_empty_plugins_scope(scope)
+      _find_non_empty_scope(:plugin, scope)
+    end
 
-      else
-        ::Guard.groups
-      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

@@ -0,0 +1,248 @@
+require 'thread'
+require 'listen'
+require 'guard/options'
+
+module Guard
+
+  module Setuper
+
+    DEFAULT_OPTIONS = {
+      clear: false,
+      notify: true,
+      debug: false,
+      group: [],
+      plugin: [],
+      watchdir: nil,
+      guardfile: nil,
+      no_interactions: false,
+      no_bundler_warning: false,
+      show_deprecations: false,
+      latency: nil,
+      force_polling: false
+    }
+    DEFAULT_GROUPS = [:default]
+
+    # Initializes the Guard singleton:
+    #
+    # * Initialize the internal Guard state;
+    # * Create the interactor when necessary for user interaction;
+    # * Select and initialize the file change listener.
+    #
+    # @option options [Boolean] clear if auto clear the UI should be done
+    # @option options [Boolean] notify if system notifications should be shown
+    # @option options [Boolean] debug if debug output should be shown
+    # @option options [Array<String>] group the list of groups to start
+    # @option options [Array<String>] watchdir the directories to watch
+    # @option options [String] guardfile the path to the Guardfile
+    #
+    # @return [Guard] the Guard singleton
+    #
+    def setup(opts = {})
+      @running   = true
+      @lock      = Mutex.new
+      @opts      = opts
+      @watchdirs = [Dir.pwd]
+      @evaluator = ::Guard::Guardfile::Evaluator.new(opts)
+      @runner    = ::Guard::Runner.new
+
+      if options.watchdir
+        # Ensure we have an array
+        @watchdirs = Array(options.watchdir).map { |dir| File.expand_path dir }
+      end
+
+      ::Guard::UI.clear(force: true)
+      _setup_debug if options.debug
+      _setup_listener
+      _setup_signal_traps
+
+      reset_groups
+      reset_plugins
+      reset_scope
+
+      evaluate_guardfile
+
+      setup_scope(groups: options.group, plugins: options.plugin)
+
+      _setup_notifier
+      _setup_interactor
+
+      self
+    end
+
+    # Lazy initializer for Guard's options hash
+    #
+    def options
+      @options ||= ::Guard::Options.new(@opts || {}, DEFAULT_OPTIONS)
+    end
+
+    # Clear Guard's options hash
+    #
+    def clear_options
+      @options = nil
+    end
+
+    # Initializes the groups array with the default group(s).
+    #
+    # @see DEFAULT_GROUPS
+    #
+    def reset_groups
+      @groups = DEFAULT_GROUPS.map { |name| Group.new(name) }
+    end
+
+    # Initializes the plugins array to an empty array.
+    #
+    # @see Guard.plugins
+    #
+    def reset_plugins
+      @plugins = []
+    end
+
+    # Initializes the scope hash to `{ groups: [], plugins: [] }`.
+    #
+    # @see Guard.setup_scope
+    #
+    def reset_scope
+      @scope = { groups: [], plugins: [] }
+    end
+
+    # 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) }
+      end
+    end
+
+    # Evaluates the Guardfile content. It displays an error message if no
+    # Guard plugins are instantiated after the Guardfile evaluation.
+    #
+    # @see Guard::Guardfile::Evaluator#evaluate_guardfile
+    #
+    def evaluate_guardfile
+      evaluator.evaluate_guardfile
+      ::Guard::UI.error 'No plugins found in Guardfile, please add at least one.' if plugins.empty?
+    end
+
+    private
+
+    # Sets up various debug behaviors:
+    #
+    # * Abort threads on exception;
+    # * Set the logging level to `:debug`;
+    # * Modify the system and ` methods to log themselves before being executed
+    #
+    # @see #_debug_command_execution
+    #
+    def _setup_debug
+      Thread.abort_on_exception = true
+      ::Guard::UI.options.level = :debug
+      _debug_command_execution
+    end
+
+    # Initializes the listener and registers a callback for changes.
+    #
+    def _setup_listener
+      listener_callback = lambda do |modified, added, removed|
+        # Convert to relative paths (respective to the watchdir it came from)
+        @watchdirs.each do |watchdir|
+          [modified, added, removed].each do |paths|
+            paths.map! do |path|
+              if path.start_with? watchdir
+                path.sub "#{watchdir}#{File::SEPARATOR}", ''
+              else
+                path
+              end
+            end
+          end
+        end
+        evaluator.reevaluate_guardfile if ::Guard::Watcher.match_guardfile?(modified)
+
+        within_preserved_state do
+          runner.run_on_changes(modified, added, removed)
+        end
+      end
+
+      listener_options = {}
+      %w[latency force_polling].each do |option|
+        listener_options[option.to_sym] = options.send(option) if options.send(option)
+      end
+
+      listen_args = @watchdirs + [listener_options]
+      @listener = Listen.to(*listen_args).change(&listener_callback)
+    end
+
+    # Sets up traps to catch signals used to control Guard.
+    #
+    # Currently two signals are caught:
+    # - `USR1` which pauses listening to changes.
+    # - `USR2` which resumes listening to changes.
+    # - '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') { ::Guard.pause unless listener.paused? }
+        end
+
+        if Signal.list.keys.include?('USR2')
+          Signal.trap('USR2') { ::Guard.pause if listener.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
+      end
+    end
+
+    # Enables or disables the notifier based on user's configurations.
+    #
+    def _setup_notifier
+      if options.notify && ENV['GUARD_NOTIFY'] != 'false'
+        ::Guard::Notifier.turn_on
+      else
+        ::Guard::Notifier.turn_off
+      end
+    end
+
+    # Initializes the interactor unless the user has specified not to.
+    #
+    def _setup_interactor
+      unless options.no_interactions || !::Guard::Interactor.enabled
+        @interactor = ::Guard::Interactor.new
+      end
+    end
+
+    # Adds a command logger in debug mode. This wraps common command
+    # execution functions and logs the executed command before execution.
+    #
+    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(' ') }"
+        Kernel.send :original_system, command, *args
+      end
+
+      Kernel.send(:alias_method, :original_backtick, :'`')
+      Kernel.send(:define_method, :'`') do |command|
+        ::Guard::UI.debug "Command execution: #{ command }"
+        Kernel.send :original_backtick, command
+      end
+    end
+
+  end
+end