[RFC] Add a Guard::API module that Guard plugins should include

.rspec

@@ -1,4 +1,3 @@
---fail-fast
 --format documentation
 --color
 --require spec_helper

config/Guardfile

@@ -2,7 +2,7 @@ scope(groups: %w(specs))
 
 directories %w(spec lib config features man)
 
-watch ("config/Guardfile") { UI.info "Exiting guard because config changed"; exit 0 }
+# watch ("config/Guardfile") { UI.info "Exiting guard because config changed"; exit 0 }
 
 group :specs, halt_on_fail: true do
   guard :rspec, cmd: "bundle exec rspec", failed_mode: :keep do
@@ -25,27 +25,27 @@ group :specs, halt_on_fail: true do
     #  watch("lib/guard/interactor.rb")         { "spec/guard/commands" }
     #  watch(%r{^lib/guard/(guard|plugin).rb$}) { "spec/guard/plugin" }
   end
-
-  guard :rubocop, all_on_start: false, cli: "--rails" do
-    watch(%r{.+\.rb$}) { |m| m[0] }
-    watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
-  end
-
-  guard "cucumber", keep_failed: true, all_on_start: false, cmd_additional_args: '--profile guard' do
-    watch(%r{^features/.+\.feature$})
-    watch(%r{^features/support/.+$})          { "features" }
-    watch(%r{^features/step_definitions/(.+)_steps\.rb$}) do |m|
-      Dir[File.join("**/#{m[1]}.feature")][0] || "features"
-    end
-  end
-end
-
-if !defined?(JRUBY_VERSION)
-  if ENV["CI"] != "true"
-    group :docs do
-      guard :ronn do
-        watch(%r{^man/.+\.ronn?$})
-      end
-    end
-  end
+  #
+  # guard :rubocop, all_on_start: false, cli: "--rails" do
+  #   watch(%r{.+\.rb$}) { |m| m[0] }
+  #   watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
+  # end
+  #
+  # guard "cucumber", keep_failed: true, all_on_start: false, cmd_additional_args: '--profile guard' do
+  #   watch(%r{^features/.+\.feature$})
+  #   watch(%r{^features/support/.+$})          { "features" }
+  #   watch(%r{^features/step_definitions/(.+)_steps\.rb$}) do |m|
+  #     Dir[File.join("**/#{m[1]}.feature")][0] || "features"
+  #   end
+  # end
 end
+#
+# if !defined?(JRUBY_VERSION)
+#   if ENV["CI"] != "true"
+#     group :docs do
+#       guard :ronn do
+#         watch(%r{^man/.+\.ronn?$})
+#       end
+#     end
+#   end
+# end

lib/guard.rb

@@ -1,9 +1,12 @@
 require "thread"
 require "listen"
+require "forwardable"
 
 require "guard/config"
+require "guard/engine"
+require "guard/api"
+require "guard/plugin"
 require "guard/deprecated/guard" unless Guard::Config.new.strict?
-require "guard/internals/helpers"
 
 require "guard/internals/debugging"
 require "guard/internals/traps"
@@ -18,152 +21,40 @@ module Guard
   Deprecated::Guard.add_deprecated(self) unless Config.new.strict?
 
   class << self
-    attr_reader :state
-    attr_reader :queue
-    attr_reader :listener
-    attr_reader :interactor
-
     # @private api
 
-    include Internals::Helpers
-
-    # Initializes the Guard singleton:
-    #
-    # * Initialize the internal Guard state;
-    # * Create the interactor
-    # * 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(cmdline_options = {})
-      init(cmdline_options)
-
-      @queue = Internals::Queue.new(Guard)
-
-      _evaluate(state.session.evaluator_options)
-
-      # NOTE: this should be *after* evaluate so :directories can work
-      # TODO: move listener setup to session?
-      @listener = Listen.send(*state.session.listener_args, &_listener_callback)
-
-      ignores = state.session.guardfile_ignore
-      @listener.ignore(ignores) unless ignores.empty?
-
-      ignores = state.session.guardfile_ignore_bang
-      @listener.ignore!(ignores) unless ignores.empty?
-
-      Notifier.connect(state.session.notify_options)
-
-      traps = Internals::Traps
-      traps.handle("USR1") { async_queue_add([:guard_pause, :paused]) }
-      traps.handle("USR2") { async_queue_add([:guard_pause, :unpaused]) }
-
-      @interactor = Interactor.new(state.session.interactor_name == :sleep)
-      traps.handle("INT") { @interactor.handle_interrupt }
-
-      self
-    end
+    # Backward-compatibility with the Guard singleton approach
+    def state
+      return unless @engine
 
-    def init(cmdline_options)
-      @state = Internals::State.new(cmdline_options)
+      @engine.state
     end
 
-    # Asynchronously trigger changes
-    #
-    # Currently supported args:
-    #
-    #   @example Old style hash:
-    #     async_queue_add(modified: ['foo'], added: ['bar'], removed: [])
-    #
-    #   @example New style signals with args:
-    #     async_queue_add([:guard_pause, :unpaused ])
-    #
-    def async_queue_add(changes)
-      @queue << changes
+    def queue
+      return unless @engine
 
-      # Putting interactor in background puts guard into foreground
-      # so it can handle change notifications
-      Thread.new { interactor.background }
+      @engine.queue
     end
 
-    private
+    def listener
+      return unless @engine
 
-    # Check if any of the changes are actually watched for
-    # TODO: why iterate twice? reuse this info when running tasks
-    def _relevant_changes?(changes)
-      # TODO: no coverage!
-      files = changes.values.flatten(1)
-      scope = Guard.state.scope
-      watchers = scope.grouped_plugins.map do |_group, plugins|
-        plugins.map(&:watchers).flatten
-      end.flatten
-      watchers.any? { |watcher| files.any? { |file| watcher.match(file) } }
+      @engine.listener
     end
 
-    def _relative_pathnames(paths)
-      paths.map { |path| _relative_pathname(path) }
-    end
-
-    def _listener_callback
-      lambda do |modified, added, removed|
-        relative_paths = {
-          modified: _relative_pathnames(modified),
-          added: _relative_pathnames(added),
-          removed: _relative_pathnames(removed)
-        }
-
-        _guardfile_deprecated_check(relative_paths[:modified])
+    def interactor
+      return unless @engine
 
-        async_queue_add(relative_paths) if _relevant_changes?(relative_paths)
-      end
+      @engine.interactor
     end
 
-    # TODO: obsoleted? (move to Dsl?)
-    def _pluginless_guardfile?
-      state.session.plugins.all.empty?
+    def start(cmdline_opts = {})
+      @engine = init(cmdline_opts)
+      @engine.start
     end
 
-    def _evaluate(options)
-      evaluator = Guardfile::Evaluator.new(options)
-      evaluator.evaluate
-
-      UI.reset_and_clear
-
-      msg = "No plugins found in Guardfile, please add at least one."
-      UI.error msg if _pluginless_guardfile?
-
-      if evaluator.inline?
-        UI.info("Using inline Guardfile.")
-      elsif evaluator.custom?
-        UI.info("Using Guardfile at #{ evaluator.path }.")
-      end
-    rescue Guardfile::Evaluator::NoPluginsError => e
-      UI.error(e.message)
-    end
-
-    # TODO: remove at some point
-    # TODO: not tested because collides with ongoing refactoring
-    def _guardfile_deprecated_check(modified)
-      modified.map!(&:to_s)
-      regexp = %r{^(?:.+/)?Guardfile$}
-      guardfiles = modified.select { |path| regexp.match(path) }
-      return if guardfiles.empty?
-
-      guardfile = Pathname("Guardfile").realpath
-      real_guardfiles = guardfiles.detect do |path|
-        /^Guardfile$/.match(path) || Pathname(path).expand_path == guardfile
-      end
-
-      return unless real_guardfiles
-
-      UI.warning "Guardfile changed -- _guard-core will exit.\n"
-      exit 2 # nonzero to break any while loop
+    def init(cmdline_opts = {})
+      Engine.new(cmdline_opts: cmdline_opts)
     end
   end
 end