directory_watcher 1.4.1 → 1.5.1

data/.gitignore

@@ -0,0 +1,17 @@
+# git-ls-files --others --exclude-from=.git/info/exclude
+# Lines that start with '#' are comments.
+# For a project mostly in C, the following would be a good set of
+# exclude patterns (uncomment them if you want to use them):
+# *.[oa]
+# *~
+announcement.txt
+coverage
+doc
+pkg
+tags
+temp.dir
+tmp.rb
+tmp.yml
+vendor
+script
+spec/scratch

data/History.txt

@@ -1,3 +1,13 @@
+== Next Version / 2011-XX-XX
+
+Major Enhancements
+- tests!
+- major refactor
+
+Minor Enhancement
+- events generated from full scans may be sorted by mtime or size
+- stat information is propagated into the event
+
 == 1.4.1 / 2011-08-29
 
 Minor Enhancements

data/README.txt

@@ -41,7 +41,7 @@ the same disclaimer as the EventMachine functionality.
 == LICENSE:
 
 MIT License
-Copyright (c) 2007 - 2009
+Copyright (c) 2007 - 2013
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/Rakefile

@@ -5,16 +5,27 @@ rescue LoadError
   abort '### please install the "bones" gem ###'
 end
 
+task :default => 'spec:run'
+#task 'gem:release' => 'spec:run'
+
 Bones {
   name         'directory_watcher'
   summary      'A class for watching files within a directory and generating events when those files change'
-  authors      'Tim Pease'
+  authors      ['Tim Pease', 'Jeremy Hinegardner']
   email        'tim.pease@gmail.com'
-  url          'http://gemcutter.org/gems/directory_watcher'
-  ignore_file  '.gitignore'
+  url          'http://rubygems.org/gems/directory_watcher'
+
+  spec.opts << "--color" << "--format documentation"
 
-  depend_on  'bones-git',    :development => true
-  depend_on  'rev',          :development => true
+  # these are optional dependencies for runtime, adding one of them will provide
+  # additional Scanner backends.
+  depend_on  'rev'         , :development => true
   depend_on  'eventmachine', :development => true
+  depend_on  'cool.io'     , :development => true
+
+  depend_on 'bones-git'  , '~> 1.2.4', :development => true
+  depend_on 'bones-rspec', '~> 2.0.1', :development => true
+  depend_on 'rspec'      , '~> 2.7.0', :development => true
+  depend_on 'logging'    , '~> 1.6.1', :development => true
 }
 

data/lib/directory_watcher.rb

@@ -4,9 +4,15 @@
 # See DirectoryWatcher for detailed documentation and usage.
 #
 
-require 'observer'
+require 'set'
+require 'thread'
 require 'yaml'
 
+require 'directory_watcher/paths'
+require 'directory_watcher/version'
+require 'directory_watcher/configuration'
+require 'directory_watcher/logable'
+
 # == Synopsis
 #
 # A class for watching files within a directory and generating events when
@@ -167,6 +173,21 @@ require 'yaml'
 #    dw.run_once
 #    dw.persist!    # stores state to dw_state.yml
 #
+# === Ordering of Events
+#
+# In the case, particularly in the initial scan, or in cases where the Scanner
+# may be doing a large pass over the monitored locations, many events may be
+# generated all at once. In the default case, these will be emitted in the order
+# in which they are observed, which tends to be alphabetical, but it not
+# guaranteed. If you wish the events to be order by modified time, or file size
+# this may be done by setting the +sort_by+ and/or the +order_by+ options.
+#
+#    dw = DirectoryWatcher.new '.', :glob => '**/*.rb', :sort_by => :mtime
+#    dw.add_observer {|*args| args.each {|event| puts event}}
+#    dw.start
+#    gets      # when the user hits "enter" the script will terminate
+#    dw.stop
+#
 # === Scanning Strategies
 #
 # By default DirectoryWatcher uses a thread that scans the directory being
@@ -221,74 +242,12 @@ require 'yaml'
 # Tim Pease
 #
 class DirectoryWatcher
+  extend Paths
+  extend Version
+  include Logable
 
-  # An +Event+ structure contains the _type_ of the event and the file _path_
-  # to which the event pertains. The type can be one of the following:
-  #
-  #    :added      =>  file has been added to the directory
-  #    :modified   =>  file has been modified (either mtime or size or both
-  #                    have changed)
-  #    :removed    =>  file has been removed from the directory
-  #    :stable     =>  file has stabilized since being added or modified
-  #
-  Event = Struct.new(:type, :path) {
-    def to_s( ) "#{type} '#{path}'" end
-  }
-
-  # :stopdoc:
-  # A persistable file stat structure used internally by the directory
-  # watcher.
-  #
-  FileStat = Struct.new(:mtime, :size, :stable) {
-    def eql?( other )
-      return false unless other.instance_of? FileStat
-      self.mtime == other.mtime and self.size == other.size
-    end
-    alias :== :eql?
-  }
-
-  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
-  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
-  # :startdoc:
-
-  # Returns the version string for the library.
-  #
-  def self.version
-    @version ||= File.read(path('version.txt')).strip
-  end
-
-  # Returns the library path for the module. If any arguments are given,
-  # they will be joined to the end of the libray path using
-  # <tt>File.join</tt>.
-  #
-  def self.libpath( *args, &block )
-    rv =  args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
-    if block
-      begin
-        $LOAD_PATH.unshift LIBPATH
-        rv = block.call
-      ensure
-        $LOAD_PATH.shift
-      end
-    end
-    return rv
-  end
-
-  # Returns the lpath for the module. If any arguments are given, they
-  # will be joined to the end of the path using <tt>File.join</tt>.
-  #
-  def self.path( *args, &block )
-    rv = args.empty? ? PATH : ::File.join(PATH, args.flatten)
-    if block
-      begin
-        $LOAD_PATH.unshift PATH
-        rv = block.call
-      ensure
-        $LOAD_PATH.shift
-      end
-    end
-    return rv
-  end
+  # access the configuration of the DirectoryWatcher
+  attr_reader :config
 
   # call-seq:
   #    DirectoryWatcher.new( directory, options )
@@ -312,33 +271,51 @@ class DirectoryWatcher
   #                            stopped and started (respectively)
   #    :scanner   =>  nil      the directory scanning strategy to use with
   #                            the directory watcher (either :coolio, :em, :rev or nil)
+  #    :sort_by   =>  :path    the sort order of the scans, when there are
+  #                            multiple events ready for deliver. This can be
+  #                            one of:
+  #
+  #                               :path  => default, order by file name
+  #                               :mtime => order by last modified time
+  #                               :size  => order by file size
+  #   :order_by   => :ascending The direction in which the sorted items are
+  #                             sorted. Either :ascending or :descending
+  #   :logger     => nil      An object that responds to the debug, info, warn,
+  #                           error and fatal methods. Using the default will
+  #                           use Logging gem if it is available and then fall
+  #                           back to NullLogger
   #
   # The default glob pattern will scan all files in the configured directory.
   # Setting the :stable option to +nil+ will prevent stable events from being
   # generated.
   #
+  # Additional information about the available options is documented in the
+  # Configuration class.
+  #
   def initialize( directory, opts = {} )
-    @dir = directory
     @observer_peers = {}
+    @config = Configuration.new( opts.merge( :dir => directory ) )
+
+    setup_dir(config.dir)
 
-    if Kernel.test(?e, @dir)
-      unless Kernel.test(?d, @dir)
-        raise ArgumentError, "'#{@dir}' is not a directory"
+    @notifier = Notifier.new(config, @observer_peers)
+    @collector = Collector.new(config)
+    @scanner = config.scanner_class.new(config)
+  end
+
+  # Setup the directory existence.
+  #
+  # Raise an error if the item passed in does exist but is not a directory
+  #
+  # Returns nothing
+  def setup_dir( dir )
+    if Kernel.test(?e, dir)
+      unless Kernel.test(?d, dir)
+        raise ArgumentError, "'#{dir}' is not a directory"
       end
     else
-      Dir.mkdir @dir
+      Dir.mkdir dir
     end
-
-    klass = opts[:scanner].to_s.capitalize + 'Scanner'
-    klass = DirectoryWatcher.const_get klass rescue Scanner
-    @scanner = klass.new {|events| notify_observers(events)}
-
-    self.glob = opts[:glob] || '*'
-    self.interval = opts[:interval] || 30
-    self.stable = opts[:stable] || nil
-    self.persist = opts[:persist]
-
-    @scanner.reset opts[:pre_load]
   end
 
   # call-seq:
@@ -365,6 +342,7 @@ class DirectoryWatcher
       raise NoMethodError, "observer does not respond to `#{func.to_s}'"
     end
 
+    logger.debug "Added observer"
     @observer_peers[observer] = func
     observer
   end
@@ -396,21 +374,11 @@ class DirectoryWatcher
   # files. A single glob pattern can be given or an array of glob patterns.
   #
   def glob=( val )
-    glob = case val
-           when String; [File.join(@dir, val)]
-           when Array; val.flatten.map! {|g| File.join(@dir, g)}
-           else
-             raise(ArgumentError,
-                   'expecting a glob pattern or an array of glob patterns')
-           end
-    glob.uniq!
-    @scanner.glob = glob
+    config.glob = val
   end
 
-  # Returns the array of glob patterns used to monitor files in the directory.
-  #
   def glob
-    @scanner.glob
+    config.glob
   end
 
   # Sets the directory scan interval. The directory will be scanned every
@@ -418,15 +386,11 @@ class DirectoryWatcher
   # Raises +ArgumentError+ if the interval is zero or negative.
   #
   def interval=( val )
-    val = Float(val)
-    raise ArgumentError, "interval must be greater than zero" if val <= 0
-    @scanner.interval = val
+    config.interval = val
   end
 
-  # Returns the directory scan interval in seconds.
-  #
   def interval
-    @scanner.interval
+    config.interval
   end
 
   # Sets the number of intervals a file must remain unchanged before it is
@@ -450,21 +414,11 @@ class DirectoryWatcher
   # time is 60 seconds (15.0 * 4).
   #
   def stable=( val )
-    if val.nil?
-      @scanner.stable = nil
-      return
-    end
-
-    val = Integer(val)
-    raise ArgumentError, "stable must be greater than zero" if val <= 0
-    @scanner.stable = val
+    config.stable = val
   end
 
-  # Returs the number of intervals a file must remain unchanged before it is
-  # considered "stable".
-  #
   def stable
-    @scanner.stable
+    config.stable
   end
 
   # Sets the name of the file to which the directory watcher state will be
@@ -472,9 +426,12 @@ class DirectoryWatcher
   # disable this feature.
   #
   def persist=( filename )
-    @persist = filename ? filename.to_s : nil
+    config.persist = filename
+  end
+
+  def persist
+    config.persist
   end
-  attr_reader :persist
 
   # Write the current state of the directory watcher to the persist file.
   # This method will do nothing if the directory watcher is running or if
@@ -482,8 +439,16 @@ class DirectoryWatcher
   #
   def persist!
     return if running?
-    File.open(@persist, 'w') {|fd| fd.write YAML.dump(@scanner.files)} if @persist
+    File.open(persist, 'w') { |fd| @collector.dump_stats(fd) } if persist?
     self
+  rescue => e
+    logger.error "Failure to write to persitence file #{persist.inspect} : #{e}"
+  end
+
+  # Is persistence done on this DirectoryWatcher
+  #
+  def persist?
+    config.persist
   end
 
   # Loads the state of the directory watcher from the persist file. This
@@ -492,7 +457,7 @@ class DirectoryWatcher
   #
   def load!
     return if running?
-    @scanner.files = YAML.load_file(@persist) if @persist and test(?f, @persist)
+    File.open(persist, 'r') { |fd| @collector.load_stats(fd) } if persist? and test(?f, persist)
     self
   end
 
@@ -506,26 +471,93 @@ class DirectoryWatcher
   # Start the directory watcher scanning thread. If the directory watcher is
   # already running, this method will return without taking any action.
   #
+  # Start returns one the scanner and the notifier say they are running
+  #
   def start
+    logger.debug "start (running -> #{running?})"
     return self if running?
 
     load!
+    logger.debug "starting notifier #{@notifier.object_id}"
+    @notifier.start
+    Thread.pass until @notifier.running?
+
+    logger.debug "starting collector"
+    @collector.start
+    Thread.pass until @collector.running?
+
+    logger.debug "starting scanner"
     @scanner.start
+    Thread.pass until @scanner.running?
+
     self
   end
 
+  # Pauses the scanner.
+  #
+  def pause
+    @scanner.pause
+  end
+
+  # Resume the emitting of events
+  #
+  def resume
+    @scanner.resume
+  end
+
   # Stop the directory watcher scanning thread. If the directory watcher is
   # already stopped, this method will return without taking any action.
   #
+  # Stop returns once the scanner and notifier say they are no longer running
   def stop
+    logger.debug "stop (running -> #{running?})"
     return self unless running?
 
+    logger.debug"stopping scanner"
     @scanner.stop
+    Thread.pass while @scanner.running?
+
+    logger.debug"stopping collector"
+    @collector.stop
+    Thread.pass while @collector.running?
+
+    logger.debug"stopping notifier"
+    @notifier.stop
+    Thread.pass while @notifier.running?
+
     self
   ensure
     persist!
   end
 
+  # Sets the maximum number of scans the scanner is to make on the directory
+  #
+  def maximum_iterations=( value )
+    @scanner.maximum_iterations = value
+  end
+
+  # Returns the maximum number of scans the directory scanner will perform
+  #
+  def maximum_iterations
+    @scanner.maximum_iterations
+  end
+
+  # Returns the number of scans of the directory scanner it has
+  # completed thus far.
+  #
+  # This will always report 0 unless a maximum number of scans has been set
+  #
+  def scans
+    @scanner.iterations
+  end
+
+  # Returns true if the maximum number of scans has been reached.
+  #
+  def finished_scans?
+    return true if maximum_iterations and (scans >= maximum_iterations)
+    return false
+  end
+
   # call-seq:
   #    reset( pre_load = false )
   #
@@ -540,7 +572,7 @@ class DirectoryWatcher
     was_running = @scanner.running?
 
     stop if was_running
-    File.delete(@persist) if @persist and test(?f, @persist)
+    File.delete(config.persist) if persist? and test(?f, config.persist)
     @scanner.reset pre_load
     start if was_running
     self
@@ -565,29 +597,24 @@ class DirectoryWatcher
   # the observers.
   #
   def run_once
-    @scanner.run_once
+    @scanner.run
+    @collector.start unless running?
+    @notifier.start unless running?
     self
   end
-
-
-  private
-
-  # Invoke the update method of each registered observer in turn passing the
-  # list of file events to each.
-  #
-  def notify_observers( events )
-    @observer_peers.each do |observer, func|
-      begin; observer.send(func, *events); rescue Exception; end
-    end
-  end
-
 end  # class DirectoryWatcher
 
-DirectoryWatcher.libpath {
-  require 'directory_watcher/scanner'
-  require 'directory_watcher/coolio_scanner'
-  require 'directory_watcher/em_scanner'
-  require 'directory_watcher/rev_scanner'
-}
+require 'directory_watcher/file_stat'
+require 'directory_watcher/scan'
+require 'directory_watcher/event'
+require 'directory_watcher/threaded'
+require 'directory_watcher/collector'
+require 'directory_watcher/notifier'
+require 'directory_watcher/scan_and_queue'
+require 'directory_watcher/scanner'
+require 'directory_watcher/eventable_scanner'
+require 'directory_watcher/coolio_scanner'
+require 'directory_watcher/em_scanner'
+require 'directory_watcher/rev_scanner'
 
 # EOF