listen 0.3.3 → 0.4.0

data/CHANGELOG.md

@@ -1,3 +1,25 @@
+## 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][])
+
+### Removals
+
+- Remove `wait_until_listening` as adapters doesn't need to run inside threads anymore ([@Maher4Ever][])
+
 ## 0.3.3 - March 6, 2012
 
 ### Improvements

data/README.md

@@ -5,12 +5,13 @@ The Listen gem listens to file modifications and notifies you about the changes.
 ## Features
 
 * Works everywhere!
+* 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.
+* Allows ignoring paths and supplying filters for better results.
 * Tested on all Ruby environments via [travis-ci](http://travis-ci.org/guard/listen).
-* Threadable.
 
 ## Install
 
@@ -20,19 +21,25 @@ gem install listen
 
 ## Usage
 
-There are two ways you can use Listen.
+There are **two ways** to use Listen:
 
-1. call `Listen.to` with a path params, and define callbacks in a block.
-2. create a `listener` object usable in an (ARel style) chainable way.
+1. Call `Listen.to` with either a single directory or multiple directories, then define the `change` callback in a block.
+2. Create a `listener` object and use it in an (ARel style) chainable way.
 
 Feel free to give your feeback via [Listen issues](https://github.com/guard/listener/issues)
 
 ### Block API
 
 ``` ruby
+# Listen to a single directory.
 Listen.to('dir/path/to/listen', filter: /.*\.rb/, ignore: '/ignored/path') do |modified, added, removed|
   # ...
 end
+
+# Listen to multiple directories.
+Listen.to('dir/to/awesome_app', 'dir/to/other_app', filter: /.*\.rb/, latency: 0.1) do |modified, added, removed|
+  # ...
+end
 ```
 
 ### "Object" API
@@ -45,11 +52,10 @@ listener = listener.latency(0.5)
 listener = listener.force_polling(true)
 listener = listener.polling_fallback_message(false)
 listener = listener.change(&callback)
-listener.start # enter the run loop
-listener.stop
+listener.start # blocks execution!
 ```
 
-#### Chainable
+### Chainable
 
 ``` ruby
 Listen.to('dir/path/to/listen')
@@ -59,21 +65,121 @@ Listen.to('dir/path/to/listen')
       .force_polling(true)
       .polling_fallback_message('custom message')
       .change(&callback)
-      .start # enter the run loop
+      .start # blocks execution!
 ```
 
-#### Multiple listeners support available via Thread
+### Pause/Unpause
+
+Listener can also easily be paused/unpaused:
 
 ``` ruby
-listener = Listen.to(dir1).ignore('/ignored/path/')
-styles   = listener.filter(/.*\.css/).change(&style_callback)
-scripts  = listener.filter(/.*\.js/).change(&scripts_callback)
+listener = Listen.to('dir/path/to/listen')
+listener.start(false) # non-blocking mode
+listener.pause   # stop listening to changes
+listener.paused? # => true
+listener.unpause
+listener.stop
+```
+
+## Listening to changes on multiple directories
+
+The Listen gem provides the `MultiListener` class to watch multiple directories and
+handle their changes from a single listener:
+
+```ruby
+listener = Listen::MultiListener.new('app/css', 'app/js')
+listener.latency(0.5)
+
+# Configure the listener to your needs...
+
+listener.start # blocks execution!
+````
+
+For an easier access, the `Listen.to` method can also be used to create a multi-listener:
+
+``` ruby
+listener = Listen.to('app/css', 'app/js')
+                 .ignore('vendor') # both js/vendor and css/vendor will be ignored
+                 .change(&assets_callback)
+
+listener.start # blocks execution!
+```
+
+## Changes callback
+
+Changes to the listened-to directories gets reported back to the user in a callback.
+The registered callback gets invoked, when there are changes, with **three** parameters:
+`modified_paths`, `added_paths` and `removed_paths` in that particular order.
+
+You can register a callback in two ways. The first way is by passing a block when calling
+the `Listen.to` method or when initializing a listener object:
+
+```ruby
+Listen.to('path/to/app') do |modified, added, removed|
+  # This block will be called when there are changes.
+end
+
+# or ...
+
+listener = Listen::Listener.new('path/to/app') do |modified, added, removed|
+  # This block will be called when there are changes.
+end
+
+```
 
-Thread.new { styles.start } # enter the run loop
-Thread.new { scripts.start } # enter the run loop
+The second way to register a callback is be calling the `change` method on any
+listener passing it a block:
+
+```ruby
+# Create a callback
+callback = Proc.new do |modified, added, removed|
+  # This proc will be called when there are changes.
+end
+
+listener = Listen.to('dir')
+listener.change(&callback) # convert the callback to a block and register it
+
+listener.start # blocks execution
+```
+
+### Paths in callbacks
+
+Listeners invoke callbacks passing them absolute paths by default:
+
+```ruby
+# Assume someone changes the 'style.css' file in '/home/user/app/css' after creating
+# the listener.
+Listen.to('/home/user/app/css') do |modified, added, removed|
+  modified.inspect # => ['/home/user/app/css/style.css']
+end
+```
+
+#### Relative paths in callbacks
+
+When creating a listener for a **single** path (more specifically a `Listen::Listener` instance),
+you can pass `:relative_paths => true` as an option to get relative paths in
+your callback:
+
+```ruby
+# Assume someone changes the 'style.css' file in '/home/user/app/css' after creating
+# the listener.
+Listen.to('/home/user/app/css', :relative_paths => true) do |modified, added, removed|
+  modified.inspect # => ['style.css']
+end
 ```
 
-### Options
+Passing the `:relative_paths => true` option won't work when listeneing to multiple
+directories:
+
+```ruby
+# Assume someone changes the 'style.css' file in '/home/user/app/css' after creating
+# the listener.
+Listen.to('/home/user/app/css', '/home/user/app/js', :relative_paths => true) do |modified, added, removed|
+  modified.inspect # => ['/home/user/app/css/style.css']
+end
+```
+
+## Options
 
 These options can be set through `Listen.to` params or via methods (see the "Object" API)
 
@@ -94,19 +200,28 @@ These options can be set through `Listen.to` params or via methods (see the "Obj
                                                # default: "WARNING: Listen fallen back to polling, learn more at https://github.com/guard/listen#fallback."
 ```
 
-### Pause/Unpause
+### Non-blocking listening to changes
 
-Listener can also easily be paused/unpaused:
+Starting a listener blocks the current thread by default. That means any code after the
+`start` call won't be run until the listener is stopped (which needs to be done from another thread).
 
-``` ruby
+For advanced usage there is an option to disable this behavior and have the listener start working
+in the background without blocking. To enable non-blocking listening the `start` method of
+the listener (be it `Listener` or `MultiListener`) needs to be called with `false` as a parameter.
+
+Here is an example of using a listener in the non-blocking mode:
+
+```ruby
 listener = Listen.to('dir/path/to/listen')
-listener.start   # enter the run loop
-listener.pause   # stop listening changes
-listener.paused? => true
-listener.unpause
-listener.stop
+listener.start(false) # doesn't block execution
+
+# Code here will run immediately after starting the listener
+
 ```
 
+**note**: Using the `Listen.to` helper-method with a callback-block will always
+block execution. See the "Block API" section for an example.
+
 ## Listen adapters
 
 The Listen gem has a set of adapters to notify it when there are changes.
@@ -122,17 +237,17 @@ while initializing the listener or call the `force_polling` method on your liste
 before starting it.
 
 <a name="fallback"/>
-### Polling fallback
+## Polling fallback
 
-When the OS-specific adapter doesn't work the Listen gem automatically falls back to the polling adapter.
-Here some things to try to avoiding this fallback:
+When a OS-specific adapter doesn't work the Listen gem automatically falls back to the polling adapter.
+Here are some things you could try to avoid the polling fallback:
 
 * [Update your Dropbox client](http://www.dropbox.com/downloading) (if used).
 * Increase latency. (Please [open an issue](https://github.com/guard/listen/issues/new) if you think that default is too low.)
 * Move or rename the listened folder.
 * Update/reboot your OS.
 
-If it still falling back, feel free to [open an issue](https://github.com/guard/listen/issues/new) (and be sure to give all details).
+If your application keeps using the polling-adapter and you can't figure out why, feel free to [open an issue](https://github.com/guard/listen/issues/new) (and be sure to give all the details).
 
 ## Development [![Dependency Status](https://gemnasium.com/guard/listen.png?branch=master)](https://gemnasium.com/guard/listen)
 
@@ -159,15 +274,17 @@ For questions please join us in our [Google group](http://groups.google.com/grou
 * [stereobooster][] for [rb-fchange][], windows support wouldn't exist without him.
 * [Yehuda Katz (wycats)][] for [vigilo][], that has been a great source of inspiration.
 
-## Author
+## Authors
 
-[Thibaud Guillaume-Gentil][] ([@thibaudgg](http://twitter.com/thibaudgg))
+* [Thibaud Guillaume-Gentil][] ([@thibaudgg](http://twitter.com/thibaudgg))
+* [Maher Sallam][] ([@mahersalam](http://twitter.com/mahersalam))
 
 ## Contributors
 
 [https://github.com/guard/listen/contributors](https://github.com/guard/listen/contributors)
 
 [Thibaud Guillaume-Gentil]: https://github.com/thibaudgg
+[Maher Sallam]: https://github.com/Maher4Ever
 [Michael Kessler (netzpirat)]: https://github.com/netzpirat
 [Travis Tilley (ttilley)]: https://github.com/ttilley
 [fssm]: https://github.com/ttilley/fssm

data/lib/listen.rb

@@ -1,15 +1,22 @@
-require 'listen/listener'
-
 module Listen
 
-  # Listen to file system modifications.
+  autoload :Turnstile,       'listen/turnstile'
+  autoload :Listener,        'listen/listener'
+  autoload :MultiListener,   'listen/multi_listener'
+  autoload :DirectoryRecord, 'listen/directory_record'
+  autoload :Adapter,         'listen/adapter'
+
+  module Adapters
+    autoload :Darwin,  'listen/adapters/darwin'
+    autoload :Linux,   'listen/adapters/linux'
+    autoload :Windows, 'listen/adapters/windows'
+    autoload :Polling, 'listen/adapters/polling'
+  end
+
+  # Listens to filesystem modifications on a either single directory or multiple directories.
   #
-  # @param [String, Pathname] dir the directory to watch
-  # @param [Hash] options the listen options
-  # @option options [String] ignore a list of paths to ignore
-  # @option options [Regexp] filter a list of regexps file filters
-  # @option options [Float] latency the delay between checking for changes in seconds
-  # @option options [Boolean] polling whether to force or disable the polling adapter
+  # @param (see Listen::Listener#new)
+  # @param (see Listen::MultiListener#new)
   #
   # @yield [modified, added, removed] the changed files
   # @yieldparam [Array<String>] modified the list of modified files
@@ -19,7 +26,12 @@ module Listen
   # @return [Listen::Listener] the file listener if no block given
   #
   def self.to(*args, &block)
-    listener = Listener.new(*args, &block)
+    listener = if args.length == 1 || ! args[1].is_a?(String)
+      Listener.new(*args, &block)
+    else
+      MultiListener.new(*args, &block)
+    end
+
     block ? listener.start : listener
   end
 

data/lib/listen/adapter.rb

@@ -1,18 +1,22 @@
 require 'rbconfig'
+require 'thread'
+require 'set'
+require 'fileutils'
 
 module Listen
   class Adapter
-    attr_accessor :latency, :paused
+    attr_accessor :directories, :latency, :paused
 
     # The default delay between checking for changes.
     DEFAULT_LATENCY = 0.1
+
     # The default warning message when falling back to polling adapter.
-    POLLING_FALLBACK_MESSAGE = "WARNING: Listen fallen back to polling, learn more at https://github.com/guard/listen#fallback."
+    POLLING_FALLBACK_MESSAGE = "WARNING: Listen has fallen back to polling, learn more at https://github.com/guard/listen#fallback."
 
-    # Select the appropriate adapter implementation for the
+    # Selects the appropriate adapter implementation for the
     # current OS and initializes it.
     #
-    # @param [String, Pathname] directory the directory to watch
+    # @param [String, Array<String>] directories the directories to watch
     # @param [Hash] options the adapter options
     # @option options [Boolean] force_polling to force polling or not
     # @option options [String, Boolean] polling_fallback_message to change polling fallback message or remove it
@@ -24,26 +28,26 @@ module Listen
     #
     # @return [Listen::Adapter] the chosen adapter
     #
-    def self.select_and_initialize(directory, options = {}, &callback)
-      return Adapters::Polling.new(directory, options, &callback) if options.delete(:force_polling)
+    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_work?(directory, options)
-        Adapters::Darwin.new(directory, options, &callback)
-      elsif Adapters::Linux.usable_and_work?(directory, options)
-        Adapters::Linux.new(directory, options, &callback)
-      elsif Adapters::Windows.usable_and_work?(directory, options)
-        Adapters::Windows.new(directory, options, &callback)
+      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)
         end
-        Adapters::Polling.new(directory, options, &callback)
+        Adapters::Polling.new(directories, options, &callback)
       end
     end
 
-    # Initialize the adapter.
+    # Initializes the adapter.
     #
-    # @param [String, Pathname] directory the directory to watch
+    # @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
     #
@@ -53,68 +57,103 @@ module Listen
     #
     # @return [Listen::Adapter] the adapter
     #
-    def initialize(directory, options = {}, &callback)
-      @directory = directory
-      @callback  = callback
-      @latency ||= DEFAULT_LATENCY
-      @latency   = options[:latency] if options[:latency]
-      @paused    = false
+    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
     end
 
-    # Start the adapter.
+    # Starts the adapter.
     #
-    def start
+    # @param [Boolean] blocking whether or not to block the current thread after starting
+    #
+    def start(blocking = true)
       @stop = false
     end
 
-    # Stop the adapter.
+    # Stops the adapter.
     #
     def stop
       @stop = true
+      @turnstile.signal # ensure no thread is blocked
     end
 
-  private
+    # Blocks the main thread until the poll thread
+    # calls the callback.
+    #
+    def wait_for_callback
+      @turnstile.wait unless @paused
+    end
 
-    # Check if the adapter is usable and works on the current OS.
+    # Checks if the adapter is usable and works on the current OS.
     #
-    # @param [String, Pathname] directory the directory to watch
+    # @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
     #
     # @return [Boolean] whether usable and work or not
     #
-    def self.usable_and_work?(directory, options = {})
-      usable? && work?(directory, options)
+    def self.usable_and_works?(directories, options = {})
+      usable? && Array(directories).all? { |d| works?(d, options) }
     end
 
-    # Check if the adapter is really working on the current OS by actually testing it.
-    # This test take some time depending the adapter latency (max latency + 0.2 seconds).
+    # Runs a tests to determine if the adapter can actually pick up
+    # changes in a given directory and returns the result.
+    #
+    # @note This test takes some time depending the adapter latency.
     #
     # @param [String, Pathname] directory the directory to watch
     # @param [Hash] options the adapter options
     # @option options [Float] latency the delay between checking for changes in seconds
     #
-    # @return [Boolean] whether work or not
-    #
-    def self.work?(directory, options = {})
-      @work = nil
-      Thread.new do
-        begin
-          callback = lambda { |changed_dirs, options| @work = true }
-          adapter  = self.new(directory, options, &callback)
-          thread   = Thread.new { adapter.start }
-          sleep 0.1 # wait for the adapter starts
-          FileUtils.touch "#{directory}/.listen_test"
-          sleep adapter.latency + 0.1 # wait for callback
-          @work ||= false
-          Thread.kill(thread)
-        ensure
-          FileUtils.rm "#{directory}/.listen_test"
+    # @return [Boolean] whether the adapter works or not
+    #
+    def self.works?(directory, options = {})
+      work = false
+      test_file = "#{directory}/.listen_test"
+      callback = lambda { |changed_dirs, options| work = true }
+      adapter  = self.new(directory, options, &callback)
+      adapter.start(false)
+
+      FileUtils.touch(test_file)
+
+      t = Thread.new { sleep(adapter.latency * 5); adapter.stop }
+
+      adapter.wait_for_callback
+      work
+    ensure
+      Thread.kill(t) if t
+      FileUtils.rm(test_file) if File.exists?(test_file)
+      adapter.stop
+    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)
+      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} : {})
+        @turnstile.signal
       end
-      sleep 0.01 while @work.nil?
-      @work
     end
-
   end
 end