lumberjack 1.2.7 → 1.2.9

data/lib/lumberjack/device/size_rolling_log_file.rb

@@ -8,30 +8,30 @@ module Lumberjack
     # production.log.1, then production.log.2, etc.
     class SizeRollingLogFile < RollingLogFile
       attr_reader :max_size
-      
+
       # Create an new log device to the specified file. The maximum size of the log file is specified with
       # the :max_size option. The unit can also be specified: "32K", "100M", "2G" are all valid.
       def initialize(path, options = {})
         @manual = options[:manual]
         @max_size = options[:max_size]
         if @max_size.is_a?(String)
-          if @max_size.match(/^(\d+(\.\d+)?)([KMG])?$/i)
+          if @max_size =~ /^(\d+(\.\d+)?)([KMG])?$/i
             @max_size = $~[1].to_f
             units = $~[3].to_s.upcase
             case units
             when "K"
               @max_size *= 1024
             when "M"
-              @max_size *= 1024 ** 2
+              @max_size *= 1024**2
             when "G"
-              @max_size *= 1024 ** 3
+              @max_size *= 1024**3
             end
             @max_size = @max_size.round
           else
             raise ArgumentError.new("illegal value for :max_size (#{@max_size})")
           end
         end
-        
+
         super
       end
 
@@ -44,15 +44,15 @@ module Lumberjack
       rescue SystemCallError
         false
       end
-      
+
       protected
-      
+
       # Calculate the next archive file name extension.
       def next_archive_number # :nodoc:
         max = 0
         Dir.glob("#{path}.*").each do |filename|
-          if filename.match(/\.\d+$/)
-            suffix = filename.split('.').last.to_i
+          if /\.\d+\z/ =~ filename
+            suffix = filename.split(".").last.to_i
             max = suffix if suffix > max
           end
         end

data/lib/lumberjack/device/writer.rb

@@ -60,6 +60,9 @@ module Lumberjack
       # work id will only appear if it is present.
       #
       # The size of the internal buffer in bytes can be set by providing :buffer_size (defaults to 32K).
+      #
+      # @param [IO] stream The stream to write log entries to.
+      # @param [Hash] options The options for the device.
       def initialize(stream, options = {})
         @lock = Mutex.new
         @stream = stream
@@ -71,18 +74,24 @@ module Lumberjack
           @template = template
         else
           additional_lines = (options[:additional_lines] || DEFAULT_ADDITIONAL_LINES_TEMPLATE)
-          @template = Template.new(template, :additional_lines => additional_lines, :time_format => options[:time_format])
+          @template = Template.new(template, additional_lines: additional_lines, time_format: options[:time_format])
         end
       end
 
       # Set the buffer size in bytes. The device will only be physically written to when the buffer size
       # is exceeded.
+      #
+      # @param [Integer] value The size of the buffer in bytes.
+      # @return [void]
       def buffer_size=(value)
         @buffer_size = value
         flush
       end
 
       # Write an entry to the stream. The entry will be converted into a string using the defined template.
+      #
+      # @param [LogEntry, String] entry The entry to write to the stream.
+      # @return [void]
       def write(entry)
         string = (entry.is_a?(LogEntry) ? @template.call(entry) : entry)
         return if string.nil?
@@ -105,12 +114,16 @@ module Lumberjack
       end
 
       # Close the underlying stream.
+      #
+      # @return [void]
       def close
         flush
         stream.close
       end
 
       # Flush the underlying stream.
+      #
+      # @return [void]
       def flush
         lines = nil
         @lock.synchronize do
@@ -120,10 +133,17 @@ module Lumberjack
         write_to_stream(lines) if lines
       end
 
+      # Get the datetime format.
+      #
+      # @return [String] The datetime format.
       def datetime_format
         @template.datetime_format if @template.respond_to?(:datetime_format)
       end
 
+      # Set the datetime format.
+      #
+      # @param [String] format The datetime format.
+      # @return [void]
       def datetime_format=(format)
         if @template.respond_to?(:datetime_format=)
           @template.datetime_format = format
@@ -133,14 +153,10 @@ module Lumberjack
       protected
 
       # Set the underlying stream.
-      def stream=(stream)
-        @stream = stream
-      end
+      attr_writer :stream
 
       # Get the underlying stream.
-      def stream
-        @stream
-      end
+      attr_reader :stream
 
       private
 
@@ -149,10 +165,10 @@ module Lumberjack
         lines = lines.first if lines.is_a?(Array) && lines.size == 1
 
         out = nil
-        if lines.is_a?(Array)
-          out = "#{lines.join(Lumberjack::LINE_SEPARATOR)}#{Lumberjack::LINE_SEPARATOR}"
+        out = if lines.is_a?(Array)
+          "#{lines.join(Lumberjack::LINE_SEPARATOR)}#{Lumberjack::LINE_SEPARATOR}"
         else
-          out = "#{lines}#{Lumberjack::LINE_SEPARATOR}"
+          "#{lines}#{Lumberjack::LINE_SEPARATOR}"
         end
 
         begin
@@ -170,9 +186,13 @@ module Lumberjack
               end
             end
           end
-          stream.flush rescue nil
+          begin
+            stream.flush
+          rescue
+            nil
+          end
         rescue => e
-          $stderr.write("#{e.class.name}: #{e.message}#{' at ' + e.backtrace.first if e.backtrace}")
+          $stderr.write("#{e.class.name}: #{e.message}#{" at " + e.backtrace.first if e.backtrace}")
           $stderr.write(out)
           $stderr.flush
         end

data/lib/lumberjack/device.rb

@@ -4,38 +4,53 @@ module Lumberjack
   # This is an abstract class for logging devices. Subclasses must implement the +write+ method and
   # may implement the +close+ and +flush+ methods if applicable.
   class Device
-    require_relative "device/writer.rb"
-    require_relative "device/log_file.rb"
-    require_relative "device/rolling_log_file.rb"
-    require_relative "device/date_rolling_log_file.rb"
-    require_relative "device/size_rolling_log_file.rb"
-    require_relative "device/multi.rb"
-    require_relative "device/null.rb"
+    require_relative "device/writer"
+    require_relative "device/log_file"
+    require_relative "device/rolling_log_file"
+    require_relative "device/date_rolling_log_file"
+    require_relative "device/size_rolling_log_file"
+    require_relative "device/multi"
+    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

@@ -5,13 +5,13 @@ module Lumberjack
     # 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
-      
+
+      # @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
-      
+
       def call(obj)
         if @format && obj.respond_to?(:strftime)
           obj.strftime(@format)

data/lib/lumberjack/formatter/exception_formatter.rb

@@ -7,9 +7,10 @@ module Lumberjack
     # 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
 
+      # @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
@@ -33,7 +34,6 @@ module Lumberjack
           trace
         end
       end
-
     end
   end
 end

data/lib/lumberjack/formatter/id_formatter.rb

@@ -6,14 +6,15 @@ 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
-      
+
       def call(obj)
         if obj.respond_to?(@id_attribute)
           id = obj.send(@id_attribute)
-          { "class" => obj.class.name, "id" => id }
+          {"class" => obj.class.name, "id" => id}
         else
           obj.to_s
         end

data/lib/lumberjack/formatter/pretty_print_formatter.rb

@@ -1,20 +1,22 @@
 # 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).
+      #
+      # @param [Integer] width The maximum width of the message.
       def initialize(width = 79)
         @width = width
       end
-      
+
       def call(obj)
         s = StringIO.new
         PP.pp(obj, s)

data/lib/lumberjack/formatter/structured_formatter.rb

@@ -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_literals: 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

@@ -12,25 +12,28 @@ module Lumberjack
   #
   # Enumerable objects (including Hash and Array) will call the formatter recursively for each element.
   class Formatter
-    require_relative "formatter/date_time_formatter.rb"
-    require_relative "formatter/exception_formatter.rb"
-    require_relative "formatter/id_formatter.rb"
-    require_relative "formatter/inspect_formatter.rb"
-    require_relative "formatter/object_formatter.rb"
-    require_relative "formatter/pretty_print_formatter.rb"
-    require_relative "formatter/string_formatter.rb"
-    require_relative "formatter/strip_formatter.rb"
-    require_relative "formatter/structured_formatter.rb"
+    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"
+    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
     end
-    
+
     def initialize
       @class_formatters = {}
       @module_formatters = {}
@@ -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
+          formatter_class_name = "#{formatter.to_s.gsub(/(^|_)([a-z])/) { |m| $~[2].upcase }}Formatter"
+        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)
@@ -106,18 +142,23 @@ module Lumberjack
       end
       self
     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 && formatter.respond_to?(:call)
+      if formatter&.respond_to?(:call)
         formatter.call(message)
       else
         message
@@ -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,9 +179,9 @@ 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
-      while klass != nil do
+      until klass.nil?
         formatter = @class_formatters[klass.name]
         return formatter if formatter
 

data/lib/lumberjack/log_entry.rb

@@ -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))
@@ -17,10 +25,10 @@ module Lumberjack
       @progname = progname
       @pid = pid
       # backward compatibility with 1.0 API where the last argument was the unit of work id
-      if tags.nil? || tags.is_a?(Hash)
-        @tags = tags
+      @tags = if tags.nil? || tags.is_a?(Hash)
+        tags
       else
-        @tags = { UNIT_OF_WORK_ID => tags }
+        {UNIT_OF_WORK_ID => tags}
       end
     end
 
@@ -29,7 +37,7 @@ module Lumberjack
     end
 
     def to_s
-      "[#{time.strftime(TIME_FORMAT)}.#{(time.usec / 1000.0).round.to_s.rjust(3, '0')} #{severity_label} #{progname}(#{pid})#{tags_to_s}] #{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
@@ -46,10 +54,10 @@ module Lumberjack
       if tags
         tags[UNIT_OF_WORK_ID] = value
       else
-        @tags = { UNIT_OF_WORK_ID => value }
+        @tags = {UNIT_OF_WORK_ID => value}
       end
     end
-    
+
     # Return the tag with the specified name.
     def tag(name)
       tags[name.to_s] if tags
@@ -58,10 +66,8 @@ module Lumberjack
     private
 
     def tags_to_s
-      tags_string = String.new
-      if tags
-        tags.each { |name, value| tags_string << " #{name}:#{value.inspect}" }
-      end
+      tags_string = ""
+      tags&.each { |name, value| tags_string << " #{name}:#{value.inspect}" }
       tags_string
     end
   end