mynyml-watchr 0.3.0 → 0.5.2

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
+

data/lib/watchr/event_handlers/base.rb

@@ -0,0 +1,48 @@
+require 'observer'
+
+module Watchr
+  module EventHandler
+    class AbstractMethod < Exception; end
+
+    # Base functionality mixin meant to be included in specific event handlers.
+    module Base
+      include Observable
+
+      # Notify that a file was modified.
+      #
+      # ===== Parameters
+      # path<Pathname, String>:: full path or path relative to current working directory
+      # event<Symbol>:: event type (not yet used).
+      #
+      #--
+      # #changed and #notify_observers are Observable methods
+      def notify(path, event = nil)
+        changed(true)
+        notify_observers(path, event)
+      end
+
+      # Begin watching given paths and enter listening loop. Called by the controller.
+      #
+      # Abstract method
+      #
+      # ===== Parameters
+      # monitored_paths<Array(Pathname)>:: list of paths the application is currently monitoring.
+      #
+      def listen(monitored_paths)
+        raise AbstractMethod
+      end
+
+      # Called by the controller when the list of paths monitored by wantchr
+      # has changed. It should refresh the list of paths being watched.
+      #
+      # Abstract method
+      #
+      # ===== Parameters
+      # monitored_paths<Array(Pathname)>:: list of paths the application is currently monitoring.
+      #
+      def refresh(monitored_paths)
+        raise AbstractMethod
+      end
+    end
+  end
+end

data/lib/watchr/event_handlers/portable.rb

@@ -0,0 +1,55 @@
+module Watchr
+  module EventHandler
+    class Portable
+      include Base
+
+      attr_accessor :monitored_paths
+      attr_accessor :reference_mtime
+
+      def initialize
+        @reference_mtime = Time.now
+      end
+
+      # Enters listening loop.
+      #
+      # Will block control flow until application is explicitly stopped/killed.
+      #
+      def listen(monitored_paths)
+        @monitored_paths = monitored_paths
+        loop { trigger; sleep(1) }
+      end
+
+      # See if an event occured, and if so notify observers.
+      def trigger #:nodoc:
+        path, type = detect_event
+        notify(path, type) unless path.nil?
+      end
+
+      # Update list of monitored paths.
+      def refresh(monitored_paths)
+        @monitored_paths = monitored_paths
+      end
+
+      private
+
+      # Verify mtimes of monitored files.
+      #
+      # If the latest mtime is more recent than the reference mtime, return
+      # that file's path.
+      #
+      # ===== Returns
+      # path and type of event if event occured, nil otherwise
+      #
+      def detect_event
+        path = @monitored_paths.max {|a,b| a.mtime <=> b.mtime }
+
+        if path.mtime > @reference_mtime
+          @reference_mtime = path.mtime
+          [path, :changed]
+        else
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/watchr/event_handlers/unix.rb

@@ -0,0 +1,62 @@
+require 'rev'
+
+module Watchr
+  module EventHandler
+    class Unix
+      include Base
+
+      # Used by Rev. Wraps a monitored path, and Rev::Loop will call its
+      # callback on file events.
+      class SingleFileWatcher < Rev::StatWatcher #:nodoc:
+        class << self
+          # Stores a reference back to handler so we can call its #nofity
+          # method with file event info
+          attr_accessor :handler
+        end
+
+        # Callback. Called on file change event
+        # Delegates to Controller#update, passing in path and event type
+        def on_change
+          self.class.handler.notify(path, :changed)
+        end
+      end
+
+      def initialize
+        SingleFileWatcher.handler = self
+        @loop = Rev::Loop.default
+      end
+
+      # Enters listening loop.
+      #
+      # Will block control flow until application is explicitly stopped/killed.
+      #
+      def listen(monitored_paths)
+        @monitored_paths = monitored_paths
+        attach
+        @loop.run
+      end
+
+      # Rebuilds file bindings.
+      #
+      # will detach all current bindings, and reattach the <tt>monitored_paths</tt>
+      #
+      def refresh(monitored_paths)
+        @monitored_paths = monitored_paths
+        detach
+        attach
+      end
+
+      private
+
+      # Binds all <tt>monitored_paths</tt> to the listening loop.
+      def attach
+        @monitored_paths.each {|path| SingleFileWatcher.new(path.to_s).attach(@loop) }
+      end
+
+      # Unbinds all paths currently attached to listening loop.
+      def detach
+        @loop.watchers.each {|watcher| watcher.detach }
+      end
+    end
+  end
+end

data/lib/watchr/script.rb

@@ -0,0 +1,192 @@
+module Watchr
+
+  # A script object wraps a script file, and is used by a controller.
+  #
+  # ===== Examples
+  #
+  #   path   = Pathname.new('specs.watchr')
+  #   script = Watchr::Script.new(path)
+  #
+  class Script
+
+    # Convenience type. Provides clearer and simpler access to rule properties.
+    #
+    # ===== Examples
+    #
+    #   rule = script.watch('lib/.*\.rb') { 'ohaie' }
+    #   rule.pattern      #=> 'lib/.*\.rb'
+    #   rule.action.call  #=> 'ohaie'
+    #
+    Rule = Struct.new(:pattern, :action)
+
+    # TODO eval context
+    class API #:nodoc:
+    end
+
+    # Creates a script object for <tt>file</tt>.
+    #
+    # Will also immediatly parse the script so it is ready to be passed to a
+    # controller.
+    #
+    # ===== Parameters
+    # file<Pathname>:: the path to the script
+    #
+    # ===== TODO
+    # * only accept Pathname/String
+    #
+    #--
+    # see issue with #parse!
+    # (update class example when fixed)
+    #
+    def initialize(file = StringIO.new)
+      @file  = file
+      @rules = []
+      @default_action = lambda {}
+      parse!
+    end
+
+    # Main script API method. Builds a new rule, binding a pattern to an action.
+    #
+    # Whenever a file is saved that matches a rule's <tt>pattern</tt>, its
+    # corresponding <tt>action</tt> is triggered.
+    #
+    # Patterns can be either a Regexp or a string. Because they always
+    # represent paths however, it's simpler to use strings. But remember to use
+    # single quotes (not double quotes), otherwise escape sequences will be
+    # parsed (for example "foo/bar\.rb" #=> "foo/bar.rb", notice "\." becomes
+    # "."), and won't be interpreted as the regexp you expect.
+    #
+    # Also note that patterns will be matched against relative paths (relative
+    # from current working directory).
+    #
+    # Actions, the blocks passed to <tt>watch</tt>, receive a MatchData object
+    # as argument. It will be populated with the whole matched string (md[0])
+    # as well as individual backreferences (md[1..n]). See MatchData#[]
+    # documentation for more details.
+    #
+    # ===== Examples
+    #
+    #   # in script file
+    #   watch( 'test/test_.*\.rb' )  {|md| system("ruby #{md[0]}") }
+    #   watch( 'lib/(.*)\.rb' )      {|md| system("ruby test/test_#{md[1]}.rb") }
+    #
+    # With these two rules, watchr will run any test file whenever it is itself
+    # changed (first rule), and will also run a corresponding test file
+    # whenever a lib file is changed (second rule).
+    #
+    # ===== Parameters
+    # pattern<~#match>:: pattern to match targetted paths
+    # action<Block>:: action to trigger
+    #
+    # ===== Returns
+    # rule<Rule>:: rule created by the method
+    #
+    def watch(pattern, &action)
+      @rules << Rule.new(pattern, action || @default_action)
+      @rules.last
+    end
+
+    # Convenience method. Define a default action to be triggered when a rule
+    # has none specified.
+    #
+    # ===== Examples
+    #
+    #   # in script file
+    #
+    #   default_action { system('rake --silent rdoc') }
+    #
+    #   watch( 'lib/.*\.rb'  )
+    #   watch( 'README.rdoc' )
+    #   watch( 'TODO.txt'    )
+    #   watch( 'LICENSE'     )
+    #
+    #   # equivalent to:
+    #
+    #   watch( 'lib/.*\.rb'  ) { system('rake --silent rdoc') }
+    #   watch( 'README.rdoc' ) { system('rake --silent rdoc') }
+    #   watch( 'TODO.txt'    ) { system('rake --silent rdoc') }
+    #   watch( 'LICENSE'     ) { system('rake --silent rdoc') }
+    #
+    def default_action(&action)
+      @default_action = action
+    end
+
+    # Eval content of script file.
+    #--
+    # TODO @file.read will only work with Pathname objects!
+    # TODO fix script file not found error
+    def parse!
+      Watchr.debug('loading script file %s' % @file.to_s.inspect)
+
+      @rules.clear
+      instance_eval(@file.read)
+
+    rescue Errno::ENOENT
+      # TODO figure out why this is happening. still can't reproduce
+      Watchr.debug('script file "not found". wth')
+      sleep(0.3) #enough?
+      instance_eval(@file.read)
+    end
+
+    # Find an action corresponding to a path. The returned action is actually a
+    # wrapper around the rule's action, with the match_data prepopulated.
+    #
+    # ===== Examples
+    #
+    #   script.watch( 'test/test_.*\.rb' ) {|md| "ruby #{md[0]}" }
+    #   script.action_for('test/test_watchr.rb').call #=> "ruby test/test_watchr.rb"
+    #
+    def action_for(path)
+      path = rel_path(path).to_s
+      rule = rule_for(path)
+      data = path.match(rule.pattern)
+      lambda { rule.action.call(data) }
+    end
+
+    # Collection of all patterns defined in script.
+    #
+    # ===== Returns
+    # patterns<String, Regexp>:: all patterns
+    #
+    def patterns
+      #@rules.every.pattern
+      @rules.map {|r| r.pattern }
+    end
+
+    # Path to the script file
+    #
+    # ===== Returns
+    # path<Pathname>:: path to script file
+    #
+    def path
+      Pathname(@file.respond_to?(:to_path) ? @file.to_path : @file.to_s).expand_path
+    end
+
+    private
+
+    # Rule corresponding to a given path. If more than one rule matches, then
+    # the last defined rule takes precedence.
+    #
+    # ===== Parameters
+    # path<Pathname, String>:: path to look up rule for
+    #
+    # ===== Returns
+    # rule<Rule>:: rule corresponding to <tt>path</tt>
+    #
+    def rule_for(path)
+      @rules.reverse.detect {|rule| path.match(rule.pattern) }
+    end
+
+    # Make a path relative to current working directory.
+    #
+    # ===== Parameters
+    # path<Pathname, String>:: absolute or relative path
+    #
+    # ===== Returns
+    # path<Pathname>:: relative path, from current working directory.
+    #
+    def rel_path(path)
+      Pathname(path).expand_path.relative_path_from(Pathname(Dir.pwd))
+    end
+  end
+end

data/lib/watchr/version.rb

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