eventmachine-tail 0.2.20100516235116 → 0.2.20100517011408

data/lib/em/filetail.rb

@@ -1,6 +1,5 @@
 #!/usr/bin/env ruby
 
-require "rubygems" if __FILE__ == $0
 require "eventmachine"
 require "logger"
 
@@ -9,7 +8,7 @@ EventMachine.epoll if EventMachine.epoll?
 # Tail a file.
 #
 # Example
-#   class Tailer < EventMachine::Tail
+#   class Tailer < EventMachine::FileTail
 #     def receive_data(data)
 #       puts "Got #{data.length} bytes"
 #     end
@@ -24,18 +23,26 @@ EventMachine.epoll if EventMachine.epoll?
 #   EM.run do
 #     Tailer.new("/var/log/messages")
 #   end
+#
+# See also: EventMachine::FileTail#receive_data
 class EventMachine::FileTail
+  # Maximum size to read at a time from a single file.
   CHUNKSIZE = 65536 
-  MAXSLEEP = 2
 
+  # 
+  #MAXSLEEP = 2
+
+  # The path of the file being tailed
   attr_reader :path
   
   # Tail a file
   #
-  # path is a string file path
-  # startpos is an offset to start tailing the file at. If -1, start at end of 
+  # * path is a string file path to tail
+  # * startpos is an offset to start tailing the file at. If -1, start at end of 
   # file.
   #
+  # See also: EventMachine::file_tail
+  #
   public
   def initialize(path, startpos=-1)
     @path = path
@@ -51,7 +58,7 @@ class EventMachine::FileTail
     end
 
     open
-    watch
+    watch { |what| notify(what) }
     if (startpos == -1)
       @file.sysseek(0, IO::SEEK_END)
     else
@@ -60,11 +67,33 @@ class EventMachine::FileTail
     end
   end # def initialize
 
-  # notify is invoked by EventMachine when the file you are tailing
-  # has been modified or otherwise needs to be acted on.
+  # This method is called when a tailed file has data read. 
+  #
+  # * data - string data read from the file.
+  #
+  # If you want to read lines from your file, you should use BufferedTokenizer
+  # (which comes with EventMachine):
+  #   class Tailer < EventMachine::FileTail
+  #     def initialize(*args)
+  #       super(*args)
+  #       @buffer = BufferedTokenizer.new
+  #     end
   #
-  # You won't normally call this method.
+  #     def receive_data(data)
+  #       @buffer.extract(data).each do |line|
+  #         # do something with 'line'
+  #       end
+  #     end  
   public
+  def receive_data(data)
+    raise NotImplementedError.new("#{self.class.name}#receive_data is not "\
+      "implemented. Did you forget to implement this in your subclass or "\
+      "module?")
+  end # def receive_data
+
+  # notify is invoked when the file you are tailing has been modified or
+  # otherwise needs to be acted on.
+  private
   def notify(status)
     @logger.debug("#{status} on #{path}")
     if status == :modified
@@ -75,11 +104,7 @@ class EventMachine::FileTail
     end
   end
 
-  public
-  def receive_data(data)
-    @logger.warn("Got #{data.length} bytes")
-  end
-
+  # Open (or reopen, if necessary) our file and schedule a read.
   private
   def open
     @file.close if @file
@@ -95,11 +120,13 @@ class EventMachine::FileTail
     schedule_next_read
   end
 
+  # Watch our file.
   private
-  def watch
-    EventMachine::watch_file(@path, EventMachine::FileTail::FileWatcher, self)
+  def watch(&block)
+    EventMachine::watch_file(@path, EventMachine::FileTail::FileWatcher, block)
   end
 
+  # Schedule a read.
   private
   def schedule_next_read
     EventMachine::add_timer(@naptime) do
@@ -107,6 +134,7 @@ class EventMachine::FileTail
     end
   end
 
+  # Read CHUNKSIZE from our file and pass it to .receive_data()
   private
   def read
     begin
@@ -132,11 +160,12 @@ class EventMachine::FileTail
       #@logger.info("EOF. Naptime: #{@naptime}")
     #end
 
-    # TODO(sissel): schedule an fstat instead of doing it now.
+    # TODO(sissel): should we schedule an fstat instead of doing it now?
     fstat = File.stat(@path)
     handle_fstat(fstat)
   end # def eof
 
+  # Handle fstat changes appropriately.
   private
   def handle_fstat(fstat)
     if (fstat.ino != @fstat.ino)
@@ -144,6 +173,7 @@ class EventMachine::FileTail
     elsif (fstat.rdev != @fstat.rdev)
       open # Reopen if the filesystem device changed
     elsif (fstat.size < @fstat.size)
+      # Schedule a read if the file size has changed
       @logger.info("File likely truncated... #{path}")
       @file.sysseek(0, IO::SEEK_SET)
       schedule_next_read
@@ -152,30 +182,32 @@ class EventMachine::FileTail
   end # def eof
 end # class EventMachine::FileTail
 
-# Internal usage only
+# Internal usage only. This class is used by EventMachine::FileTail
+# to watch files you are tailing.
+#
+# See also: EventMachine::FileTail#watch
 class EventMachine::FileTail::FileWatcher < EventMachine::FileWatch
-  def initialize(filewatch)
-    @filewatch = filewatch
+  def initialize(block)
     @logger = Logger.new(STDOUT)
     @logger.level = ($DEBUG and Logger::DEBUG or Logger::WARN)
-    @logger.debug("Watching on #{filewatch.path}")
-  end
+    @callback = block
+  end # def initialize
 
   def file_modified
-    @filewatch.notify :modified
-  end
+    @callback.call(:modified)
+  end # def file_modified
 
   def file_moved
-    @filewatch.notify :moved
-  end
+    @callback.call(:moved)
+  end # def file_moved
 
   def file_deleted
-    @filewatch.notify :deleted
-  end
+    @callback.call(:deleted)
+  end # def file_deleted
 
   def unbind
-    @filewatch.notify :unbind
-  end
+    @callback.call(:unbind)
+  end # def unbind
 end # class EventMachine::FileTail::FileWatch < EventMachine::FileWatch
 
 # Add EventMachine::file_tail

data/lib/em/globwatcher.rb

@@ -1,9 +1,11 @@
 #!/usr/bin/env ruby
 
-require "set"
+require "em/filetail"
 require "eventmachine"
 require "logger"
-require "em/filetail"
+require "set"
+
+EventMachine.epoll if EventMachine.epoll?
 
 # A file glob pattern watcher for EventMachine.
 #
@@ -16,10 +18,22 @@ require "em/filetail"
 # This class will allow you to get notified whenever a file
 # is created or deleted that matches your glob.
 #
+# If you are subclassing, here are the methods you should implement:
+#    file_found(path)
+#    file_deleted(path)
+#
+# See alsoe
+# * EventMachine::watch_glob
+# * EventMachine::FileGlobWatch#file_found
+# * EventMachine::FileGlobWatch#file_deleted
 #
 class EventMachine::FileGlobWatch
-  def initialize(pathglob, interval=60)
-    @pathglob = pathglob
+  # Watch a glob
+  #
+  # * glob - a string path or glob, such as "/var/log/*.log"
+  # * interval - number of seconds between scanning the glob for changes
+  def initialize(glob, interval=60)
+    @glob = glob
     @files = Set.new
     @watches = Hash.new
     @logger = Logger.new(STDOUT)
@@ -36,13 +50,39 @@ class EventMachine::FileGlobWatch
       EM.add_periodic_timer(interval) do
         find_files
       end
-    end
+    end # EM.next_tick
   end # def initialize
 
+  # This method is called when a new file is found
+  #
+  # * path - the string path of the file found
+  #
+  # You must implement this in your subclass or module for it
+  # to work with EventMachine::watch_glob
+  public
+  def file_found(path)
+    raise NotImplementedError.new("#{self.class.name}#file_found is not "\
+      "implemented. Did you forget to implement this in your subclass or "\
+      "module?")
+  end # def file_found
+
+  # This method is called when a file is deleted.
+  #
+  # * path - the string path of the file deleted
+  #
+  # You must implement this in your subclass or module for it
+  # to work with EventMachine::watch_glob
+  public
+  def file_deleted(path)
+    raise NotImplementedError.new("#{self.class.name}#file_found is not "\
+      "implemented. Did you forget to implement this in your subclass or "\
+      "module?")
+  end # def file_found
+
   private
   def find_files
-    @logger.info("Searching for files in #{@pathglob}")
-    list = Set.new(Dir.glob(@pathglob))
+    @logger.info("Searching for files in #{@glob}")
+    list = Set.new(Dir.glob(@glob))
     list.each do |path|
       next if @files.include?(path)
       add(path)
@@ -53,56 +93,82 @@ class EventMachine::FileGlobWatch
     end
   end # def find_files
 
-  public
+  # Remove a file from being watched and notify file_deleted()
+  private
   def remove(path)
     @files.delete(path)
     @watches.delete(path)
-    file_removed(path)
-  end
+    file_deleted(path)
+  end # def remove
 
+  # Add a file to watch and notify file_found()
   private
   def add(path)
     @files.add(path)
 
     # If EventMachine::watch_file fails, that's ok, I guess.
     # We'll still find the file 'missing' from the next glob attempt.
-    begin
+    #begin
       # EM currently has a bug that only the first handler for a watch_file
       # on each file gets events. This causes globtails to never get data 
       # since the glob is watching the file already.
       # Until we fix that, let's skip file watching here.
-      #@watches[path] = EventMachine::watch_file(path, GlobFileWatch, self)
-    rescue Errno::EACCES => e
-      @logger.warn(e)
-    end
+      #@watches[path] = EventMachine::watch_file(path, FileWatcher, self) do |path|
+      #  remove(path)
+      #end
+    #rescue Errno::EACCES => e
+      #@logger.warn(e)
+    #end
     file_found(path)
   end # def watch
 
   private
-  class GlobFileWatch < EventMachine::FileWatch
-    def initialize(globwatch)
+  class FileWatcher < EventMachine::FileWatch
+    def initialize(globwatch, &block)
       @globwatch = globwatch
+      @block = block
     end
 
     def file_moved
       stop_watching
-      @globwatch.remove(path)
+      block.call path
     end
 
     def file_deleted
-      @globwatch.remove(path)
+      block.call path
     end
-  end # class GlobFileWatch < EventMachine::FileWatch
+  end # class EventMachine::FileGlobWatch::FileWatcher < EventMachine::FileWatch
 end # class EventMachine::FileGlobWatch
 
+# A glob tailer for EventMachine
+#
+# This class combines features of EventMachine::file_tail and 
+# EventMachine::watch_glob.
+#
+# You won't generally subclass this class (See EventMachine::FileGlobWatch)
+#
+# See also: EventMachine::glob_tail
+#
 class EventMachine::FileGlobWatchTail < EventMachine::FileGlobWatch
+  # Initialize a new file glob tail.
+  #
+  # path should be a glob or file path.
+  # handler should be a module or subclass of EventMachine::FileTail
+  #   See also EventMachine::file_tail
+  # interval is how often (seconds) the glob path should be scanned
+  # exclude is an array of Regexp (or anything with .match) for 
+  #   excluding from things to tail
+  # The remainder of arguments are passed to EventMachine::file_tail as
+  #   EventMachine::file_tail(path_found, handler, *args)
+  public
   def initialize(path, handler=nil, interval=60, exclude=[], *args)
     super(path, interval)
     @handler = handler
     @args = args
     @exclude = exclude
-  end
+  end # def initialize
 
+  public
   def file_found(path)
     begin
       @logger.info "#{self.class}: Trying #{path}"
@@ -120,25 +186,32 @@ class EventMachine::FileGlobWatchTail < EventMachine::FileGlobWatch
       file_error(path, e)
     rescue Errno::EISDIR => e
       file_error(path, e)
-    end
-  end
+    end 
+  end # def file_found
 
+  public
   def file_excluded(path)
     @logger.info "#{self.class}: Skipping path #{path} due to exclude rule"
-  end
+  end # def file_excluded
 
-  def file_removed(path)
+  public
+  def file_deleted(path)
     # Nothing to do
-  end
+  end # def file_deleted
 
+  public
   def file_error(path, e)
     $stderr.puts "#{e.class} while trying to tail #{path}"
     # otherwise, drop the error by default
-  end
+  end # def file_error
 end # class EventMachine::FileGlobWatchHandler
 
-# Add EventMachine::glob_tail
 module EventMachine
+  # Watch a glob and tail any files found.
+  #
+  # 'glob' should be a string path or glob, such as /var/log/*.log
+  # handler must be a module or subclass of EventMachine::FileGlobWatchTail
+  #   See EventMachine::FileGlobWatchTail for the callback methods.
   def self.glob_tail(glob, handler=nil, *args)
     handler = EventMachine::FileGlobWatch if handler == nil
     args.unshift(glob)
@@ -146,12 +219,25 @@ module EventMachine
     c = klass.new(*args)
     yield c if block_given?
     return c
-  end
-
-  def self.watch_glob(path, handler=nil, *args)
+  end 
+
+  # Watch a glob for any files.
+  #
+  # * glob - a string path or glob, such as "/var/log/*.log"
+  # * handler - must be a module or a subclass of EventMachine::FileGlobWatch
+  # 
+  # The remaining (optional) arguments are passed to your handler like this:
+  #   If you call this:
+  #     EventMachine.watch_glob("/var/log/*.log", YourHandler, 1, 2, 3, ...)
+  #   This will be invoked when new matching files are found:
+  #     YourHandler.new(path_found, 1, 2, 3, ...)
+  #     ^ path_found is the new path found by the glob
+  #
+  # See EventMachine::FileGlobWatch for the callback methods.
+  def self.watch_glob(glob, handler=nil, *args)
     # This code mostly styled on what EventMachine does in many of it's other
     # methods.
-    args = [path, *args]
+    args = [glob, *args]
     klass = klass_from_handler(EventMachine::FileGlobWatch, handler, *args);
     c = klass.new(*args)
     yield c if block_given?

data/samples/globwatch.rb

@@ -9,7 +9,7 @@ class Watcher < EventMachine::FileGlobWatch
     super(pathglob, interval)
   end
 
-  def file_removed(path)
+  def file_deleted(path)
     puts "Removed: #{path}"
   end
 

data/test/alltests.rb

@@ -0,0 +1,2 @@
+require 'test_filetail'
+require 'test_glob'

data/test/test_glob.rb

@@ -25,7 +25,7 @@ class Watcher < EventMachine::FileGlobWatch
     @testobj.finish if @data.length == 0
   end
 
-  def file_removed(path)
+  def file_deleted(path)
     @testobj.assert(@data.include?(path), "Expected #{path} in \n#{@data.join("\n")}")
     @data.delete(path)
     @testobj.finish if @data.length == 0

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 2
-  - 20100516235116
-  version: 0.2.20100516235116
+  - 20100517011408
+  version: 0.2.20100517011408
 platform: ruby
 authors: 
 - Jordan Sissel
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-16 00:00:00 -07:00
+date: 2010-05-17 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -46,6 +46,7 @@ files:
 - samples/globwatch.rb
 - test/test_filetail.rb
 - test/test_glob.rb
+- test/alltests.rb
 - test/testcase_helpers.rb
 - bin/rtail
 has_rdoc: true