guard 1.8.3 → 2.0.0.pre

data/lib/guard/options.rb

@@ -0,0 +1,21 @@
+require 'ostruct'
+
+module Guard
+
+  # A class that holds options. Can be instantiated with default options.
+  #
+  class Options < OpenStruct
+
+    # Initializes an Guard::Options object. `default_opts` is merged into
+    # `opts`.
+    #
+    # @param [Hash] opts the options
+    # @param [Hash] default_opts the default options
+    #
+    def initialize(opts = {}, default_opts = {})
+      super(default_opts.dup.merge(opts.dup))
+    end
+
+  end
+
+end

data/lib/guard/plugin.rb

@@ -0,0 +1,66 @@
+require 'guard/plugin/base'
+
+module Guard
+
+  # Base class from which every Guard plugin implementation must inherit.
+  #
+  # Guard will trigger the {#start}, {#stop}, {#reload}, {#run_all} and
+  # {#run_on_changes} ({#run_on_additions}, {#run_on_modifications} and
+  # {#run_on_removals}) task methods depending on user interaction and file
+  # modification.
+  #
+  # {#run_on_changes} could be implemented to handle all the changes task case
+  # (additions, modifications, removals) in once, or each task can be
+  # implemented separately with a specific behavior.
+  #
+  # In each of these Guard task methods you have to implement some work when
+  # you want to support this kind of task. The return value of each Guard task
+  # method is not evaluated by Guard, but it'll be passed to the "_end" hook
+  # for further evaluation. You can throw `:task_has_failed` to indicate that
+  # your Guard plugin method was not successful, and successive Guard plugin
+  # tasks will be aborted when the group has set the `:halt_on_fail` option.
+  #
+  # @see Guard::Base
+  # @see Guard::Hooker
+  # @see Guard::Group
+  #
+  # @example Throw :task_has_failed
+  #
+  #   def run_all
+  #     if !runner.run(['all'])
+  #       throw :task_has_failed
+  #     end
+  #   end
+  #
+  # Each Guard plugin should provide a template Guardfile located within the Gem
+  # at `lib/guard/guard-name/templates/Guardfile`.
+  #
+  # Watchers for a Guard plugin should return a file path or an array of files
+  # paths to Guard, but if your Guard plugin wants to allow any return value
+  # from a watcher, you can set the `any_return` option to true.
+  #
+  # If one of those methods raises an exception other than `:task_has_failed`,
+  # the `Guard::GuardName` instance will be removed from the active Guard
+  # plugins.
+  #
+  class Plugin
+    include Base
+
+    # Initializes a Guard plugin.
+    # Don't do any work here, especially as Guard plugins get initialized even
+    # if they are not in an active group!
+    #
+    # @param [Hash] options the Guard plugin options
+    # @option options [Array<Guard::Watcher>] watchers the Guard plugin file
+    #   watchers
+    # @option options [Symbol] group the group this Guard plugin belongs to
+    # @option options [Boolean] any_return allow any object to be returned from
+    #   a watcher
+    #
+    def initialize(options = {})
+      _set_instance_variables_from_options(options)
+      _register_callbacks
+    end
+  end
+
+end

data/lib/guard/plugin/base.rb

@@ -0,0 +1,178 @@
+module Guard
+
+  class Plugin
+
+    # Colection of shared methods between `Guard::Guard` (deprecated)
+    # and `Guard::Plugin`.
+    #
+    module Base
+      require 'guard/ui'
+      require 'guard/plugin/hooker'
+
+      include ::Guard::Plugin::Hooker
+
+      attr_accessor :group, :watchers, :callbacks, :options
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Returns the non-namespaced class name of the plugin
+        #
+        #
+        # @example Non-namespaced class name for Guard::RSpec
+        #   Guard::RSpec.non_namespaced_classname
+        #   #=> "RSpec"
+        #
+        # @return [String]
+        #
+        def non_namespaced_classname
+          self.to_s.sub('Guard::', '')
+        end
+
+        # Returns the non-namespaced name of the plugin
+        #
+        #
+        # @example Non-namespaced name for Guard::RSpec
+        #   Guard::RSpec.non_namespaced_name
+        #   #=> "rspec"
+        #
+        # @return [String]
+        #
+        def non_namespaced_name
+          non_namespaced_classname.downcase
+        end
+
+        # Specify the source for the Guardfile template.
+        # Each Guard plugin can redefine this method to add its own logic.
+        #
+        # @param [String] plugin_location the plugin location
+        #
+        def template(plugin_location)
+          File.read("#{ plugin_location }/lib/guard/#{ non_namespaced_name }/templates/Guardfile")
+        end
+      end
+
+      # Called once when Guard starts. Please override initialize method to
+      # init stuff.
+      #
+      # @raise [:task_has_failed] when start has failed
+      # @return [Object] the task result
+      #
+      # @!method start
+
+      # Called when `stop|quit|exit|s|q|e + enter` is pressed (when Guard
+      # quits).
+      #
+      # @raise [:task_has_failed] when stop has failed
+      # @return [Object] the task result
+      #
+      # @!method stop
+
+      # Called when `reload|r|z + enter` is pressed.
+      # This method should be mainly used for "reload" (really!) actions like
+      # reloading passenger/spork/bundler/...
+      #
+      # @raise [:task_has_failed] when reload has failed
+      # @return [Object] the task result
+      #
+      # @!method reload
+
+      # Called when just `enter` is pressed
+      # This method should be principally used for long action like running all
+      # specs/tests/...
+      #
+      # @raise [:task_has_failed] when run_all has failed
+      # @return [Object] the task result
+      #
+      # @!method run_all
+
+      # Default behaviour on file(s) changes that the Guard plugin watches.
+      #
+      # @param [Array<String>] paths the changes files or paths
+      # @raise [:task_has_failed] when run_on_changes has failed
+      # @return [Object] the task result
+      #
+      # @!method run_on_changes(paths)
+
+      # Called on file(s) additions that the Guard plugin watches.
+      #
+      # @param [Array<String>] paths the changes files or paths
+      # @raise [:task_has_failed] when run_on_additions has failed
+      # @return [Object] the task result
+      #
+      # @!method run_on_additions(paths)
+
+      # Called on file(s) modifications that the Guard plugin watches.
+      #
+      # @param [Array<String>] paths the changes files or paths
+      # @raise [:task_has_failed] when run_on_modifications has failed
+      # @return [Object] the task result
+      #
+      # @!method run_on_modifications(paths)
+
+      # Called on file(s) removals that the Guard plugin watches.
+      #
+      # @param [Array<String>] paths the changes files or paths
+      # @raise [:task_has_failed] when run_on_removals has failed
+      # @return [Object] the task result
+      #
+      # @!method run_on_removals(paths)
+
+      # Returns the plugin's name (without "guard-").
+      #
+      # @example Name for Guard::RSpec
+      #   > Guard::RSpec.new.name
+      #   => "rspec"
+      #
+      # @return [String]
+      #
+      def name
+        @name ||= self.class.non_namespaced_name
+      end
+
+      # Returns the plugin's class name without the Guard:: namespace.
+      #
+      # @example Title for Guard::RSpec
+      #   > Guard::RSpec.new.title
+      #   => "RSpec"
+      #
+      # @return [String]
+      #
+      def title
+        @title ||= self.class.non_namespaced_classname
+      end
+
+      # String representation of the plugin.
+      #
+      # @example String representation of an instance of the Guard::RSpec plugin
+      #   Guard::RSpec.new.title
+      #   #=> "#<Guard::RSpec @name=rspec @group=#<Guard::Group @name=default @options={}> @watchers=[] @callbacks=[] @options={all_after_pass: true}>"
+      #
+      # @return [String] the string representation
+      #
+      def to_s
+        "#<#{self.class} @name=#{name} @group=#{group} @watchers=#{watchers} @callbacks=#{callbacks} @options=#{options}>"
+      end
+
+      private
+
+      # Sets the @group, @watchers, @callbacks and @options variables from the
+      # given options hash.
+      #
+      # @param [Hash] options the Guard plugin options
+      #
+      # @see Guard::Plugin.initialize
+      #
+      def _set_instance_variables_from_options(options)
+        group_name = options.delete(:group) { :default }
+        @group = ::Guard.add_group(group_name)
+        @watchers  = options.delete(:watchers) { [] }
+        @callbacks = options.delete(:callbacks) { [] }
+        @options   = options
+      end
+
+    end
+  end
+end

data/lib/guard/plugin/hooker.rb

@@ -0,0 +1,123 @@
+module Guard
+
+  class Plugin
+
+    # Guard has a hook mechanism that allows you to insert callbacks for
+    # individual Guard plugins.
+    # By default, each of the Guard plugin instance methods has a "_begin" and
+    # an "_end" hook.
+    # For example, the Guard::Plugin#start method has a :start_begin hook that
+    # is runs immediately before Guard::Plugin#start, and a :start_end hook
+    # that runs immediately after Guard::Plugin#start.
+    #
+    # Read more about [hooks and callbacks on the
+    # wiki](https://github.com/guard/guard/wiki/Hooks-and-callbacks).
+    #
+    module Hooker
+
+      require 'guard/ui'
+
+      # Get all callbacks registered for all Guard plugins present in the
+      # Guardfile.
+      #
+      def self.callbacks
+        @callbacks ||= Hash.new { |hash, key| hash[key] = [] }
+      end
+
+      # Add a callback.
+      #
+      # @param [Block] listener the listener to notify
+      # @param [Guard::Plugin] guard_plugin the Guard plugin to add the callback
+      # @param [Array<Symbol>] events the events to register
+      #
+      def self.add_callback(listener, guard_plugin, events)
+        _events = events.is_a?(Array) ? events : [events]
+        _events.each do |event|
+          callbacks[[guard_plugin, event]] << listener
+        end
+      end
+
+      # Checks if a callback has been registered.
+      #
+      # @param [Block] listener the listener to notify
+      # @param [Guard::Plugin] guard_plugin the Guard plugin to add the callback
+      # @param [Symbol] event the event to look for
+      #
+      def self.has_callback?(listener, guard_plugin, event)
+        callbacks[[guard_plugin, event]].include?(listener)
+      end
+
+      # Notify a callback.
+      #
+      # @param [Guard::Plugin] guard_plugin the Guard plugin to add the callback
+      # @param [Symbol] event the event to trigger
+      # @param [Array] args the arguments for the listener
+      #
+      def self.notify(guard_plugin, event, *args)
+        callbacks[[guard_plugin, event]].each do |listener|
+          listener.call(guard_plugin, event, *args)
+        end
+      end
+
+      # Reset all callbacks.
+      #
+      def self.reset_callbacks!
+        @callbacks = nil
+      end
+
+      # When event is a Symbol, {#hook} will generate a hook name
+      # by concatenating the method name from where {#hook} is called
+      # with the given Symbol.
+      #
+      # @example Add a hook with a Symbol
+      #
+      #   def run_all
+      #     hook :foo
+      #   end
+      #
+      # Here, when {Guard::Plugin::Base#run_all} is called, {#hook} will notify
+      # callbacks registered for the "run_all_foo" event.
+      #
+      # When event is a String, {#hook} will directly turn the String
+      # into a Symbol.
+      #
+      # @example Add a hook with a String
+      #
+      #   def run_all
+      #     hook "foo_bar"
+      #   end
+      #
+      # When {Guard::Plugin::Base#run_all} is called, {#hook} will notify
+      # callbacks registered for the "foo_bar" event.
+      #
+      # @param [Symbol, String] event the name of the Guard event
+      # @param [Array] args the parameters are passed as is to the callbacks
+      #   registered for the given event.
+      #
+      def hook(event, *args)
+        hook_name = if event.is_a? Symbol
+                      calling_method = caller[0][/`([^']*)'/, 1]
+                      "#{ calling_method }_#{ event }"
+                    else
+                      event
+                    end
+
+        ::Guard::UI.debug "Hook :#{ hook_name } executed for #{ self }"
+
+        Hooker.notify(self, hook_name.to_sym, *args)
+      end
+
+      private
+
+      # Add all the Guard::Plugin's callbacks to the global @callbacks array
+      # that's used by Guard to know which callbacks to notify.
+      #
+      def _register_callbacks
+        callbacks.each do |callback|
+          self.class.add_callback(callback[:listener], self, callback[:events])
+        end
+      end
+
+    end
+  end
+end

data/lib/guard/plugin_util.rb

@@ -0,0 +1,158 @@
+require 'guard/ui'
+
+module Guard
+
+  # This class contains useful methods to:
+  #
+  # * Fetch all the Guard plugins names;
+  # * Initialize a plugin, get its location;
+  # * Return its class name;
+  # * Add its template to the Guardfile.
+  #
+  class PluginUtil
+
+    attr_accessor :name
+
+    # Returns a list of Guard plugin Gem names installed locally.
+    #
+    # @return [Array<String>] a list of Guard plugin gem names
+    #
+    def self.plugin_names
+      if Gem::Version.create(Gem::VERSION) >= Gem::Version.create('1.8.0')
+        Gem::Specification.find_all.select do |x|
+          if x.name =~ /^guard-/
+            true
+          elsif x.name != 'guard'
+            guard_plugin_path = File.join(x.full_gem_path, "lib/guard/#{ x.name }.rb")
+            File.exists?( guard_plugin_path )
+          end
+        end
+      else
+        Gem.source_index.find_name(/^guard-/)
+      end.map { |x| x.name.sub(/^guard-/, '') }.uniq
+    end
+
+    # Initializes a new `Guard::PluginUtil` object.
+    #
+    # @param [String] name the name of the Guard plugin
+    #
+    def initialize(name)
+      @name = name.to_s.sub(/^guard-/, '')
+    end
+
+    # Initializes a new `Guard::Plugin` with the given `options` hash. This
+    # methods handles plugins that inherit from the deprecated `Guard::Guard`
+    # class as well as plugins that inherit from `Guard::Plugin`.
+    #
+    # @see Guard::Plugin
+    # @see https://github.com/guard/guard/wiki/Upgrading-to-Guard-2.0 How to upgrade for Guard 2.0
+    #
+    # @return [Guard::Plugin] the initialized plugin
+    # @return [Guard::Guard] the initialized plugin. This return type is
+    #   deprecated and the plugin's maintainer should update it to be
+    #   compatible with Guard 2.0. For more information on how to upgrade for
+    #   Guard 2.0, please head over to: https://github.com/guard/guard/wiki/Upgrading-to-Guard-2.0
+    #
+    def initialize_plugin(options)
+      if plugin_class.superclass == ::Guard::Guard
+        plugin_class.new(options.delete(:watchers), options)
+      else
+        plugin_class.new(options)
+      end
+    end
+
+    # Locates a path to a Guard plugin gem.
+    #
+    # @return [String] the full path to the plugin gem
+    #
+    def plugin_location
+      @plugin_location ||= begin
+        if Gem::Version.create(Gem::VERSION) >= Gem::Version.create('1.8.0')
+          Gem::Specification.find_by_name("guard-#{ name }").full_gem_path
+        else
+          Gem.source_index.find_name("guard-#{ name }").last.full_gem_path
+        end
+      end
+    rescue
+      ::Guard::UI.error "Could not find 'guard-#{ name }' gem path."
+    end
+
+    # Tries to load the Guard plugin main class. This transforms the supplied
+    # plugin name into a class name:
+    #
+    # * `guardname` will become `Guard::Guardname`
+    # * `dashed-guard-name` will become `Guard::DashedGuardName`
+    # * `underscore_guard_name` will become `Guard::UnderscoreGuardName`
+    #
+    # When no class is found with the strict case sensitive rules, another
+    # try is made to locate the class without matching case:
+    #
+    # * `rspec` will find a class `Guard::RSpec`
+    #
+    # @option options [Boolean] fail_gracefully whether error messages should not be printed
+    # @return [Class, nil] the loaded class
+    #
+    def plugin_class(options = {})
+      options = { fail_gracefully: false }.merge(options)
+
+      try_require = false
+      begin
+        require "guard/#{ name.downcase }" if try_require
+
+        @plugin_class ||= ::Guard.const_get(_plugin_constant)
+      rescue TypeError
+        if try_require
+          ::Guard::UI.error "Could not find class Guard::#{ _constant_name }"
+        else
+          try_require = true
+          retry
+        end
+      rescue LoadError => loadError
+        unless options[:fail_gracefully]
+          ::Guard::UI.error "Could not load 'guard/#{ name.downcase }' or find class Guard::#{ _constant_name }"
+          ::Guard::UI.error loadError.to_s
+        end
+      end
+    end
+
+    # Adds a plugin's template to the Guardfile.
+    #
+    def add_to_guardfile
+      if ::Guard.evaluator.guardfile_include?(name)
+        ::Guard::UI.info "Guardfile already includes #{ name } guard"
+      else
+        content = File.read('Guardfile')
+        File.open('Guardfile', 'wb') do |f|
+          f.puts(content)
+          f.puts('')
+          f.puts(plugin_class.template(plugin_location))
+        end
+
+        ::Guard::UI.info "#{ name } guard added to Guardfile, feel free to edit it"
+      end
+    end
+
+    private
+
+    # Returns the constant for the current plugin.
+    #
+    # @example Returns the constant for a plugin
+    #   > Guard::PluginUtil.new('rspec').send(:_plugin_constant)
+    #   => Guard::RSpec
+    #
+    def _plugin_constant
+      @_plugin_constant ||= ::Guard.constants.find { |c| c.to_s.downcase == _constant_name.downcase }
+    end
+
+    # Guesses the most probable name for the current plugin based on its name.
+    #
+    # @example Returns the most probable name for a plugin
+    #   > Guard::PluginUtil.new('rspec').send(:_constant_name)
+    #   => "Rspec"
+    #
+    def _constant_name
+      @_constant_name ||= name.gsub(/\/(.?)/) { "::#{ $1.upcase }" }.gsub(/(?:^|[_-])(.)/) { $1.upcase }
+    end
+
+  end
+end