listen 0.4.7 → 0.5.0

data/CHANGELOG.md

@@ -1,147 +1,161 @@
-## 0.4.7 - June 27, 2012
-
-### Bug fixes
-
-- Increase latency to 0.25, to avoid useless polling fallback. (fixed by [@thibaudgg][])
-- Change watched inotify events, to avoid duplication callback. (fixed by [@thibaudgg][])
-- [#41](https://github.com/guard/listen/issues/41) Use lstat instead of stat when calculating mtime. (fixed by [@ebroder][])
-
-## 0.4.6 - June 20, 2012
-
-### Bug fix
-
-- [#39](https://github.com/guard/listen/issues/39) Fix digest race condition. (fixed by [@dkubb][])
-
-## 0.4.5 - June 13, 2012
-
-### Bug fix
-
-- [#39](https://github.com/guard/listen/issues/39) Rescue Errno::ENOENT when path inserted doesn't exist. (reported by [@textgoeshere][], fixed by [@thibaudgg][] and [@rymai][])
-
-## 0.4.4 - June 8, 2012
-
-### Bug fixes
-
-- ~~[#39](https://github.com/guard/listen/issues/39) Non-existing path insertion bug. (reported by [@textgoeshere][], fixed by [@thibaudgg][])~~
-- Fix relative path for directories containing special characters. (reported by [@napcs][], fixed by [@netzpirat][])
-
-## 0.4.3 - June 6, 2012
-
-### Bug fixes
-
-- [#24](https://github.com/guard/listen/issues/24) Fail gracefully when the inotify limit is not enough for Listen to function. (reported by [@daemonza][], fixed by [@Maher4Ever][])
-- [#32](https://github.com/guard/listen/issues/32) Fix a crash when trying to calculate the checksum of unreadable files. (reported by [@nex3][], fixed by [@Maher4Ever][])
-
-### Improvements
-
-- Add `#relative_paths` method to listeners. ([@Maher4Ever][])
-- Add `#started?` query-method to adapters. ([@Maher4Ever][])
-- Dynamically detect the mtime precision used on a system. ([@Maher4Ever][] with help from [@nex3][])
-
-## 0.4.2 - May 1, 2012
-
-### Bug fixes
-
-- [#21](https://github.com/guard/listen/issues/21) Issues when listening to changes in relative paths. (reported by [@akerbos][], fixed by [@Maher4Ever][])
-- [#27](https://github.com/guard/listen/issues/27) Wrong reports for files modifications. (reported by [@cobychapple][], fixed by [@Maher4Ever][])
-- Fix segmentation fault when profiling on Windows. ([@Maher4Ever][])
-- Fix redundant watchers on Windows. ([@Maher4Ever][])
-
-### Improvements
-
-- [#17](https://github.com/guard/listen/issues/17) Use regexp-patterns with the `ignore` method instead of supplying paths. (reported by [@fny][], added by [@Maher4Ever][])
-- Speed improvement when listening to changes in directories with ignored paths. ([@Maher4Ever][])
-- Added `.rbx` and `.svn` to ignored directories. ([@Maher4Ever][])
-
-## 0.4.1 - April 15, 2012
-
-### Bug fix
-
-- [#18](https://github.com/guard/listen/issues/18) Listener crashes when removing directories with nested paths. (reported by [@daemonza][], fixed by [@Maher4Ever][])
-
-## 0.4.0 - April 9, 2012
-
-### New features
-
-- Add `wait_for_callback` method to all adapters. ([@Maher4Ever][])
-- Add `Listen::MultiListener` class to listen to multiple directories at once. ([@Maher4Ever][])
-- Allow passing multiple directories to the `Listen.to` method. ([@Maher4Ever][])
-- Add `blocking` option to `Listen#start` which can be used to disable blocking the current thread upon starting. ([@Maher4Ever][])
-- Use absolute-paths in callbacks by default instead of relative-paths. ([@Maher4Ever][])
-- Add `relative_paths` option to `Listen::Listener` to retain the old functionality. ([@Maher4Ever][])
-
-### Improvements
-
-- Encapsulate thread spawning in the linux-adapter. ([@Maher4Ever][])
-- Encapsulate thread spawning in the darwin-adapter. ([@Maher4Ever][] with [@scottdavis][] help)
-- Encapsulate thread spawning in the windows-adapter. ([@Maher4Ever][])
-- Fix linux-adapter bug where Listen would report file-modification events on the parent-directory. ([@Maher4Ever][])
-
-### Change
-
-- Remove `wait_until_listening` as adapters doesn't need to run inside threads anymore ([@Maher4Ever][])
-
-## 0.3.3 - March 6, 2012
-
-### Improvement
-
-- Improve pause/unpause. ([@thibaudgg][])
-
-## 0.3.2 - March 4, 2012
-
-### New feature
-
-- Add pause/unpause listener's methods. ([@thibaudgg][])
-
-## 0.3.1 - February 22, 2012
-
-### Bug fix
-
-- [#9](https://github.com/guard/listen/issues/9) Ignore doesn't seem to work. (reported by [@markiz][], fixed by [@thibaudgg][])
-
-## 0.3.0 - February 21, 2012
-
-### New features
-
-- Add automatic fallback to polling if system adapter doesn't work (like a DropBox folder). ([@thibaudgg][])
-- Add latency and force_polling options. ([@Maher4Ever][])
-
-## 0.2.0 - February 13, 2012
-
-### New features
-
-- Add checksum comparaison support for detecting consecutive file modifications made during the same second. ([@thibaudgg][])
-- Add rb-fchange support. ([@thibaudgg][])
-- Add rb-inotify support. ([@thibaudgg][] with [@Maher4Ever][] help)
-- Add rb-fsevent support. ([@thibaudgg][])
-- Add non-recursive diff with multiple directories support. ([@thibaudgg][])
-- Ignore .DS_Store by default. ([@thibaudgg][])
-
-## 0.1.0 - January 28, 2012
-
-- First version with only a polling adapter and basic features set (ignore & filter). ([@thibaudgg][])
-
-<!--- The following link definition list is generated by PimpMyChangelog --->
-[#9]: https://github.com/guard/listen/issues/9
-[#17]: https://github.com/guard/listen/issues/17
-[#18]: https://github.com/guard/listen/issues/18
-[#21]: https://github.com/guard/listen/issues/21
-[#24]: https://github.com/guard/listen/issues/24
-[#27]: https://github.com/guard/listen/issues/27
-[#32]: https://github.com/guard/listen/issues/32
-[#39]: https://github.com/guard/listen/issues/39
-[@Maher4Ever]: https://github.com/Maher4Ever
-[@dkubb]: https://github.com/dkubb
-[@ebroder]: https://github.com/ebroder
-[@akerbos]: https://github.com/akerbos
-[@cobychapple]: https://github.com/cobychapple
-[@daemonza]: https://github.com/daemonza
-[@fny]: https://github.com/fny
-[@markiz]: https://github.com/markiz
-[@napcs]: https://github.com/napcs
-[@netzpirat]: https://github.com/netzpirat
-[@nex3]: https://github.com/nex3
-[@rymai]: https://github.com/rymai
-[@scottdavis]: https://github.com/scottdavis
-[@textgoeshere]: https://github.com/textgoeshere
-[@thibaudgg]: https://github.com/thibaudgg
+## 0.5.0 - Septemper 1, 2012
+
+### New features
+
+- Add a dependency manager to handle platform-specific gems. So there is no need anymore to install
+  extra gems which will never be used on the user system. ([@Maher4Ever][])
+- Add a manual reporting mode to the adapters. ([@Maher4Ever][])
+
+### Improvements
+
+- [#28] Enhance the speed of detecting changes on Windows by using the [WDM][] library. ([@Maher4Ever][])
+
+## 0.4.7 - June 27, 2012
+
+### Bug fixes
+
+- Increase latency to 0.25, to avoid useless polling fallback. (fixed by [@thibaudgg][])
+- Change watched inotify events, to avoid duplication callback. (fixed by [@thibaudgg][])
+- [#41](https://github.com/guard/listen/issues/41) Use lstat instead of stat when calculating mtime. (fixed by [@ebroder][])
+
+## 0.4.6 - June 20, 2012
+
+### Bug fix
+
+- [#39](https://github.com/guard/listen/issues/39) Fix digest race condition. (fixed by [@dkubb][])
+
+## 0.4.5 - June 13, 2012
+
+### Bug fix
+
+- [#39](https://github.com/guard/listen/issues/39) Rescue Errno::ENOENT when path inserted doesn't exist. (reported by [@textgoeshere][], fixed by [@thibaudgg][] and [@rymai][])
+
+## 0.4.4 - June 8, 2012
+
+### Bug fixes
+
+- ~~[#39](https://github.com/guard/listen/issues/39) Non-existing path insertion bug. (reported by [@textgoeshere][], fixed by [@thibaudgg][])~~
+- Fix relative path for directories containing special characters. (reported by [@napcs][], fixed by [@netzpirat][])
+
+## 0.4.3 - June 6, 2012
+
+### Bug fixes
+
+- [#24](https://github.com/guard/listen/issues/24) Fail gracefully when the inotify limit is not enough for Listen to function. (reported by [@daemonza][], fixed by [@Maher4Ever][])
+- [#32](https://github.com/guard/listen/issues/32) Fix a crash when trying to calculate the checksum of unreadable files. (reported by [@nex3][], fixed by [@Maher4Ever][])
+
+### Improvements
+
+- Add `#relative_paths` method to listeners. ([@Maher4Ever][])
+- Add `#started?` query-method to adapters. ([@Maher4Ever][])
+- Dynamically detect the mtime precision used on a system. ([@Maher4Ever][] with help from [@nex3][])
+
+## 0.4.2 - May 1, 2012
+
+### Bug fixes
+
+- [#21](https://github.com/guard/listen/issues/21) Issues when listening to changes in relative paths. (reported by [@akerbos][], fixed by [@Maher4Ever][])
+- [#27](https://github.com/guard/listen/issues/27) Wrong reports for files modifications. (reported by [@cobychapple][], fixed by [@Maher4Ever][])
+- Fix segmentation fault when profiling on Windows. ([@Maher4Ever][])
+- Fix redundant watchers on Windows. ([@Maher4Ever][])
+
+### Improvements
+
+- [#17](https://github.com/guard/listen/issues/17) Use regexp-patterns with the `ignore` method instead of supplying paths. (reported by [@fny][], added by [@Maher4Ever][])
+- Speed improvement when listening to changes in directories with ignored paths. ([@Maher4Ever][])
+- Added `.rbx` and `.svn` to ignored directories. ([@Maher4Ever][])
+
+## 0.4.1 - April 15, 2012
+
+### Bug fix
+
+- [#18](https://github.com/guard/listen/issues/18) Listener crashes when removing directories with nested paths. (reported by [@daemonza][], fixed by [@Maher4Ever][])
+
+## 0.4.0 - April 9, 2012
+
+### New features
+
+- Add `wait_for_callback` method to all adapters. ([@Maher4Ever][])
+- Add `Listen::MultiListener` class to listen to multiple directories at once. ([@Maher4Ever][])
+- Allow passing multiple directories to the `Listen.to` method. ([@Maher4Ever][])
+- Add `blocking` option to `Listen#start` which can be used to disable blocking the current thread upon starting. ([@Maher4Ever][])
+- Use absolute-paths in callbacks by default instead of relative-paths. ([@Maher4Ever][])
+- Add `relative_paths` option to `Listen::Listener` to retain the old functionality. ([@Maher4Ever][])
+
+### Improvements
+
+- Encapsulate thread spawning in the linux-adapter. ([@Maher4Ever][])
+- Encapsulate thread spawning in the darwin-adapter. ([@Maher4Ever][] with [@scottdavis][] help)
+- Encapsulate thread spawning in the windows-adapter. ([@Maher4Ever][])
+- Fix linux-adapter bug where Listen would report file-modification events on the parent-directory. ([@Maher4Ever][])
+
+### Change
+
+- Remove `wait_until_listening` as adapters doesn't need to run inside threads anymore ([@Maher4Ever][])
+
+## 0.3.3 - March 6, 2012
+
+### Improvement
+
+- Improve pause/unpause. ([@thibaudgg][])
+
+## 0.3.2 - March 4, 2012
+
+### New feature
+
+- Add pause/unpause listener's methods. ([@thibaudgg][])
+
+## 0.3.1 - February 22, 2012
+
+### Bug fix
+
+- [#9](https://github.com/guard/listen/issues/9) Ignore doesn't seem to work. (reported by [@markiz][], fixed by [@thibaudgg][])
+
+## 0.3.0 - February 21, 2012
+
+### New features
+
+- Add automatic fallback to polling if system adapter doesn't work (like a DropBox folder). ([@thibaudgg][])
+- Add latency and force_polling options. ([@Maher4Ever][])
+
+## 0.2.0 - February 13, 2012
+
+### New features
+
+- Add checksum comparaison support for detecting consecutive file modifications made during the same second. ([@thibaudgg][])
+- Add rb-fchange support. ([@thibaudgg][])
+- Add rb-inotify support. ([@thibaudgg][] with [@Maher4Ever][] help)
+- Add rb-fsevent support. ([@thibaudgg][])
+- Add non-recursive diff with multiple directories support. ([@thibaudgg][])
+- Ignore .DS_Store by default. ([@thibaudgg][])
+
+## 0.1.0 - January 28, 2012
+
+- First version with only a polling adapter and basic features set (ignore & filter). ([@thibaudgg][])
+
+<!--- The following link definition list is generated by PimpMyChangelog --->
+[#9]: https://github.com/guard/listen/issues/9
+[#17]: https://github.com/guard/listen/issues/17
+[#18]: https://github.com/guard/listen/issues/18
+[#21]: https://github.com/guard/listen/issues/21
+[#24]: https://github.com/guard/listen/issues/24
+[#27]: https://github.com/guard/listen/issues/27
+[#28]: https://github.com/guard/listen/issues/28
+[#32]: https://github.com/guard/listen/issues/32
+[#39]: https://github.com/guard/listen/issues/39
+[@Maher4Ever]: https://github.com/Maher4Ever
+[@dkubb]: https://github.com/dkubb
+[@ebroder]: https://github.com/ebroder
+[@akerbos]: https://github.com/akerbos
+[@cobychapple]: https://github.com/cobychapple
+[@daemonza]: https://github.com/daemonza
+[@fny]: https://github.com/fny
+[@markiz]: https://github.com/markiz
+[@napcs]: https://github.com/napcs
+[@netzpirat]: https://github.com/netzpirat
+[@nex3]: https://github.com/nex3
+[@rymai]: https://github.com/rymai
+[@scottdavis]: https://github.com/scottdavis
+[@textgoeshere]: https://github.com/textgoeshere
+[@thibaudgg]: https://github.com/thibaudgg
+[WDM]: https://github.com/Maher4Ever/wdm

data/LICENSE

@@ -1,20 +1,20 @@
-Copyright (c) 2012 Thibaud Guillaume-Gentil
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Copyright (c) 2012 Thibaud Guillaume-Gentil
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -8,8 +8,8 @@ The Listen gem listens to file modifications and notifies you about the changes.
 * Supports watching multiple directories from a single listener.
 * OS-specific adapters for Mac OS X 10.6+, Linux and Windows.
 * Automatic fallback to polling if OS-specific adapter doesn't work.
-* Detects files modification, addidation and removal.
-* Checksum comparaison for modifications made under the same second.
+* Detects file modification, addition and removal.
+* Checksum comparison for modifications made under the same second.
 * Allows supplying regexp-patterns to ignore and filter paths for better results.
 * Tested on all Ruby environments via [travis-ci](http://travis-ci.org/guard/listen).
 
@@ -251,7 +251,6 @@ want to force the use of the polling adapter, either use the `:force_polling` op
 while initializing the listener or call the `force_polling` method on your listener
 before starting it.
 
-<a name="fallback"/>
 ## Polling fallback
 
 When a OS-specific adapter doesn't work the Listen gem automatically falls back to the polling adapter.

data/lib/listen.rb

@@ -1,10 +1,11 @@
 module Listen
 
-  autoload :Turnstile,       'listen/turnstile'
-  autoload :Listener,        'listen/listener'
-  autoload :MultiListener,   'listen/multi_listener'
-  autoload :DirectoryRecord, 'listen/directory_record'
-  autoload :Adapter,         'listen/adapter'
+  autoload :Turnstile,         'listen/turnstile'
+  autoload :Listener,          'listen/listener'
+  autoload :MultiListener,     'listen/multi_listener'
+  autoload :DirectoryRecord,   'listen/directory_record'
+  autoload :DependencyManager, 'listen/dependency_manager'
+  autoload :Adapter,           'listen/adapter'
 
   module Adapters
     autoload :Darwin,  'listen/adapters/darwin'

data/lib/listen/adapter.rb

@@ -10,8 +10,15 @@ module Listen
     # The default delay between checking for changes.
     DEFAULT_LATENCY = 0.25
 
+    # The default warning message when there is a missing dependency.
+    MISSING_DEPENDENCY_MESSAGE = <<-EOS.gsub(/^\s*/, '')
+      For a better performance, it's recommended that you satisfy the missing dependency.
+    EOS
+
     # The default warning message when falling back to polling adapter.
-    POLLING_FALLBACK_MESSAGE = "WARNING: Listen has fallen back to polling, learn more at https://github.com/guard/listen#fallback."
+    POLLING_FALLBACK_MESSAGE = <<-EOS.gsub(/^\s*/, '')
+      Listen will be polling changes. Learn more at https://github.com/guard/listen#polling-fallback.
+    EOS
 
     # Selects the appropriate adapter implementation for the
     # current OS and initializes it.
@@ -31,18 +38,26 @@ module Listen
     def self.select_and_initialize(directories, options = {}, &callback)
       return Adapters::Polling.new(directories, options, &callback) if options.delete(:force_polling)
 
-      if Adapters::Darwin.usable_and_works?(directories, options)
-        Adapters::Darwin.new(directories, options, &callback)
-      elsif Adapters::Linux.usable_and_works?(directories, options)
-        Adapters::Linux.new(directories, options, &callback)
-      elsif Adapters::Windows.usable_and_works?(directories, options)
-        Adapters::Windows.new(directories, options, &callback)
-      else
-        unless options[:polling_fallback_message] == false
-          Kernel.warn(options[:polling_fallback_message] || POLLING_FALLBACK_MESSAGE)
+      warning = ''
+
+      begin
+        if Adapters::Darwin.usable_and_works?(directories, options)
+          return Adapters::Darwin.new(directories, options, &callback)
+        elsif Adapters::Linux.usable_and_works?(directories, options)
+          return Adapters::Linux.new(directories, options, &callback)
+        elsif Adapters::Windows.usable_and_works?(directories, options)
+          return Adapters::Windows.new(directories, options, &callback)
         end
-        Adapters::Polling.new(directories, options, &callback)
+      rescue DependencyManager::Error => e
+        warning += e.message + "\n" + MISSING_DEPENDENCY_MESSAGE
+      end
+
+      unless options[:polling_fallback_message] == false
+        warning += options[:polling_fallback_message] || POLLING_FALLBACK_MESSAGE
+        Kernel.warn "[Listen warning]:\n" + warning.gsub(/^(.*)/, '  \1')
       end
+
+      Adapters::Polling.new(directories, options, &callback)
     end
 
     # Initializes the adapter.
@@ -50,6 +65,7 @@ module Listen
     # @param [String, Array<String>] directories the directories to watch
     # @param [Hash] options the adapter options
     # @option options [Float] latency the delay between checking for changes in seconds
+    # @option options [Boolean] report_changes whether or not to automatically report changes (run the callback)
     #
     # @yield [changed_dirs, options] callback Callback called when a change happens
     # @yieldparam [Array<String>] changed_dirs the changed directories
@@ -60,12 +76,13 @@ module Listen
     def initialize(directories, options = {}, &callback)
       @directories  = Array(directories)
       @callback     = callback
-      @latency    ||= DEFAULT_LATENCY
-      @latency      = options[:latency] if options[:latency]
       @paused       = false
       @mutex        = Mutex.new
       @changed_dirs = Set.new
       @turnstile    = Turnstile.new
+      @latency    ||= DEFAULT_LATENCY
+      @latency      = options[:latency] if options[:latency]
+      @report_changes = options[:report_changes].nil? ? true : options[:report_changes]
     end
 
     # Starts the adapter.
@@ -92,12 +109,37 @@ module Listen
     end
 
     # Blocks the main thread until the poll thread
-    # calls the callback.
+    # runs the callback.
     #
     def wait_for_callback
       @turnstile.wait unless @paused
     end
 
+    # Blocks the main thread until N changes are
+    # detected.
+    #
+    def wait_for_changes(goal = 0)
+      changes = 0
+
+      loop do
+        @mutex.synchronize { changes = @changed_dirs.size }
+
+        return if @paused || @stop
+        return if changes >= goal
+
+        sleep(@latency)
+      end
+    end
+
+    # Checks if the adapter is usable on the current OS.
+    #
+    # @return [Boolean] whether usable or not
+    #
+    def self.usable?
+      load_depenencies
+      dependencies_loaded?
+    end
+
     # Checks if the adapter is usable and works on the current OS.
     #
     # @param [String, Array<String>] directories the directories to watch
@@ -140,26 +182,29 @@ module Listen
       adapter.stop if adapter && adapter.started?
     end
 
+    # Runs the callback and passes it the changes if there are any.
+    #
+    def report_changes
+      changed_dirs = nil
+
+      @mutex.synchronize do
+        return if @changed_dirs.empty?
+        changed_dirs = @changed_dirs.to_a
+        @changed_dirs.clear
+      end
+
+      @callback.call(changed_dirs, {})
+    end
+
     private
 
     # Polls changed directories and reports them back
     # when there are changes.
     #
-    # @option [Boolean] recursive whether or not to pass the recursive option to the callback
-    #
-    def poll_changed_dirs(recursive = false)
+    def poll_changed_dirs
       until @stop
         sleep(@latency)
-        next if @changed_dirs.empty?
-
-        changed_dirs = []
-
-        @mutex.synchronize do
-          changed_dirs = @changed_dirs.to_a
-          @changed_dirs.clear
-        end
-
-        @callback.call(changed_dirs, recursive ? {:recursive => recursive} : {})
+        report_changes
         @turnstile.signal
       end
     end