mynyml-watchr 0.3.0 → 0.5.2

data/README.rdoc

@@ -1,32 +1,39 @@
-==== Summary
+=== Summary
 
-Agile development tool that monitors a directory recursively, and triggers a
-user defined action whenever an observed file is modified. Its most typical use
-is continious testing, and as such it is a more flexible alternative to
-autotest.
+Agile development tool that monitors a directory tree, and triggers a user
+defined action whenever an observed file is modified. Its most typical use is
+continuous testing, and as such it is a more flexible alternative to autotest.
 
 
-==== Features
+=== Features
 
-* Ridiculously simple to use
-* web framework agnostic        <i>(rails, merb, sinatra, camping, invisible, ...)</i>
-* test framework agnostic       <i>(test/unit, minitest, rspec, test/spec, expectations, ...)</i>
-* ruby interpreter agnostic     <i>(ruby1.8, ruby1.9, MRI, JRuby, ...)</i>
-* package framework agnostic    <i>(rubygems, rip, ...)</i>
-* Low level / highly flexible
+watchr is:
 
+* Simple to use
+* Highly flexible
+* Evented               ( Listens for filesystem events with native c libs )
+* Portable              ( Linux, *BSD, OSX, Solaris, Windows )
+* Fast                  ( Immediately reacts to file changes )
 
-==== Usage
+Most importantly it allows running tests in an environment that is *agnostic* to:
+
+* Web frameworks        ( rails, merb, sinatra, camping, invisible, ... )
+* Test frameworks       ( test/unit, minitest, rspec, test/spec, expectations, ... )
+* Ruby interpreters     ( ruby1.8, ruby1.9, MRI, JRuby, Rubinius, ... )
+* Package frameworks    ( rubygems, rip, ... )
+
+
+=== Usage
 
 On the command line,
 
   $ watchr path/to/script.file
 
-will monitor all files from within the current directory and below it
-recursively, and react to events on those files in accordance with the script.
+will monitor files in the current directory tree, and react to events on those
+files in accordance with the script.
 
 
-==== Scripts
+=== Scripts
 
 The script contains a set of simple rules that map observed files to an action.
 Its DSL is a single method: watch(pattern, &action)
@@ -37,9 +44,9 @@ So for example,
 
   watch( 'test/test_.*\.rb' )  {|md| system("ruby #{md[0]}") }
 
-will match test files and run them whenever they are modified.
+will match any test file and run it whenever it is saved.
 
-A continious testing script for a basic project could be
+A continuous testing script for a basic project could be
 
   watch( 'test/test_.*\.rb' )  {|md| system("ruby #{md[0]}") }
   watch( 'lib/(.*)\.rb' )      {|md| system("ruby test/test_#{md[1]}.rb") }
@@ -48,26 +55,41 @@ which, in addition to running any saved test file as above, will also run a
 lib file's associated test. This mimics the equivalent autotest behaviour.
 
 It's easy to see why watchr is so flexible, since the whole command is custom.
+The above actions could just as easily call "jruby", "ruby --rubygems", "ruby
+-Ilib", "specrb", "rbx", ... or any combination of these. For the sake of
+comparison, autotest runs with:
+
+  /usr/bin/ruby1.8 -I.:lib:test -rubygems -e "%w[test/unit test/test_helper.rb test/test_watchr.rb].each { |f| require f }"
+
+locking the environment into ruby1.8, rubygems and test/unit for all tests.
+
 And remember the scripts are pure ruby, so feel free to add methods,
-Signal#trap calls, etc.
+Signal#trap calls, etc. Updates to script files are picked up on the fly (no
+need to restart watchr) so experimenting is painless.
 
 The wiki[http://wiki.github.com/mynyml/watchr] has more details and examples.
+You can also take a look at watchr's own specs.watchr script in the root dir,
+as well as docs.watchr
 
 
-==== Install
+=== Install
 
-  gem install mynyml-watchr --source http://gems.github.com/
+  gem install watchr --source http://gemcutter.org
 
 
-==== See Also
+=== See Also
 
 redgreen[http://github.com/mynyml/redgreen]:: Standalone redgreen eye candy for test results, ala autotest.
 phocus[http://github.com/mynyml/phocus]::     Run focused tests when running the whole file/suite is unnecessary.
 
 
-==== Links
+=== Links
 
 source:: http://github.com/mynyml/watchr
-rdocs::  http://docs.github.com/mynyml/watchr
+docs::   http://docs.github.com/mynyml/watchr
 wiki::   http://wiki.github.com/mynyml/watchr
+bugs::   http://github.com/mynyml/watchr/issues
+
+=== Acknowledgement
 
+* Thanks to macournoyer[http://github.com/macournoyer] for the evented backend idea

data/Rakefile

@@ -1,39 +1,7 @@
-# --------------------------------------------------
-# based on thin's Rakefile (http://github.com/macournoyer/thin)
-# --------------------------------------------------
-require 'rake/gempackagetask'
 require 'rake/rdoctask'
-require 'pathname'
-require 'yaml'
-require 'lib/watchr/version'
-
-RUBY_1_9  = RUBY_VERSION =~ /^1\.9/
-WIN       = (RUBY_PLATFORM =~ /mswin|cygwin/)
-SUDO      = (WIN ? "" : "sudo")
-
-def gem
-  RUBY_1_9 ? 'gem19' : 'gem'
-end
-
-def all_except(res)
-  Dir['**/*'].reject do |path|
-    Array(res).any? {|re| path.match(re) }
-  end
-end
-
-spec = Gem::Specification.new do |s|
-  s.name            = 'watchr'
-  s.version         =  Watchr.version
-  s.summary         = "Continious anything"
-  s.description     = "Continious anything; project files observer/trigger."
-  s.author          = "Martin Aumont"
-  s.email           = 'mynyml@gmail.com'
-  s.homepage        = ''
-  s.has_rdoc        = true
-  s.require_path    = "lib"
-  s.bindir          = "bin"
-  s.executables     = "watchr"
-  s.files           = all_except %w( ^doc ^pkg ^test/fixtures )
+begin
+  require 'yard'
+rescue LoadError, RuntimeError
 end
 
 desc "Generate rdoc documentation."
@@ -44,27 +12,14 @@ Rake::RDocTask.new(:rdoc => 'rdoc', :clobber_rdoc => 'rdoc:clean', :rerdoc => 'r
   rdoc.options << '--charset' << 'utf-8'
   rdoc.main = 'README.rdoc'
   rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('TODO.txt')
+  rdoc.rdoc_files.include('LICENSE')
   rdoc.rdoc_files.include('lib/**/*.rb')
 }
 
-Rake::GemPackageTask.new(spec) do |p|
-  p.gem_spec = spec
-end
-
-desc "Remove package products"
-task :clean => :clobber_package
-
-desc "Update the gemspec for GitHub's gem server"
-task :gemspec do
-  Pathname("#{spec.name}.gemspec").open('w') {|f| f << YAML.dump(spec) }
-end
-
-desc "Install gem"
-task :install => [:clobber, :package] do
-  sh "#{SUDO} #{gem} install pkg/#{spec.full_name}.gem"
-end
-
-desc "Uninstall gem"
-task :uninstall => :clean do
-  sh "#{SUDO} #{gem} uninstall -v #{spec.version} -x #{spec.name}"
+if defined? YARD
+  YARD::Rake::YardocTask.new do |t|
+    t.files   = %w( lib/**/*.rb )
+    t.options = %w( -o doc/yard --readme README.rdoc --files LICENSE,TODO.txt )
+  end
 end

data/TODO.txt

@@ -1,27 +1,31 @@
 
-o write a few prepackaged scripts
-  o post on gists
-  o post links on wiki
-  o post main links in readme
-
-o split watchr.rb classes into own files?
-o run script within own context?
-
-o use filesystem events for file monitoring (MA)
-  o linux:   inotify
-  o osx:     fsevent
-  o win:     Directory Management? NTFS Change Journal? ReadDirectoryChangesW?
-  o *BSD:    kqueue? pnotify?
-  o solaris: FEM?
-  o fallback to current method when no other method is available
-  o api will also need refactoring for clearer separation of functionality
-
-o document source
-  o rdoc or yard?
-
-o respond to different file events
-  o modified
-  o created
-  o deleted
-  o etc.
-  o watch(pattern, EVENT, &action)
+* rev dependency should be conditional on OS
+
+* fix issue with Script#parse!
+  * only accept paths in initialize?
+
+* sometimes an action is fired without a file being saved
+  * buffer flushing issue?
+  * libev issue?
+
+* test on other platforms
+  * mswin
+  * bsd
+  * osx
+  * solaris
+
+* write a few prepackaged scripts
+  * post on gists
+  * post links on wiki
+  * post main links in readme
+
+* eval script within own context?
+
+* respond to different file events?
+  * modified
+  * created
+  * deleted
+  * etc.
+  * watch(pattern, EVENT, &action)
+
+* memory profiling / benchmarks

data/bin/watchr

@@ -2,14 +2,13 @@
 
 require 'pathname'
 require 'optparse'
-root  = Pathname(__FILE__).dirname.parent
-require root.join('lib/watchr')
-require root.join('lib/watchr/version')
+
+require 'watchr'
+require 'watchr/version'
 
 def usage
   "Usage: watchr [opts] path/to/script"
 end
-
 def version
   "watchr version: %s" % Watchr.version
 end
@@ -19,6 +18,10 @@ opts = OptionParser.new do |opts|
 
   opts.on('-d', '--debug', "Print extra debug info while program runs") {
     Watchr.options.debug = true
+    begin
+      require 'ruby-debug'
+    rescue LoadError, RuntimeError
+    end
   }
 
   opts.on_tail('-h', '--help', "Print inline help") { puts opts;    exit }
@@ -29,8 +32,8 @@ end
 
 abort(usage) unless ARGV.first
 
-file = Pathname(ARGV.first)
+file = Pathname(ARGV.first).expand_path
 abort(%|no script found; file "#{file.to_s}" doesn't exist.|) unless file.exist?
 
-Watchr::Runner.new(file).run
+Watchr::Controller.new(Watchr::Script.new(file), Watchr.handler.new).run
 

data/docs.watchr

@@ -0,0 +1,26 @@
+# Run me with:
+#
+#   $ watchr docs.watchr
+
+def run_rdoc
+  system('rake --silent rdoc')
+end
+
+def run_yard
+  print "\nUpdating yardocs... "
+  system('rake --silent yardoc')
+  print "done.\n"
+end
+
+def document
+  run_rdoc
+  run_yard
+end
+
+watch( 'lib/.*\.rb'  ) { document }
+watch( 'README.rdoc' ) { document }
+watch( 'TODO.txt'    ) { document }
+watch( 'LICENSE'     ) { document }
+
+
+# vim:ft=ruby

data/lib/watchr.rb

@@ -1,137 +1,76 @@
+require 'pathname'
+require 'rbconfig'
+
+# Agile development tool that monitors a directory recursively, and triggers a
+# user defined action whenever an observed file is modified. Its most typical
+# use is continuous testing.
+#
+# Usage:
+#
+#   # on command line, from project's root dir
+#   $ watchr path/to/script
+#
+# See README for more details
+#
 module Watchr
+  autoload :Script,     'watchr/script'
+  autoload :Controller, 'watchr/controller'
+
+  module EventHandler
+    autoload :Base,     'watchr/event_handlers/base'
+    autoload :Unix,     'watchr/event_handlers/unix'
+    autoload :Portable, 'watchr/event_handlers/portable'
+  end
+
   class << self
     attr_accessor :options
-
+    attr_accessor :handler
+
+    # Options proxy.
+    #
+    # Currently supported options:
+    # * debug<Boolean> Debugging state. More verbose.
+    #
+    # ===== Examples
+    #
+    #   Watchr.options.debug #=> false
+    #   Watchr.options.debug = true
+    #
+    # ===== Returns
+    # options<Struct>:: options proxy.
+    #
+    #--
+    # On first use, initialize the options struct and default option values.
     def options
       @options ||= Struct.new(:debug).new
-      # set default options
       @options.debug ||= false
       @options
     end
-  end
-
-  class Script
-    attr_accessor :map
-    attr_accessor :file
-    attr_accessor :reference_time
-
-    def initialize(file = nil)
-      self.map  = []
-      self.file = file.is_a?(Pathname) ? file : Pathname.new(file) unless file.nil?
-      self.parse!
-    end
-
-    def watch(pattern, &action)
-      a = block_given? ? action : @default_action
-      self.map << [pattern, a]
-    end
-
-    def default_action(&action)
-      @default_action = action
-    end
-
-    def changed?
-      return false unless self.bound?
-      self.file.mtime > self.reference_time
-    end
-
-    def parse!
-      puts "[debug] loading script file #{self.file.to_s.inspect}" if Watchr.options.debug
-
-      return false unless self.bound?
-      self.map.clear
-      self.instance_eval(self.file.read)
-      self.reference_time = self.file.mtime
-    end
-
-    def bound?
-      self.file && self.file.respond_to?(:exist?) && self.file.exist?
-    end
-  end
-
-  class Runner
-    attr_accessor :script
-    attr_accessor :map
-    attr_accessor :init_time
-    attr_accessor :reference_file
-
-    # Caches reference_file.mtime to allow picking up an update to the
-    # reference file itself
-    attr_accessor :reference_time
-
-    def initialize(script)
-      self.init_time = Time.now.to_f
-      self.script = script.is_a?(Script) ? script : Script.new(script)
-    end
-
-    def paths
-      self.map.keys
-    end
-
-    def last_updated_file
-      path = self.paths.max {|a,b| File.mtime(a) <=> File.mtime(b) }
-      Pathname(path)
-    end
-
-    # TODO extract updating the reference out of this method
-    def changed?
-      return true  if self.paths.empty?
-      return false if self.last_updated_file.mtime.to_f < self.init_time.to_f
-
-      if self.reference_file.nil? || (self.reference_time.to_f < self.last_updated_file.mtime.to_f)
-         self.reference_file  = self.last_updated_file
-         self.reference_time  = self.last_updated_file.mtime
-         true
-      else
-         false
-      end
-    end
-
-    def run
-      # enter monitoring state
-      loop do
-        self.trigger
-        Kernel.sleep(1)
-      end
-    end
-
-    def trigger
-      self.script.parse! && self.map! if self.script.changed?
-      self.call_action!               if self.changed?
-    end
 
-    def map
-      @map || self.map!
+    # Outputs formatted debug statement to stdout, only if ::options.debug is true
+    #
+    # ===== Examples
+    #
+    #   Watchr.options.debug = true
+    #   Watchr.debug('im in ur codes, notifayinin u')
+    #
+    # outputs: "[watchr debug] im in ur codes, notifayinin u"
+    #
+    def debug(str)
+      puts "[watchr debug] #{str}" if options.debug
     end
 
-    protected
-
-      def call_action!
-        puts "[debug] monitoring paths: #{self.paths.inspect}" if Watchr.options.debug
-        raise "no reference file" if self.reference_file.nil?
-
-        ref = self.reference_file.to_s
-        pattern, action = self.map[ref]
-        md = ref.match(pattern)
-        action.call(md)
-      end
-
-      def map!
-        @map = {}
-        patterns = self.script.map.map {|mapping| mapping[0] }
-        patterns.each do |pattern|
-          local_files.each do |path|
-            if path.match(pattern)
-              action = self.script.map.assoc(pattern)[1]
-              @map[path] = [pattern, action]
-            end
-          end
+    def handler
+      @handler ||=
+       #case ENV['HANDLER'] || RUBY_PLATFORM
+        case ENV['HANDLER'] || Config::CONFIG['host_os']
+          when /mswin|windows|cygwin/i
+            Watchr::EventHandler::Portable
+          when /bsd|sunos|solaris|darwin|osx|mach|linux/i, 'unix'
+            Watchr::EventHandler::Unix
+          else
+            Watchr::EventHandler::Portable
         end
-        @map
-      end
-
-      def local_files
-        Dir['**/*']
-      end
+    end
   end
 end