filewatcher 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2fb39cdddc7a64525396dac78226807bb53e450a
-  data.tar.gz: 641cea3ede6d8d1eb20fe7a0b8aa5ad75e86d75e
+  metadata.gz: 43546a6002f63f8251ab718f13676e812c47a64c
+  data.tar.gz: 734a6f6708d85692d9141644a1f583f5633c1dc3
 SHA512:
-  metadata.gz: 728a408d87cfb6be8eb5556f31bc74972645275d0bb0c3c9a1045a9d4287e1aa3ff4f5a15fb46dfa14953e837ed2b38cdcfc8ad8e34e380b6f2980a9cebbc932
-  data.tar.gz: bad167aae4d3e3e7fe9848ea7295f1a0fd71e4984480f35765ee869814eeee8555f0fe705b5b61a33c7dc4cc8fd95d3e6bbce6410935e3c0c22b3233effcc950
+  metadata.gz: 240dd96db19430b21f3fd29baedd6d3ad4a7cd3fb1089e76930de90a6d38f5fbc2c6f1d55fa34c6a17ae1192352021cc82395e14344666ff0dc8649ff7e82951
+  data.tar.gz: ef86c4909413021b72f7c93e7a46451f62bc358a8db175c0757c837627ef0d37dd3fabd1441f2fbeced9cd728148527aa8fa2743f5e026d427b5010af3751359

data/README.md

@@ -84,12 +84,16 @@ filesystem gets updated:
 
     $ filewatcher "src test" "ruby test/test_suite.rb"
 
-Automatic restart of processes
-------------------------------
+Restart long running commands
+-----------------------------
+
+The `--restart` option kills the command if it's still running when a filesystem change happens. Can be used to restart locally running webservers on updates, or kill long running tests and restart on updates. This option often makes filewatcher faster in general. To not wait for tests to finish:
 
-The `--restart` option restarts the command when changes happens on the file system. The `--dontwait` starts the command when filewatcher is started. To start a webserver and have it automatically restart when html files are updated:
+    $ filewatcher --restart "**/*.rb" "rake test"
 
-    $ filewatcher --dontwait --restart "*.html" "python -m SimpleHTTPServer"
+The `--dontwait` option starts the command on startup without waiting for filesystem updates. To start a webserver and have it automatically restart when html files are updated:
+
+    $ filewatcher --restart --dontwait "*.html" "python -m SimpleHTTPServer"
 
 Available enviroment variables
 ------------------------------
@@ -105,13 +109,20 @@ The environment variables $FILEPATH, $FILEDIR and $FSEVENT is also available.
 Command line options
 --------------------
 
+Useful command line options:
+
+            --list, -l:   Print name of files being watched on startup
+         --restart, -r:   Kill the command if it's still running
+        --dontwait, -d:   Start the command immediately
+
+Other command line options:
+
+         --version, -v:   Print version and exit
+            --help, -h:   Show this message
     --interval, -i <f>:   Interval in seconds to scan filesystem. Defaults to 0.5 seconds.
-            --exec, -e:   Execute file as a script when file is updated.
+            --exec, -e:   Execute file as a script when file is updated
      --include, -n <s>:   Include files (default: *)
      --exclude, -x <s>:   Exclude file(s) matching (default: "")
-            --list, -l:   Print name of files being watched
-         --version, -v:   Print version and exit
-            --help, -h:   Show this message
 
 Ruby API
 --------
@@ -188,18 +199,41 @@ for syntax.
       puts "Updated " + filename
     end
 
-The filewatcher library is just a single file with 96 LOC (including comments)
+Start, pause, resume, stop, and finalize a running watch. This is particularly
+useful when the update block takes a while to process each file (eg. sending
+over the network)
+
+    filewatcher = FileWatcher.new(["*.rb"])
+    thread = Thread.new(filewatcher){|fw| fw.watch{|f| puts "Updated " + f}}
+      ...
+    filewatcher.pause       # block stops responding to filesystem changes
+    filewatcher.finalize    # Ensure all filesystem changes made prior to
+                            # pausing are handled.
+      ...
+    filewatcher.resume       # block begins responding again, but is not given
+                             # changes made between #pause_watch and
+                             # #resume_watch
+      ...
+    filewatcher.end        # block stops responding to filesystem changes
+                           # and takes a final snapshot of the filesystem
+    thread.join
+
+    filewatcher.finalize   # Ensure all filesystem changes made prior to
+                           # ending the watch are handled.
+
+The filewatcher library is just a single file with 147 LOC (including comments)
 with no dependencies.
 
 
 Credits
 -------
-This project would not be where it is today without the generous help provided by people reporting issues and these contributors: 
-
+This project would not be where it is today without the generous help provided by people reporting issues and these contributors:
 
- * Support for absolute and globbed paths by Franco Leonardo Bulgarelli: https://github.com/flbulgarelli
+ * Penn Taylor: Spinner displayed in the terminal and Start, pause, resume, stop, and finalize a running watch.
+  
+ * Franco Leonardo Bulgarelli: Support for absolute and globbed paths by  https://github.com/flbulgarelli
 
- * Command line globbing by Kristoffer Roupé https://github.com/kitofr
+ * Kristoffer Roupé https://github.com/kitofr Command line globbing by 
 
 This gem was initially inspired by Tom Lieber's blogg posting: http://alltom.com/pages/detecting-file-changes-with-ruby
 

data/bin/filewatcher

@@ -29,10 +29,11 @@ EOS
   opt :exec, "Execute file as a script when file is updated.", :short => 'e', :type => :boolean, :default => false
   opt :include, "Include files", :type => :string, :default => "*"
   opt :exclude, "Exclude file(s) matching", :type => :string, :default => ""
-  opt :interval, "Interval to scan filesystem. Defaults to 0.5 seconds.", :short => 'i', :type => :float, :default => 0.5  
+  opt :interval, "Interval to scan filesystem.", :short => 'i', :type => :float, :default => 0.5
+  opt :quiet, "Hide spinner", :short => 'q', :type => :boolean, :default => false
 end
 
-Trollop::die "must have at least one argument" if(ARGV.size == 0)
+Trollop::die Trollop::educate if(ARGV.size == 0)
 
 files = []
 ARGV[0...-1].each do |a|
@@ -59,37 +60,13 @@ end
 
 files = split_files_void_escaped_whitespace(files)
 
-def fork_process(env, cmd)
-  pipe_read, pipe_write = IO.pipe
-  fork do
-    pipe_read.close
-    pipe_write.write Process.spawn(env,cmd).to_s
-    exit
-  end
-
-  Kernel.sleep 1
-  pipe_write.close
-  child_pid = pipe_read.read.to_i
-  pipe_read.close
-  return child_pid
-end
-
-def kill_process(child_pid)
-  still_running = true
-  begin
-    Process.kill(1, child_pid)
-  rescue Errno::ESRCH
-    still_running = false
-  end
-  while still_running do
-    begin
-      Process.getpgid( child_pid)
-      still_running = true
-    rescue Errno::ESRCH
-      still_running = false
-    end
-    Kernel.sleep 0.1
-  end
+def restart(child_pid, env, cmd)
+  Process.kill(9,child_pid)
+  Process.wait(child_pid)
+rescue Errno::ESRCH
+  # already killed
+ensure
+  child_pid = Process.spawn(env, cmd)
 end
 
 if(options[:restart])
@@ -97,70 +74,74 @@ if(options[:restart])
   child_pid = nil
 end
 
-FileWatcher.new(files, options[:list], options[:dontwait]).watch(options[:interval]) do |filename, event|
-  cmd = nil
-  if(options[:exec] and File.exist?(filename))
-    extension = filename[/(\.[^\.]*)$/,0]
-    runners = {
-      ".py" => "python",
-      ".js" => "node",
-      ".rb" => "ruby",
-      ".pl" => "perl",
-      ".awk" => "awk",
-      ".php" => "php",
-      ".phtml" => "php",
-      ".php4" => "php",
-      ".php3" => "php",
-      ".php5" => "php",
-      ".phps" => "php"
-    }
-    runner = runners[extension]
-    if(runner)
-      cmd = "env #{runner.to_s} #{filename}"
+begin
+  fw = FileWatcher.new(files, options[:list], options[:dontwait], !options[:quiet])
+  fw.watch(options[:interval]) do |filename, event|
+    cmd = nil
+    if(options[:exec] and File.exist?(filename))
+      extension = filename[/(\.[^\.]*)$/,0]
+      runners = {
+        ".py" => "python",
+        ".js" => "node",
+        ".rb" => "ruby",
+        ".pl" => "perl",
+        ".awk" => "awk",
+        ".php" => "php",
+        ".phtml" => "php",
+        ".php4" => "php",
+        ".php3" => "php",
+        ".php5" => "php",
+        ".phps" => "php"
+      }
+      runner = runners[extension]
+      if(runner)
+        cmd = "env #{runner.to_s} #{filename}"
+      end
+    elsif(ARGV.length > 1)
+      cmd = ARGV[-1]
     end
-  elsif(ARGV.length > 1)
-    cmd = ARGV[-1]
-  end
 
-  if(cmd)
-    path = Pathname.new(filename)
-    env = {
-      'FILENAME'=> path.to_s,
-      'FILEDIR' => path.parent.realpath.to_s,
-      'FSEVENT' => event.to_s
-    }
-    if(event != :delete)
-      ENV['FILEPATH'] = path.realpath.to_s
-    end
+    if(cmd)
+      path = Pathname.new(filename)
+      env = {
+        'FILENAME'=> path.to_s,
+        'FILEDIR' => path.parent.realpath.to_s,
+        'FSEVENT' => event.to_s
+      }
+      if(event != :delete)
+        ENV['FILEPATH'] = path.realpath.to_s
+      end
 
-    if(options[:restart])
-      if(child_pid == nil)
-        child_pid = fork_process(env, cmd)
+      if(options[:restart])
+        if(child_pid == nil)
+          child_pid = Process.spawn(env, cmd)
+        else
+          child_id = restart(child_pid, env, cmd)
+        end
       else
-        kill_process(child_pid)
-        child_pid = fork_process(env, cmd)
+        begin
+          pid = Process.spawn(env, cmd)
+          Process.wait()
+        rescue SystemExit, Interrupt
+          exit(0)
+        end
       end
+
     else
-      begin
-        pid = Process.spawn(env, cmd)
-        Process.wait()
-      rescue SystemExit, Interrupt
-        exit(0)
+      case(event)
+      when :changed
+        print "file updated"
+      when :delete
+        print "file deleted"
+      when :new
+        print "new file"
+      else
+        print event.to_s
       end
+      puts ": " + filename
     end
 
-  else
-    case(event)
-    when :changed
-      print "file updated"
-    when :delete
-      print "file deleted"
-    when :new
-      print "new file"
-    else
-      print event.to_s
-    end
-    puts ": " + filename
   end
-
+rescue SystemExit, Interrupt
+  fw.finalize
 end

data/lib/filewatcher.rb

@@ -6,76 +6,135 @@ class FileWatcher
   attr_accessor :filenames
 
   def self.VERSION
-    return '0.4.0'
+    return '0.5.0'
   end
 
-  def initialize(unexpanded_filenames, print_filelist=false, dontwait=false)
+  def update_spinner(label)
+    return nil unless @show_spinner
+    @spinner ||= %w(\\ | / -)
+    print "#{' ' * 30}\r#{label}  #{@spinner.rotate!.first}\r"
+  end
+
+  def initialize(unexpanded_filenames, print_filelist=false, dontwait=false, show_spinner=false)
     @unexpanded_filenames = unexpanded_filenames
-    @last_mtimes = { }
-    @filenames = expand_directories(@unexpanded_filenames)
+    @filenames = nil
+    @stored_update = nil
+    @keep_watching = false
+    @pausing = false
+    @last_snapshot = mtime_snapshot
+    @end_snapshot = nil
     @dontwait = dontwait
+    @show_spinner = show_spinner
     puts 'Watching:' if print_filelist
     @filenames.each do |filename|
       raise 'File does not exist' unless File.exist?(filename)
-      @last_mtimes[filename] = File.stat(filename).mtime
       puts filename if print_filelist
     end
   end
 
-  def watch(sleep=1, &on_update)
+  def watch(sleep=0.5, &on_update)
+    @sleep = sleep
+    @stored_update = on_update
+    @keep_watching = true
     if(@dontwait)
       yield '',''
     end
-    loop do
-      begin
-        Kernel.sleep sleep until filesystem_updated?
-      rescue SystemExit,Interrupt
-        Kernel.exit
+    while @keep_watching
+      @end_snapshot = mtime_snapshot if @pausing
+      while @keep_watching && @pausing
+        update_spinner('Pausing')
+        Kernel.sleep sleep
       end
-      yield @updated_file, @event
+      while @keep_watching && !filesystem_updated? && !@pausing
+        update_spinner('Scanning')
+        Kernel.sleep sleep
+      end
+      # test and null @updated_file to prevent yielding the last
+      # file twice if @keep_watching has just been set to false
+      yield @updated_file, @event if @updated_file
+      @updated_file = nil
     end
+    @end_snapshot = mtime_snapshot
+    finalize(&on_update)
   end
 
-  def filesystem_updated?
-    filenames = expand_directories(@unexpanded_filenames)
+  def pause
+    @pausing = true
+    update_spinner('Initiating pause')
+    Kernel.sleep @sleep # Ensure we wait long enough to enter pause loop
+                        # in #watch
+  end
 
-    if(filenames.size > @filenames.size)
-      filename = (filenames - @filenames).first
-      @filenames << filename
-      @last_mtimes[filename] = File.stat(filename).mtime
-      @updated_file = filename
-      @event = :new
-      return true
+  def resume
+    if !@keep_watching || !@pausing
+      raise "Can't resume unless #watch and #pause were first called"
     end
+    @last_snapshot = mtime_snapshot  # resume with fresh snapshot
+    @pausing = false
+    update_spinner('Resuming')
+    Kernel.sleep @sleep # Wait long enough to exit pause loop in #watch
+  end
 
-    if(filenames.size < @filenames.size)
-      filename = (@filenames - filenames).first
-      @filenames.delete(filename)
-      @last_mtimes.delete(filename)
-      @updated_file = filename
-      @event = :delete
-      return true
+  # Ends the watch, allowing any remaining changes to be finalized.
+  # Used mainly in multi-threaded situations.
+  def stop
+    @keep_watching = false
+    update_spinner('Stopping')
+    return nil
+  end
+
+  # Calls the update block repeatedly until all changes in the
+  # current snapshot are dealt with
+  def finalize(&on_update)
+    on_update = @stored_update if !block_given?
+    snapshot = @end_snapshot ? @end_snapshot : mtime_snapshot
+    while filesystem_updated?(snapshot)
+      update_spinner('Finalizing')
+      on_update.call(@updated_file, @event)
     end
+    @end_snapshot =nil
+    return nil
+  end
 
+  # Takes a snapshot of the current status of watched files.
+  # (Allows avoidance of potential race condition during #finalize)
+  def mtime_snapshot
+    snapshot = {}
+    @filenames = expand_directories(@unexpanded_filenames)
     @filenames.each do |filename|
-      if(not(File.exists?(filename)))
-        @filenames.delete(filename)
-        @last_mtimes.delete(filename)
-        @updated_file = filename
-        @event = :delete
-        return true
-      end
-      mtime = File.stat(filename).mtime
-      updated = @last_mtimes[filename] < mtime
+      mtime = File.exist?(filename) ? File.stat(filename).mtime : Time.new(0)
+      snapshot[filename] = mtime
+    end
+    return snapshot
+  end
+
+  def filesystem_updated?(snapshot_to_use = nil)
+    snapshot = snapshot_to_use ? snapshot_to_use : mtime_snapshot
 
-      @last_mtimes[filename] = mtime
-      if(updated)
-        @updated_file = filename
+    forward_changes = snapshot.to_a - @last_snapshot.to_a
+
+    forward_changes.each do |file,mtime|
+      @updated_file = file
+      unless @last_snapshot.fetch(@updated_file,false)
+        @last_snapshot[file] = mtime
+        @event = :new
+        return true
+      else
+        @last_snapshot[file] = mtime
         @event = :changed
         return true
       end
     end
 
+    backward_changes = @last_snapshot.to_a - snapshot.to_a
+    forward_names = forward_changes.map{|change| change.first}
+    backward_changes.reject!{|f,m| forward_names.include?(f)}
+    backward_changes.each do |file,mtime|
+      @updated_file = file
+      @last_snapshot.delete(file)
+      @event = :delete
+      return true
+    end
     return false
   end
 

data/test/fixtures/file1.txt

@@ -1 +1 @@
-content2
+content1

data/test/fixtures/file2.txt

@@ -1 +1 @@
-content
+content2

data/test/test_filewatcher.rb

@@ -98,4 +98,61 @@ describe FileWatcher do
     filewatcher.filesystem_updated?.should.be.true
   end
 
+  it "should be stoppable" do
+    filewatcher = FileWatcher.new(["test/fixtures"])
+    thread = Thread.new(filewatcher){filewatcher.watch(0.1)}
+    sleep 0.2  # thread needs a chance to start
+    filewatcher.stop
+    thread.join.should.equal thread # Proves thread successfully joined
+  end
+
+  it "should be pauseable/resumable" do
+    filewatcher = FileWatcher.new(["test/fixtures"])
+    filewatcher.filesystem_updated?.should.be.false
+    processed = []
+    thread = Thread.new(filewatcher,processed) do
+      filewatcher.watch(0.1){|f,e| processed << f }
+    end
+    sleep 0.2  # thread needs a chance to start
+    filewatcher.pause
+    (1..4).each do |n|
+      open("test/fixtures/file#{n}.txt","w") { |f| f.puts "content#{n}" }
+    end
+    sleep 0.2 # Give filewatcher time to respond
+    processed.should.equal []  #update block should not have been called
+    filewatcher.resume
+    sleep 0.2 # Give filewatcher time to respond
+    processed.should.equal []  #update block still should not have been called
+    added_files = []
+    (5..7).each do |n|
+      added_files << "test/fixtures/file#{n}.txt"
+      open(added_files.last,"w") { |f| f.puts "content#{n}" }
+    end
+    sleep 0.2 # Give filewatcher time to respond
+    filewatcher.stop
+    processed.should.satisfy &includes_all(added_files)
+  end
+
+  it "should process all remaining changes at finalize" do
+    filewatcher = FileWatcher.new(["test/fixtures"])
+    filewatcher.filesystem_updated?.should.be.false
+    processed = []
+    thread = Thread.new(filewatcher,processed) do
+      filewatcher.watch(0.1){|f,e| processed << f }
+    end
+    sleep 0.2  # thread needs a chance to start
+    filewatcher.stop
+    thread.join
+    added_files = []
+    (1..4).each do |n|
+      added_files << "test/fixtures/file#{n}.txt"
+      open(added_files.last,"w") { |f| f.puts "content#{n}" }
+    end
+    filewatcher.finalize
+    puts "What is wrong with finalize:"
+    puts "Expect: #{added_files.inspect}"
+    puts "Actual: #{processed.inspect}"
+    processed.should.satisfy &includes_all(added_files)
+  end
+
 end

metadata

@@ -1,55 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: filewatcher
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Thomas Flemming
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-06 00:00:00.000000000 Z
+date: 2015-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: trollop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '10.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '10.3'
 - !ruby/object:Gem::Dependency
   name: bacon
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
 description: Detect changes in filesystem. Works anywhere.
@@ -82,12 +82,12 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []