listen 0.7.3 → 1.0.0

data/lib/listen/directory_record.rb

@@ -11,8 +11,10 @@ module Listen
   class DirectoryRecord
     attr_reader :directory, :paths, :sha1_checksums
 
+    # The default list of directories that get ignored by the listener.
     DEFAULT_IGNORED_DIRECTORIES = %w[.rbx .bundle .git .svn log tmp vendor]
 
+    # The default list of files that get ignored by the listener.
     DEFAULT_IGNORED_EXTENSIONS  = %w[.DS_Store]
 
     # Defines the used precision based on the type of mtime returned by the
@@ -56,15 +58,14 @@ module Listen
     def initialize(directory)
       raise ArgumentError, "The path '#{directory}' is not a directory!" unless File.directory?(directory)
 
-      @directory          = directory
-      @ignoring_patterns  = Set.new
-      @filtering_patterns = Set.new
-      @sha1_checksums     = Hash.new
+      @directory, @sha1_checksums = directory, Hash.new
+      @ignoring_patterns, @filtering_patterns = Set.new, Set.new
 
       @ignoring_patterns.merge(DirectoryRecord.generate_default_ignoring_patterns)
     end
 
-    # Returns the ignoring patterns in the record
+    # Returns the ignoring patterns in the record to know
+    # which paths should be ignored.
     #
     # @return [Array<Regexp>] the ignoring patterns
     #
@@ -72,7 +73,7 @@ module Listen
       @ignoring_patterns.to_a
     end
 
-    # Returns the filtering patterns used in the record to know
+    # Returns the filtering patterns in the record to know
     # which paths should be stored.
     #
     # @return [Array<Regexp>] the filtering patterns
@@ -86,10 +87,10 @@ module Listen
     # @example Ignore some paths
     #   ignore %r{^ignored/path/}, /man/
     #
-    # @param [Regexp] regexp a pattern for ignoring paths
+    # @param [Regexp] regexps a list of patterns for ignoring paths
     #
     def ignore(*regexps)
-      @ignoring_patterns.merge(regexps)
+      @ignoring_patterns.merge(regexps).reject! { |r| r.nil? }
     end
 
     # Replaces ignoring patterns in the record.
@@ -97,37 +98,37 @@ module Listen
     # @example Ignore only these paths
     #   ignore! %r{^ignored/path/}, /man/
     #
-    # @param [Regexp] regexp a pattern for ignoring paths
+    # @param [Regexp] regexps a list of patterns for ignoring paths
     #
     def ignore!(*regexps)
-      @ignoring_patterns.replace(regexps)
+      @ignoring_patterns.replace(regexps).reject! { |r| r.nil? }
     end
 
-    # Adds filtering patterns to the listener.
+    # Adds filtering patterns to the record.
     #
     # @example Filter some files
-    #   ignore /\.txt$/, /.*\.zip/
+    #   filter /\.txt$/, /.*\.zip/
     #
-    # @param [Regexp] regexp a pattern for filtering paths
+    # @param [Regexp] regexps a list of patterns for filtering files
     #
     def filter(*regexps)
-      @filtering_patterns.merge(regexps)
+      @filtering_patterns.merge(regexps).reject! { |r| r.nil? }
     end
 
-    # Replaces filtering patterns in the listener.
+    # Replaces filtering patterns in the record.
     #
     # @example Filter only these files
-    #   ignore /\.txt$/, /.*\.zip/
+    #   filter! /\.txt$/, /.*\.zip/
     #
-    # @param [Regexp] regexp a pattern for filtering paths
+    # @param [Regexp] regexps a list of patterns for filtering files
     #
     def filter!(*regexps)
-      @filtering_patterns.replace(regexps)
+      @filtering_patterns.replace(regexps).reject! { |r| r.nil? }
     end
 
     # Returns whether a path should be ignored or not.
     #
-    # @param [String] path the path to test.
+    # @param [String] path the path to test
     #
     # @return [Boolean]
     #
@@ -138,7 +139,7 @@ module Listen
 
     # Returns whether a path should be filtered or not.
     #
-    # @param [String] path the path to test.
+    # @param [String] path the path to test
     #
     # @return [Boolean]
     #
@@ -159,9 +160,9 @@ module Listen
     end
 
     # Detects changes in the passed directories, updates
-    # the record with the new changes and returns the changes
+    # the record with the new changes and returns the changes.
     #
-    # @param [Array] directories the list of directories scan for changes
+    # @param [Array] directories the list of directories to scan for changes
     # @param [Hash] options
     # @option options [Boolean] recursive scan all sub-directories recursively
     # @option options [Boolean] relative_paths whether or not to use relative paths for changes
@@ -174,6 +175,7 @@ module Listen
 
       directories.each do |directory|
         next unless directory[@directory] # Path is or inside directory
+
         detect_modifications_and_removals(directory, options)
         detect_additions(directory, options)
       end
@@ -188,9 +190,10 @@ module Listen
     # @return [String] the relative path
     #
     def relative_to_base(path)
-      return nil unless path[@directory]
+      return nil unless path[directory]
+
       path = path.force_encoding("BINARY") if path.respond_to?(:force_encoding)
-      path.sub(%r{^#{Regexp.quote(@directory)}#{File::SEPARATOR}?}, '')
+      path.sub(%r{^#{Regexp.quote(directory)}#{File::SEPARATOR}?}, '')
     end
 
     private
@@ -207,43 +210,69 @@ module Listen
     # @option options [Boolean] relative_paths whether or not to use relative paths for changes
     #
     def detect_modifications_and_removals(directory, options = {})
-      @paths[directory].each do |basename, meta_data|
+      paths[directory].each do |basename, meta_data|
         path = File.join(directory, basename)
-
         case meta_data.type
         when 'Dir'
-          if File.directory?(path)
-            detect_modifications_and_removals(path, options) if options[:recursive]
-          else
-            detect_modifications_and_removals(path, { :recursive => true }.merge(options))
-            @paths[directory].delete(basename)
-            @paths.delete("#{directory}/#{basename}")
-          end
+          detect_modification_or_removal_for_dir(path, options)
         when 'File'
-          if File.exist?(path)
-            new_mtime = mtime_of(path)
+          detect_modification_or_removal_for_file(path, meta_data, options)
+        end
+      end
+    end
 
-            # First check if we are in the same second (to update checksums)
-            # before checking the time difference
-            if (meta_data.mtime.to_i == new_mtime.to_i && content_modified?(path)) || meta_data.mtime < new_mtime
-              # Update the sha1 checksum of the file
-              insert_sha1_checksum(path)
+    def detect_modification_or_removal_for_dir(path, options)
 
-              # Update the meta data of the file
-              meta_data.mtime = new_mtime
-              @paths[directory][basename] = meta_data
+      # Directory still exists
+      if File.directory?(path)
+        detect_modifications_and_removals(path, options) if options[:recursive]
 
-              @changes[:modified] << (options[:relative_paths] ? relative_to_base(path) : path)
-            end
-          else
-            @paths[directory].delete(basename)
-            @sha1_checksums.delete(path)
-            @changes[:removed] << (options[:relative_paths] ? relative_to_base(path) : path)
-          end
-        end
+      # Directory has been removed
+      else
+        detect_modifications_and_removals(path, options)
+        @paths[File.dirname(path)].delete(File.basename(path))
+        @paths.delete("#{File.dirname(path)}/#{File.basename(path)}")
+      end
+    end
+
+    def detect_modification_or_removal_for_file(path, meta_data, options)
+      # File still exists
+      if File.exist?(path)
+        detect_modification(path, meta_data, options)
+
+      # File has been removed
+      else
+        removal_detected(path, meta_data, options)
+      end
+    end
+
+    def detect_modification(path, meta_data, options)
+      new_mtime = mtime_of(path)
+
+      # First check if we are in the same second (to update checksums)
+      # before checking the time difference
+      if (meta_data.mtime.to_i == new_mtime.to_i && content_modified?(path)) || meta_data.mtime < new_mtime
+        modification_detected(path, meta_data, new_mtime, options)
       end
     end
 
+    def modification_detected(path, meta_data, new_mtime, options)
+      # Update the sha1 checksum of the file
+      update_sha1_checksum(path)
+
+      # Update the meta data of the file
+      meta_data.mtime = new_mtime
+      @paths[File.dirname(path)][File.basename(path)] = meta_data
+
+      @changes[:modified] << (options[:relative_paths] ? relative_to_base(path) : path)
+    end
+
+    def removal_detected(path, meta_data, options)
+      @paths[File.dirname(path)].delete(File.basename(path))
+      @sha1_checksums.delete(path)
+      @changes[:removed] << (options[:relative_paths] ? relative_to_base(path) : path)
+    end
+
     # Detects additions in a directory.
     #
     # @param [String] directory the path to analyze
@@ -283,9 +312,10 @@ module Listen
     # @param [String] path the file path
     #
     def content_modified?(path)
+      return false unless File.ftype(path) == 'file'
       @sha1_checksum = sha1_checksum(path)
-      if @sha1_checksums[path] == @sha1_checksum || !@sha1_checksums.key?(path)
-        insert_sha1_checksum(path)
+      if sha1_checksums[path] == @sha1_checksum || !sha1_checksums.key?(path)
+        update_sha1_checksum(path)
         false
       else
         true
@@ -296,7 +326,7 @@ module Listen
     #
     # @param [String] path the SHA1-checksum path to insert in @sha1_checksums.
     #
-    def insert_sha1_checksum(path)
+    def update_sha1_checksum(path)
       if @sha1_checksum ||= sha1_checksum(path)
         @sha1_checksums[path] = @sha1_checksum
         @sha1_checksum = nil
@@ -314,13 +344,13 @@ module Listen
     end
 
     # Traverses the base directory looking for paths that should
-    # be stored; thus paths that are filters or not ignored.
+    # be stored; thus paths that are filtered or not ignored.
     #
     # @yield [path] an important path
     #
     def important_paths
-      Find.find(@directory) do |path|
-        next if path == @directory
+      Find.find(directory) do |path|
+        next if path == directory
 
         if File.directory?(path)
           # Add a trailing slash to directories when checking if a directory is
@@ -355,7 +385,7 @@ module Listen
     # @return [Boolean]
     #
     def existing_path?(path)
-      @paths[File.dirname(path)][File.basename(path)] != nil
+      paths[File.dirname(path)][File.basename(path)] != nil
     end
 
     # Returns the modification time of a file based on the precision defined by the system

data/lib/listen/listener.rb

@@ -2,14 +2,16 @@ require 'pathname'
 
 module Listen
   class Listener
-    attr_reader :directory, :directory_record, :adapter
+    attr_reader :directories, :directories_records, :block, :adapter, :adapter_options, :use_relative_paths
 
-    # The default value for using relative paths in the callback.
-    DEFAULT_TO_RELATIVE_PATHS = false
+    BLOCKING_PARAMETER_DEPRECATION_MESSAGE = <<-EOS.gsub(/^\s*/, '')
+      The blocking parameter of Listen::Listener#start is deprecated.\n
+      Please use Listen::Adapter#start for a non-blocking listener and Listen::Listener#start! for a blocking one.
+    EOS
 
-    # Initializes the directory listener.
+    # Initializes the directories listener.
     #
-    # @param [String] directory the directory to listen to
+    # @param [String] directory the directories to listen to
     # @param [Hash] options the listen options
     # @option options [Regexp] ignore a pattern for ignoring paths
     # @option options [Regexp] filter a pattern for filtering paths
@@ -23,36 +25,48 @@ module Listen
     # @yieldparam [Array<String>] added the list of added files
     # @yieldparam [Array<String>] removed the list of removed files
     #
-    def initialize(directory, options = {}, &block)
-      @block              = block
-      @directory          = Pathname.new(directory).realpath.to_s
-      @directory_record   = DirectoryRecord.new(@directory)
-      @use_relative_paths = DEFAULT_TO_RELATIVE_PATHS
+    def initialize(*args, &block)
+      options     = args.last.is_a?(Hash) ? args.pop : {}
+      directories = args.flatten
+      initialize_directories_and_directories_records(directories)
+      initialize_relative_paths_usage(options)
+      @block = block
 
-      @use_relative_paths = options.delete(:relative_paths) if options[:relative_paths]
-      @directory_record.ignore(*options.delete(:ignore))    if options[:ignore]
-      @directory_record.filter(*options.delete(:filter))    if options[:filter]
+      ignore(*options.delete(:ignore))
+      filter(*options.delete(:filter))
 
       @adapter_options = options
     end
 
     # Starts the listener by initializing the adapter and building
     # the directory record concurrently, then it starts the adapter to watch
-    # for changes.
+    # for changes. The current thread is not blocked after starting.
     #
-    # @param [Boolean] blocking whether or not to block the current thread after starting
+    # @see Listen::Listener#start!
     #
-    def start(blocking = true)
-      t = Thread.new { @directory_record.build }
-      @adapter = initialize_adapter
-      t.join
-      @adapter.start(blocking)
+    def start(deprecated_blocking = nil)
+      Kernel.warn "[Listen warning]:\n#{BLOCKING_PARAMETER_DEPRECATION_MESSAGE}" unless deprecated_blocking.nil?
+      setup
+      adapter.start
+    end
+
+    # Starts the listener by initializing the adapter and building
+    # the directory record concurrently, then it starts the adapter to watch
+    # for changes. The current thread is blocked after starting.
+    #
+    # @see Listen::Listener#start
+    #
+    # @since 1.0.0
+    #
+    def start!
+      setup
+      adapter.start!
     end
 
     # Stops the listener.
     #
     def stop
-      @adapter.stop
+      adapter.stop
     end
 
     # Pauses the listener.
@@ -60,7 +74,7 @@ module Listen
     # @return [Listen::Listener] the listener
     #
     def pause
-      @adapter.paused = true
+      adapter.pause
       self
     end
 
@@ -69,8 +83,8 @@ module Listen
     # @return [Listen::Listener] the listener
     #
     def unpause
-      @directory_record.build
-      @adapter.paused = false
+      build_directories_records
+      adapter.unpause
       self
     end
 
@@ -79,7 +93,7 @@ module Listen
     # @return [Boolean] adapter paused status
     #
     def paused?
-      !!@adapter && @adapter.paused == true
+      !!adapter && adapter.paused?
     end
 
     # Adds ignoring patterns to the listener.
@@ -88,8 +102,10 @@ module Listen
     #
     # @return [Listen::Listener] the listener
     #
+    # @see Listen::DirectoryRecord#ignore
+    #
     def ignore(*regexps)
-      @directory_record.ignore(*regexps)
+      directories_records.each { |r| r.ignore(*regexps) }
       self
     end
 
@@ -99,8 +115,10 @@ module Listen
     #
     # @return [Listen::Listener] the listener
     #
+    # @see Listen::DirectoryRecord#ignore!
+    #
     def ignore!(*regexps)
-      @directory_record.ignore!(*regexps)
+      directories_records.each { |r| r.ignore!(*regexps) }
       self
     end
 
@@ -110,19 +128,23 @@ module Listen
     #
     # @return [Listen::Listener] the listener
     #
+    # @see Listen::DirectoryRecord#filter
+    #
     def filter(*regexps)
-      @directory_record.filter(*regexps)
+      directories_records.each { |r| r.filter(*regexps) }
       self
     end
 
-    # Replacing filtering patterns in the listener.
+    # Replaces filtering patterns in the listener.
     #
     # @param (see Listen::DirectoryRecord#filter!)
     #
     # @return [Listen::Listener] the listener
     #
+    # @see Listen::DirectoryRecord#filter!
+    #
     def filter!(*regexps)
-      @directory_record.filter!(*regexps)
+      directories_records.each { |r| r.filter!(*regexps) }
       self
     end
 
@@ -171,7 +193,7 @@ module Listen
       self
     end
 
-    # Defines a custom polling fallback message of disable it.
+    # Defines a custom polling fallback message or disable it.
     #
     # @example Disabling the polling fallback message
     #   polling_fallback_message false
@@ -204,22 +226,74 @@ module Listen
     #
     # @param (see Listen::DirectoryRecord#fetch_changes)
     #
+    # @see Listen::DirectoryRecord#fetch_changes
+    #
     def on_change(directories, options = {})
-      changes = @directory_record.fetch_changes(directories, options.merge(
-        :relative_paths => @use_relative_paths
-      ))
+      changes = fetch_records_changes(directories, options)
       unless changes.values.all? { |paths| paths.empty? }
-        @block.call(changes[:modified],changes[:added],changes[:removed])
+        block.call(changes[:modified], changes[:added], changes[:removed])
       end
     end
 
     private
 
+    # Initializes the directories to watch as well as the directories records.
+    #
+    # @see Listen::DirectoryRecord
+    #
+    def initialize_directories_and_directories_records(directories)
+      @directories = directories.map { |d| Pathname.new(d).realpath.to_s }
+      @directories_records = directories.map { |d| DirectoryRecord.new(d) }
+    end
+
+    # Initializes whether or not using relative paths.
+    #
+    def initialize_relative_paths_usage(options)
+      @use_relative_paths = directories.one? && options.delete(:relative_paths) { true }
+    end
+
+    # Build the directory record concurrently and initialize the adapter.
+    #
+    def setup
+      t = Thread.new { build_directories_records }
+      @adapter = initialize_adapter
+      t.join
+    end
+
     # Initializes an adapter passing it the callback and adapters' options.
     #
     def initialize_adapter
-      callback = lambda { |changed_dirs, options| self.on_change(changed_dirs, options) }
-      Adapter.select_and_initialize(@directory, @adapter_options, &callback)
+      callback = lambda { |changed_directories, options| self.on_change(changed_directories, options) }
+      Adapter.select_and_initialize(directories, adapter_options, &callback)
+    end
+
+    # Build the watched directories' records.
+    #
+    def build_directories_records
+      directories_records.each { |r| r.build }
     end
+
+    # Returns the sum of all the changes to the directories records
+    #
+    # @param (see Listen::DirectoryRecord#fetch_changes)
+    #
+    # @return [Hash] the changes
+    #
+    def fetch_records_changes(directories_to_search, options)
+      directories_records.inject({}) do |h, r|
+        # directory records skips paths outside their range, so passing the
+        # whole `directories` array is not a problem.
+        record_changes = r.fetch_changes(directories_to_search, options.merge(:relative_paths => use_relative_paths))
+
+        if h.empty?
+          h.merge!(record_changes)
+        else
+          h.each { |k, v| h[k] += record_changes[k] }
+        end
+
+        h
+      end
+    end
+
   end
 end