observr 1.0

data/lib/observr/controller.rb

@@ -0,0 +1,87 @@
+module Observr
+
+  # The controller contains the app's core logic.
+  #
+  # @example
+  #
+  #     script = Observr::Script.new(file)
+  #     contrl = Observr::Controller.new(script, Observr.handler.new)
+  #     contrl.run
+  #
+  #     # Calling `run` will enter the listening loop, and from then on every
+  #     # file event will trigger its corresponding action defined in `script`
+  #
+  #     # The controller also automatically adds the script's file to its list of
+  #     # monitored files and will detect any changes to it, providing on the fly
+  #     # updates of defined rules.
+  #
+  class Controller
+
+    # Create a controller object around given `script`
+    #
+    # @param [Script] script
+    #   The script object
+    #
+    # @param [EventHandler::Base] handler
+    #   The filesystem event handler
+    #
+    # @see Observr::Script
+    # @see Observr.handler
+    #
+    def initialize(script, handler)
+      @script, @handler = script, handler
+      @handler.add_observer(self)
+
+      Observr.debug "using %s handler" % handler.class.name
+    end
+
+    # Enter listening loop. Will block control flow until application is
+    # explicitly stopped/killed.
+    def run
+      @script.parse!
+      @handler.listen(monitored_paths)
+    rescue Interrupt
+    end
+
+    # Callback for file events
+    #
+    # Called while control flow is 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.
+    #
+    # @param [Pathname, String] path
+    #   path that triggered the event
+    #
+    # @param [Symbol] event
+    #   event type
+    #
+    def update(path, event_type = nil)
+      path = Pathname(path).expand_path
+
+      Observr.debug("received #{event_type.inspect} event for #{path.relative_path_from(Pathname(Dir.pwd))}")
+      if path == @script.path && event_type != :accessed
+        @script.parse!
+        @handler.refresh(monitored_paths)
+      else
+        @script.action_for(path, event_type).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.
+    #
+    # @return [Array<Pathname>]
+    #   list of all 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/observr/event_handlers/base.rb

@@ -0,0 +1,57 @@
+require 'observer'
+
+module Observr
+  module EventHandler
+
+    # @private
+    class AbstractMethod < Exception; end
+
+    # Base functionality mixin, meant to be included in specific event handlers.
+    #
+    # @abstract
+    module Base
+      include Observable
+
+      # Notify that a file was modified.
+      #
+      # @param [Pathname, String] path
+      #   full path or path relative to current working directory
+      #
+      # @param [Symbol] event
+      #   event type.
+      #
+      # @return [undefined]
+      #
+      def notify(path, event_type = nil)
+        changed(true)
+        notify_observers(path, event_type)
+      end
+
+      # Begin watching given paths and enter listening loop. Called by the
+      # controller.
+      #
+      # @param [Array<Pathname>] monitored_paths
+      #   list of paths the application is currently monitoring.
+      #
+      # @return [undefined]
+      #
+      # @abstract
+      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.
+      #
+      # @param [Array<Pathname>] monitored_paths
+      #   list of paths the application is currently monitoring.
+      #
+      # @return [undefined]
+      #
+      # @abstract
+      def refresh(monitored_paths)
+        raise AbstractMethod
+      end
+    end
+  end
+end

data/lib/observr/event_handlers/darwin.rb

@@ -0,0 +1,160 @@
+module Observr
+  module EventHandler
+
+    class ::FSEvents
+      # Same as Watch.debug, but prefixed with [fsevents] instead.
+      #
+      # @example
+      #
+      #     FSEvents.debug('missfired')
+      #
+      # @param [String] message
+      #   debug message to print
+      #
+      # @return [nil]
+      #
+      def self.debug(msg)
+        puts "[fsevents] #{msg}" if Observr.options.debug
+      end
+    end
+
+    # FSEvents based event handler for Darwin/OSX
+    #
+    # Uses ruby-fsevents (http://github.com/sandro/ruby-fsevent)
+    #
+    class Darwin < FSEvent
+      include Base
+
+      def initialize
+        super
+        self.latency = 0.2
+      end
+
+      # Enter listening loop. Will block control flow until application is
+      # explicitly stopped/killed.
+      #
+      # @return [undefined]
+      #
+      def listen(monitored_paths)
+        register_paths(monitored_paths)
+        start
+      end
+
+      # Rebuild file bindings. Will detach all current bindings, and reattach
+      # the `monitored_paths`
+      #
+      # @param [Array<Pathname>] monitored_paths
+      #   list of paths the application is currently monitoring.
+      #
+      # @return [undefined]
+      #
+      def refresh(monitored_paths)
+        register_paths(monitored_paths)
+        restart
+      end
+
+      private
+
+        # Callback. Called on file change event. Delegates to
+        # {Controller#update}, passing in path and event type
+        #
+        # @return [undefined]
+        #
+        def on_change(dirs)
+          dirs.each do |dir|
+            path, type = detect_change(dir)
+            notify(path, type) unless path.nil?
+          end
+        end
+
+        # Detected latest updated file within given directory
+        #
+        # @param [Pathname, String] dir
+        #   directory reporting event
+        #
+        # @return [Array(Pathname, Symbol)] path and type
+        #   path to updated file and event type
+        #
+        def detect_change(dir)
+          paths = monitored_paths_for(dir)
+          type  = nil
+          path  = paths.find {|path| type = event_type(path) }
+
+          FSEvents.debug("event detection error") if type.nil?
+
+          update_reference_times
+          [path, type]
+        end
+
+        # Detect type of event for path, if any
+        #
+        # Path times (atime, mtime, ctime) are compared to stored references.
+        # If any is more recent, the event is reported as a symbol.
+        #
+        # @param [Pathname] path
+        #
+        # @return [Symbol, nil] event type
+        #   Event type if detected, nil otherwise.
+        #   Symbol is on of :deleted, :modified, :accessed, :changed
+        #
+        def event_type(path)
+          return :deleted   if !path.exist?
+          return :modified  if  path.mtime > @reference_times[path][:mtime]
+          return :accessed  if  path.atime > @reference_times[path][:atime]
+          return :changed   if  path.ctime > @reference_times[path][:ctime]
+          nil
+        end
+
+        # Monitored paths within given dir
+        #
+        # @param [Pathname, String] dir
+        #
+        # @return [Array<Pathname>] monitored_paths
+        #
+        def monitored_paths_for(dir)
+          dir = Pathname(dir).expand_path
+          @paths.select {|path| path.dirname.expand_path == dir }
+        end
+
+        # Register watches for paths
+        #
+        # @param [Array<Pathname>] paths
+        #
+        # @return [undefined]
+        #
+        def register_paths(paths)
+          @paths = paths
+          watch_directories(dirs_for(@paths))
+          update_reference_times
+        end
+
+        # Directories for paths
+        #
+        # A unique list of directories containing given paths
+        #
+        # @param [Array<Pathname>] paths
+        #
+        # @return [Array<Pathname>] dirs
+        #
+        def dirs_for(paths)
+          paths.map {|path| path.dirname.to_s }.uniq
+        end
+
+        # Update reference times for registered paths
+        #
+        # @return [undefined]
+        #
+        def update_reference_times
+          @reference_times = {}
+          now = Time.now
+          @paths.each do |path|
+            @reference_times[path] = {}
+            @reference_times[path][:atime] = now
+            @reference_times[path][:mtime] = now
+            @reference_times[path][:ctime] = now
+          end
+        end
+    end
+  end
+end
+

data/lib/observr/event_handlers/portable.rb

@@ -0,0 +1,75 @@
+module Observr
+  module EventHandler
+    class Portable
+      include Base
+
+      def initialize
+        @reference_mtime = @reference_atime = @reference_ctime = Time.now
+      end
+
+      # Enters listening loop.
+      #
+      # Will block control flow until application is explicitly stopped/killed.
+      #
+      # @param [Array<Pathname>] monitored_paths
+      #   list of paths the application is currently monitoring.
+      #
+      # @return [undefined]
+      #
+      def listen(monitored_paths)
+        @monitored_paths = monitored_paths
+        loop { trigger; sleep(1) }
+      end
+
+      # See if an event occured, and if so notify observers.
+      #
+      # @return [undefined]
+      #
+      # @private
+      def trigger
+        path, type = detect_event
+        notify(path, type) unless path.nil?
+      end
+
+      # Update list of monitored paths.
+      #
+      # @param [Array<Pathname>] monitored_paths
+      #   list of paths the application is currently monitoring.
+      #
+      # @return [undefined]
+      #
+      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.
+      #
+      # @return [[Pathname, Symbol]]
+      #   path and type of event if event occured, nil otherwise
+      #
+      # @todo improve ENOENT error handling
+      #
+      def detect_event # OPTIMIZE, REFACTOR
+        @monitored_paths.each do |path|
+          return [path, :deleted] unless path.exist?
+        end
+
+        mtime_path = @monitored_paths.max {|a,b| a.mtime <=> b.mtime }
+        atime_path = @monitored_paths.max {|a,b| a.atime <=> b.atime }
+        ctime_path = @monitored_paths.max {|a,b| a.ctime <=> b.ctime }
+
+        if    mtime_path.mtime > @reference_mtime then @reference_mtime = mtime_path.mtime; [mtime_path, :modified]
+        elsif atime_path.atime > @reference_atime then @reference_atime = atime_path.atime; [atime_path, :accessed]
+        elsif ctime_path.ctime > @reference_ctime then @reference_ctime = ctime_path.ctime; [ctime_path, :changed ]
+        else; nil; end
+      rescue Errno::ENOENT
+        retry
+      end
+    end
+  end
+end

data/lib/observr/event_handlers/unix.rb

@@ -0,0 +1,125 @@
+module Observr
+  module EventHandler
+    class Unix
+      include Base
+
+      # Used by Rev. Wraps a monitored path, and `Rev::Loop` will call its
+      # callback on file events.
+      #
+      # @private
+      class SingleFileWatcher < Rev::StatWatcher
+        class << self
+          # Stores a reference back to handler so we can call its {Base#notify notify}
+          # method with file event info
+          #
+          # @return [EventHandler::Base]
+          #
+          attr_accessor :handler
+        end
+
+        # @param [String] path
+        #   single file to monitor
+        #
+        def initialize(path)
+          super
+          update_reference_times
+        end
+
+        # File's path as a Pathname
+        #
+        # @return [Pathname]
+        #
+        def pathname
+          @pathname ||= Pathname(@path)
+        end
+
+        # Callback. Called on file change event. Delegates to
+        # {Controller#update}, passing in path and event type
+        #
+        # @return [undefined]
+        #
+        def on_change
+          self.class.handler.notify(path, type)
+          update_reference_times unless type == :deleted
+        end
+
+        private
+
+        # @todo improve ENOENT error handling
+        def update_reference_times
+          @reference_atime = pathname.atime
+          @reference_mtime = pathname.mtime
+          @reference_ctime = pathname.ctime
+        rescue Errno::ENOENT
+          retry
+        end
+
+        # Type of latest event.
+        #
+        # A single type is determined, even though more than one stat times may
+        # have changed on the file. The type is the first to match in the
+        # following hierarchy:
+        #
+        #     :deleted, :modified (mtime), :accessed (atime), :changed (ctime)
+        #
+        # @return [Symbol] type
+        #   latest event's type
+        #
+        def type
+          return :deleted   if !pathname.exist?
+          return :modified  if  pathname.mtime > @reference_mtime
+          return :accessed  if  pathname.atime > @reference_atime
+          return :changed   if  pathname.ctime > @reference_ctime
+        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.
+      #
+      # @return [undefined]
+      #
+      def listen(monitored_paths)
+        @monitored_paths = monitored_paths
+        attach
+        @loop.run
+      end
+
+      # Rebuilds file bindings. Will detach all current bindings, and reattach
+      # the `monitored_paths`
+      #
+      # @param [Array<Pathname>] monitored_paths
+      #   list of paths the application is currently monitoring.
+      #
+      # @return [undefined]
+      #
+      def refresh(monitored_paths)
+        @monitored_paths = monitored_paths
+        detach
+        attach
+      end
+
+      private
+
+      # Binds all `monitored_paths` to the listening loop.
+      #
+      # @return [undefined]
+      #
+      def attach
+        @monitored_paths.each {|path| SingleFileWatcher.new(path.to_s).attach(@loop) }
+      end
+
+      # Unbinds all paths currently attached to listening loop.
+      #
+      # @return [undefined]
+      #
+      def detach
+        @loop.watchers.each {|watcher| watcher.detach }
+      end
+    end
+  end
+end