sawmill 0.0.2 → 0.0.3

data/History.rdoc

@@ -1,3 +1,20 @@
+=== 0.0.3 / 2009-10-31
+
+* API CHANGE: Renamed processor close methods to "finish" and introduced return value semantics for passing "final" information back up the processor tree.
+* API CHANGE: Renamed :dirname options to :basedir on both rotater strategies
+* API CHANGE: Renamed :filename option to :filepath on ShiftingLogFile
+* API CHANGE: Renamed :local_timezone option to :local_datestamps on DateBasedLogFile
+* API CHANGE: Renamed FilterBasicFields to FilterByBasicFields
+* Added FilterByBlock processors
+* Added CompileReport processors
+* Processors can now add custom methods to the processor building DSL.
+* Added a bunch of convenience methods to the toplevel Sawmill module.
+* Entries can be truncated at a particular length when formatting.
+* Records can compute and cache values.
+* Support length limits when formatting entries.
+* Fixed a few more bugs related to processors.
+* More work on the RDocs
+
 === 0.0.2 / 2009-10-28
 
 * Added multi-parser utility.

data/lib/sawmill/entry.rb

@@ -103,12 +103,16 @@ module Sawmill
       
       # The log level as a Sawmill::Level object
       attr_reader :level
+      
       # The timestamp as a Time object
       attr_reader :timestamp
+      
       # The progname as a string
       attr_reader :progname
+      
       # The record ID as a string
       attr_reader :record_id
+      
       # The message as a string
       attr_reader :message
       
@@ -157,10 +161,13 @@ module Sawmill
       
       # The log level as a Sawmill::Level object
       attr_reader :level
+      
       # The timestamp as a Time object
       attr_reader :timestamp
+      
       # The progname as a string
       attr_reader :progname
+      
       # The record ID as a string
       attr_reader :record_id
       
@@ -207,10 +214,13 @@ module Sawmill
       
       # The log level as a Sawmill::Level object
       attr_reader :level
+      
       # The timestamp as a Time object
       attr_reader :timestamp
+      
       # The progname as a string
       attr_reader :progname
+      
       # The record ID as a string
       attr_reader :record_id
       
@@ -263,16 +273,22 @@ module Sawmill
       
       # The log level as a Sawmill::Level object
       attr_reader :level
+      
       # The timestamp as a Time object
       attr_reader :timestamp
+      
       # The progname as a string
       attr_reader :progname
+      
       # The record ID as a string
       attr_reader :record_id
-      # The operation, which can be :set, :append, :remove, :unset
+      
+      # The operation, which can currently be :set or :append
       attr_reader :operation
+      
       # The attribute key as a string
       attr_reader :key
+      
       # The attribute value as a string
       attr_reader :value
       

data/lib/sawmill/entry_processor/build_records.rb

@@ -49,15 +49,15 @@ module Sawmill
       # 
       # Recognized options include:
       # 
-      # <tt>:emit_incomplete_records_on_close</tt>::
-      #   When the processor is closed, any records that are still not
+      # <tt>:emit_incomplete_records_on_finish</tt>::
+      #   When the processor is finished, any records that are still not
       #   complete will be emitted to the record processor anyway, even
       #   in their incomplete state.
       
       def initialize(processor_, opts_={})
         @processor = processor_
         @records = {}
-        @emit_incomplete_records_on_close = opts_[:emit_incomplete_records_on_close]
+        @emit_incomplete_records_on_finish = opts_[:emit_incomplete_records_on_finish]
       end
       
       
@@ -135,11 +135,14 @@ module Sawmill
       end
       
       
-      def close
-        if @records && @emit_incomplete_records_on_close
-          emit_incomplete_records
+      def finish
+        if @records
+          emit_incomplete_records if @emit_incomplete_records_on_close
+          @records = nil
+          @processor.finish
+        else
+          nil
         end
-        @records = nil
       end
       
       

data/lib/sawmill/entry_processor/compile_report.rb

@@ -0,0 +1,115 @@
+# -----------------------------------------------------------------------------
+# 
+# Sawmill entry processor that generates reports
+# 
+# -----------------------------------------------------------------------------
+# Copyright 2009 Daniel Azuma
+# 
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of the copyright holder, nor the names of any other
+#   contributors to this software, may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+# -----------------------------------------------------------------------------
+;
+
+
+module Sawmill
+  
+  
+  module EntryProcessor
+    
+    
+    # This processor collects and formats reports from descendant
+    # entry processors.
+    
+    class CompileReport < All
+      
+      
+      # Create a report collection.
+      # 
+      # Recognized options include:
+      # 
+      # <tt>:postprocessor</tt>::
+      #   Postprocessor proc for individual reports.
+      #   See to_postprocess_value.
+      # <tt>:separator</tt>::
+      #   Separator string to be inserted between individual reports.
+      #   Default is a single newline.
+      # <tt>:header</tt>::
+      #   Header string for the final compiled report.
+      #   Default is the empty string.
+      # <tt>:footer</tt>::
+      #   Footer string for the final compiled report.
+      #   Default is the empty string.
+      
+      def initialize(*children_)
+        opts_ = children_.last.kind_of?(::Hash) ? children_.pop : {}
+        @postprocessor = opts_[:postprocessor]
+        @separator = opts_[:separator] || "\n"
+        @header = opts_[:header] || ''
+        @footer = opts_[:footer] || ''
+        super(*children_)
+      end
+      
+      
+      # Separator string to be inserted between individual reports.
+      attr_accessor :separator
+      
+      # Header string for the final compiled report.
+      attr_accessor :header
+      
+      # Footer string for the final compiled report.
+      attr_accessor :footer
+      
+      
+      # Provide a postprocessor block for individual report values.
+      # This block should take a single parameter and return a string
+      # that should be included in the compiled report. It may also
+      # return nil to indicate that the data should not be included.
+      
+      def to_postprocess_value(&block_)
+        @postprocessor = block_
+      end
+      
+      
+      # On finish, this processor calls finish on its descendants, converts
+      # their values into strings and compiles them into a report. It then
+      # returns that report as a string.
+      
+      def finish
+        values_ = super || []
+        values_ = [values_] unless values_.kind_of?(::Array)
+        values_.map!{ |val_| @postprocessor.call(val_) } if @postprocessor
+        values_.compact!
+        "#{@header}#{values_.join(@separator)}#{@footer}"
+      end
+      
+      
+    end
+    
+    
+  end
+  
+  
+end

data/lib/sawmill/entry_processor/conditionals.rb

@@ -48,7 +48,7 @@ module Sawmill
     # to STDOUT only if their level is at least INFO:
     # 
     #  processor = Sawmill::EntryProcessor.build do
-    #    If(FilterBasicFields(:level => :INFO), Format(STDOUT))
+    #    If(FilterByBasicFields(:level => :INFO), Format(STDOUT))
     #  end
     
     class If < Base
@@ -108,9 +108,8 @@ module Sawmill
         end
       end
       
-      def close
-        @on_true.close
-        @on_false.close if @on_false
+      def finish
+        Util::ProcessorTools.collect_finish_values([@on_true, @on_false])
       end
     
       
@@ -124,7 +123,7 @@ module Sawmill
     # to STDOUT only if their level is NOT at least INFO:
     # 
     #  processor = Sawmill::EntryProcessor.build do
-    #    If(Not(FilterBasicFields(:level => :INFO)), Format(STDOUT))
+    #    If(Not(FilterByBasicFields(:level => :INFO)), Format(STDOUT))
     #  end
     
     class Not < Base
@@ -158,8 +157,8 @@ module Sawmill
         !@child.unknown_data(entry_)
       end
       
-      def close
-        @child.close
+      def finish
+        @child.finish
       end
     
       
@@ -176,8 +175,8 @@ module Sawmill
     # is "rails":
     # 
     #  processor = Sawmill::EntryProcessor.build do
-    #    If(And(FilterBasicFields(:level => :INFO),
-    #           FilterBasicFields(:progname => 'rails')),
+    #    If(And(FilterByBasicFields(:level => :INFO),
+    #           FilterByBasicFields(:progname => 'rails')),
     #       Format(STDOUT))
     #  end
     
@@ -227,8 +226,8 @@ module Sawmill
         true
       end
       
-      def close
-        @children.each{ |forward_| forward_.close }
+      def finish
+        Util::ProcessorTools.collect_finish_values(@children)
       end
     
       
@@ -245,8 +244,8 @@ module Sawmill
     # "rails":
     # 
     #  processor = Sawmill::EntryProcessor.build do
-    #    If(Or(FilterBasicFields(:level => :INFO),
-    #          FilterBasicFields(:progname => 'rails')),
+    #    If(Or(FilterByBasicFields(:level => :INFO),
+    #          FilterByBasicFields(:progname => 'rails')),
     #       Format(STDOUT))
     #  end
     
@@ -296,8 +295,8 @@ module Sawmill
         false
       end
       
-      def close
-        @children.each{ |forward_| forward_.close }
+      def finish
+        Util::ProcessorTools.collect_finish_values(@children)
       end
     
       
@@ -315,8 +314,8 @@ module Sawmill
     # "rails":
     # 
     #  processor = Sawmill::EntryProcessor.build do
-    #    If(All(FilterBasicFields(:level => :INFO),
-    #           FilterBasicFields(:progname => 'rails')),
+    #    If(All(FilterByBasicFields(:level => :INFO),
+    #           FilterByBasicFields(:progname => 'rails')),
     #       Format(STDOUT))
     #  end
     # 
@@ -367,8 +366,8 @@ module Sawmill
         end
       end
       
-      def close
-        @children.each{ |forward_| forward_.close }
+      def finish
+        Util::ProcessorTools.collect_finish_values(@children)
       end
     
       
@@ -385,8 +384,8 @@ module Sawmill
     # "rails":
     # 
     #  processor = Sawmill::EntryProcessor.build do
-    #    If(Any(FilterBasicFields(:level => :INFO),
-    #           FilterBasicFields(:progname => 'rails')),
+    #    If(Any(FilterByBasicFields(:level => :INFO),
+    #           FilterByBasicFields(:progname => 'rails')),
     #       Format(STDOUT))
     #  end
     
@@ -431,8 +430,8 @@ module Sawmill
         end
       end
       
-      def close
-        @children.each{ |forward_| forward_.close }
+      def finish
+        Util::ProcessorTools.collect_finish_values(@children)
       end
     
       

data/lib/sawmill/entry_processor/count_entries.rb

@@ -0,0 +1,112 @@
+# -----------------------------------------------------------------------------
+# 
+# Sawmill entry processor that generates reports
+# 
+# -----------------------------------------------------------------------------
+# Copyright 2009 Daniel Azuma
+# 
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of the copyright holder, nor the names of any other
+#   contributors to this software, may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+# -----------------------------------------------------------------------------
+;
+
+
+module Sawmill
+  
+  module EntryProcessor
+    
+    
+    # This processor reports the number of entries processed.
+    
+    class CountEntries < Base
+      
+      
+      # Create a count-entries report.
+      # 
+      # Recognized options include:
+      # 
+      # <tt>:label</tt>::
+      #   Label to use for the report.
+      #   If provided, the report is returned as a string of the form
+      #   "#{label}#{value}"
+      #   If set to nil or absent, the report is returned as an integer.
+      # <tt>:omit_unknown_data</tt>::
+      #   If set to true, omits unknown_data from the count.
+      #   Default is false.
+      # <tt>:omit_attributes</tt>::
+      #   If set to true, omits attributes from the count.
+      #   Default is false.
+      # <tt>:omit_record_delimiters</tt>::
+      #   If set to true, omits begin_record and end_record from the count.
+      #   Default is false.
+      
+      def initialize(opts_={})
+        @label = opts_[:label]
+        @omit_unknown_data = opts_[:omit_unknown_data]
+        @omit_attributes = opts_[:omit_attributes]
+        @omit_record_delimiters = opts_[:omit_record_delimiters]
+        @finished = false
+        @count = 0
+      end
+      
+      
+      def begin_record(entry_)
+        @count += 1 unless @finished || @omit_record_delimiters
+        true
+      end
+      
+      def end_record(entry_)
+        @count += 1 unless @finished || @omit_record_delimiters
+        true
+      end
+      
+      def message(entry_)
+        @count += 1 unless @finished
+        true
+      end
+      
+      def attribute(entry_)
+        @count += 1 unless @finished || @omit_attributes
+        true
+      end
+      
+      def unknown_data(entry_)
+        @count += 1 unless @finished || @omit_unknown_data
+        true
+      end
+      
+      def finish
+        @finished = true
+        @label ? "#{@label}#{@count}" : @count
+      end
+      
+      
+    end
+    
+    
+  end
+  
+end

data/lib/sawmill/entry_processor/{filter_basic_fields.rb → filter_by_basic_fields.rb}

@@ -45,7 +45,7 @@ module Sawmill
     # on the filter result. Use this in conjunction with an If processor to
     # actually perform other actions based on the result.
     
-    class FilterBasicFields < Base
+    class FilterByBasicFields < Base
       
       
       # Create a new filter.
@@ -108,8 +108,8 @@ module Sawmill
         @accept_unknown
       end
       
-      
-      def close
+      def finish
+        nil
       end
       
       

data/lib/sawmill/entry_processor/filter_by_block.rb

@@ -0,0 +1,96 @@
+# -----------------------------------------------------------------------------
+# 
+# Sawmill entry processor that calls a block
+# 
+# -----------------------------------------------------------------------------
+# Copyright 2009 Daniel Azuma
+# 
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of the copyright holder, nor the names of any other
+#   contributors to this software, may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+# -----------------------------------------------------------------------------
+;
+
+
+module Sawmill
+  
+  module EntryProcessor
+    
+    
+    # A entry filter that calls a block to perform its check.
+    # 
+    # This is a boolean processor, so it merely returns true or false based
+    # on the filter result. Use this in conjunction with an If processor to
+    # actually perform other actions based on the result.
+    
+    class FilterByBlock < Base
+      
+      
+      # Create a new filter. Provide the block, which should take an entry
+      # object as the parameter and return a boolean.
+      
+      def initialize(&block_)
+        to_filter_entry(&block_)
+      end
+      
+      
+      # Provide a block to filter entries. It should take an entry object
+      # as the parameter, and return a boolean.
+      
+      def to_filter_entry(&block_)
+        @block = block_ || Proc.new{ |entry_| false }
+      end
+      
+      
+      def begin_record(entry_)
+        @block.call(entry_)
+      end
+      
+      def end_record(entry_)
+        @block.call(entry_)
+      end
+      
+      def message(entry_)
+        @block.call(entry_)
+      end
+      
+      def attribute(entry_)
+        @block.call(entry_)
+      end
+      
+      def unknown_data(entry_)
+        @block.call(entry_)
+      end
+      
+      def finish
+        nil
+      end
+      
+    end
+    
+    
+  end
+  
+end

data/lib/sawmill/entry_processor/format.rb

@@ -65,6 +65,9 @@ module Sawmill
       # <tt>:iso_8601_time</tt>::
       #   If true, outputs time in strict ISO 8601 format.
       #   If false (the default), outputs a slightly more readable format.
+      # <tt>:length_limit</tt>::
+      #   Limit to the entry length. Entries are truncated to this length
+      #   when written. If not specified, entries are not truncated.
       
       def initialize(destination_, opts_={})
         if destination_.kind_of?(Rotater)
@@ -83,6 +86,7 @@ module Sawmill
         @usec_factor = 1
         (6 - @fractional_second_digits).times{ @usec_factor *= 10 }
         @level_width = opts_[:level_width]
+        @length_limit = opts_[:length_limit]
       end
       
       
@@ -143,7 +147,7 @@ module Sawmill
         true
       end
       
-      def close
+      def finish
         if @rotater
           @default_channel.close
           @channels.values.each{ |channel_| channel_.close }
@@ -152,6 +156,7 @@ module Sawmill
           @io.close
           @io = nil
         end
+        nil
       end
       
       private
@@ -211,6 +216,9 @@ module Sawmill
         end
         levelstr_ = entry_.level.name.to_s
         levelstr_ = levelstr_.rjust(@level_width) if @level_width
+        if @length_limit && @length_limit < str_.length
+          str_ = str_[0, @length_limit] + "... (and #{str_.length-@length_limit} more characters) ..."
+        end
         "[#{levelstr_} #{timestr_} #{entry_.progname}#{id_} #{marker_}] #{str_}\n"
       end
       

data/lib/sawmill/entry_processor/simple_queue.rb

@@ -109,8 +109,9 @@ module Sawmill
         !@closed
       end
       
-      def close
+      def finish
         @closed = true
+        nil
       end