osx_watchfolder 1.0.1

data/History.txt

@@ -0,0 +1,3 @@
+== 1.0.0 / 2009-02-18
+
+* First let out into the wild

data/README.rdoc

@@ -0,0 +1,58 @@
+osx_watchfolder
+    by Paul Wilson
+    http://merecomplexities.com 
+
+== DESCRIPTION:
+
+osx_watchfolder is a tiny gem to take advantages of OSX 10.5's folder watching functionality. 
+
+== FEATURES/PROBLEMS:
+
+osx\_watchfolder  enables you to point a script at a directory, or group of directories, and be notified of changes.  Example usages are _autotest_-like scripts.
+
+Due to limitations with Ruby threading and Ruby-Cocoa, folders may only be watched from the main Ruby thread.
+
+Only works on OSX 10.5+ (Leopard), obviously.
+
+
+== SYNOPSIS:
+
+To run a method 'run_tests' when a change is detected in a couple of folders:
+
+  require 'rubygems'
+  require 'osx_watchfolder'
+  OsxWatchfolder::FolderWatcher.new("lib", "test") { run_tests}.start
+
+== REQUIREMENTS:
+
+* Only works on OSX 10.5+ (Leopard)
+
+== INSTALL:
+
+  sudo gem install paulanthonywilson-osx_watchfolder
+
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 
+
+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/Rakefile

@@ -0,0 +1,30 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+begin
+  require 'bones'
+  Bones.setup
+rescue LoadError
+  begin
+    load 'tasks/setup.rb'
+  rescue LoadError
+    raise RuntimeError, '### please install the "bones" gem ###'
+  end
+end
+
+ensure_in_path 'lib'
+require 'osx_watchfolder'
+
+task :default => 'test:run'
+
+PROJ.name = 'osx_watchfolder'
+PROJ.authors = 'Paul Wilson'
+PROJ.email = 'paul.wilson@merecomplexities.com'
+PROJ.url = 'http://github.com/paulanthonywilson/osx_watchfolder'
+PROJ.version = OsxWatchfolder::VERSION
+PROJ.exclude << '\.gitignore'
+PROJ.notes.exclude = %w(^README\.txt$ ^data/)
+PROJ.readme_file = 'README.rdoc'
+
+# EOF

data/lib/osx_watchfolder.rb

@@ -0,0 +1,49 @@
+
+module OsxWatchfolder
+
+  # :stopdoc:
+  VERSION = '1.0.1'
+  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
+  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 )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+  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 )
+    args.empty? ? PATH : ::File.join(PATH, args.flatten)
+  end
+
+  # Utility method used to require all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+
+end  # module OsxWatchfolder
+
+OsxWatchfolder.require_all_libs_relative_to(__FILE__)
+
+# EOF

data/lib/osx_watchfolder/folder_watcher.rb

@@ -0,0 +1,82 @@
+require 'osx/foundation'  
+OSX.require_framework '/System/Library/Frameworks/CoreServices.framework/Frameworks/CarbonCore.framework'
+
+module OsxWatchfolder
+
+  # To run the method 'run_tests' when a change is detected in a couple of folders:
+  #
+  #  folder_watcher = OsxWatchfolder::FolderWatcher.new("lib", "test") { run_tests}
+  #  folder_wacher.start
+  #
+  class FolderWatcher
+    
+    # directory update notification latency in seconds.  Defaults to 1 
+    attr_accessor :latency
+    
+    # runloop timeout in seconds - on all but the 1st interrupt for the script it will take a maximum of 
+    # this long for interrupts to be noticed. Defaults to 5
+    attr_accessor :runloop_interval
+    
+    # how many times has this been interrupted?
+    attr_reader :interrupted_count
+
+
+    def stop
+      @running = false
+      OSX::CFRunLoopStop(@runloop)
+    end
+
+    def start
+      raise "May only be started from main thread" unless Thread.current == Thread.main
+      prepare_stream
+      enter_run_loop
+    rescue Interrupt
+      stop
+      @interrupted_count += 1
+    ensure
+      cleanup_stream 
+    end  
+
+
+    def initialize(*folders, &block)
+      @folders = Array === folders.first ? folders.first : folders
+      @block = block
+      @running = true
+      @latency = 1
+      @runloop_interval = 5
+      @interrupted_count = 0
+    end
+
+    private
+
+
+    def enter_run_loop
+      @running = true
+      OSX::CFRunLoopRunInMode(OSX::KCFRunLoopDefaultMode, @runloop_interval, true) while @running
+    end
+
+    def cleanup_stream 
+      if (@stream)
+        OSX::FSEventStreamStop(@stream)
+        OSX::FSEventStreamInvalidate(@stream)
+        OSX::FSEventStreamRelease(@stream)
+      end
+      @stream = nil
+    end
+
+    def prepare_stream
+      callback = lambda do |streamRef, clientCallBackInfo, numEvents,eventPaths, eventFlags,eventIds| 
+        @block.call
+      end
+      @stream = OSX::FSEventStreamCreate(nil,callback,nil,@folders,OSX::KFSEventStreamEventIdSinceNow, @latency,OSX::KFSEventStreamCreateFlagNone)
+
+      @runloop = OSX::CFRunLoopGetCurrent()
+
+      OSX::FSEventStreamScheduleWithRunLoop(@stream, @runloop, OSX::KCFRunLoopDefaultMode)   
+      OSX::FSEventStreamStart(@stream)
+    end
+
+
+
+  end
+end

data/test/test_folder_watch.rb

@@ -0,0 +1,89 @@
+require 'test/unit'
+require 'tmpdir'
+require 'fileutils'
+require File.expand_path(File.dirname(__FILE__) + '/../lib/osx_watchfolder')
+
+class TestFolderWatch <  Test::Unit::TestCase
+  include FileUtils
+  include OsxWatchfolder
+
+  def setup
+    @some_folders = [Dir.tmpdir + "/folder_watch_test1", Dir.tmpdir + "/folder_watch_test2"]
+    @some_folders.each {|dir| rm_rf dir}
+    @some_folders.each {|dir| mkdir dir}
+    @folder_changed = false
+  end
+
+  def teardown
+    @some_folders.each {|dir| rm_rf dir}
+  end
+
+  def test_nothing_happens_if_a_watched_folder_does_not_change
+    in_a_second_yield_and_stop_watcher
+    watch_folders
+    assert !@folder_changed
+  end
+
+  def test_can_be_initialised_with_var_args_or_array
+    assert_equal @some_folders,  FolderWatcher.new(*@some_folders).instance_variable_get(:@folders)
+    assert_equal @some_folders,  FolderWatcher.new(@some_folders).instance_variable_get(:@folders)
+  end
+
+
+  def test_notified_if_first_watched_folder_changes
+    in_a_second_write_file_and_stop_watcher @some_folders.first + "/somefile"
+    watch_folders
+    assert @folder_changed    
+  end
+
+
+  def test_notified_if_another_watched_folder_changes
+    in_a_second_write_file_and_stop_watcher @some_folders.last + "/somefile"
+    watch_folders
+    assert @folder_changed    
+  end
+
+  def test_must_be_started_in_main_thread
+    @testee = FolderWatcher.new(*@some_folders) {}
+    t = Thread.new do
+      assert_raise(RuntimeError){ @testee.start}
+    end
+    t.join
+  end
+
+  def test_handles_interrupts
+    @testee = FolderWatcher.new(*@some_folders) {}
+    assert_equal 0, @testee.interrupted_count 
+    class << @testee
+      def enter_run_loop
+        raise Interrupt, "stopped!"
+      end
+    end
+    @testee.start
+    assert_equal 1, @testee.interrupted_count 
+  end
+  
+
+  def in_a_second_yield_and_stop_watcher
+    Thread.new do
+      yield if block_given?
+      sleep 1
+      @testee.stop
+    end
+  end
+
+  def in_a_second_write_file_and_stop_watcher(file)
+    in_a_second_yield_and_stop_watcher do
+      File.open(file, "w"){|f| f.write "hello"}
+    end
+  end
+
+  def watch_folders
+    @testee = FolderWatcher.new(*@some_folders) {@folder_changed = true}
+    @testee.latency = 0.1
+    @testee.runloop_interval = 0.5
+    @testee.start
+  end
+
+
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification 
+name: osx_watchfolder
+version: !ruby/object:Gem::Version 
+  version: 1.0.1
+platform: ruby
+authors: 
+- Paul Wilson
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-02-18 00:00:00 +00:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bones
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.4.0
+    version: 
+description: osx_watchfolder is a tiny gem to take advantages of OSX 10.5's folder watching functionality.
+email: paul.wilson@merecomplexities.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- README.rdoc
+files: 
+- .DS_Store
+- History.txt
+- README.rdoc
+- Rakefile
+- lib/osx_watchfolder.rb
+- lib/osx_watchfolder/folder_watcher.rb
+- osx_watchfolder.gemspec
+- test/test_folder_watch.rb
+has_rdoc: true
+homepage: http://github.com/paulanthonywilson/osx_watchfolder
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: !binary |
+  AA==
+
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 2
+summary: osx_watchfolder is a tiny gem to take advantages of OSX 10
+test_files: 
+- test/test_folder_watch.rb