lumberjack 1.0.13 → 1.2.8

data/lib/lumberjack/formatter.rb

@@ -1,33 +1,57 @@
 # frozen_string_literals: true
 
 module Lumberjack
-  # This class controls the conversion of log entry messages into strings. This allows you
-  # to log any object you want and have the logging system worry about converting it into a string.
+  # This class controls the conversion of log entry messages into a loggable format. This allows you
+  # to log any object you want and have the logging system deal with converting it into a string.
   #
   # Formats are added to a Formatter by associating them with a class using the +add+ method. Formats
   # are any object that responds to the +call+ method.
   #
   # By default, all object will be converted to strings using their inspect method except for Strings
   # and Exceptions. Strings are not converted and Exceptions are converted using the ExceptionFormatter.
+  #
+  # Enumerable objects (including Hash and Array) will call the formatter recursively for each element.
   class Formatter
-    require File.expand_path("../formatter/exception_formatter.rb", __FILE__)
-    require File.expand_path("../formatter/inspect_formatter.rb", __FILE__)
-    require File.expand_path("../formatter/pretty_print_formatter.rb", __FILE__)
-    require File.expand_path("../formatter/string_formatter.rb", __FILE__)
-    
+    require_relative "formatter/date_time_formatter"
+    require_relative "formatter/exception_formatter"
+    require_relative "formatter/id_formatter"
+    require_relative "formatter/inspect_formatter"
+    require_relative "formatter/object_formatter"
+    require_relative "formatter/pretty_print_formatter"
+    require_relative "formatter/string_formatter"
+    require_relative "formatter/strip_formatter"
+    require_relative "formatter/structured_formatter"
+
+    class << self
+      # Returns a new empty formatter with no mapping. For historical reasons, a formatter
+      # is initialized with mappings to help output objects as strings. This will return one
+      # without the default mappings.
+      def empty
+        new.clear
+      end
+    end
+
     def initialize
       @class_formatters = {}
-      @_default_formatter = InspectFormatter.new
-      add(Object, @_default_formatter)
-      add(String, :string)
+      @module_formatters = {}
+      structured_formatter = StructuredFormatter.new(self)
+      add([String, Numeric, TrueClass, FalseClass], :object)
+      add(Object, InspectFormatter.new)
       add(Exception, :exception)
+      add(Enumerable, structured_formatter)
     end
-    
+
     # Add a formatter for a class. The formatter can be specified as either an object
     # that responds to the +call+ method or as a symbol representing one of the predefined
     # formatters, or as a block to the method call.
     #
-    # The predefined formatters are: <tt>:inspect</tt>, <tt>:string</tt>, <tt>:exception</tt>, and <tt>:pretty_print</tt>.
+    # The predefined formatters are: :inspect, :string, :exception, and :pretty_print.
+    #
+    # You can add multiple classes at once by passing an array of classes.
+    #
+    # You can also pass class names as strings instead of the classes themselves. This can
+    # help avoid loading dependency issues. This applies only to classes; modules cannot be
+    # passed in as strings.
     #
     # === Examples
     #
@@ -44,40 +68,85 @@ module Lumberjack
     #   formatter.add(MyClass, :pretty_print).add(YourClass){|obj| obj.humanize}
     def add(klass, formatter = nil, &block)
       formatter ||= block
-      if formatter.is_a?(Symbol)
-        formatter_class_name = "#{formatter.to_s.gsub(/(^|_)([a-z])/){|m| $~[2].upcase}}Formatter"
-        formatter = Formatter.const_get(formatter_class_name).new
+      if formatter.nil?
+        remove(klass)
+      else
+        if formatter.is_a?(Symbol)
+          formatter_class_name = "#{formatter.to_s.gsub(/(^|_)([a-z])/) { |m| $~[2].upcase }}Formatter"
+          formatter = Formatter.const_get(formatter_class_name).new
+        end
+
+        Array(klass).each do |k|
+          if k.class == Module
+            @module_formatters[k] = formatter
+          else
+            k = k.name if k.is_a?(Class)
+            @class_formatters[k] = formatter
+          end
+        end
       end
-      @class_formatters[klass] = formatter
       self
     end
-    
+
     # Remove the formatter associated with a class. Remove statements can be chained together.
+    #
+    # You can remove multiple classes at once by passing an array of classes.
+    #
+    # You can also pass class names as strings instead of the classes themselves. This can
+    # help avoid loading dependency issues. This applies only to classes; modules cannot be
+    # passed in as strings.
     def remove(klass)
-      @class_formatters.delete(klass)
+      Array(klass).each do |k|
+        if k.class == Module
+          @module_formatters.delete(k)
+        else
+          k = k.name if k.is_a?(Class)
+          @class_formatters.delete(k)
+        end
+      end
+      self
+    end
+
+    # Remove all formatters including the default formatter. Can be chained to add method calls.
+    def clear
+      @class_formatters.clear
+      @module_formatters.clear
       self
     end
-    
+
     # Format a message object as a string.
     def format(message)
-      formatter_for(message.class).call(message)
+      formatter = formatter_for(message.class)
+      if formatter&.respond_to?(:call)
+        formatter.call(message)
+      else
+        message
+      end
     end
-    
-    # Hack for compatibility with Logger::Formatter
+
+    # Compatibility with the Logger::Formatter signature. This method will just convert the message
+    # object to a string and ignores the other parameters.
     def call(severity, timestamp, progname, msg)
-      "#{format(msg)}\n"
-    end    
+      "#{format(msg)}#{Lumberjack::LINE_SEPARATOR}"
+    end
 
     private
-    
+
     # Find the formatter for a class by looking it up using the class hierarchy.
     def formatter_for(klass) #:nodoc:
-      while klass != nil do
-        formatter = @class_formatters[klass]
+      check_modules = true
+      until klass.nil?
+        formatter = @class_formatters[klass.name]
         return formatter if formatter
+
+        if check_modules
+          _, formatter = @module_formatters.detect { |mod, f| klass.include?(mod) }
+          check_modules = false
+          return formatter if formatter
+        end
+
         klass = klass.superclass
       end
-      @_default_formatter
     end
   end
 end

data/lib/lumberjack/formatter/date_time_formatter.rb

@@ -0,0 +1,25 @@
+# frozen_string_literals: true
+
+module Lumberjack
+  class Formatter
+    # Format a Date, Time, or DateTime object. If you don't specify a format in the constructor,
+    # it will use the ISO-8601 format.
+    class DateTimeFormatter
+      attr_reader :format
+
+      def initialize(format = nil)
+        @format = format.dup.to_s.freeze unless format.nil?
+      end
+
+      def call(obj)
+        if @format && obj.respond_to?(:strftime)
+          obj.strftime(@format)
+        elsif obj.respond_to?(:iso8601)
+          obj.iso8601
+        else
+          obj.to_s
+        end
+      end
+    end
+  end
+end

data/lib/lumberjack/formatter/exception_formatter.rb

@@ -2,13 +2,36 @@
 
 module Lumberjack
   class Formatter
-    # Format an exception including the backtrace.
+    # Format an exception including the backtrace. You can specify an object that
+    # responds to `call` as a backtrace cleaner. The exception backtrace will be
+    # passed to this object and the returned array is what will be logged. You can
+    # use this to clean out superfluous lines.
     class ExceptionFormatter
+      attr_accessor :backtrace_cleaner
+
+      def initialize(backtrace_cleaner = nil)
+        self.backtrace_cleaner = backtrace_cleaner
+      end
+
       def call(exception)
         message = "#{exception.class.name}: #{exception.message}"
-        message << "#{Lumberjack::LINE_SEPARATOR}  #{exception.backtrace.join("#{Lumberjack::LINE_SEPARATOR}  ")}" if exception.backtrace
+        trace = exception.backtrace
+        if trace
+          trace = clean_backtrace(trace)
+          message << "#{Lumberjack::LINE_SEPARATOR}  #{trace.join("#{Lumberjack::LINE_SEPARATOR}  ")}"
+        end
         message
       end
+
+      private
+
+      def clean_backtrace(trace)
+        if trace && backtrace_cleaner
+          backtrace_cleaner.call(trace)
+        else
+          trace
+        end
+      end
     end
   end
 end

data/lib/lumberjack/formatter/id_formatter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literals: true
+
+module Lumberjack
+  class Formatter
+    # Format an object that has an id as a hash with keys for class and id. This formatter is useful
+    # as a default formatter for objects pulled from a data store. By default it will use :id as the
+    # id attribute.
+    class IdFormatter
+      def initialize(id_attribute = :id)
+        @id_attribute = id_attribute
+      end
+
+      def call(obj)
+        if obj.respond_to?(@id_attribute)
+          id = obj.send(@id_attribute)
+          {"class" => obj.class.name, "id" => id}
+        else
+          obj.to_s
+        end
+      end
+    end
+  end
+end

data/lib/lumberjack/formatter/object_formatter.rb

@@ -0,0 +1,12 @@
+# frozen_string_literals: true
+
+module Lumberjack
+  class Formatter
+    # No-op formatter that just returns the object itself.
+    class ObjectFormatter
+      def call(obj)
+        obj
+      end
+    end
+  end
+end

data/lib/lumberjack/formatter/pretty_print_formatter.rb

@@ -1,20 +1,20 @@
 # frozen_string_literals: true
 
-require 'pp'
-require 'stringio'
+require "pp"
+require "stringio"
 
 module Lumberjack
   class Formatter
     # Format an object with it's pretty print method.
     class PrettyPrintFormatter
       attr_accessor :width
-      
+
       # Create a new formatter. The maximum width of the message can be specified with the width
       # parameter (defaults to 79 characters).
       def initialize(width = 79)
         @width = width
       end
-      
+
       def call(obj)
         s = StringIO.new
         PP.pp(obj, s)

data/lib/lumberjack/formatter/string_formatter.rb

@@ -2,7 +2,7 @@
 
 module Lumberjack
   class Formatter
-    # Format an object by calling +to_s+ on it.
+    # Format an object by calling `to_s` on it.
     class StringFormatter
       def call(obj)
         obj.to_s

data/lib/lumberjack/formatter/strip_formatter.rb

@@ -0,0 +1,12 @@
+# frozen_string_literals: true
+
+module Lumberjack
+  class Formatter
+    # Format an object by calling `to_s` on it and stripping leading and trailing whitespace.
+    class StripFormatter
+      def call(obj)
+        obj.to_s.strip
+      end
+    end
+  end
+end

data/lib/lumberjack/formatter/structured_formatter.rb

@@ -0,0 +1,63 @@
+# frozen_string_literals: true
+
+require "set"
+
+module Lumberjack
+  class Formatter
+    # Dereference arrays and hashes and recursively call formatters on each element.
+    class StructuredFormatter
+      class RecusiveReferenceError < StandardError
+      end
+
+      def initialize(formatter = nil)
+        @formatter = formatter
+      end
+
+      def call(obj)
+        call_with_references(obj, Set.new)
+      end
+
+      private
+
+      def call_with_references(obj, references)
+        if obj.is_a?(Hash)
+          with_object_reference(obj, references) do
+            hash = {}
+            obj.each do |name, value|
+              value = call_with_references(value, references)
+              hash[name.to_s] = value unless value.is_a?(RecusiveReferenceError)
+            end
+            hash
+          end
+        elsif obj.is_a?(Enumerable) && obj.respond_to?(:size) && obj.size != Float::INFINITY
+          with_object_reference(obj, references) do
+            array = []
+            obj.each do |value|
+              value = call_with_references(value, references)
+              array << value unless value.is_a?(RecusiveReferenceError)
+            end
+            array
+          end
+        elsif @formatter
+          @formatter.format(obj)
+        else
+          obj
+        end
+      end
+
+      def with_object_reference(obj, references)
+        if obj.is_a?(Enumerable)
+          return RecusiveReferenceError.new if references.include?(obj.object_id)
+          references << obj.object_id
+          begin
+            yield
+          ensure
+            references.delete(obj.object_id)
+          end
+        else
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/lumberjack/log_entry.rb

@@ -4,35 +4,63 @@ module Lumberjack
   # An entry in a log is a data structure that captures the log message as well as
   # information about the system that logged the message.
   class LogEntry
-    attr_accessor :time, :message, :severity, :progname, :pid, :unit_of_work_id
-    
-    TIME_FORMAT = "%Y-%m-%dT%H:%M:%S".freeze
-    
-    def initialize(time, severity, message, progname, pid, unit_of_work_id)
+    attr_accessor :time, :message, :severity, :progname, :pid, :tags
+
+    TIME_FORMAT = "%Y-%m-%dT%H:%M:%S"
+
+    UNIT_OF_WORK_ID = "unit_of_work_id"
+
+    def initialize(time, severity, message, progname, pid, tags)
       @time = time
       @severity = (severity.is_a?(Integer) ? severity : Severity.label_to_level(severity))
       @message = message
       @progname = progname
       @pid = pid
-      @unit_of_work_id = unit_of_work_id
+      # backward compatibility with 1.0 API where the last argument was the unit of work id
+      @tags = if tags.nil? || tags.is_a?(Hash)
+        tags
+      else
+        {UNIT_OF_WORK_ID => tags}
+      end
     end
-    
+
     def severity_label
       Severity.level_to_label(severity)
     end
-    
+
     def to_s
-      buf = "[#{time.strftime(TIME_FORMAT)}.#{(time.usec / 1000.0).round.to_s.rjust(3, '0')} #{severity_label} #{progname}(#{pid})"
-      if unit_of_work_id
-        buf << " #"
-        buf << unit_of_work_id
-      end
-      buf << "] "
-      buf << message
+      "[#{time.strftime(TIME_FORMAT)}.#{(time.usec / 1000.0).round.to_s.rjust(3, "0")} #{severity_label} #{progname}(#{pid})#{tags_to_s}] #{message}"
     end
-    
+
     def inspect
       to_s
     end
+
+    # Deprecated - backward compatibility with 1.0 API
+    def unit_of_work_id
+      tags[UNIT_OF_WORK_ID] if tags
+    end
+
+    # Deprecated - backward compatibility with 1.0 API
+    def unit_of_work_id=(value)
+      if tags
+        tags[UNIT_OF_WORK_ID] = value
+      else
+        @tags = {UNIT_OF_WORK_ID => value}
+      end
+    end
+
+    # Return the tag with the specified name.
+    def tag(name)
+      tags[name.to_s] if tags
+    end
+
+    private
+
+    def tags_to_s
+      tags_string = ""
+      tags&.each { |name, value| tags_string << " #{name}:#{value.inspect}" }
+      tags_string
+    end
   end
 end