observr 1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    OGYwNDY2YjY5OWRmYjBiYjFhMDM2ZmYxYTYyZWFiYTVmODY2MWQ1Yg==
+  data.tar.gz: !binary |-
+    ZTUzMzdkYzM0NDBjZTAwOTA3ZTkzYmYwNGEwMDU5MjM3NWQ5ODViYw==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    ZjViMjA2YmVjMGE5OWRiZjY1ZWMzOTYxNzc0NWYyZmQxZTgxNTNmYjFmYThj
+    YWMyOTRjYzJlYzM5ODc1M2NlZjE5ODM3YjE2M2Y3NTIyMjRkMGJjNThkYTkw
+    NDY2OTZiMTIzYTI4NjRiNGJmMWM5ZTdlMmViNTg5ZDBiMjhhYmE=
+  data.tar.gz: !binary |-
+    NmExZGIzMjRmMjk5MDdjOWUwOTk0ODZlYzhkMjFmZjZiOTY0NWIxOGY4NGNj
+    YzgzMzE4MmNlYTM4NzY2NGIzMmNmNzIxNmE1MmM2NTIxZTA0OTcxZGRiZjU0
+    NjRiYTIzZWQwNGQzYjhlZGMxMWRmM2Y5ZGNhN2IyYzc0NGY3ZjU=

data/.gitignore

@@ -0,0 +1,6 @@
+doc/
+pkg/
+bk/
+.wiki
+.yardoc
+*.gem

data/History.txt

@@ -0,0 +1,32 @@
+
+=== v0.5.7
+
+* Added manifest.watchr script
+* Unix handler supports :deleted event type
+* Unix handler supports :accessed (atime), :modified (mtime) and :changed
+  (ctime) event types (thanks gzuki[http://github.com/gzuki] for initial work)
+
+
+=== v0.5.6
+
+* Rev gem optional in development (thanks TwP[http://github.com/TwP])
+* Allow gems to bundle .watchr scripts (thanks foca[http://github.com/foca])
+
+    gemname/lib/gemname.watchr
+
+  is now automatically picked up with
+
+    $ watchr gemname.watchr
+
+* Look for script in path
+* debug msg when rev not found on *nix
+* rake task for cross interpreter testing
+
+
+=== v0.5.5
+
+* Rev gem is optional. Fixes issue #1
+  Install Rev to automatically get evented handler on *nix
+
+    gem install rev
+

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright © 2013 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.md

@@ -0,0 +1,119 @@
+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
+--------
+
+observr 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,
+
+    $ observr 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 observr 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_observr.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 observr) so experimenting is painless.
+
+The [wiki][5] has more details and examples.  You might also want to take a
+look at observr's own scripts, [specs.observr][1], [docs.observr][2] and
+[gem.observr][3], to get you started.
+
+Install
+-------
+
+    gem install observr
+
+If you're on Linux/BSD and have the [rev][4] gem installed, Observr will detect
+it and use it automatically. This will make Observr evented.
+
+    gem install rev
+
+You can get the same evented behaviour on OS X by installing
+[ruby-fsevent][10].
+
+    gem install ruby-fsevent
+
+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.
+* [autoobservr][8]: Provides some autotest-like behavior for observr
+* [nestor][9]:     Continuous testing server for Rails
+
+Links
+-----
+
+* code:  <http://github.com/kevinburke/observr>
+* docs:  <http://yardoc.org/docs/mynyml-observr/file:README.rdoc>
+* wiki:  <http://wiki.github.com/mynyml/observr>
+* bugs:  <http://github.com/kevinburke/observr/issues>
+
+
+
+
+[1]:  http://github.com/kevinburke/observr/blob/master/specs.observr
+[2]:  http://github.com/kevinburke/observr/blob/master/docs.observr
+[3]:  http://github.com/kevinburke/observr/blob/master/gem.observr
+[4]:  http://github.com/tarcieri/rev/
+[5]:  http://wiki.github.com/mynyml/observr
+[6]:  http://github.com/mynyml/redgreen
+[7]:  http://github.com/mynyml/phocus
+[8]:  http://github.com/viking/autoobservr
+[9]:  http://github.com/francois/nestor
+[10]: http://github.com/sandro/ruby-fsevent
+

data/Rakefile

@@ -0,0 +1,34 @@
+def gem_opt
+  defined?(Gem) ? "-rubygems" : ""
+end
+
+def ruby
+  require 'rbconfig'
+  File.join([Config::CONFIG['bindir'], Config::CONFIG['ruby_install_name']]) << Config::CONFIG['EXEEXT']
+end
+
+# --------------------------------------------------
+# Tests
+# --------------------------------------------------
+task(:default => "test:all")
+
+namespace(:test) do
+
+  desc "Run all tests"
+  task(:all) do
+    tests = Dir['test/**/test_*.rb'] - ['test/test_helper.rb']
+    exit system(%Q{#{ruby} #{gem_opt} -I.:lib -e"%w( #{tests.join(' ')} ).each {|file| require file }"})
+  end
+
+  desc "Run all tests on multiple ruby versions (requires rvm)"
+  task(:portability) do
+    %w( 1.8.6  1.8.7  1.9.1  1.9.2 ).each do |version|
+      system <<-BASH
+        bash -c 'source ~/.rvm/scripts/rvm;
+                 rvm #{version};
+                 echo "--------- v#{version} ----------\n";
+                 rake -s test:all'
+      BASH
+    end
+  end
+end

data/TODO.md

@@ -0,0 +1,31 @@
+Features
+--------
+
+* observr -e ( `$ observr -e "watch('foo.gemspec') { system('gem build foo.gemspec') }"` )
+* observr --auto
+* observr --fetch
+
+* enable ability to watch dirs
+  * requires new handler(s)
+  * will allow recognizing `:added` events
+
+* allow setting latency
+
+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/observr

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby
+
+require 'pathname'
+require 'optparse'
+require 'tempfile'
+
+require File.dirname(__FILE__) + '/../lib/observr'
+
+module Observr
+  # Namespaced to avoid defining global methods
+  #
+  # @private
+  module Bin
+    extend self
+
+    DEFAULT_SCRIPT_PATH = Pathname.new('specs.observr')
+
+    attr_accessor :path
+
+    def usage
+      "Usage: observr [opts] path/to/script"
+    end
+
+    def version
+      "observr version: %s" % Observr::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
+    #
+    # @param [Pathname] path
+    #   partial pathname
+    #
+    # @return [Pathname]
+    #   absolute path of first occurence of partial path in load path, or nil if not found
+    #
+    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
+
+opts = OptionParser.new do |opts|
+  opts.banner = Observr::Bin.usage
+
+  opts.on('-d', '--debug', "Print extra debug info while program runs") {
+    Observr.options.debug = true
+    begin
+      require 'ruby-debug'
+    rescue LoadError, RuntimeError
+    end
+  }
+  opts.on('-l', '--list', "Display list of files monitored by script and exit") {
+    script     = Observr::Script.new(Observr::Bin.path!)
+    controller = Observr::Controller.new(script, Observr.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 ($ observr -e "watch('foo') { puts 'bar' }")|) {|code|
+    assert_syntax(code)
+
+    Tempfile.open('foo') {|f| f << code; @__path = f.path }
+    Observr::Bin.path = Pathname(@__path)
+  }
+
+  opts.on_tail('-h', '--help', "Print inline help") { puts opts; exit }
+  opts.on_tail('-v', '--version', "Print version" ) { puts Observr::Bin.version; exit }
+
+  opts.parse! ARGV
+end
+
+Observr::Controller.new(Observr::Script.new(Observr::Bin.path!), Observr.handler.new).run
+

data/contributions.txt

@@ -0,0 +1,7 @@
+
+Suggestions:
+  macournoyer, foca
+
+Patches:
+  TwP, gzuki, spraints, francois
+

data/docs.observr

@@ -0,0 +1,26 @@
+# Run me with:
+#   $ observr docs.observr
+
+require 'yard'
+# --------------------------------------------------
+# Rules
+# --------------------------------------------------
+watch( 'lib/.*\.rb' ) { yard }
+watch( 'README.md'  ) { yard }
+watch( 'TODO.md'    ) { yard }
+watch( 'LICENSE'    ) { yard }
+
+# --------------------------------------------------
+# Signal Handling
+# --------------------------------------------------
+Signal.trap('QUIT') { yard }        # Ctrl-\
+Signal.trap('INT' ) { abort("\n") } # Ctrl-C
+
+# --------------------------------------------------
+# 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

data/gem.observr

@@ -0,0 +1,22 @@
+# Run me with:
+#   $ observr gem.observr
+
+def gemspec() Dir['*.gemspec'].first end
+# --------------------------------------------------
+# Rules
+# --------------------------------------------------
+watch( gemspec ) { build }
+
+# --------------------------------------------------
+# Signal Handling
+# --------------------------------------------------
+Signal.trap('QUIT') { build }       # Ctrl-\
+Signal.trap('INT' ) { abort("\n") } # Ctrl-C
+
+# --------------------------------------------------
+# Helpers
+# --------------------------------------------------
+def build
+  puts; system "gem build #{gemspec}"
+  FileUtils.mv( Dir['*.gem'], 'pkg/' )
+end

data/lib/observr.rb

@@ -0,0 +1,133 @@
+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.
+#
+# See README for more details
+#
+# @example
+#
+#     # on command line, from project's root dir
+#     $ observr path/to/script
+#
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+module Observr
+  VERSION = '1.0'
+
+  begin
+    #require 'fsevent'
+    #HAVE_FSE = true
+  #rescue LoadError, RuntimeError
+    HAVE_FSE = false
+  end
+
+  begin
+    require 'rev'
+    HAVE_REV = true
+  rescue LoadError, RuntimeError
+    HAVE_REV = false
+  end
+
+  autoload :Script,     'observr/script'
+  autoload :Controller, 'observr/controller'
+
+  module EventHandler
+    autoload :Base,     'observr/event_handlers/base'
+    autoload :Portable, 'observr/event_handlers/portable'
+    autoload :Unix,     'observr/event_handlers/unix'      if ::Observr::HAVE_REV
+    autoload :Darwin,   'observr/event_handlers/darwin'    if ::Observr::HAVE_FSE
+  end
+
+  class << self
+    attr_accessor :options
+    attr_accessor :handler
+
+    # @deprecated
+    def version #:nodoc:
+      Observr::VERSION
+    end
+
+    # Options proxy.
+    #
+    # Currently supported options:
+    #
+    # * debug[Boolean] Debugging state. More verbose.
+    #
+    # @example
+    #
+    #     Observr.options.debug #=> false
+    #     Observr.options.debug = true
+    #
+    # @return [Struct]
+    #   options proxy.
+    #
+    def options
+      @options ||= Struct.new(:debug).new
+      @options.debug ||= false
+      @options
+    end
+
+    # Outputs formatted debug statement to stdout, only if `::options.debug` is true
+    #
+    # @example
+    #
+    #     Observr.options.debug = true
+    #     Observr.debug('im in ur codes, notifayinin u')
+    #
+    #     #outputs: "[observr debug] im in ur codes, notifayinin u"
+    #
+    # @param [String] message
+    #   debug message to print
+    #
+    # @return [nil]
+    #
+    def debug(msg)
+      puts "[observr debug] #{msg}" if options.debug
+    end
+
+    # Detect current OS and return appropriate handler.
+    #
+    # @example
+    #
+    #     Config::CONFIG['host_os'] #=> 'linux-gnu'
+    #     Observr.handler #=> Observr::EventHandler::Unix
+    #
+    #     Config::CONFIG['host_os'] #=> 'cygwin'
+    #     Observr.handler #=> Observr::EventHandler::Portable
+    #
+    #     ENV['HANDLER'] #=> 'unix'
+    #     Observr.handler #=> Observr::EventHandler::Unix
+    #
+    #     ENV['HANDLER'] #=> 'portable'
+    #     Observr.handler #=> Observr::EventHandler::Portable
+    #
+    # @return [Class]
+    #   handler class for current architecture
+    #
+    def handler
+      @handler ||=
+        case ENV['HANDLER'] || Config::CONFIG['host_os']
+          when /darwin|mach|osx|fsevents?/i
+            if Observr::HAVE_FSE
+              Observr::EventHandler::Darwin
+            else
+              Observr.debug "fsevent not found. `gem install ruby-fsevent` to get evented handler"
+              Observr::EventHandler::Portable
+            end
+          when /sunos|solaris|bsd|linux|unix/i
+            if Observr::HAVE_REV
+              Observr::EventHandler::Unix
+            else
+              Observr.debug "rev not found. `gem install rev` to get evented handler"
+              Observr::EventHandler::Portable
+            end
+          when /mswin|windows|cygwin/i
+            Observr::EventHandler::Portable
+          else
+            Observr::EventHandler::Portable
+        end
+    end
+  end
+end