lumberjack 1.4.2 → 2.0.0

data/lib/lumberjack/template.rb

@@ -1,50 +1,175 @@
 # frozen_string_literal: true
 
 module Lumberjack
-  # A template converts entries to strings. Templates can contain the following place holders to
-  # reference log entry values:
+  # A flexible template system for converting log entries into formatted strings.
+  # Templates use mustache style placeholders to create customizable log output formats.
   #
-  # * :time
-  # * :severity
-  # * :progname
-  # * :tags
-  # * :message
+  # The template system supports the following built-in placeholders:
   #
-  # Any other words prefixed with a colon will be substituted with the value of the tag with that name.
-  # If your tag name contains characters other than alpha numerics and the underscore, you must surround it
-  # with curly brackets: `:{http.request-id}`.
+  # - <code>{{time}}</code> - The log entry timestamp
+  # - <code>{{severity}}</code> - The severity level (DEBUG, INFO, WARN, ERROR, FATAL). The severity
+  #   can also be formatted in a variety of ways with an optional format specifier.
+  #   Supported formats include:
+  #   - <code>{{severity(padded)}}</code> - Right padded so that all values are five characters
+  #   - <code>{{severity(char)}}</code> - Single character representation (D, I, W, E, F)
+  #   - <code>{{severity(emoji)}}</code> - Emoji representation
+  #   - <code>{{severity(level)}}</code> - Numeric level representation
+  # - <code>{{progname}}</code> - The program name that generated the entry
+  # - <code>{{pid}}</code> - The process ID
+  # - <code>{{message}}</code> - The main log message content
+  # - <code>{{attributes}}</code> - All custom attributes formatted as key:value pairs
+  #
+  # Custom attribute placeholders can also be put in the double bracket placeholders.
+  # Any attributes explicitly added to the template in their own placeholder will be removed
+  # from the general list of attributes.
+  #
+  # @example Basic template usage
+  #   template = Lumberjack::Template.new("[{{time}} {{severity}}] {{message}}")
+  #   # Output: [2023-08-21T10:30:15.123 INFO] User logged in
+  #
+  # @example Multi-line message formatting
+  #   template = Lumberjack::Template.new(
+  #     "[{{time}} {{severity}}] {{message}}",
+  #     additional_lines: "\n    | {{message}}"
+  #   )
+  #   # Output:
+  #   # [2023-08-21T10:30:15.123 INFO] First line
+  #   #     | Second line
+  #   #     | Third line
+  #
+  # @example Custom attribute placeholders
+  #   # The user_id attribute will be put before the message instead of with the rest of the attributes.
+  #   template = Lumberjack::Template.new("[{{time}} {{severity}}] (usr:{{user_id}} {{message}} -- {{attributes}})")
   class Template
-    TEMPLATE_ARGUMENT_ORDER = %w[:time :severity :progname :pid :message :tags].freeze
+    DEFAULT_FIRST_LINE_TEMPLATE = "[{{time}} {{severity(padded)}} {{progname}}({{pid}})] {{message}} {{attributes}}"
+    STDLIB_FIRST_LINE_TEMPLATE = "{{severity(char)}}, [{{time}} {{pid}}] {{severity(padded)}} -- {{progname}}: {{message}} {{attributes}}"
+    DEFAULT_ADDITIONAL_LINES_TEMPLATE = "#{Lumberjack::LINE_SEPARATOR}> {{message}}"
+    DEFAULT_ATTRIBUTE_FORMAT = "[%s:%s]"
+
+    TemplateRegistry.add(:default, DEFAULT_FIRST_LINE_TEMPLATE)
+    TemplateRegistry.add(:stdlib, STDLIB_FIRST_LINE_TEMPLATE)
+    TemplateRegistry.add(:message, "{{message}}")
+
+    # A wrapper template that delegates formatting to a standard Ruby Logger formatter.
+    # This provides compatibility with existing Logger::Formatter implementations while
+    # maintaining the Template interface for consistent usage within Lumberjack.
+    class StandardFormatterTemplate < Template
+      # Create a new wrapper for a standard Ruby Logger formatter.
+      #
+      # @param formatter [Logger::Formatter] The formatter to wrap
+      def initialize(formatter)
+        @formatter = formatter
+      end
+
+      # Format a log entry using the wrapped formatter.
+      #
+      # @param entry [Lumberjack::LogEntry] The log entry to format
+      # @return [String] The formatted log entry
+      def call(entry)
+        @formatter.call(entry.severity_label, entry.time, entry.progname, entry.message)
+      end
+
+      # Set the datetime format on the wrapped formatter if supported.
+      #
+      # @param value [String] The datetime format string
+      # @return [void]
+      def datetime_format=(value)
+        @formatter.datetime_format = value if @formatter.respond_to?(:datetime_format=)
+      end
+
+      # Get the datetime format from the wrapped formatter if supported.
+      #
+      # @return [String, nil] The datetime format string, or nil if not supported
+      def datetime_format
+        @formatter.datetime_format if @formatter.respond_to?(:datetime_format)
+      end
+    end
+
+    TEMPLATE_ARGUMENT_ORDER = %w[
+      time
+      severity
+      severity(padded)
+      severity(char)
+      severity(emoji)
+      severity(level)
+      progname
+      pid
+      message
+      attributes
+    ].freeze
+
     MILLISECOND_TIME_FORMAT = "%Y-%m-%dT%H:%M:%S.%3N"
     MICROSECOND_TIME_FORMAT = "%Y-%m-%dT%H:%M:%S.%6N"
-    PLACEHOLDER_PATTERN = /:(([a-z0-9_]+)|({[^}]+}))/i.freeze
+    PLACEHOLDER_PATTERN = /{{ *((?:[^}]|}(?!}))*) *}}/i
+    V1_PLACEHOLDER_PATTERN = /:[a-z0-9_.-]+/i
+    RESET_CHAR = "\e[0m"
+    private_constant :TEMPLATE_ARGUMENT_ORDER, :MILLISECOND_TIME_FORMAT, :MICROSECOND_TIME_FORMAT, :PLACEHOLDER_PATTERN, :V1_PLACEHOLDER_PATTERN, :RESET_CHAR
 
-    # Create a new template from the markup. The +first_line+ argument is used to format only the first
-    # line of a message. Additional lines will be added to the message unformatted. If you wish to format
-    # the additional lines, use the :additional_lines options to specify a template. Note that you'll need
-    # to provide the line separator character in this template if you want to keep the message on multiple lines.
-    #
-    # The time will be formatted as YYYY-MM-DDTHH:MM:SSS.SSS by default. If you wish to change the format, you
-    # can specify the :time_format option which can be either a time format template as documented in
-    # +Time#strftime+ or the values +:milliseconds+ or +:microseconds+ to use the standard format with the
-    # specified precision.
-    #
-    # Messages will have white space stripped from both ends.
+    class << self
+      def colorize_entry(formatted_string, entry)
+        color_start = entry.severity_data.terminal_color
+        formatted_string.split(Lumberjack::LINE_SEPARATOR).collect do |line|
+          "\e7#{color_start}#{line}\e8"
+        end.join(Lumberjack::LINE_SEPARATOR)
+      end
+    end
+
+    # Create a new template with customizable formatting options. The template
+    # supports different formatting for single-line and multi-line messages,
+    # custom time formatting, and configurable attribute display.
     #
-    # @param [String] first_line The template to use to format the first line of a message.
-    # @param [Hash] options The options for the template.
-    def initialize(first_line, options = {})
-      @first_line_template, @first_line_tags = compile(first_line)
-      additional_lines = options[:additional_lines] || "#{Lumberjack::LINE_SEPARATOR}:message"
-      @additional_line_template, @additional_line_tags = compile(additional_lines)
+    # @param first_line [String, nil] Template for formatting the first line of messages.
+    #   Defaults to <code>[{{ time }} {{ severity(padded) }} {{ progname }}({{ pid }})] {{ message }} {{ attributes }}</code>
+    # @param additional_lines [String, nil] Template for formatting additional lines
+    #   in multi-line messages. Defaults to <code>\\n> {{ message }}</code>
+    # @param time_format [String, Symbol, nil] Time formatting specification. Can be:
+    #   - A strftime format string (e.g., "%Y-%m-%d %H:%M:%S")
+    #   - +:milliseconds+ for ISO format with millisecond precision (default)
+    #   - +:microseconds+ for ISO format with microsecond precision
+    # @param attribute_format [String, nil] Printf-style format for individual attributes.
+    #   Must contain exactly two %s placeholders for name and value. Defaults to "[%s:%s]"
+    # @param colorize [Boolean] Whether to colorize the log entry based on severity (default: false)
+    # @raise [ArgumentError] If attribute_format doesn't contain exactly two %s placeholders
+    def initialize(first_line = nil, additional_lines: nil, time_format: nil, attribute_format: nil, colorize: false)
+      first_line ||= DEFAULT_FIRST_LINE_TEMPLATE
+      first_line = "#{first_line.chomp}#{Lumberjack::LINE_SEPARATOR}"
+      if !first_line.include?("{{") && first_line.match?(V1_PLACEHOLDER_PATTERN)
+        Utils.deprecated("Template.v1", "Templates now use {{placeholder}} instead of :placeholder and :tags has been replaced with {{attributes}}.") do
+          @first_line_template, @first_line_attributes = compile_v1(first_line)
+        end
+      else
+        @first_line_template, @first_line_attributes = compile(first_line)
+      end
+
+      additional_lines ||= DEFAULT_ADDITIONAL_LINES_TEMPLATE
+      if !additional_lines.include?("{{") && additional_lines.match?(V1_PLACEHOLDER_PATTERN)
+        Utils.deprecated("Template.v1", "Templates now use {{placeholder}} instead of :placeholder and :tags has been replaced with {{attributes}}.") do
+          @additional_line_template, @additional_line_attributes = compile_v1(additional_lines)
+        end
+      else
+        @additional_line_template, @additional_line_attributes = compile(additional_lines)
+      end
+
+      @attribute_template = attribute_format || DEFAULT_ATTRIBUTE_FORMAT
+      unless @attribute_template.scan("%s").size == 2
+        raise ArgumentError.new("attribute_format must be a printf template with exactly two '%s' placeholders")
+      end
+
       # Formatting the time is relatively expensive, so only do it if it will be used
-      @template_include_time = first_line.include?(":time") || additional_lines.include?(":time")
-      self.datetime_format = (options[:time_format] || :milliseconds)
+      @template_include_time = "#{@first_line_template} #{@additional_line_template}".include?("%1$s")
+      self.datetime_format = (time_format || :milliseconds)
+
+      @colorize = colorize
     end
 
-    # Set the format used to format the time.
+    # Set the datetime format used for timestamp formatting in the template.
+    # This method accepts both strftime format strings and symbolic shortcuts.
     #
-    # @param [String] format The format to use to format the time.
+    # @param format [String, Symbol] The datetime format specification:
+    #   - String: A strftime format pattern (e.g., "%Y-%m-%d %H:%M:%S")
+    #   - +:milliseconds+: ISO format with millisecond precision (YYYY-MM-DDTHH:MM:SS.sss)
+    #   - +:microseconds+: ISO format with microsecond precision (YYYY-MM-DDTHH:MM:SS.ssssss)
+    # @return [void]
     def datetime_format=(format)
       if format == :milliseconds
         format = MILLISECOND_TIME_FORMAT
@@ -54,17 +179,19 @@ module Lumberjack
       @time_formatter = Formatter::DateTimeFormatter.new(format)
     end
 
-    # Get the format used to format the time.
+    # Get the current datetime format string used for timestamp formatting.
     #
-    # @return [String]
+    # @return [String] The strftime format string currently in use
     def datetime_format
       @time_formatter.format
     end
 
-    # Convert an entry into a string using the template.
+    # Convert a log entry into a formatted string using the template. This method
+    # handles both single-line and multi-line messages, applying the appropriate
+    # templates and performing placeholder substitution.
     #
-    # @param [Lumberjack::LogEntry] entry The entry to convert to a string.
-    # @return [String] The entry converted to a string.
+    # @param entry [Lumberjack::LogEntry] The log entry to format
+    # @return [String] The formatted log entry string
     def call(entry)
       return entry unless entry.is_a?(LogEntry)
 
@@ -76,58 +203,121 @@ module Lumberjack
       end
 
       formatted_time = @time_formatter.call(entry.time) if @template_include_time
-      format_args = [formatted_time, entry.severity_label, entry.progname, entry.pid, first_line]
-      tag_arguments = tag_args(entry.tags, @first_line_tags)
-      message = (@first_line_template % (format_args + tag_arguments))
-      message.rstrip! if message.end_with?(" ")
+      severity = entry.severity_data
+      format_args = [
+        formatted_time,
+        severity.label,
+        severity.padded_label,
+        severity.char,
+        severity.emoji,
+        severity.level,
+        entry.progname,
+        entry.pid,
+        first_line
+      ]
+      append_attribute_args!(format_args, entry.attributes, @first_line_attributes)
+      message = (@first_line_template % format_args)
 
       if additional_lines && !additional_lines.empty?
-        tag_arguments = tag_args(entry.tags, @additional_line_tags) unless @additional_line_tags == @first_line_tags
+        format_args.slice!(9, format_args.size)
+        append_attribute_args!(format_args, entry.attributes, @additional_line_attributes)
+
+        message_length = message.length
+        message.chomp!(Lumberjack::LINE_SEPARATOR)
+        chomped = message.length != message_length
+
         additional_lines.each do |line|
-          format_args[format_args.size - 1] = line
-          line_message = (@additional_line_template % (format_args + tag_arguments)).rstrip
-          line_message.rstrip! if line_message.end_with?(" ")
+          format_args[8] = line
+          line_message = @additional_line_template % format_args
           message << line_message
         end
+
+        message << Lumberjack::LINE_SEPARATOR if chomped
       end
+
+      message = Template.colorize_entry(message, entry) if @colorize
+
       message
     end
 
     private
 
-    def tag_args(tags, tag_vars)
-      return [nil] * (tag_vars.size + 1) if tags.nil? || tags.size == 0
+    # Build the arguments array for sprintf formatting by appending attribute values.
+    # This method handles both the general :attributes placeholder and specific
+    # attribute placeholders defined in the template.
+    #
+    # @param args [Array] The existing format arguments array to modify
+    # @param attributes [Hash, nil] The log entry attributes hash
+    # @param attribute_vars [Array<String>] List of specific attribute names used in template
+    # @return [void]
+    def append_attribute_args!(args, attributes, attribute_vars)
+      if attributes.nil? || attributes.size == 0
+        (attribute_vars.length + 1).times { args << nil }
+        return
+      end
 
-      tags_string = +""
-      Lumberjack::Utils.flatten_tags(tags).each do |name, value|
-        unless value.nil? || tag_vars.include?(name)
+      attributes_string = +""
+      attributes.each do |name, value|
+        unless value.nil? || attribute_vars.include?(name)
           value = value.to_s
           value = value.gsub(Lumberjack::LINE_SEPARATOR, " ") if value.include?(Lumberjack::LINE_SEPARATOR)
-          tags_string << "[#{name}:#{value}] "
+          attributes_string << " "
+          attributes_string << @attribute_template % [name, value]
         end
       end
 
-      args = [tags_string.chop]
-      tag_vars.each do |name|
-        args << tags[name]
+      args << attributes_string
+      attribute_vars.each do |name|
+        args << attributes[name]
       end
-      args
     end
 
-    # Compile the template string into a value that can be used with sprintf.
+    # Parse and compile a template string into a sprintf-compatible format string
+    # and extract attribute variable names. This method handles placeholder
+    # substitution and escape sequence processing.
+    #
+    # @param template [String] The raw template string with placeholders
+    # @return [Array<String, Array<String>>] A tuple of [compiled_template, attribute_vars]
     def compile(template) # :nodoc:
-      tag_vars = []
+      template = template.gsub(/ ({{ *)attributes( *}})/, "\\1attributes\\2")
+      template = template.gsub(/%(?!%)/, "%%")
+
+      attribute_vars = []
       template = template.gsub(PLACEHOLDER_PATTERN) do |match|
-        var_name = match.sub("{", "").sub("}", "")
+        var_name = match.sub(/{{ */, "").sub(/ *}}/, "")
+        position = TEMPLATE_ARGUMENT_ORDER.index(var_name)
+        if position
+          "%#{position + 1}$s"
+        else
+          attribute_vars << var_name
+          "%#{TEMPLATE_ARGUMENT_ORDER.size + attribute_vars.size}$s"
+        end
+      end
+      [template, attribute_vars]
+    end
+
+    # Parse and compile a template string into a sprintf-compatible format string
+    # and extract attribute variable names. This method handles placeholder
+    # substitution and escape sequence processing.
+    #
+    # @param template [String] The raw template string with placeholders
+    # @return [Array<String, Array<String>>] A tuple of [compiled_template, attribute_vars]
+    def compile_v1(template) # :nodoc:
+      template = template.gsub(":tags", ":attributes").gsub(/ ?:attributes/, ":attributes")
+      template = template.gsub(/%(?!%)/, "%%")
+
+      attribute_vars = []
+      template = template.gsub(V1_PLACEHOLDER_PATTERN) do |match|
+        var_name = match[1, match.length]
         position = TEMPLATE_ARGUMENT_ORDER.index(var_name)
         if position
           "%#{position + 1}$s"
         else
-          tag_vars << var_name[1, var_name.length]
-          "%#{TEMPLATE_ARGUMENT_ORDER.size + tag_vars.size}$s"
+          attribute_vars << var_name
+          "%#{TEMPLATE_ARGUMENT_ORDER.size + attribute_vars.size}$s"
         end
       end
-      [template, tag_vars]
+      [template, attribute_vars]
     end
   end
 end

data/lib/lumberjack/template_registry.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  class TemplateRegistry
+    @templates = {}
+
+    class << self
+      # Register a log template class with a symbol.
+      #
+      # @param name [Symbol] The name of the template.
+      # @param template [String, Class, #call] The log template to register.
+      def add(name, template)
+        unless template.is_a?(String) || template.is_a?(Class) || template.respond_to?(:call)
+          raise ArgumentError.new("template must be a String, Class, or respond to :call")
+        end
+
+        @templates[name.to_sym] = template
+      end
+
+      # Remove a template from the registry.        raise ArgumentError.new("template must be a String, Class, or respond to :call")
+      #
+      # @param name [Symbol] The name of the template to remove.
+      # @return [void]
+      def remove(name)
+        @templates.delete(name.to_sym)
+      end
+
+      # Check if a template is registered.
+      #
+      # @param name [Symbol] The name of the template.
+      # @return [Boolean] True if the template is registered, false otherwise.
+      def registered?(name)
+        @templates.include(name.to_sym)
+      end
+
+      # Get a registered log template class by its symbol.
+      #
+      # @param name [Symbol] The symbol of the registered log template class.
+      # @return [Class, nil] The registered log template class, or nil if not found.
+      def template(name, options = {})
+        template = @templates[name.to_sym]
+        if template.is_a?(Class)
+          template.new(options)
+        elsif template.is_a?(String)
+          template_options = options.slice(:additional_lines, :time_format, :attribute_format, :colorize)
+          Template.new(template, **template_options)
+        else
+          template
+        end
+      end
+
+      # List all registered log template symbols.
+      #
+      # @return [Array<Symbol>] An array of all registered log template symbols.
+      def registered_templates
+        @templates.dup
+      end
+    end
+  end
+end