watchr 0.5.1

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,94 @@
+=== Summary
+
+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
+
+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 )
+
+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 files in the current directory tree, 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 any test file and run it whenever it is saved.
+
+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") }
+
+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. 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
+
+  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
+
+=== Acknowledgement
+
+* Thanks to macournoyer[http://github.com/macournoyer] for the evented backend idea

data/Rakefile

@@ -0,0 +1,85 @@
+# --------------------------------------------------
+# based on thin's Rakefile (http://github.com/macournoyer/thin)
+# --------------------------------------------------
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'pathname'
+require 'yaml'
+require 'lib/watchr/version'
+begin
+  require 'yard'
+rescue LoadError, RuntimeError
+end
+
+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/ ^doc$ ^pkg ^bk ^\.wiki ^\.yardoc )
+ #s.add_dependency 'every', '>= 1.0'
+  s.add_dependency 'rev',   '>= 0.3.0'
+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('TODO.txt')
+  rdoc.rdoc_files.include('LICENSE')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+}
+
+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
+
+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,31 @@
+
+* 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

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+
+require 'pathname'
+require 'optparse'
+
+require 'watchr'
+require '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
+    begin
+      require 'ruby-debug'
+    rescue LoadError, RuntimeError
+    end
+  }
+
+  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).expand_path
+abort(%|no script found; file "#{file.to_s}" doesn't exist.|) unless file.exist?
+
+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

@@ -0,0 +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
+      @options.debug ||= false
+      @options
+    end
+
+    # 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
+
+    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
+    end
+  end
+end

data/lib/watchr/controller.rb

@@ -0,0 +1,79 @@
+module Watchr
+
+  # The controller contains the app's core logic.
+  #
+  # ===== Examples
+  #
+  #   script = Watchr::Script.new(file)
+  #   contrl = Watchr::Controller.new(script)
+  #   contrl.run
+  #
+  # Calling <tt>#run</tt> will enter the listening loop, and from then on every
+  # file event will trigger its corresponding action defined in <tt>script</tt>
+  #
+  # The controller also automatically adds the script's file itself to its list
+  # of monitored files and will detect any changes to it, providing on the fly
+  # updates of defined rules.
+  #
+  class Controller
+
+    # Creates a controller object around given <tt>script</tt>
+    #
+    # ===== Parameters
+    # script<Script>:: The script object
+    #
+    def initialize(script, handler)
+      @script  = script
+      @handler = handler
+      @handler.add_observer(self)
+
+      Watchr.debug "using %s handler" % handler.class.name
+    end
+
+    # Enters listening loop.
+    #
+    # Will block control flow until application is explicitly stopped/killed.
+    #
+    def run
+      @handler.listen(monitored_paths)
+    end
+
+    # Callback for file events.
+    #
+    # Called while control flow in in listening loop. It will execute the
+    # file's corresponding action as defined in the script. If the file is the
+    # script itself, it will refresh its state to account for potential changes.
+    #
+    # ===== Parameters
+    # path<Pathname, String>:: path that triggered event
+    # event<Symbol>:: event type (ignored for now)
+    #
+    def update(path, event = nil)
+      path = Pathname(path).expand_path
+
+      if path == @script.path
+        @script.parse!
+        @handler.refresh(monitored_paths)
+      else
+        @script.action_for(path).call
+      end
+    end
+
+    # List of paths the script is monitoring.
+    #
+    # Basically this means all paths below current directoly recursivelly that
+    # match any of the rules' patterns, plus the script file.
+    #
+    # ===== Returns
+    # paths<Array[Pathname]>:: List of monitored paths
+    #
+    def monitored_paths
+      paths = Dir['**/*'].select do |path|
+        @script.patterns.any? {|p| path.match(p) }
+      end
+      paths.push(@script.path).compact!
+      paths.map {|path| Pathname(path).expand_path }
+    end
+  end
+end
+