lumberjack 1.2.8 → 1.2.10

data/lib/lumberjack/device.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   # This is an abstract class for logging devices. Subclasses must implement the +write+ method and
@@ -13,29 +13,44 @@ module Lumberjack
     require_relative "device/null"
 
     # Subclasses must implement this method to write a LogEntry.
+    #
+    # @param [Lumberjack::LogEntry] entry The entry to write.
+    # @return [void]
     def write(entry)
       raise NotImplementedError
     end
 
     # Subclasses may implement this method to close the device.
+    #
+    # @return [void]
     def close
       flush
     end
 
     # Subclasses may implement this method to reopen the device.
+    #
+    # @param [Object] logdev The log device to use.
+    # @return [void]
     def reopen(logdev = nil)
       flush
     end
 
     # Subclasses may implement this method to flush any buffers used by the device.
+    #
+    # @return [void]
     def flush
     end
 
     # Subclasses may implement this method to get the format for log timestamps.
+    #
+    # @return [String] The format for log timestamps.
     def datetime_format
     end
 
     # Subclasses may implement this method to set a format for log timestamps.
+    #
+    # @param [String] format The format for log timestamps.
+    # @return [void]
     def datetime_format=(format)
     end
   end

data/lib/lumberjack/formatter/date_time_formatter.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   class Formatter
@@ -7,6 +7,7 @@ module Lumberjack
     class DateTimeFormatter
       attr_reader :format
 
+      # @param [String] format The format to use when formatting the date/time object.
       def initialize(format = nil)
         @format = format.dup.to_s.freeze unless format.nil?
       end

data/lib/lumberjack/formatter/exception_formatter.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   class Formatter
@@ -9,12 +9,14 @@ module Lumberjack
     class ExceptionFormatter
       attr_accessor :backtrace_cleaner
 
+      # @param [#call] backtrace_cleaner An object that responds to `call` and takes
+      #   an array of strings (the backtrace) and returns an array of strings (the
       def initialize(backtrace_cleaner = nil)
         self.backtrace_cleaner = backtrace_cleaner
       end
 
       def call(exception)
-        message = "#{exception.class.name}: #{exception.message}"
+        message = +"#{exception.class.name}: #{exception.message}"
         trace = exception.backtrace
         if trace
           trace = clean_backtrace(trace)

data/lib/lumberjack/formatter/id_formatter.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   class Formatter
@@ -6,6 +6,7 @@ module Lumberjack
     # as a default formatter for objects pulled from a data store. By default it will use :id as the
     # id attribute.
     class IdFormatter
+      # @param [Symbol, String] id_attribute The attribute to use as the id.
       def initialize(id_attribute = :id)
         @id_attribute = id_attribute
       end

data/lib/lumberjack/formatter/inspect_formatter.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   class Formatter

data/lib/lumberjack/formatter/object_formatter.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   class Formatter

data/lib/lumberjack/formatter/pretty_print_formatter.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 require "pp"
 require "stringio"
@@ -11,6 +11,8 @@ module Lumberjack
 
       # Create a new formatter. The maximum width of the message can be specified with the width
       # parameter (defaults to 79 characters).
+      #
+      # @param [Integer] width The maximum width of the message.
       def initialize(width = 79)
         @width = width
       end

data/lib/lumberjack/formatter/string_formatter.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   class Formatter

data/lib/lumberjack/formatter/strip_formatter.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   class Formatter

data/lib/lumberjack/formatter/structured_formatter.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 require "set"
 
@@ -9,6 +9,8 @@ module Lumberjack
       class RecusiveReferenceError < StandardError
       end
 
+      # @param [Formatter] formatter The formatter to call on each element
+      #   in the structure.
       def initialize(formatter = nil)
         @formatter = formatter
       end

data/lib/lumberjack/formatter/truncate_formatter.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  class Formatter
+    # Truncate a string object to a specific length. This is useful
+    # for formatting messages when there is a limit on the number of
+    # characters that can be logged per message. This formatter should
+    # only be used when necessary since it is a lossy formatter.
+    #
+    # When a string is truncated, it will have a unicode ellipsis
+    # character (U+2026) appended to the end of the string.
+    class TruncateFormatter
+      # @param [Integer] length The maximum length of the string (defaults to 32K)
+      def initialize(length = 32768)
+        @length = length
+      end
+
+      def call(obj)
+        if obj.is_a?(String) && obj.length > @length
+          "#{obj[0, @length - 1]}…"
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/lumberjack/formatter.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   # This class controls the conversion of log entry messages into a loggable format. This allows you
@@ -21,11 +21,14 @@ module Lumberjack
     require_relative "formatter/string_formatter"
     require_relative "formatter/strip_formatter"
     require_relative "formatter/structured_formatter"
+    require_relative "formatter/truncate_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.
+      #
+      # @return [Lumberjack::Formatter] a new empty formatter
       def empty
         new.clear
       end
@@ -45,7 +48,17 @@ module Lumberjack
     # 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: :inspect, :string, :exception, and :pretty_print.
+    # The predefined formatters are:
+    #   - :date_time
+    #   - :exception
+    #   - :id
+    #   - :inspect
+    #   - :object
+    #   - :pretty_print
+    #   - :string
+    #   - :strip
+    #   - :structured
+    #   - :truncate
     #
     # You can add multiple classes at once by passing an array of classes.
     #
@@ -53,7 +66,18 @@ module Lumberjack
     # help avoid loading dependency issues. This applies only to classes; modules cannot be
     # passed in as strings.
     #
-    # === Examples
+    # @param [Class, Module, String, Array<Class, Module, String>] klass The class or module to add a formatter for.
+    # @param [Symbol, Class, String, #call] formatter The formatter to use for the class.
+    #   If a symbol is passed in, it will be used to load one of the predefined formatters.
+    #   If a class is passed in, it will be initialized with the args passed in.
+    #   Otherwise, the object will be used as the formatter and must respond to call method.
+    # @param [Array] args Arguments to pass to the formatter when it is initialized.
+    # @yield [obj] A block that will be used as the formatter for the class.
+    # @yieldparam [Object] obj The object to format.
+    # @yieldreturn [String] The formatted string.
+    # @return [self] Returns itself so that add statements can be chained together.
+    #
+    # @example
     #
     #   # Use a predefined formatter
     #   formatter.add(MyClass, :pretty_print)
@@ -66,18 +90,27 @@ module Lumberjack
     #
     #   # Add statements can be chained together
     #   formatter.add(MyClass, :pretty_print).add(YourClass){|obj| obj.humanize}
-    def add(klass, formatter = nil, &block)
+    def add(klass, formatter = nil, *args, &block)
       formatter ||= block
       if formatter.nil?
         remove(klass)
       else
+        formatter_class_name = nil
         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
+        elsif formatter.is_a?(String)
+          formatter_class_name = formatter
+        end
+        if formatter_class_name
+          formatter = Formatter.const_get(formatter_class_name)
+        end
+
+        if formatter.is_a?(Class)
+          formatter = formatter.new(*args)
         end
 
         Array(klass).each do |k|
-          if k.class == Module
+          if k.instance_of?(Module)
             @module_formatters[k] = formatter
           else
             k = k.name if k.is_a?(Class)
@@ -95,9 +128,12 @@ module Lumberjack
     # 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.
+    #
+    # @param [Class, Module, String, Array<Class, Module, String>] klass The class or module to remove the formatters for.
+    # @return [self] Returns itself so that remove statements can be chained together.
     def remove(klass)
       Array(klass).each do |k|
-        if k.class == Module
+        if k.instance_of?(Module)
           @module_formatters.delete(k)
         else
           k = k.name if k.is_a?(Class)
@@ -108,13 +144,18 @@ module Lumberjack
     end
 
     # Remove all formatters including the default formatter. Can be chained to add method calls.
+    #
+    # @return [self] Returns itself so that clear statements can be chained together.
     def clear
       @class_formatters.clear
       @module_formatters.clear
       self
     end
 
-    # Format a message object as a string.
+    # Format a message object by applying all formatters attached to it.
+    #
+    # @param [Object] message The message object to format.
+    # @return [Object] The formatted object.
     def format(message)
       formatter = formatter_for(message.class)
       if formatter&.respond_to?(:call)
@@ -126,6 +167,11 @@ module Lumberjack
 
     # Compatibility with the Logger::Formatter signature. This method will just convert the message
     # object to a string and ignores the other parameters.
+    #
+    # @param [Integer, String, Symbol] severity The severity of the message.
+    # @param [Time] timestamp The time the message was logged.
+    # @param [String] progname The name of the program logging the message.
+    # @param [Object] msg The message object to format.
     def call(severity, timestamp, progname, msg)
       "#{format(msg)}#{Lumberjack::LINE_SEPARATOR}"
     end
@@ -133,7 +179,7 @@ module Lumberjack
     private
 
     # Find the formatter for a class by looking it up using the class hierarchy.
-    def formatter_for(klass) #:nodoc:
+    def formatter_for(klass) # :nodoc:
       check_modules = true
       until klass.nil?
         formatter = @class_formatters[klass.name]

data/lib/lumberjack/log_entry.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   # An entry in a log is a data structure that captures the log message as well as
@@ -10,6 +10,14 @@ module Lumberjack
 
     UNIT_OF_WORK_ID = "unit_of_work_id"
 
+    # Create a new log entry.
+    #
+    # @param [Time] time The time the log entry was created.
+    # @param [Integer, String] severity The severity of the log entry.
+    # @param [String] message The message to log.
+    # @param [String] progname The name of the program that created the log entry.
+    # @param [Integer] pid The process id of the program that created the log entry.
+    # @param [Hash] tags A hash of tags to associate with the log entry.
     def initialize(time, severity, message, progname, pid, tags)
       @time = time
       @severity = (severity.is_a?(Integer) ? severity : Severity.label_to_level(severity))
@@ -58,7 +66,7 @@ module Lumberjack
     private
 
     def tags_to_s
-      tags_string = ""
+      tags_string = +""
       tags&.each { |name, value| tags_string << " #{name}:#{value.inspect}" }
       tags_string
     end