apache_log_tail 0.0.1 → 0.0.2

data/lib/apache_log_tail.rb

@@ -1,40 +1,43 @@
 
 # Facilitates reading the most recent additions to a log file.
 #
-# Note that rotation of log files is *not* handled.
-#
 # Example:
-#   >> tail = LogTail.new "/var/log/apache2/access.log"
-#   >> tail.state_store.path_to_file = "/tmp/my-state.txt" # Optional: there is a default path
-#   >> tail.each_new_line {|line| puts line }
+#     tail = LogTail.new "/var/log/apache2/access.log"
+#     tail.state_store.path_to_file = "/tmp/my-state.txt" # Optional: there is a default path
+#     tail.each_new_line {|line| puts line }
+#
+# ## A custom StateStore
+#
+#     tail.state_store = MyStateStore.new
+#
+# A StateStore object must provide these methods:
 #
+#  - remember( state:Hash)
+#  - recall(): Hash
 #
 class LogTail
 
+  # @param [String] path_to_file  the path to the file to process
+  #
   def initialize path_to_file
     @path_to_file = path_to_file
   end
 
-
-  # Provides a StateStore object that provides persistent storage of a Hash.
+  # The StateStore provides persistent storage of a Hash.
   #
   def state_store
     @state_store ||= FileStateStore.new
   end
+  attr_writer :state_store
 
-  # Accepts a StateStore object that provides persistent storage of a Hash.
-  #
-  # Example:
-  #   >> tail.state_store = MyStateStore.new
+  # Goes through each line in the file that has not yet been processed and
+  # passes it to the block given.
   #
-  # A StateStore object must provide these methods:
+  # @param [String] path_to_file  the path to the file that should be
+  #                               processed.  This parameter is only intended
+  #                               for internal use ( processing rotated log
+  #                               files) and should be omitted for normal use
   #
-  #  - remember( state:Hash)
-  #  - recall(): Hash
-  #
-  attr_writer :state_store
-
-
   def each_new_line path_to_file = @path_to_file
 
     # Recall the cursor ( the location in the log file where we left off
@@ -55,13 +58,15 @@ class LogTail
     end
   end
 
-
   # This is the default implementation of StateStore, which stores the state in
   # a file ( by default in /tmp with a static name although this is
   # configurable).
   #
   class FileStateStore
 
+    # Provides the path to the file that is used to store the state ( unless a
+    # custom StateStore is used).
+    #
     def path_to_file
       @path_to_file ||= "/tmp/.apache_log_tail-state.yml"
     end
@@ -69,6 +74,9 @@ class LogTail
 
     require "yaml"
 
+    # Retrieves the state from the store.
+    # @return [Hash]
+    #
     def recall
       if not File.exists? path_to_file
         {}
@@ -77,6 +85,9 @@ class LogTail
       end
     end
 
+    # Stores the supplied state.
+    # @param [Hash] state
+    #
     def remember state
       File.open  path_to_file, "w" do |file|
         file.write  state.to_yaml
@@ -88,12 +99,21 @@ class LogTail
 end
 
 
+# (see LogTail)
+#
+# Will not miss any lines when the log file is rotated between two invocations
+# of #each_new_line ( as long as the rotated file has the same name as the
+# original except for a `.1` suffix and as long as the file hasn't been rotated
+# twice between invocations of #each_new_line).
+#
 # Note that this class does no parse Apache log entries, only knows how Apache
-# log files are rotated on Debian.  I have enjoyed using the apachelogregex gem
-# for parsing.
+# log files are rotated on Debian.  I have enjoyed using the `apachelogregex`
+# gem for parsing.
 #
 class ApacheLogTail < LogTail
 
+  # (see LogTail#each_new_line)
+  #
   # Note: This method must be invoked more frequently than the log file
   # rotation period ( typically 1 week) otherwise an entire file will be
   # missed.

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: apache_log_tail
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 27
   prerelease: 
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Neil Stockbridge
@@ -29,8 +29,8 @@ extra_rdoc_files: []
 files: 
 - lib/apache_log_tail.rb
 homepage: http://rubygems.org/gems/apache_log_tail
-licenses: []
-
+licenses: 
+- MIT
 post_install_message: 
 rdoc_options: []
 
@@ -63,3 +63,4 @@ specification_version: 3
 summary: Process only the new lines from an Apache log file
 test_files: []
 
+has_rdoc: