guard 0.7.0 → 0.8.0

data/lib/guard/group.rb

@@ -0,0 +1,22 @@
+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

data/lib/guard/guard.rb

@@ -1,21 +1,39 @@
 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.delete(:group) || :default
+      @group = options[:group] ? options.delete(:group).to_sym : :default
       @watchers, @options = watchers, options
     end
 
-    # Guardfile template needed inside guard gem
+    # 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"
+        ::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")
+        guard   = File.read("#{ ::Guard.locate_guard(name) }/lib/guard/#{ name }/templates/Guardfile")
         File.open('Guardfile', 'wb') do |f|
           f.puts(content)
           f.puts("")
@@ -25,34 +43,56 @@ module Guard
       end
     end
 
-    # ================
-    # = Guard method =
-    # ================
-
-    # Call once when guard starts
-    # Please override initialize method to init stuff
+    # 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
+    # Call once when Guard quit.
+    #
+    # @return [Boolean] Whether the stop action was successful or not
+    #
     def stop
       true
     end
 
-    # Should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
+    # 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 principally used for long action like running all specs/tests/...
+    # 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

data/lib/guard/hook.rb

@@ -1,51 +1,82 @@
 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
+
+      # 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<Symbol>] 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 +84,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

data/lib/guard/interactor.rb

@@ -1,39 +1,77 @@
 module Guard
+
+  # The interactor reads user input and triggers
+  # specific action upon them unless its locked.
+  #
+  # Currently the following actions are implemented:
+  #
+  # - stop, quit, exit, s, q, e => Exit Guard
+  # - reload, r, z => Reload Guard
+  # - pause, p => Pause Guard
+  # - Everything else => Run all
+  #
   class Interactor
 
+    class LockException < Exception; end
+    class UnlockException < Exception; end
+
     attr_reader :locked
 
+    # Initialize the interactor in unlocked state.
+    #
     def initialize
       @locked = false
     end
 
+    # Start the interactor in its own thread.
+    #
     def start
       return if ENV["GUARD_ENV"] == 'test'
-      Thread.new do
+
+      @thread = Thread.new do
         loop do
-          if (entry = $stdin.gets) && !@locked
-            entry.gsub! /\n/, ''
-            case entry
-            when 'stop', 'quit', 'exit', 's', 'q', 'e'
-              ::Guard.stop
-            when 'reload', 'r', 'z'
-              ::Guard.reload
-            when 'pause', 'p'
-              ::Guard.pause
-            else
-              ::Guard.run_all
+          begin
+            if !@locked && (entry = $stdin.gets)
+              entry.gsub! /\n/, ''
+              case entry
+                when 'stop', 'quit', 'exit', 's', 'q', 'e'
+                  ::Guard.stop
+                when 'reload', 'r', 'z'
+                  ::Guard::Dsl.reevaluate_guardfile
+                  ::Guard.reload
+                when 'pause', 'p'
+                  ::Guard.pause
+                else
+                  ::Guard.run_all
+              end
             end
+          rescue LockException
+            lock
+          rescue UnlockException
+            unlock
           end
         end
       end
     end
 
+    # Lock the interactor.
+    #
     def lock
-      @locked = true
+      if !@thread || @thread == Thread.current
+        @locked = true
+      else
+        @thread.raise(LockException)
+      end
     end
 
+    # Unlock the interactor.
+    #
     def unlock
-      @locked = false
+      if !@thread || @thread == Thread.current
+        @locked = false
+      else
+        @thread.raise(UnlockException)
+      end
     end
 
   end

data/lib/guard/listener.rb

@@ -8,40 +8,64 @@ module Guard
   autoload :Windows, 'guard/listeners/windows'
   autoload :Polling, 'guard/listeners/polling'
 
+  # The Listener is the base class for all listener
+  # implementations.
+  #
+  # @abstract
+  #
   class Listener
 
-    DefaultIgnorePaths = %w[. .. .bundle .git log tmp vendor]
+    # Default paths that gets ignored by the listener
+    DEFAULT_IGNORE_PATHS = %w[. .. .bundle .git log tmp vendor]
+
     attr_accessor :changed_files
     attr_reader :directory, :ignore_paths, :locked
 
-    def self.select_and_init(*a)
+    # Select the appropriate listener implementation for the
+    # current OS and initializes it.
+    #
+    # @param [Array] args the arguments for the listener
+    # @return [Guard::Listener] the chosen listener
+    #
+    def self.select_and_init(*args)
       if mac? && Darwin.usable?
-        Darwin.new(*a)
+        Darwin.new(*args)
       elsif linux? && Linux.usable?
-        Linux.new(*a)
+        Linux.new(*args)
       elsif windows? && Windows.usable?
-        Windows.new(*a)
+        Windows.new(*args)
       else
-        UI.info "Using polling (Please help us to support your system better than that.)"
-        Polling.new(*a)
+        UI.info 'Using polling (Please help us to support your system better than that).'
+        Polling.new(*args)
       end
     end
 
+    # Initialize the listener.
+    #
+    # @param [String] directory the root directory to listen to
+    # @option options [Boolean] relativize_paths use only relative paths
+    # @option options [Array<String>] ignore_paths the paths to ignore by the listener
+    #
     def initialize(directory = Dir.pwd, options = {})
-      @directory           = directory.to_s
-      @sha1_checksums_hash = {}
-      @relativize_paths    = options.fetch(:relativize_paths, true)
-      @changed_files       = []
-      @locked              = false
-      @ignore_paths        = DefaultIgnorePaths
-      @ignore_paths        |= options[:ignore_paths] if options[:ignore_paths]
+      @directory                = directory.to_s
+      @sha1_checksums_hash      = {}
+      @file_timestamp_hash      = {}
+      @relativize_paths         = options.fetch(:relativize_paths, true)
+      @changed_files            = []
+      @locked                   = false
+      @ignore_paths             = DEFAULT_IGNORE_PATHS
+      @ignore_paths            |= options[:ignore_paths] if options[:ignore_paths]
+      @watch_all_modifications  = options.fetch(:watch_all_modifications, false)
 
       update_last_event
       start_reactor
     end
 
+    # Start the listener thread.
+    #
     def start_reactor
       return if ENV["GUARD_ENV"] == 'test'
+
       Thread.new do
         loop do
           if @changed_files != [] && !@locked
@@ -55,75 +79,146 @@ module Guard
       end
     end
 
+    # Start watching the root directory.
+    #
     def start
       watch(@directory)
+      timestamp_files
     end
 
+    # Stop listening for events.
+    #
     def stop
     end
 
+    # Lock the listener to ignore change events.
+    #
     def lock
       @locked = true
     end
 
+    # Unlock the listener to listen again to change events.
+    #
     def unlock
       @locked = false
     end
 
+    # Clear the list of changed files.
+    #
     def clear_changed_files
       @changed_files.clear
     end
 
+    # Store a listener callback.
+    #
+    # @param [Block] callback the callback to store
+    #
     def on_change(&callback)
       @callback = callback
     end
 
+    # Updates the timestamp of the last event.
+    #
     def update_last_event
       @last_event = Time.now
     end
 
+    # Get the modified files.
+    #
+    # If the `:watch_all_modifications` option is true, then moved and
+    # deleted files are also reported, but prefixed by an exclamation point.
+    #
+    # @example Deleted or moved file
+    #   !/home/user/dir/file.rb
+    #
+    # @param [Array<String>] dirs the watched directories
+    # @param [Hash] options the listener options
+    # @option options [Symbol] all whether to files in sub directories
+    # @return [Array<String>] paths of files that have been modified
+    #
     def modified_files(dirs, options = {})
       last_event = @last_event
+      files = []
+      if @watch_all_modifications
+        deleted_files = @file_timestamp_hash.collect do |path, ts|
+          unless File.exists?(path)
+            @sha1_checksums_hash.delete(path)
+            @file_timestamp_hash.delete(path)
+            "!#{path}"
+          end
+        end
+        files.concat(deleted_files.compact)
+      end
       update_last_event
-      files = potentially_modified_files(dirs, options).select { |path| file_modified?(path, last_event) }
-      relativize_paths(files)
-    end
+      files.concat(potentially_modified_files(dirs, options).select { |path| file_modified?(path, last_event) })
 
-    def worker
-      raise NotImplementedError, "should respond to #watch"
+      relativize_paths(files)
     end
 
-    # register a directory to watch. must be implemented by the subclasses
+    # Register a directory to watch.
+    # Must be implemented by the subclasses.
+    #
+    # @param [String] directory the directory to watch
+    #
     def watch(directory)
       raise NotImplementedError, "do whatever you want here, given the directory as only argument"
     end
 
+    # Get all files that are in the watched directory.
+    #
+    # @return [Array<String>] the list of files
+    #
     def all_files
       potentially_modified_files([@directory], :all => true)
     end
 
-    # scopes all given paths to the current #directory
+    # Scopes all given paths to the current directory.
+    #
+    # @param [Array<String>] paths the paths to change
+    # @return [Array<String>] all paths now relative to the current dir
+    #
     def relativize_paths(paths)
       return paths unless relativize_paths?
       paths.map do |path|
-        path.gsub(%r{^#{@directory}/}, '')
+      path.gsub(%r{^(!)?#{ @directory }/},'\1')
       end
     end
 
+    # Use paths relative to the current directory.
+    #
+    # @return [Boolean] whether to use relative or absolute paths
+    #
     def relativize_paths?
       !!@relativize_paths
     end
 
-    # return children of the passed dirs that are not in the ignore_paths list
+    # Populate initial timestamp file hash to watch for deleted or moved files.
+    #
+    def timestamp_files
+      all_files.each {|path| set_file_timestamp_hash(path, file_timestamp(path)) } if @watch_all_modifications
+    end
+
+    # Removes the ignored paths from the directory list.
+    #
+    # @param [Array<String>] dirs the directory to listen to
+    # @param [Array<String>] ignore_paths the paths to ignore
+    # @return children of the passed dirs that are not in the ignore_paths list
+    #
     def exclude_ignored_paths(dirs, ignore_paths = self.ignore_paths)
       Dir.glob(dirs.map { |d| "#{d.sub(%r{/+$}, '')}/*" }, File::FNM_DOTMATCH).reject do |path|
         ignore_paths.include?(File.basename(path))
       end
     end
 
-  private
+    private
 
-    def potentially_modified_files(dirs, options={})
+    # Gets a list of files that are in the modified directories.
+    #
+    # @param [Array<String>] dirs the list of directories
+    # @param [Hash] options the find file option
+    # @option options [Symbol] all whether to files in sub directories
+    #
+    def potentially_modified_files(dirs, options = {})
       paths = exclude_ignored_paths(dirs)
 
       if options[:all]
@@ -131,7 +226,7 @@ module Guard
           if File.file?(path)
             array << path
           else
-            array += Dir.glob("#{path}/**/*", File::FNM_DOTMATCH).select { |p| File.file?(p) }
+            array += Dir.glob("#{ path }/**/*", File::FNM_DOTMATCH).select { |p| File.file?(p) }
           end
           array
         end
@@ -140,9 +235,17 @@ module Guard
       end
     end
 
+    # Test if the file content has changed.
+    #
     # Depending on the filesystem, mtime/ctime is probably only precise to the second, so round
     # both values down to the second for the comparison.
+    #
     # ctime is used only on == comparison to always catches Rails 3.1 Assets pipelined on Mac OSX
+    #
+    # @param [String] path the file path
+    # @param [Time] last_event the time of the last event
+    # @return [Boolean] Whether the file content has changed or not.
+    #
     def file_modified?(path, last_event)
       ctime = File.ctime(path).to_i
       mtime = File.mtime(path).to_i
@@ -151,6 +254,12 @@ module Guard
       elsif mtime > last_event.to_i
         set_sha1_checksums_hash(path, sha1_checksum(path))
         true
+      elsif @watch_all_modifications
+        ts = file_timestamp(path)
+        if ts != @file_timestamp_hash[path]
+          set_file_timestamp_hash(path, ts)
+          true
+        end
       else
         false
       end
@@ -158,6 +267,12 @@ module Guard
       false
     end
 
+    # Tests if the file content has been modified by
+    # comparing the SHA1 checksum.
+    #
+    # @param [String] path the file path
+    # @param [String] sha1_checksum the checksum of the file
+    #
     def file_content_modified?(path, sha1_checksum)
       if @sha1_checksums_hash[path] != sha1_checksum
         set_sha1_checksums_hash(path, sha1_checksum)
@@ -167,22 +282,62 @@ module Guard
       end
     end
 
+    # Set save a files current timestamp
+    #
+    # @param [String] path the file path
+    # @param [Int] file_timestamp the files modified timestamp
+    #
+    def set_file_timestamp_hash(path, file_timestamp)
+        @file_timestamp_hash[path] = file_timestamp
+    end
+
+    # Set the current checksum of a file.
+    #
+    # @param [String] path the file path
+    # @param [String] sha1_checksum the checksum of the file
+    #
     def set_sha1_checksums_hash(path, sha1_checksum)
       @sha1_checksums_hash[path] = sha1_checksum
     end
 
+    # Gets a files modified timestamp
+    #
+    # @path [String] path the file path
+    # @return [Int] file modified timestamp
+    #
+    def file_timestamp(path)
+      File.mtime(path).to_i
+    end
+
+    # Calculates the SHA1 checksum of a file.
+    #
+    # @param [String] path the path to the file
+    # @return [String] the SHA1 checksum
+    #
     def sha1_checksum(path)
       Digest::SHA1.file(path).to_s
     end
 
+    # Test if the OS is Mac OS X.
+    #
+    # @return [Boolean] Whether the OS is Mac OS X
+    #
     def self.mac?
       RbConfig::CONFIG['target_os'] =~ /darwin/i
     end
 
+    # Test if the OS is Linux.
+    #
+    # @return [Boolean] Whether the OS is Linux
+    #
     def self.linux?
       RbConfig::CONFIG['target_os'] =~ /linux/i
     end
 
+    # Test if the OS is Windows.
+    #
+    # @return [Boolean] Whether the OS is Windows
+    #
     def self.windows?
       RbConfig::CONFIG['target_os'] =~ /mswin|mingw/i
     end