mynyml-watchr 0.3.0

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright © 2009 Martin Aumont (mynyml)
+
+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/README.rdoc

@@ -0,0 +1,73 @@
+==== 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.
+
+
+==== 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
+
+
+==== 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.
+
+
+==== 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)
+
+  watch( 'a regexp pattern matching paths to observe' )  {|match_data_object| command_to_run }
+
+So for example,
+
+  watch( 'test/test_.*\.rb' )  {|md| system("ruby #{md[0]}") }
+
+will match test files and run them whenever they are modified.
+
+A continious 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") }
+
+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.
+And remember the scripts are pure ruby, so feel free to add methods,
+Signal#trap calls, etc.
+
+The wiki[http://wiki.github.com/mynyml/watchr] has more details and examples.
+
+
+==== Install
+
+  gem install mynyml-watchr --source http://gems.github.com/
+
+
+==== 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
+
+source:: http://github.com/mynyml/watchr
+rdocs::  http://docs.github.com/mynyml/watchr
+wiki::   http://wiki.github.com/mynyml/watchr
+

data/Rakefile

@@ -0,0 +1,70 @@
+# --------------------------------------------------
+# 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 )
+end
+
+desc "Generate rdoc documentation."
+Rake::RDocTask.new(:rdoc => 'rdoc', :clobber_rdoc => 'rdoc:clean', :rerdoc => 'rdoc:force') { |rdoc|
+  rdoc.rdoc_dir = 'doc/rdoc'
+  rdoc.title    = "Watchr"
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.options << '--charset' << 'utf-8'
+  rdoc.main = 'README.rdoc'
+  rdoc.rdoc_files.include('README.rdoc')
+  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}"
+end

data/TODO.txt

@@ -0,0 +1,27 @@
+
+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)

data/bin/watchr

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+
+require 'pathname'
+require 'optparse'
+root  = Pathname(__FILE__).dirname.parent
+require root.join('lib/watchr')
+require root.join('lib/watchr/version')
+
+def usage
+  "Usage: watchr [opts] path/to/script"
+end
+
+def version
+  "watchr version: %s" % Watchr.version
+end
+
+opts = OptionParser.new do |opts|
+  opts.banner = usage
+
+  opts.on('-d', '--debug', "Print extra debug info while program runs") {
+    Watchr.options.debug = true
+  }
+
+  opts.on_tail('-h', '--help', "Print inline help") { puts opts;    exit }
+  opts.on_tail('-v', '--version', "Print version" ) { puts version; exit }
+
+  opts.parse! ARGV
+end
+
+abort(usage) unless ARGV.first
+
+file = Pathname(ARGV.first)
+abort(%|no script found; file "#{file.to_s}" doesn't exist.|) unless file.exist?
+
+Watchr::Runner.new(file).run
+

data/lib/watchr/version.rb

@@ -0,0 +1,11 @@
+module Watchr
+  module VERSION
+    MAJOR = 0
+    MINOR = 3
+    TINY  = 0
+  end
+
+  def self.version
+    [VERSION::MAJOR, VERSION::MINOR, VERSION::TINY].join('.')
+  end
+end

data/lib/watchr.rb

@@ -0,0 +1,137 @@
+module Watchr
+  class << self
+    attr_accessor :options
+
+    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!
+    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
+        end
+        @map
+      end
+
+      def local_files
+        Dir['**/*']
+      end
+  end
+end

data/rdoc.watchr

@@ -0,0 +1,15 @@
+# Run me with:
+#
+#   $ watchr docs.watchr
+
+run_rdoc = lambda { system('rake --silent rdoc') }
+
+watch( '(lib|bin)/.*\.rb', &run_rdoc )
+watch( 'README.rdoc',      &run_rdoc )
+watch( 'TODO.txt',         &run_rdoc )
+watch( 'LICENSE',          &run_rdoc )
+
+
+
+
+# vim:ft=ruby

data/specs.watchr

@@ -0,0 +1,35 @@
+# Run me with:
+#
+#   $ watchr specs.watchr
+
+def all_test_files
+  Dir['test/**/test_*.rb'] - ['test/test_helper.rb']
+end
+
+def run(cmd)
+  puts(cmd)
+  system(cmd)
+end
+
+def run_all_tests
+  cmd = "ruby -rubygems -I.:lib:test -e'%w( #{all_test_files.join(' ')} ).each {|file| require file }'"
+  run(cmd)
+end
+
+watch( 'test/test_.*\.rb' )     {|md| run("ruby -rubygems #{md[0]}") }
+watch( 'lib/(.*)\.rb' )         {|md| run("ruby -rubygems test/test_#{md[1]}.rb") }
+watch( 'test/test_helper\.rb' ) { run_all_tests }
+
+# Ctrl-C
+Signal.trap('INT') do
+  puts " RERUNING ALL TESTS (Ctrl-\\ to quit)\n\n"
+  run_all_tests
+end
+
+# Ctrl-\
+Signal.trap('QUIT') { abort("\n") }
+
+
+
+
+# vim:ft=ruby

data/test/test_helper.rb

@@ -0,0 +1,67 @@
+require 'pathname'
+require 'test/unit'
+require 'matchy'
+require 'mocha'
+require 'every'
+require 'pending'
+begin
+  require 'ruby-debug'
+  require 'phocus'
+  require 'redgreen'
+rescue LoadError, RuntimeError
+end
+
+ROOT = Pathname(__FILE__).dirname.parent
+$:.unshift(ROOT.join('lib'))
+
+require 'watchr'
+
+class Test::Unit::TestCase
+  class << self
+    def test(name, &block)
+      name = :"test_#{name.gsub(/\s/,'_')}"
+      define_method(name, &block)
+    end
+    alias :should :test
+  end
+end
+
+class Pathname
+  def rel
+    self.relative_path_from(ROOT).to_s
+  end
+  def pattern
+    Regexp.escape(self.rel)
+  end
+  def touch(time = Time.now)
+    `touch -mt #{time.strftime('%Y%m%d%H%M.%S')} #{self.expand_path.to_s}`
+    self
+  end
+  def mtime=(t)
+    self.touch(t).mtime
+  end
+end
+
+class Fixture
+  DIR = Pathname(__FILE__).dirname.join('fixtures')
+
+  class << self
+    attr_accessor :files
+
+    def create(name=nil, content=nil)
+      name ||= 'a.rb'
+      file = DIR.join(name)
+      self.files ||= []
+      self.files << file
+      file.open('w+') {|f| f << (content || "fixture\n") }
+      file
+    end
+
+    def delete_all
+      DIR.entries.each do |fixture|
+        next if %w( .. . ).include?(fixture.to_s)
+        DIR.join(fixture.to_s).expand_path.delete
+      end
+    end
+  end
+end

data/test/test_watchr.rb

@@ -0,0 +1,182 @@
+require 'test/test_helper'
+
+class TestWatchr < Test::Unit::TestCase
+
+  def setup
+    Watchr.options = nil
+  end
+
+  ## options
+
+  test "debug" do
+    Watchr.options.debug.should be(false)
+    Watchr.options.debug = true
+    Watchr.options.debug.should be(true)
+  end
+end
+
+class TestScript < Test::Unit::TestCase
+  include Watchr
+
+  ## api
+
+  test "watch" do
+    script = Script.new
+    script.watch('pattern') { nil }
+
+    script.map.first[0].should be('pattern')
+    script.map.first[1].call.should be(nil)
+  end
+
+  test "default action" do
+    script = Script.new
+    script.default_action { nil }
+    script.watch('pattern')
+
+    script.map.first[0].should be('pattern')
+    script.map.first[1].call.should be(nil)
+  end
+
+  test "automatically picks up changes to script file" do
+    file = Fixture.create('script.watchr', "watch('abc')")
+    script = Script.new(file)
+    script.changed?.should be(false)
+
+    script.stubs(:reference_time).returns(Time.now - 10) #mock sleep
+
+    Fixture.create('script.watchr', "watch('def')")
+    script.changed?.should be(true)
+  end
+
+  test "reparses script file" do
+    file   = Fixture.create('script.watchr', "watch('abc')")
+    script = Script.new(file)
+    script.map.first.should include('abc')
+    script.map.first.should exclude('def')
+
+    script.stubs(:reference_time).returns(Time.now - 10) #mock sleep
+    Fixture.create('script.watchr', "watch('def')")
+    script.parse!
+    script.map.first.should include('def')
+    script.map.first.should exclude('abc')
+  end
+end
+
+class TestRunner < Test::Unit::TestCase
+  include Watchr
+
+  def teardown
+    Fixture.delete_all
+    Watchr.options = nil
+  end
+
+  test "maps observed files to their pattern and the actions they trigger" do
+    file_a = Fixture.create('a.rb')
+    file_b = Fixture.create('b.rb')
+    script = Script.new
+    script.watch(file_a.pattern) { 'ohaie' }
+    script.watch(file_b.pattern) { 'kthnx' }
+
+    runner = Runner.new(script)
+    runner.map[file_a.rel][0].should be(file_a.pattern)
+    runner.map[file_b.rel][0].should be(file_b.pattern)
+    runner.map[file_a.rel][1].call.should be('ohaie')
+    runner.map[file_b.rel][1].call.should be('kthnx')
+  end
+
+  test "latest mtime" do
+    file_a = Fixture.create('a.rb')
+    file_b = Fixture.create('b.rb')
+    script = Script.new
+    script.watch(file_a.pattern) { 'ohaie' }
+    script.watch(file_b.pattern) { 'kthnx' }
+
+    runner = Runner.new(script)
+    file_a.touch
+
+    runner.last_updated_file.rel.should be(file_a.rel)
+  end
+
+  test "monitors file changes" do
+    file_a = Fixture.create('a.rb')
+    script = Script.new
+    script.watch(file_a.pattern) { nil }
+
+    runner = Runner.new(script)
+    runner.changed?.should be(false)
+
+    # fake Kernel.sleep(2)
+    file_a.mtime     = Time.now - 2
+    runner.init_time = Time.now - 2
+
+    file_a.touch
+    runner.changed?.should be(true)
+  end
+
+  test "calls action corresponding to file changed" do
+    script = Script.new
+    script.watch(Fixture.create.pattern) { throw(:ohaie) }
+
+    runner = Runner.new(script)
+    runner.init_time = Time.now - 2
+    runner.changed?
+    assert_throws(:ohaie) do
+      runner.instance_eval { call_action! }
+    end
+  end
+
+  test "passes match data to action" do
+    file_a = Fixture.create('a.rb')
+    script = Script.new
+    pattern = Fixture::DIR.join('(.*)\.(.*)$').rel
+    script.watch((pattern)) {|md| [md[1], md[2]].join('|') }
+
+    runner = Runner.new(script)
+    runner.init_time = Time.now - 2
+    file_a.touch
+    runner.changed?
+    runner.instance_eval { call_action! }.should be('a|rb')
+  end
+
+  test "doesn't run at startup" do
+    file   = Fixture.create('a.rb')
+    script = Script.new
+    script.watch(file.pattern) { nil }
+
+    runner = Runner.new(script)
+    runner.changed?.should be(false)
+  end
+
+  test "a path only triggers its last matching pattern's action" do
+    file_a = Fixture.create('fix_a.rb')
+    file_b = Fixture.create('fix_b.rb')
+    script = Script.new
+    script.watch('fix_a\.rb')  { throw(:ohaie) }
+    script.watch('fix_.*\.rb') { throw(:kkthx) }
+
+    runner = Runner.new(script)
+    runner.init_time = Time.now - 2
+    file_a.touch
+    runner.changed?
+    assert_throws(:kkthx) do
+      runner.instance_eval { call_action! }
+    end
+  end
+
+  test "updates map when script changes" do
+    file_a = Fixture.create('aaa')
+    file_b = Fixture.create('bbb')
+    script = Fixture.create('script.watchr', "watch('aaa')")
+
+    # fake Kernel.sleep(2)
+    script.mtime = Time.now - 2
+
+    runner = Runner.new(script)
+    assert runner.paths.first.match('aaa')
+
+    Fixture.create('script.watchr', "watch('bbb')")
+
+    runner.trigger
+    assert runner.paths.first.match('bbb')
+  end
+end

data/watchr.gemspec

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: watchr
+version: !ruby/object:Gem::Version 
+  version: 0.3.0
+platform: ruby
+authors: 
+- Martin Aumont
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-08-26 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: Continious anything; project files observer/trigger.
+email: mynyml@gmail.com
+executables: 
+- watchr
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- Rakefile
+- test
+- test/test_watchr.rb
+- test/test_helper.rb
+- TODO.txt
+- bin
+- bin/watchr
+- lib
+- lib/watchr
+- lib/watchr/version.rb
+- lib/watchr.rb
+- README.rdoc
+- LICENSE
+- yard.watchr
+- rdoc.watchr
+- specs.watchr
+- watchr.gemspec
+has_rdoc: true
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+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: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Continious anything
+test_files: []
+

data/yard.watchr

@@ -0,0 +1,18 @@
+# Run me with:
+#
+#   $ watchr docs-yard.watchr
+
+def run_yard
+  print "Updating yardocs... "
+  system('yardoc -o doc/yard --readme README.rdoc --files LICENSE')
+  print "done.\n"
+end
+
+watch( '^(lib|bin)/.*\.rb' ) { run_yard }
+watch( '^README.rdoc'      ) { run_yard }
+watch( '^LICENSE'          ) { run_yard }
+
+
+
+
+# vim:ft=ruby

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: mynyml-watchr
+version: !ruby/object:Gem::Version 
+  version: 0.3.0
+platform: ruby
+authors: 
+- Martin Aumont
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-08-25 21:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Continious anything; project files observer/trigger.
+email: mynyml@gmail.com
+executables: 
+- watchr
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- Rakefile
+- test
+- test/test_watchr.rb
+- test/test_helper.rb
+- TODO.txt
+- bin
+- bin/watchr
+- lib
+- lib/watchr
+- lib/watchr/version.rb
+- lib/watchr.rb
+- README.rdoc
+- LICENSE
+- yard.watchr
+- rdoc.watchr
+- specs.watchr
+- watchr.gemspec
+has_rdoc: true
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+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: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Continious anything
+test_files: []
+