lumberjack 1.4.2 → 2.0.0

data/lib/lumberjack/formatter/multiply_formatter.rb

@@ -4,7 +4,12 @@ module Lumberjack
   class Formatter
     # This formatter can be used to multiply a numeric value by a specified multiplier and
     # optionally round to a specified number of decimal places.
+    #
+    # This is useful for unit conversions (e.g., converting seconds to milliseconds)
+    # or scaling values for display purposes. Non-numeric values are passed through unchanged.
     class MultiplyFormatter
+      FormatterRegistry.add(:multiply, self)
+
       # @param multiplier [Numeric] The multiplier to apply to the value.
       # @param decimals [Integer, nil] The number of decimal places to round the result to.
       #   If nil, no rounding is applied.
@@ -13,6 +18,11 @@ module Lumberjack
         @decimals = decimals
       end
 
+      # Multiply a numeric value by the configured multiplier and optionally round.
+      #
+      # @param value [Object] The value to format. Only numeric values are processed.
+      # @return [Numeric, Object] The multiplied (and optionally rounded) value if numeric,
+      #   otherwise returns the original value unchanged.
       def call(value)
         return value unless value.is_a?(Numeric)
 

data/lib/lumberjack/formatter/object_formatter.rb

@@ -2,8 +2,20 @@
 
 module Lumberjack
   class Formatter
-    # No-op formatter that just returns the object itself.
+    # No-op formatter that returns the object unchanged. This formatter is useful
+    # as a default or fallback formatter when you want to preserve the original
+    # object without any transformation.
+    #
+    # The ObjectFormatter is commonly used in scenarios where you want to maintain
+    # the original data structure and let downstream components handle the actual
+    # formatting, or when you need a placeholder formatter in the formatter chain.
     class ObjectFormatter
+      FormatterRegistry.add(:object, self)
+
+      # Return the object unchanged.
+      #
+      # @param obj [Object] The object to format.
+      # @return [Object] The original object without any modifications.
       def call(obj)
         obj
       end

data/lib/lumberjack/formatter/pretty_print_formatter.rb

@@ -5,18 +5,31 @@ require "stringio"
 
 module Lumberjack
   class Formatter
-    # Format an object with it's pretty print method.
+    # Format an object with its pretty print method. This formatter provides multi-line,
+    # indented output that makes complex data structures easier to read and debug.
+    # It's particularly useful for logging hashes, arrays, and other nested objects.
+    #
+    # The formatter uses Ruby's built-in PP (Pretty Print) library to generate
+    # well-formatted output with appropriate indentation and line breaks.
     class PrettyPrintFormatter
+      FormatterRegistry.add(:pretty_print, self)
+
+      # @!attribute [rw] width
+      #   @return [Integer] The maximum width of the message.
       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.
+      # @param width [Integer] The maximum width of the message.
       def initialize(width = 79)
         @width = width
       end
 
+      # Format an object using pretty print with the configured width.
+      #
+      # @param obj [Object] The object to format.
+      # @return [String] The pretty-printed representation of the object.
       def call(obj)
         s = StringIO.new
         PP.pp(obj, s)

data/lib/lumberjack/formatter/redact_formatter.rb

@@ -2,16 +2,31 @@
 
 module Lumberjack
   class Formatter
-    # Log sensitive information in a redacted format showing the firat and last
+    # Log sensitive information in a redacted format showing the first and last
     # characters of the value, with the rest replaced by asterisks. The number of
-    # characters shown is dependent onthe length of the value; short values will
+    # characters shown is dependent on the length of the value; short values will
     # not show any characters in order to avoid revealing too much information.
+    #
+    # This formatter is useful for logging sensitive data while still providing
+    # enough context to distinguish between different values during debugging.
     class RedactFormatter
+      FormatterRegistry.add(:redact, self)
+
+      # Redact a string value by showing only the first and last characters.
+      #
+      # @param obj [Object] The object to format. Only strings are redacted.
+      # @return [String, Object] The redacted string if the object is a string,
+      #   otherwise returns the object unchanged.
+      #
+      # @example Different string lengths
+      #   formatter.call("password123")     # => "pa*******23"
+      #   formatter.call("secret")          # => "s****t"
+      #   formatter.call("abc")             # => "*****"
       def call(obj)
         return obj unless obj.is_a?(String)
 
         if obj.length > 8
-          "#{obj[0..1]}#{"*" * (obj.length - 4)}#{obj[-2..-1]}"
+          "#{obj[0..1]}#{"*" * (obj.length - 4)}#{obj[-2..]}"
         elsif obj.length > 5
           "#{obj[0]}#{"*" * (obj.length - 2)}#{obj[-1]}"
         else

data/lib/lumberjack/formatter/round_formatter.rb

@@ -4,11 +4,23 @@ module Lumberjack
   class Formatter
     # Round numeric values to a set number of decimal places. This is useful when logging
     # floating point numbers to reduce noise and rounding errors in the logs.
+    #
+    # The formatter only affects numeric values, leaving other object types unchanged.
+    # This makes it safe to use as a general-purpose formatter for attributes that
+    # might contain various data types.
     class RoundFormatter
+      FormatterRegistry.add(:round, self)
+
+      # @param precision [Integer] The number of decimal places to round to (defaults to 3).
       def initialize(precision = 3)
         @precision = precision
       end
 
+      # Round a numeric value to the configured precision.
+      #
+      # @param obj [Object] The object to format. Only numeric values are rounded.
+      # @return [Numeric, Object] The rounded number if the object is numeric,
+      #   otherwise returns the object unchanged.
       def call(obj)
         if obj.is_a?(Numeric)
           obj.round(@precision)

data/lib/lumberjack/formatter/string_formatter.rb

@@ -2,8 +2,16 @@
 
 module Lumberjack
   class Formatter
-    # Format an object by calling `to_s` on it.
+    # Format an object by calling +to_s+ on it. This is the simplest formatter
+    # implementation and is commonly used as a fallback for objects that don't
+    # have specialized formatters.
     class StringFormatter
+      FormatterRegistry.add(:string, self)
+
+      # Convert an object to its string representation.
+      #
+      # @param obj [Object] The object to format.
+      # @return [String] The string representation of the object.
       def call(obj)
         obj.to_s
       end

data/lib/lumberjack/formatter/strip_formatter.rb

@@ -2,8 +2,20 @@
 
 module Lumberjack
   class Formatter
-    # Format an object by calling `to_s` on it and stripping leading and trailing whitespace.
+    # Format an object by calling +to_s+ on it and stripping leading and trailing whitespace.
+    # This formatter is useful for cleaning up string values that may have unwanted whitespace
+    # from user input, file processing, or other sources.
+    #
+    # The StripFormatter combines string conversion with whitespace normalization,
+    # making it ideal for attribute values that should be clean and consistent
+    # in log output.
     class StripFormatter
+      FormatterRegistry.add(:strip, self)
+
+      # Convert an object to a string and remove leading and trailing whitespace.
+      #
+      # @param obj [Object] The object to format.
+      # @return [String] The string representation with whitespace stripped.
       def call(obj)
         obj.to_s.strip
       end

data/lib/lumberjack/formatter/structured_formatter.rb

@@ -5,16 +5,31 @@ require "set"
 module Lumberjack
   class Formatter
     # Dereference arrays and hashes and recursively call formatters on each element.
+    # This formatter provides deep traversal of nested data structures, applying
+    # formatting to all contained elements while handling circular references safely.
+    #
+    # The StructuredFormatter is essential for formatting complex nested objects
+    # like configuration hashes, API responses, or any hierarchical data structures
+    # that need consistent formatting throughout their entire structure.
     class StructuredFormatter
+      FormatterRegistry.add(:structured, self)
+
+      # Exception raised when a circular reference is detected during traversal.
+      # This prevents infinite recursion when formatting objects that reference themselves.
       class RecusiveReferenceError < StandardError
       end
 
-      # @param [Formatter] formatter The formatter to call on each element
-      #   in the structure.
+      # @param formatter [Formatter, nil] The formatter to call on each element
+      #   in the structure. If nil, elements are returned unchanged.
       def initialize(formatter = nil)
         @formatter = formatter
       end
 
+      # Format a structured object by recursively processing all nested elements.
+      #
+      # @param obj [Object] The object to format. Arrays and hashes are traversed
+      #   recursively, while other objects are passed to the configured formatter.
+      # @return [Object] The formatted structure with all nested elements processed.
       def call(obj)
         call_with_references(obj, Set.new)
       end
@@ -50,6 +65,7 @@ module Lumberjack
       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

data/lib/lumberjack/formatter/tagged_message.rb

@@ -1,38 +1,16 @@
 # frozen_string_literal: true
 
-module Lumberjack
-  class Formatter
-    # This class can be used as the return value from a formatter `call` method to
-    # extract additional tags from an object being logged. This can be useful when there
-    # using structured logging to include important metadata in the log message.
-    #
-    # @example
-    #  # Automatically add tags with error details when logging an exception.
-    #  logger.add_formatter(Exception, ->(e) {
-    #    Lumberjack::Formatter::TaggedMessage.new(e.message, {
-    #      error: {
-    #        message: e.message,
-    #        class: e.class.name,
-    #        trace: e.backtrace
-    #      }
-    #    })
-    #  })
-    class TaggedMessage
-      attr_reader :message, :tags
-
-      # @param [Formatter] formatter The formatter to apply the transformation to.
-      # @param [Proc] transform The transformation function to apply to the formatted string.
-      def initialize(message, tags)
-        @message = message
-        @tags = tags || {}
-      end
+require_relative "../message_attributes"
 
-      def to_s
-        inspect
-      end
-
-      def inspect
-        {message: @message, tags: @tags}.inspect
+module Lumberjack
+  # This is a deprecated alias for Lumberjack::MessageAttributes.
+  #
+  # @deprecated Use Lumberjack::MessageAttributes instead.
+  # @see MessageAttributes
+  class Formatter::TaggedMessage < MessageAttributes
+    def initialize(message, attributes)
+      Utils.deprecated("Lumberjack::Formatter::TaggedMessage", "Use Lumberjack::MessageAttributes instead.") do
+        super
       end
     end
   end

data/lib/lumberjack/formatter/tags_formatter.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  # This formatter is designed to output tags in a specific format.
+  #
+  # - Simple values will be formatted as "[value]"
+  # - Arrays will be formatted as "[value1] [value2] [value3]"
+  # - Hashes will be formatted as "[key1=value1] [key2=value2]"
+  # - Hashes in arrays will be formatted as "[key=value]"
+  class Formatter::TagsFormatter
+    FormatterRegistry.add(:tags, self)
+
+    def call(tags)
+      tags = tags.collect { |key, value| "#{key}=#{value}" } if tags.is_a?(Hash)
+      if tags.is_a?(Array)
+        tags.collect { |tag| format_tag(tag) }.join(" ") unless tags.empty?
+      else
+        format_tag(tags)
+      end
+    end
+
+    private
+
+    def format_tag(tag)
+      if tag.is_a?(Hash)
+        tag.collect { |key, value| "[#{key}=#{value.strip}]" }.join(" ")
+      else
+        "[#{tag.strip}]"
+      end
+    end
+  end
+end

data/lib/lumberjack/formatter/truncate_formatter.rb

@@ -10,11 +10,18 @@ module Lumberjack
     # 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)
+      FormatterRegistry.add(:truncate, self)
+
+      # @param length [Integer] The maximum length of the string (defaults to 32K).
       def initialize(length = 32768)
         @length = length
       end
 
+      # Truncate a string if it exceeds the maximum length.
+      #
+      # @param obj [Object] The object to format. If it's a string longer than the maximum
+      #   length, it will be truncated. Other objects are returned unchanged.
+      # @return [String, Object] The truncated string or original object.
       def call(obj)
         if obj.is_a?(String) && obj.length > @length
           "#{obj[0, @length - 1]}…"