watchr 0.5.9 → 0.6

data/Manifest

@@ -2,9 +2,9 @@
 History.txt
 LICENSE
 Manifest
-README.rdoc
+README.md
 Rakefile
-TODO.txt
+TODO.md
 bin/watchr
 contributions.txt
 docs.watchr

data/README.md

@@ -0,0 +1,113 @@
+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][5] has more details and examples.  You might also want to take a
+look at watchr's own scripts, [specs.watchr][1], [docs.watchr][2] and
+[gem.watchr][3], to get you started.
+
+Install
+-------
+
+    gem install watchr
+
+If you're on \*nix and have the [rev][4] gem installed, Watchr will detect it
+and use it automatically. This will make Watchr evented.
+
+    gem install rev
+
+See Also
+--------
+
+* [redgreen][6]:   Standalone redgreen eye candy for test results, ala autotest.
+* [phocus][7]:     Run focused tests when running the whole file/suite is unnecessary.
+* [autowatchr][8]: Provides some autotest-like behavior for watchr
+* [nestor][9]:     Continuous testing server for Rails
+
+Links
+-----
+
+* code:  <http://github.com/mynyml/watchr>
+* docs:  <http://yardoc.org/docs/mynyml-watchr/file:README.rdoc>
+* wiki:  <http://wiki.github.com/mynyml/watchr>
+* bugs:  <http://github.com/mynyml/watchr/issues>
+
+
+
+
+[1]:  http://github.com/mynyml/watchr/blob/master/specs.watchr
+[2]:  http://github.com/mynyml/watchr/blob/master/docs.watchr
+[3]:  http://github.com/mynyml/watchr/blob/master/gem.watchr
+[4]:  http://github.com/tarcieri/rev/
+[5]:  http://wiki.github.com/mynyml/watchr
+[6]:  http://github.com/mynyml/redgreen
+[7]:  http://github.com/mynyml/phocus
+[8]:  http://github.com/viking/autowatchr
+[9]:  http://github.com/francois/nestor
+

data/Rakefile

@@ -8,9 +8,7 @@ namespace(:test) do
   desc "Run all tests"
   task(:all) do
     tests = Dir['test/**/test_*.rb'] - ['test/test_helper.rb']
-    cmd = "ruby -rubygems -I.:lib -e'%w( #{tests.join(' ')} ).each {|file| require file }'"
-    puts cmd if ENV['VERBOSE']
-    system cmd
+    exit system("ruby -rubygems -I.:lib -e'%w( #{tests.join(' ')} ).each {|file| require file }'")
   end
 
   desc "Run all tests on multiple ruby versions (requires rvm)"
@@ -25,29 +23,3 @@ namespace(:test) do
     end
   end
 end
-
-# --------------------------------------------------
-# Docs
-# --------------------------------------------------
-require 'rake/rdoctask'
-desc "Generate rdoc documentation."
-Rake::RDocTask.new(:rdoc => 'rdoc', :clobber_rdoc => 'rdoc:clean', :rerdoc => 'rdoc:force') do |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')
-end
-
-desc "Generate YARD Documentation"
-task(:yardoc) do
-  require 'yard'
-  files   = %w( lib/**/*.rb )
-  options = %w( -o doc/yard --readme README.rdoc --files LICENSE )
-  YARD::CLI::Yardoc.run *(options + files)
-end
-

data/TODO.md

@@ -0,0 +1,29 @@
+Features
+--------
+
+* watchr -e ( `$ watchr -e "watch('foo.gemspec') { system('gem build foo.gemspec') }"` )
+* watchr --auto
+* watchr --fetch
+
+* enable ability to watch dirs
+  * requires new handler(s)
+  * will allow recognizing `:added` events
+
+Bugs
+----
+
+* sometimes an action is fired without a file being saved
+  * buffer flushing issue?
+  * libev issue?
+  * probably fixed with event type handling update, which ignores atime
+    updates by defaults
+
+* when a file is saved twice quickly, subsequent events are ignored.
+  * seems like rev/libev drops the file watch
+
+Other
+-----
+
+* add tests for executable
+* memory profiling / benchmarks
+

data/bin/watchr

@@ -2,14 +2,21 @@
 
 require 'pathname'
 require 'optparse'
+require 'tempfile'
 
 require 'watchr'
 
 module Watchr
   # Namespaced to avoid defining global methods
-  module Bin #:nodoc:
+  #
+  # @private
+  module Bin
     extend self
 
+    DEFAULT_SCRIPT_PATH = Pathname.new('specs.watchr')
+
+    attr_accessor :path
+
     def usage
       "Usage: watchr [opts] path/to/script"
     end
@@ -18,20 +25,41 @@ module Watchr
       "watchr version: %s" % Watchr::VERSION
     end
 
+    # Absolute path to script file
+    #
+    # Unless set manually, the script's path is either first arg or
+    # `DEFAULT_SCRIPT_PATH`. If neither exists, the script immediatly aborts
+    # with an appropriate error message.
+    #
+    # @return [Pathname]
+    #   absolute path to script
+    #
+    def path!
+      return @path unless @path.nil?
+      rel = relative_path    or abort( usage )
+      find_in_load_path(rel) or abort("no script found: file #{rel.to_s.inspect} is not in path.")
+    end
+
     # Find a partial path name in load path
     #
-    # ===== Params
-    # path<Pathname>:: partial pathname
+    # @param [Pathname] path
+    #   partial pathname
     #
-    # ===== Returns
-    # <Pathname>::
+    # @return [Pathname]
     #   absolute path of first occurence of partial path in load path, or nil if not found
-    #--
-    # Adds '.' for ruby1.9.2
+    #
     def find_in_load_path(path)
+      # Adds '.' for ruby1.9.2
       dir = (['.'] + $LOAD_PATH).uniq.detect {|p| Pathname(p).join(path).exist? }
       dir ? path.expand_path(dir) : nil
     end
+
+    private
+
+    def relative_path
+      return Pathname.new(ARGV.first) if ARGV.first
+      return DEFAULT_SCRIPT_PATH      if DEFAULT_SCRIPT_PATH.exist?
+    end
   end
 end
 
@@ -45,6 +73,27 @@ opts = OptionParser.new do |opts|
     rescue LoadError, RuntimeError
     end
   }
+  opts.on('-l', '--list', "Display list of files monitored by script and exit") {
+    script     = Watchr::Script.new(Watchr::Bin.path!)
+    controller = Watchr::Controller.new(script, Watchr.handler.new)
+    script.parse!
+    puts controller.monitored_paths
+    exit
+  }
+
+  def assert_syntax(code)
+    catch(:ok) { Object.new.instance_eval("BEGIN { throw :ok }; #{code}", %|-e "#{code}"|, 0) }
+  rescue SyntaxError => e
+    puts e.message.split("\n")[1]
+    exit
+  end
+
+  opts.on('-e', '--eval INLINE_SCRIPT', %|Evaluate script inline ($ watchr -e "watch('foo') { puts 'bar' }")|) {|code|
+    assert_syntax(code)
+
+    Tempfile.open('foo') {|f| f << code; @__path = f.path }
+    Watchr::Bin.path = Pathname(@__path)
+  }
 
   opts.on_tail('-h', '--help', "Print inline help") { puts opts; exit }
   opts.on_tail('-v', '--version', "Print version" ) { puts Watchr::Bin.version; exit }
@@ -52,8 +101,5 @@ opts = OptionParser.new do |opts|
   opts.parse! ARGV
 end
 
-relative_path = Pathname( ARGV.first )                   rescue abort(Watchr::Bin.usage)
-absolute_path = Watchr::Bin.find_in_load_path(relative_path) or abort("no script found; file #{relative_path.to_s.inspect} is not in path.")
-
-Watchr::Controller.new(Watchr::Script.new(absolute_path), Watchr.handler.new).run
+Watchr::Controller.new(Watchr::Script.new(Watchr::Bin.path!), Watchr.handler.new).run
 

data/docs.watchr

@@ -1,26 +1,26 @@
 # Run me with:
-#
 #   $ watchr docs.watchr
 
-def run_rdoc
-  system('rake --silent rdoc')
-end
+require 'yard'
+# --------------------------------------------------
+# Rules
+# --------------------------------------------------
+watch( 'lib/.*\.rb' ) { yard }
+watch( 'README.md'  ) { yard }
+watch( 'TODO.md'    ) { yard }
+watch( 'LICENSE'    ) { yard }
 
-def run_yard
-  print "\nUpdating yardocs... "
-  system('rake --silent yardoc')
-  print "done.\n"
-end
+# --------------------------------------------------
+# Signal Handling
+# --------------------------------------------------
+Signal.trap('QUIT') { yard }        # Ctrl-\
+Signal.trap('INT' ) { abort("\n") } # Ctrl-C
 
-def document
-  run_rdoc
-  run_yard
+# --------------------------------------------------
+# Helpers
+# --------------------------------------------------
+def yard
+  print "Updating yardocs... "; STDOUT.flush
+  YARD::CLI::Yardoc.run *%w( -o doc/yard --readme README.md --markup markdown - LICENSE TODO.md )
+  print "done\n"
 end
-
-watch( 'lib/.*\.rb'  ) { document }
-watch( 'README.rdoc' ) { document }
-watch( 'TODO.txt'    ) { document }
-watch( 'LICENSE'     ) { document }
-
-
-# vim:ft=ruby

data/gem.watchr

@@ -1,32 +1,22 @@
 # Run me with:
-#
 #   $ watchr gem.watchr
 
+def gemspec() Dir['*.gemspec'].first end
 # --------------------------------------------------
-# Convenience Methods
+# Rules
 # --------------------------------------------------
-def build(gemspec)
-  system "gem build %s" % gemspec
-  FileUtils.mv Dir['watchr-*.gem'], 'pkg/'
-  puts
-end
+watch( gemspec ) { build }
 
 # --------------------------------------------------
-# Watchr Rules
+# Signal Handling
 # --------------------------------------------------
-watch( '^watchr.gemspec$' ) { |m| build m[0] }
+Signal.trap('QUIT') { build }       # Ctrl-\
+Signal.trap('INT' ) { abort("\n") } # Ctrl-C
 
 # --------------------------------------------------
-# Signal Handling
+# Helpers
 # --------------------------------------------------
-# Ctrl-\
-Signal.trap('QUIT') do
-  puts " --- Building Gem ---\n\n"
-  build 'watchr.gemspec'
+def build
+  puts; system "gem build #{gemspec}"
+  FileUtils.mv( Dir['*.gem'], 'pkg/' )
 end
-
-# Ctrl-C
-Signal.trap('INT') { abort("\n") }
-
-
-# vim:ft=ruby

data/lib/watchr.rb

@@ -5,15 +5,15 @@ require 'rbconfig'
 # user defined action whenever an observed file is modified. Its most typical
 # use is continuous testing.
 #
-# Usage:
+# See README for more details
 #
-#   # on command line, from project's root dir
-#   $ watchr path/to/script
+# @example
 #
-# See README for more details
+#     # on command line, from project's root dir
+#     $ watchr path/to/script
 #
 module Watchr
-  VERSION = '0.5.9'
+  VERSION = '0.6'
 
   begin
     require 'rev'
@@ -35,7 +35,7 @@ module Watchr
     attr_accessor :options
     attr_accessor :handler
 
-    # backwards compatibility
+    # @deprecated
     def version #:nodoc:
       Watchr::VERSION
     end
@@ -43,55 +43,59 @@ module Watchr
     # Options proxy.
     #
     # Currently supported options:
-    # * debug<Boolean> Debugging state. More verbose.
     #
-    # ===== Examples
+    # * debug[Boolean] Debugging state. More verbose.
+    #
+    # @example
     #
-    #   Watchr.options.debug #=> false
-    #   Watchr.options.debug = true
+    #     Watchr.options.debug #=> false
+    #     Watchr.options.debug = true
     #
-    # ===== Returns
-    # options<Struct>:: options proxy.
+    # @return [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
+    # Outputs formatted debug statement to stdout, only if `::options.debug` is true
+    #
+    # @example
+    #
+    #     Watchr.options.debug = true
+    #     Watchr.debug('im in ur codes, notifayinin u')
     #
-    # ===== Examples
+    #     #outputs: "[watchr debug] im in ur codes, notifayinin u"
     #
-    #   Watchr.options.debug = true
-    #   Watchr.debug('im in ur codes, notifayinin u')
+    # @param [String] message
+    #   debug message to print
     #
-    # outputs: "[watchr debug] im in ur codes, notifayinin u"
+    # @return [nil]
     #
-    def debug(str)
-      puts "[watchr debug] #{str}" if options.debug
+    def debug(msg)
+      puts "[watchr debug] #{msg}" if options.debug
     end
 
     # Detect current OS and return appropriate handler.
     #
-    # ===== Examples
+    # @example
     #
-    #   Config::CONFIG['host_os'] #=> 'linux-gnu'
-    #   Watchr.handler #=> Watchr::EventHandler::Unix
+    #     Config::CONFIG['host_os'] #=> 'linux-gnu'
+    #     Watchr.handler #=> Watchr::EventHandler::Unix
     #
-    #   Config::CONFIG['host_os'] #=> 'cygwin'
-    #   Watchr.handler #=> Watchr::EventHandler::Portable
+    #     Config::CONFIG['host_os'] #=> 'cygwin'
+    #     Watchr.handler #=> Watchr::EventHandler::Portable
     #
-    #   ENV['HANDLER'] #=> 'unix'
-    #   Watchr.handler #=> Watchr::EventHandler::Unix
+    #     ENV['HANDLER'] #=> 'unix'
+    #     Watchr.handler #=> Watchr::EventHandler::Unix
     #
-    #   ENV['HANDLER'] #=> 'portable'
-    #   Watchr.handler #=> Watchr::EventHandler::Portable
+    #     ENV['HANDLER'] #=> 'portable'
+    #     Watchr.handler #=> Watchr::EventHandler::Portable
     #
-    # ===== Returns
-    # handler<Class>:: handler class for current architecture
+    # @return [Class]
+    #   handler class for current architecture
     #
     def handler
       @handler ||=