diff --git a/lib/guard/hook.rb b/lib/guard/hook.rb index 3f57b30..a75f4c1 100644 --- a/lib/guard/hook.rb +++ b/lib/guard/hook.rb @@ -1,51 +1,80 @@ 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 run immediately + # before Guard::Guard#start and a :start_end hook that is run 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 + + # 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: + # + # @example Add a hook with a Symbol # def run_all # hook :foo # end - # Here, when #run_all is called, #hook will notify callbacks + # + # 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 + # When +event+ is a String, {#hook} will directly turn the String # into a Symbol. - # Example: + # + # @example Add a hook with a String # def run_all # hook "foo_bar" # end - # Here, when #run_all is called, #hook will notify callbacks + # + # When {Guard::Guard#run_all} is called, {#hook} will notify callbacks # registered for the "foo_bar" event. # - # +args+ parameter is passed as is to the callbacks registered - # for the given 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 + calling_method = caller[0][/`([^']*)'/, 1] + "#{ calling_method }_#{ event }" + else + event + end.to_sym - UI.debug "Hook :#{hook_name} executed for #{self.class}" + 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] events the events to register + # def add_callback(listener, guard_class, events) _events = events.is_a?(Array) ? events : [events] _events.each do |event| @@ -53,19 +82,34 @@ module Guard 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