guard 0.8.1 → 0.8.2

data/lib/guard/dsl_describer.rb

@@ -1,60 +1,60 @@
-require 'guard/dsl'
-
-module Guard
-
-  # The DslDescriber overrides methods to create an internal structure
-  # of the Guardfile that is used in some inspection utility methods
-  # like the CLI commands `show` and `list`.
-  #
-  # @see Guard::Dsl
-  # @see Guard::CLI
-  #
-  class DslDescriber < Dsl
-
-    @@guardfile_structure = [ { :guards => [] } ]
-
-    class << self
-
-      # Get the Guardfile structure.
-      #
-      # @return [Array<Hash>] the structure
-      #
-      def guardfile_structure
-        @@guardfile_structure
-      end
-    end
-
-    private
-
-    # Declares a group of guards.
-    #
-    # @param [String] name the group's name called from the CLI
-    # @yield a block where you can declare several guards
-    #
-    # @see Guard::Dsl#group
-    #
-    def group(name)
-      @@guardfile_structure << { :group => name.to_sym, :guards => [] }
-      @group = true
-
-      yield if block_given?
-
-      @group = false
-    end
-
-    # Declares a Guard.
-    #
-    # @param [String] name the Guard name
-    # @param [Hash] options the options accepted by the Guard
-    # @yield a block where you can declare several watch patterns and actions
-    #
-    # @see Guard::Dsl#guard
-    #
-    def guard(name, options = {})
-      node = (@group ? @@guardfile_structure.last : @@guardfile_structure.first)
-
-      node[:guards] << { :name => name, :options => options }
-    end
-
-  end
-end
+require 'guard/dsl'
+
+module Guard
+
+  # The DslDescriber overrides methods to create an internal structure
+  # of the Guardfile that is used in some inspection utility methods
+  # like the CLI commands `show` and `list`.
+  #
+  # @see Guard::Dsl
+  # @see Guard::CLI
+  #
+  class DslDescriber < Dsl
+
+    @@guardfile_structure = [ { :guards => [] } ]
+
+    class << self
+
+      # Get the Guardfile structure.
+      #
+      # @return [Array<Hash>] the structure
+      #
+      def guardfile_structure
+        @@guardfile_structure
+      end
+    end
+
+    private
+
+    # Declares a group of guards.
+    #
+    # @param [String] name the group's name called from the CLI
+    # @yield a block where you can declare several guards
+    #
+    # @see Guard::Dsl#group
+    #
+    def group(name)
+      @@guardfile_structure << { :group => name.to_sym, :guards => [] }
+      @group = true
+
+      yield if block_given?
+
+      @group = false
+    end
+
+    # Declares a Guard.
+    #
+    # @param [String] name the Guard name
+    # @param [Hash] options the options accepted by the Guard
+    # @yield a block where you can declare several watch patterns and actions
+    #
+    # @see Guard::Dsl#guard
+    #
+    def guard(name, options = {})
+      node = (@group ? @@guardfile_structure.last : @@guardfile_structure.first)
+
+      node[:guards] << { :name => name, :options => options }
+    end
+
+  end
+end

data/lib/guard/group.rb

@@ -1,22 +1,37 @@
-module Guard
-
-  # A group of Guards.
-  #
-  class Group
-
-    attr_accessor :name, :options
-
-    # Initialize a Group.
-    #
-    # @param [String] name the name of the group
-    # @option options [Boolean] halt_on_fail if a task execution
-    #   should be halted for all Guards in this group if one Guard throws `:task_has_failed`
-    #
-    def initialize(name, options = {})
-      @name    = name.to_sym
-      @options = options
-    end
-
-  end
-
-end
+module Guard
+
+  # A group of Guards. There are two reasons why you want to group your guards:
+  #
+  # - You can start only certain Groups from the command line by passing the `--group` option.
+  # - Abort task execution chain on failure within a group.
+  #
+  # @example Group that aborts on failure
+  #
+  #   group :frontend, :halt_on_fail => true do
+  #     guard 'coffeescript', :input => 'spec/coffeescripts', :output => 'spec/javascripts'
+  #     guard 'jasmine-headless-webkit' do
+  #       watch(%r{^spec/javascripts/(.*)\..*}) { |m| newest_js_file("spec/javascripts/#{m[1]}_spec") }
+  #     end
+  #   end
+  #
+  # @see Guard::CLI
+  #
+  class Group
+
+    attr_accessor :name, :options
+
+    # Initialize a Group.
+    #
+    # @param [String] name the name of the group
+    # @param [Hash] options the group options
+    # @option options [Boolean] halt_on_fail if a task execution
+    #   should be halted for all Guards in this group if one Guard throws `:task_has_failed`
+    #
+    def initialize(name, options = {})
+      @name    = name.to_sym
+      @options = options
+    end
+
+  end
+
+end

data/lib/guard/guard.rb

@@ -1,98 +1,113 @@
-module Guard
-
-  # Main class that every Guard implementation must subclass.
-  #
-  # Guard will trigger the `start`, `stop`, `reload`, `run_all` and `run_on_change`
-  # methods depending on user interaction and file modification.
-  #
-  # Each Guard should provide a template Guardfile located within the Gem
-  # at `lib/guard/guard-name/templates/Guardfile`.
-  #
-  class Guard
-    include Hook
-
-    attr_accessor :watchers, :options, :group
-
-    # Initialize a Guard.
-    #
-    # @param [Array<Guard::Watcher>] watchers the Guard file watchers
-    # @param [Hash] options the custom Guard options
-    #
-    def initialize(watchers = [], options = {})
-      @group = options[:group] ? options.delete(:group).to_sym : :default
-      @watchers, @options = watchers, options
-    end
-
-    # Initialize the Guard. This will copy the Guardfile template inside the Guard gem.
-    # The template Guardfile must be located within the Gem at `lib/guard/guard-name/templates/Guardfile`.
-    #
-    # @param [String] name the name of the Guard
-    #
-    def self.init(name)
-      if ::Guard::Dsl.guardfile_include?(name)
-        ::Guard::UI.info "Guardfile already includes #{ name } guard"
-      else
-        content = File.read('Guardfile')
-        guard   = File.read("#{ ::Guard.locate_guard(name) }/lib/guard/#{ name }/templates/Guardfile")
-        File.open('Guardfile', 'wb') do |f|
-          f.puts(content)
-          f.puts("")
-          f.puts(guard)
-        end
-        ::Guard::UI.info "#{name} guard added to Guardfile, feel free to edit it"
-      end
-    end
-
-    # Call once when Guard starts. Please override initialize method to init stuff.
-    #
-    # @return [Boolean] Whether the start action was successful or not
-    #
-    def start
-      true
-    end
-
-    # Call once when Guard quit.
-    #
-    # @return [Boolean] Whether the stop action was successful or not
-    #
-    def stop
-      true
-    end
-
-    # Should be used for "reload" (really!) actions like reloading passenger/spork/bundler/...
-    #
-    # @return [Boolean] Whether the reload action was successful or not
-    #
-    def reload
-      true
-    end
-
-    # Should be used for long action like running all specs/tests/...
-    #
-    # @return [Boolean] Whether the run_all action was successful or not
-    #
-    def run_all
-      true
-    end
-
-    # Will be triggered when a file change matched a watcher.
-    #
-    # @param [Array<String>] paths the changes files or paths
-    # @return [Boolean] Whether the run_on_change action was successful or not
-    #
-    def run_on_change(paths)
-      true
-    end
-
-    # Will be triggered when a file deletion matched a watcher.
-    #
-    # @param [Array<String>] paths the deleted files or paths
-    # @return [Boolean] Whether the run_on_deletion action was successful or not
-    #
-    def run_on_deletion(paths)
-      true
-    end
-
-  end
-
-end
+module Guard
+
+  # Main class that every Guard implementation must subclass.
+  #
+  # Guard will trigger the `start`, `stop`, `reload`, `run_all`, `run_on_change` and
+  # `run_on_deletion` methods depending on user interaction and file modification.
+  #
+  # In each of these Guard methods you have to implement some work when you want to
+  # support this kind of task. The return value of each Guard method is ignored, but
+  # you can throw `:task_has_failed` to indicate that your Guard method was
+  # not successful. When `:task_has_failed` is thrown, successive guard tasks
+  # can be aborted when the group has set the `:halt_on_fail` option.
+  #
+  # @see Guard::Group
+  #
+  # @example Throw :task_has_failed
+  #
+  #   def run_all
+  #     if !runner.run(['all'])
+  #       throw :task_has_failed
+  #     end
+  #   end
+  #
+  # Each Guard should provide a template Guardfile located within the Gem
+  # at `lib/guard/guard-name/templates/Guardfile`.
+  #
+  # If one of those methods raise an exception other than `:task_has_failed`,
+  # the Guard::GuardName instance will be removed from the active guards.
+  #
+  class Guard
+    include Hook
+
+    attr_accessor :watchers, :options, :group
+
+    # Initialize a Guard.
+    #
+    # @param [Array<Guard::Watcher>] watchers the Guard file watchers
+    # @param [Hash] options the custom Guard options
+    #
+    def initialize(watchers = [], options = {})
+      @group = options[:group] ? options.delete(:group).to_sym : :default
+      @watchers, @options = watchers, options
+    end
+
+    # Initialize the Guard. This will copy the Guardfile template inside the Guard gem.
+    # The template Guardfile must be located within the Gem at `lib/guard/guard-name/templates/Guardfile`.
+    #
+    # @param [String] name the name of the Guard
+    #
+    def self.init(name)
+      if ::Guard::Dsl.guardfile_include?(name)
+        ::Guard::UI.info "Guardfile already includes #{ name } guard"
+      else
+        content = File.read('Guardfile')
+        guard   = File.read("#{ ::Guard.locate_guard(name) }/lib/guard/#{ name }/templates/Guardfile")
+        File.open('Guardfile', 'wb') do |f|
+          f.puts(content)
+          f.puts("")
+          f.puts(guard)
+        end
+        ::Guard::UI.info "#{name} guard added to Guardfile, feel free to edit it"
+      end
+    end
+
+    # Call once when Guard starts. Please override initialize method to init stuff.
+    #
+    # @raise [:task_has_failed] when start has failed
+    #
+    def start
+    end
+
+    # Called when `stop|quit|exit|s|q|e + enter` is pressed (when Guard quits).
+    #
+    # @raise [:task_has_failed] when stop has failed
+    #
+    def stop
+    end
+
+    # 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
+    #
+    def reload
+    end
+
+    # 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
+    #
+    def run_all
+    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
+    #
+    def run_on_change(paths)
+    end
+
+    # Called on file(s) deletions that the Guard watches.
+    #
+    # @param [Array<String>] paths the deleted files or paths
+    # @raise [:task_has_failed] when run_on_change has failed
+    #
+    def run_on_deletion(paths)
+    end
+
+  end
+
+end

data/lib/guard/hook.rb

@@ -1,118 +1,118 @@
-module Guard
-
-  # Guard has a hook mechanism that allows you to insert callbacks for individual Guards.
-  # By default, each of the Guard instance methods has a "_begin" and an "_end" hook.
-  # For example, the Guard::Guard#start method has a :start_begin hook that is runs immediately
-  # before Guard::Guard#start, and a :start_end hook that runs immediately after Guard::Guard#start.
-  #
-  # Read more about [hooks and callbacks on the wiki](https://github.com/guard/guard/wiki/Hooks-and-callbacks).
-  #
-  module Hook
-
-    # The Hook module gets included.
-    #
-    # @param [Class] base the class that includes the module
-    #
-    def self.included(base)
-      base.send :include, InstanceMethods
-    end
-
-    # Instance methods that gets included in the base class.
-    #
-    module InstanceMethods
-
-      # 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::Guard#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::Guard#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.to_sym
-
-        UI.debug "Hook :#{ hook_name } executed for #{ self.class }"
-
-        Hook.notify(self.class, hook_name, *args)
-      end
-    end
-
-    class << self
-
-      # Get all callbacks.
-      #
-      def callbacks
-        @callbacks ||= Hash.new { |hash, key| hash[key] = [] }
-      end
-
-      # Add a callback.
-      #
-      # @param [Block] listener the listener to notify
-      # @param [Guard::Guard] guard_class the Guard class to add the callback
-      # @param [Array<Symbol>] events the events to register
-      #
-      def add_callback(listener, guard_class, events)
-        _events = events.is_a?(Array) ? events : [events]
-        _events.each do |event|
-          callbacks[[guard_class, event]] << listener
-        end
-      end
-
-      # Checks if a callback has been registered.
-      #
-      # @param [Block] listener the listener to notify
-      # @param [Guard::Guard] guard_class the Guard class to add the callback
-      # @param [Symbol] event the event to look for
-      #
-      def has_callback?(listener, guard_class, event)
-        callbacks[[guard_class, event]].include?(listener)
-      end
-
-      # Notify a callback.
-      #
-      # @param [Guard::Guard] guard_class the Guard class to add the callback
-      # @param [Symbol] event the event to trigger
-      # @param [Array] args the arguments for the listener
-      #
-      def notify(guard_class, event, *args)
-        callbacks[[guard_class, event]].each do |listener|
-          listener.call(guard_class, event, *args)
-        end
-      end
-
-      # Reset all callbacks.
-      #
-      def reset_callbacks!
-        @callbacks = nil
-      end
-
-    end
-
-  end
-end
+module Guard
+
+  # Guard has a hook mechanism that allows you to insert callbacks for individual Guards.
+  # By default, each of the Guard instance methods has a "_begin" and an "_end" hook.
+  # For example, the Guard::Guard#start method has a :start_begin hook that is runs immediately
+  # before Guard::Guard#start, and a :start_end hook that runs immediately after Guard::Guard#start.
+  #
+  # Read more about [hooks and callbacks on the wiki](https://github.com/guard/guard/wiki/Hooks-and-callbacks).
+  #
+  module Hook
+
+    # The Hook module gets included.
+    #
+    # @param [Class] base the class that includes the module
+    #
+    def self.included(base)
+      base.send :include, InstanceMethods
+    end
+
+    # Instance methods that gets included in the base class.
+    #
+    module InstanceMethods
+
+      # 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::Guard#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::Guard#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.to_sym
+
+        UI.debug "Hook :#{ hook_name } executed for #{ self.class }"
+
+        Hook.notify(self.class, hook_name, *args)
+      end
+    end
+
+    class << self
+
+      # Get all callbacks.
+      #
+      def callbacks
+        @callbacks ||= Hash.new { |hash, key| hash[key] = [] }
+      end
+
+      # Add a callback.
+      #
+      # @param [Block] listener the listener to notify
+      # @param [Guard::Guard] guard_class the Guard class to add the callback
+      # @param [Array<Symbol>] events the events to register
+      #
+      def add_callback(listener, guard_class, events)
+        _events = events.is_a?(Array) ? events : [events]
+        _events.each do |event|
+          callbacks[[guard_class, event]] << listener
+        end
+      end
+
+      # Checks if a callback has been registered.
+      #
+      # @param [Block] listener the listener to notify
+      # @param [Guard::Guard] guard_class the Guard class to add the callback
+      # @param [Symbol] event the event to look for
+      #
+      def has_callback?(listener, guard_class, event)
+        callbacks[[guard_class, event]].include?(listener)
+      end
+
+      # Notify a callback.
+      #
+      # @param [Guard::Guard] guard_class the Guard class to add the callback
+      # @param [Symbol] event the event to trigger
+      # @param [Array] args the arguments for the listener
+      #
+      def notify(guard_class, event, *args)
+        callbacks[[guard_class, event]].each do |listener|
+          listener.call(guard_class, event, *args)
+        end
+      end
+
+      # Reset all callbacks.
+      #
+      def reset_callbacks!
+        @callbacks = nil
+      end
+
+    end
+
+  end
+end