sawmill 0.0.2 → 0.0.3

data/lib/sawmill/record_processor/conditionals.rb

@@ -84,9 +84,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
       
       
@@ -122,8 +121,8 @@ module Sawmill
         !@child.extra_entry(record_)
       end
       
-      def close
-        @child.close
+      def finish
+        @child.finish
       end
       
       
@@ -170,8 +169,8 @@ module Sawmill
         true
       end
       
-      def close
-        @children.each{ |child_| child_.close }
+      def finish
+        Util::ProcessorTools.collect_finish_values(@children)
       end
       
       
@@ -218,8 +217,8 @@ module Sawmill
         false
       end
       
-      def close
-        @children.each{ |child_| child_.close }
+      def finish
+        Util::ProcessorTools.collect_finish_values(@children)
       end
       
       
@@ -271,8 +270,8 @@ module Sawmill
         end
       end
       
-      def close
-        @children.each{ |child_| child_.close }
+      def finish
+        Util::ProcessorTools.collect_finish_values(@children)
       end
       
       
@@ -317,8 +316,8 @@ module Sawmill
         end
       end
       
-      def close
-        @children.each{ |child_| child_.close }
+      def finish
+        Util::ProcessorTools.collect_finish_values(@children)
       end
       
       

data/lib/sawmill/record_processor/count_records.rb

@@ -0,0 +1,84 @@
+# -----------------------------------------------------------------------------
+# 
+# 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 RecordProcessor
+    
+    
+    # This processor reports the number of records processed.
+    
+    class CountRecords < Base
+      
+      
+      # Create a count-records 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.
+      
+      def initialize(opts_={})
+        @label = opts_[:label]
+        @finished = false
+        @count = 0
+      end
+      
+      
+      def record(record_)
+        @count += 1 unless @finished
+        true
+      end
+      
+      def extra_entry(entry_)
+        true
+      end
+      
+      def finish
+        @finished = true
+        @label ? "#{@label}#{@count}" : @count
+      end
+      
+      
+    end
+    
+    
+  end
+  
+end

data/lib/sawmill/record_processor/decompose.rb

@@ -63,8 +63,8 @@ module Sawmill
         true
       end
       
-      def close
-        @processor.close
+      def finish
+        @processor.finish
       end
       
     end

data/lib/sawmill/record_processor/filter_by_attributes.rb

@@ -76,7 +76,8 @@ module Sawmill
         false
       end
       
-      def close
+      def finish
+        nil
       end
       
     end

data/lib/sawmill/record_processor/filter_by_block.rb

@@ -0,0 +1,95 @@
+# -----------------------------------------------------------------------------
+# 
+# Sawmill record 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 RecordProcessor
+    
+    
+    # A record 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 a
+      # Sawmill::Record as the parameter and return a boolean.
+      # 
+      # By default, extra entries always return false. Provide an
+      # extra entry filter to change this behavior.
+      
+      def initialize(&block_)
+        to_filter_record(&block_)
+      end
+      
+      
+      # Provide a block to filter records. It should take a Sawmill::Record
+      # as the parameter, and return a boolean.
+      
+      def to_filter_record(&block_)
+        @block = block_ || Proc.new{ |record_| false }
+      end
+      
+      
+      # Provide a block to filter extra entries. It should take an entry
+      # object as the parameter, and return a boolean.
+      
+      def to_filter_extra_entry(&block_)
+        @extra_entry_block = block_ || Proc.new{ |entry_| false }
+      end
+      
+      
+      def record(record_)
+        @block.call(record_)
+      end
+      
+      def extra_entry(entry_)
+        @extra_entry_block.call(entry_)
+      end
+      
+      def finish
+        nil
+      end
+      
+    end
+    
+    
+  end
+  
+end

data/lib/sawmill/record_processor/filter_by_record_id.rb

@@ -66,7 +66,8 @@ module Sawmill
         @record_id === id_
       end
       
-      def close
+      def finish
+        nil
       end
       
     end

data/lib/sawmill/record_processor/format.rb

@@ -59,8 +59,14 @@ module Sawmill
       #   Default is 2. Accepted values are 0 to 6.
       # <tt>:level_width</tt>::
       #   Column width of the level field.
+      # <tt>:entry_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 (entry_length_limit_ = opts_.delete(:entry_length_limit))
+          opts_ = opts_.merge(:length_limit => entry_length_limit_)
+        end
         @formatter = EntryProcessor::Format.new(destination_, opts_)
         @classifier = EntryClassifier.new(@formatter)
       end
@@ -76,8 +82,8 @@ module Sawmill
         true
       end
       
-      def close
-        @formatter.close
+      def finish
+        @formatter.finish
       end
       
     end

data/lib/sawmill/record_processor/simple_queue.rb

@@ -117,8 +117,9 @@ module Sawmill
         @extra_entries_queue.enqueue(entry_) unless @closed
       end
       
-      def close
+      def finish
         @closed = true
+        nil
       end
       
       

data/lib/sawmill/record_processor.rb

@@ -82,15 +82,35 @@ module Sawmill
       end
       
       
-      # Close down the processor. After this is called, the processor should
-      # ignore any further records.
-      
-      def close
+      # Close down the processor, perform any finishing tasks, and return
+      # any final calculated value.
+      # 
+      # After this is called, the processor should ignore any further entries.
+      # 
+      # The return value can be used to communicate a final computed value,
+      # analysis report, or other data back to the caller. It may also be
+      # nil, signalling no finish value.
+      # 
+      # Note that some processors function to multiplex other processors. In
+      # such a case, their finish value needs to be an aggregate of the
+      # values returned by their descendants. To handle these cases, we
+      # define a protocol for finish values. A finish value may be nil, an
+      # Array, or another kind of object. Nil means "no value" and thus can
+      # be ignored by a processor that aggregates other values. An Array
+      # indicates an aggregation; if finish returns an array, it is _always_
+      # an aggregation of actual values. Any other kind of object is to be
+      # interpreted as a single value. This means that if you want to
+      # actually return an array _as_ a value, you must wrap it in another
+      # array, indicating "an array of one finish value, and that finish
+      # value also happens to be an array itself".
+      
+      def finish
+        nil
       end
       
       
       def self.inherited(subclass_)  # :nodoc:
-        if subclass_.name =~ /^Sawmill::RecordProcessor::(.*)$/
+        if subclass_.name =~ /^Sawmill::RecordProcessor::([^:]+)$/
           name_ = $1
           Builder.class_eval do
             define_method(name_) do |*args_|
@@ -101,6 +121,37 @@ module Sawmill
       end
       
       
+      # Add a method to the processor building DSL. You may call this method
+      # in the DSL to create an instance of this record processor.
+      # You must pass a method name that begins with a lower-case letter or
+      # underscore.
+      # 
+      # Processors that subclass Sawmill::RecordProcessor::Base and live in
+      # the Sawmill::RecordProcessor namespace will have their class name
+      # automatically added to the DSL. This method is primarily for other
+      # processors that do not live in that module namespace.
+      # 
+      # See Sawmill::RecordProcessor#build for more information.
+      # 
+      # Raises Sawmill::Errors::DSLMethodError if the given name is already
+      # taken.
+      
+      def self.add_dsl_method(name_)
+        klass_ = self
+        if name_.to_s !~ /^[a-z_]/
+          raise ::ArgumentError, "Method name must begin with a lower-case letter or underscore"
+        end
+        if Builder.method_defined?(name_)
+          raise Errors::DSLMethodError, "Method #{name_} already defined"
+        end
+        Builder.class_eval do
+          define_method(name_) do |*args_|
+            klass_.new(*args_)
+          end
+        end
+      end
+      
+      
       private
       
       def _interpret_processor_array(param_)  # :nodoc:
@@ -125,6 +176,19 @@ module Sawmill
     # A convenience DSL for building sets of processors. This is typically
     # useful for constructing if-expressions using the boolean operation
     # processors.
+    # 
+    # Every record processor that lives in the Sawmill::RecordProcessor
+    # module and subclasses Sawmill::RecordProcessor::Base can be
+    # instantiated by using its name as a function call. Other processors
+    # may also add themselves to the DSL by calling
+    # Sawmill::RecordProcessor::Base#add_dsl_method.
+    # 
+    # For example:
+    # 
+    #  Sawmill::RecordProcessor.build do
+    #    If(Or(FilterByRecordId('12345678'), FilterByRecordId('abcdefg')),
+    #       Format(STDOUT))
+    #  end
     
     def self.build(&block_)
       ::Blockenspiel.invoke(block_, Builder.new)

data/lib/sawmill/rotater/date_based_log_file.rb

@@ -65,27 +65,27 @@ module Sawmill
       #   How often the log files should turn over. Allowed values are:
       #   <tt>:yearly</tt>, <tt>:monthly</tt>, <tt>:daily</tt>, 
       #   <tt>:hourly</tt>, and <tt>:never</tt>.
-      # <tt>:dirname</tt>::
-      #   The directory for the logfiles to be output.
+      # <tt>:basedir</tt>::
+      #   The base directory used if the filepath is a relative path.
       #   If not specified, the current working directory is used.
       # <tt>:prefix</tt>::
-      #   The logfile name prefix.
+      #   The logfile path prefix.
       #   In the filename "rails.2009-10-11.log", the prefix is "rails".
       #   If not specified, defaults to "sawmill".
       # <tt>:suffix</tt>::
       #   The logfile name prefix.
       #   In the filename "rails.2009-10-11.log", the suffix is ".log".
       #   If not specified, defaults to ".log".
-      # <tt>:local_timezone</tt>::
+      # <tt>:local_datestamps</tt>::
       #   If true, use the local timezone to create datestamps.
       #   The default is to use UTC.
       
       def initialize(options_)
         @turnover_frequency = options_[:turnover_frequency] || :none
-        dirname_ = options_[:dirname] || ::Dir.getwd
-        @prefix = ::File.join(dirname_, options_[:prefix] || 'sawmill')
+        @prefix = ::File.expand_path(options_[:prefix] || 'sawmill',
+                                     options_[:basedir] || options_[:dirname] || ::Dir.getwd)
         @suffix = options_[:suffix] || '.log'
-        @local_timezone = options_[:local_timezone]
+        @local_datestamps = options_[:local_datestamps]
         @date_pattern =
           case @turnover_frequency
           when :yearly then "%Y"
@@ -102,7 +102,7 @@ module Sawmill
       def preferred_handle
         if @date_pattern
           time_ = ::Time.now
-          time_.utc unless @local_timezone
+          time_.utc unless @local_datestamps
           time_.strftime(@date_pattern)
         else
           ''

data/lib/sawmill/rotater/shifting_log_file.rb

@@ -56,11 +56,12 @@ module Sawmill
       # 
       # Recognized options include:
       # 
-      # <tt>:dirname</tt>::
-      #   The directory for the logfiles to be output.
+      # <tt>:basedir</tt>::
+      #   The base directory used if the filepath is a relative path.
       #   If not specified, the current working directory is used.
-      # <tt>:filename</tt>::
-      #   The logfile name.
+      # <tt>:filepath</tt>::
+      #   The path to the log file. This may be an absolute path or a
+      #   path relative to basedir.
       #   If not specified, defaults to "sawmill.log".
       # <tt>:max_logfile_size</tt>::
       #   A logfile will try to rotate once it has reached this size in
@@ -91,8 +92,8 @@ module Sawmill
         end
         @history_size = options_[:history_size].to_i
         @history_size = 1 if @history_size < 1 && (@max_logfile_size || @shift_period)
-        dirname_ = options_[:dirname] || ::Dir.getwd
-        @normal_path = ::File.join(dirname_, options_[:filename] || 'sawmill.log')
+        @normal_path = ::File.expand_path(options_[:filepath] || 'sawmill.log', 
+                                          options_[:basedir] || ::Dir.getwd)
         @preferred_handle = 0
         @open_handles = {}
         @last_shift = ::Time.now

data/lib/sawmill/util/processor_tools.rb

@@ -0,0 +1,71 @@
+# -----------------------------------------------------------------------------
+# 
+# Sawmill tools for building processors
+# 
+# -----------------------------------------------------------------------------
+# 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 Util
+    
+    
+    # Some miscellaneous tools for building processors
+    
+    module ProcessorTools
+      
+      
+      def self.collect_finish_values(children_)
+        ret_ = nil
+        children_.each do |child_|
+          unless child_.nil?
+            val_ = child_.finish
+            unless val_.nil?
+              ret_ ||= []
+              if val_.kind_of?(::Array)
+                ret_.concat(val_)
+              else
+                ret_.push(val_)
+              end
+            end
+          end
+        end
+        ret_
+      end
+      
+      
+    end
+    
+    
+  end
+  
+end

data/lib/sawmill/version.rb

@@ -34,12 +34,10 @@
 ;
 
 
-# This module is a namespace for Sawmill.
-
 module Sawmill
   
   # Current gem version, as a frozen string.
-  VERSION_STRING = '0.0.2'.freeze
+  VERSION_STRING = '0.0.3'.freeze
   
   # Current gem version, as a Versionomy::Value.
   VERSION = ::Versionomy.parse(VERSION_STRING, :standard)

data/lib/sawmill.rb

@@ -50,6 +50,7 @@ includes_ = [
  'version',
  'util/queue',
  'util/heap',
+ 'util/processor_tools',
  'errors',
  'level',
  'entry',
@@ -57,17 +58,23 @@ includes_ = [
  'entry_processor',
  'entry_processor/conditionals',
  'entry_processor/simple_queue',
- 'entry_processor/filter_basic_fields',
+ 'entry_processor/filter_by_basic_fields',
+ 'entry_processor/filter_by_block',
  'entry_processor/build_records',
  'entry_processor/format',
+ 'entry_processor/count_entries',
+ 'entry_processor/compile_report',
  'record',
  'record_processor',
  'record_processor/conditionals',
  'record_processor/filter_by_record_id',
  'record_processor/filter_by_attributes',
+ 'record_processor/filter_by_block',
  'record_processor/simple_queue',
  'record_processor/decompose',
  'record_processor/format',
+ 'record_processor/count_records',
+ 'record_processor/compile_report',
  'parser',
  'multi_parser',
  'logger',
@@ -76,5 +83,6 @@ includes_ = [
  'rotater/date_based_log_file',
  'rotater/shifting_log_file',
  'log_record_middleware',
+ 'interface',
 ]
 includes_.each{ |file_| require "#{dir_}/#{file_}" }

data/tests/tc_entry_processors.rb

@@ -53,7 +53,7 @@ module Sawmill
       
       def test_basic_level_filter
         processor_ = ::Sawmill::EntryProcessor::build do
-          If(FilterBasicFields(:level => :WARN), @entries)
+          If(FilterByBasicFields(:level => :WARN), @entries)
         end
         @logger = ::Sawmill::Logger.new(:processor => processor_)
         @logger.warn('Hello 1')
@@ -69,7 +69,7 @@ module Sawmill
       
       def test_basic_progname_filter
         processor_ = ::Sawmill::EntryProcessor::build do
-          If(FilterBasicFields(:progname => 'rails'), @entries)
+          If(FilterByBasicFields(:progname => 'rails'), @entries)
         end
         @logger = ::Sawmill::Logger.new(:processor => processor_)
         @logger.info('Hello 1')
@@ -84,8 +84,8 @@ module Sawmill
       
       def test_conjunction_and
         processor_ = ::Sawmill::EntryProcessor::build do
-          If(And(FilterBasicFields(:progname => 'rails'),
-                 FilterBasicFields(:level => :WARN)), @entries)
+          If(And(FilterByBasicFields(:progname => 'rails'),
+                 FilterByBasicFields(:level => :WARN)), @entries)
         end
         @logger = ::Sawmill::Logger.new(:processor => processor_)
         @logger.warn('Hello 1')
@@ -101,8 +101,8 @@ module Sawmill
       
       def test_conjunction_or
         processor_ = ::Sawmill::EntryProcessor::build do
-          If(Or(FilterBasicFields(:progname => 'rails'),
-                FilterBasicFields(:level => :WARN)), @entries)
+          If(Or(FilterByBasicFields(:progname => 'rails'),
+                FilterByBasicFields(:level => :WARN)), @entries)
         end
         @logger = ::Sawmill::Logger.new(:processor => processor_)
         @logger.warn('Hello 1')
@@ -120,7 +120,7 @@ module Sawmill
       
       def test_boolean_not
         processor_ = ::Sawmill::EntryProcessor::build do
-          If(Not(FilterBasicFields(:progname => 'rails')), @entries)
+          If(Not(FilterByBasicFields(:progname => 'rails')), @entries)
         end
         @logger = ::Sawmill::Logger.new(:processor => processor_)
         @logger.info('Hello 1')