filterfish-logging 0.9.8

data/lib/logging/layouts/basic.rb

@@ -0,0 +1,35 @@
+# $Id$
+
+module Logging
+module Layouts
+
+  # The +Basic+ layout class provides methods for simple formatting of log
+  # events. The resulting string follows the format below.
+  #
+  #     LEVEL  LoggerName : log message
+  #
+  # _LEVEL_ is the log level of the event. _LoggerName_ is the name of the
+  # logger that generated the event. <em>log message</em> is the message
+  # or object that was passed to the logger. If multiple message or objects
+  # were passed to the logger then each will be printed on its own line with
+  # the format show above.
+  #
+  class Basic < ::Logging::Layout
+
+    # call-seq:
+    #    format( event )
+    #
+    # Returns a string representation of the given loggging _event_. See the
+    # class documentation for details about the formatting used.
+    #
+    def format( event )
+      obj = format_obj(event.data)
+      sprintf("%*s  %s : %s\n", ::Logging::MAX_LEVEL_LENGTH,
+              ::Logging::LNAMES[event.level], event.logger, obj)
+    end
+
+  end  # class Basic
+end  # module Layouts
+end  # module Logging
+
+# EOF

data/lib/logging/layouts/pattern.rb

@@ -0,0 +1,292 @@
+# $Id$
+
+module Logging
+module Layouts
+
+  # A flexible layout configurable with pattern string.
+  #
+  # The goal of this class is to format a LogEvent and return the results as
+  # a String. The results depend on the conversion pattern.
+  #
+  # The conversion pattern is closely related to the conversion pattern of
+  # the sprintf function. A conversion pattern is composed of literal text
+  # and format control expressions called conversion specifiers.
+  #
+  # You are free to insert any literal text within the conversion pattern.
+  #
+  # Each conversion specifier starts with a percent sign (%) and is followed
+  # by optional format modifiers and a conversion character. The conversion
+  # character specifies the type of data, e.g. logger, level, date, thread
+  # ID. The format modifiers control such things as field width, padding,
+  # left and right justification. The following is a simple example.
+  #
+  # Let the conversion pattern be "%-5l [%c]: %m\n" and assume that the
+  # logging environment was set to use a Pattern layout. Then the statements
+  #
+  #    root = Logging::Logger[:root]
+  #    root.debug("Message 1")
+  #    root.warn("Message 2")
+  #
+  # would yield the output
+  #
+  #    DEBUG [root]: Message 1
+  #    WARN  [root]: Message 2
+  #
+  # Note that there is no explicit separator between text and conversion
+  # specifiers. The pattern parser knows when it has reached the end of a
+  # conversion specifier when it reads a conversion character. In the example
+  # above the conversion specifier %-5l means the level of the logging event
+  # should be left justified to a width of five characters. The recognized
+  # conversion characters are 
+  #
+  #  [c]  Used to output the name of the logger that generated the log
+  #       event.
+  #  [d]  Used to output the date of the log event. The format of the
+  #       date is specified using the :date_pattern option when the Layout
+  #       is created. ISO8601 format is assumed if not date pattern is given.
+  #  [F]  Used to output the file name where the logging request was issued.
+  #  [l]  Used to output the level of the log event.
+  #  [L]  Used to output the line number where the logging request was
+  #       issued.
+  #  [m]  Used to output the application supplied message associated with
+  #       the log event.
+  #  [M]  Used to output the method name where the logging request was
+  #       issued.
+  #  [p]  Used to output the process ID of the currently running program.
+  #  [r]  Used to output the number of milliseconds elapsed from the
+  #       construction of the Layout until creation of the log event.
+  #  [t]  Used to output the object ID of the thread that generated the
+  #       log event.
+  #  [%]  The sequence '%%' outputs a single percent sign.
+  #
+  # The directives F, L, and M will only work if the Logger generating the
+  # events is configured to generate tracing information. If this is not
+  # the case these fields will always be empty.
+  #
+  # By default the relevant information is output as is. However, with the
+  # aid of format modifiers it is possible to change the minimum field width,
+  # the maximum field width and justification.
+  #
+  # The optional format modifier is placed between the percent sign and the
+  # conversion character.
+  #
+  # The first optional format modifier is the left justification flag which
+  # is just the minus (-) character. Then comes the optional minimum field
+  # width modifier. This is a decimal constant that represents the minimum
+  # number of characters to output. If the data item requires fewer
+  # characters, it is padded on either the left or the right until the
+  # minimum width is reached. The default is to pad on the left (right
+  # justify) but you can specify right padding with the left justification
+  # flag. The padding character is space. If the data item is larger than the
+  # minimum field width, the field is expanded to accommodate the data. The
+  # value is never truncated.
+  #
+  # This behavior can be changed using the maximum field width modifier which
+  # is designated by a period followed by a decimal constant. If the data
+  # item is longer than the maximum field, then the extra characters are
+  # removed from the end of the data item.
+  #
+  # Below are various format modifier examples for the category conversion
+  # specifier.
+  # 
+  #  [%20c]      Left pad with spaces if the logger name is less than 20
+  #              characters long
+  #  [%-20c]     Right pad with spaces if the logger name is less than 20
+  #              characters long
+  #  [%.30c]     Truncates the logger name if it is longer than 30 characters
+  #  [%20.30c]   Left pad with spaces if the logger name is shorter than
+  #              20 characters. However, if the logger name is longer than
+  #              30 characters, then truncate the name.
+  #  [%-20.30c]  Right pad with spaces if the logger name is shorter than
+  #              20 characters. However, if the logger name is longer than
+  #              30 characters, then truncate the name.
+  #
+  # Below are examples of some conversion patterns.
+  #
+  #    %.1l, [%d] %5l -- %c: %m\n
+  #
+  # This is how the Logger class in the Ruby standard library formats
+  # messages. The main difference will be in the date format (the Pattern
+  # Layout uses the ISO8601 date format). Set the :date_method on the
+  # Pattern Layout to be 'to_s' and then the date formats will agree.
+  #
+  class Pattern < ::Logging::Layout
+
+    # :stopdoc:
+
+    # Arguments to sprintf keyed to directive letters
+    DIRECTIVE_TABLE = {
+      'c' => 'event.logger',
+      'd' => 'format_date',
+      'F' => 'event.file',
+      'l' => '::Logging::LNAMES[event.level]',
+      'L' => 'event.line',
+      'm' => 'format_obj(event.data)',
+      'M' => 'event.method',
+      'p' => 'Process.pid',
+      'r' => 'Integer((Time.now-@created_at)*1000).to_s',
+      't' => 'Thread.current.object_id.to_s',
+      '%' => :placeholder
+    }
+
+    # Matches the first directive encountered and the stuff around it.
+    #
+    # * $1 is the stuff before directive or "" if not applicable
+    # * $2 is the %#.# match within directive group
+    # * $3 is the directive letter
+    # * $4 is the stuff after the directive or "" if not applicable
+    DIRECTIVE_RGXP = %r/([^%]*)(?:(%-?\d*(?:\.\d+)?)([a-zA-Z%]))?(.*)/m
+
+    # default date format
+    ISO8601 = "%Y-%m-%d %H:%M:%S"
+
+    # call-seq:
+    #    Pattern.create_date_format_methods( pf )
+    #
+    # This method will create the +date_format+ method in the given Pattern
+    # Layout _pf_ based on the configured date patten and/or date method
+    # specified by the user.
+    #
+    def self.create_date_format_methods( pf )
+      code = "undef :format_date if method_defined? :format_date\n"
+      code << "def format_date\n"
+      if pf.date_method.nil?
+        if pf.date_pattern =~ %r/%s/
+          code << <<-CODE
+            now = Time.now
+            dp = '#{pf.date_pattern}'.gsub('%s','%06d' % now.usec)
+            now.strftime dp
+          CODE
+        else
+          code << "Time.now.strftime '#{pf.date_pattern}'\n"
+        end
+      else
+        code << "Time.now.#{pf.date_method}\n"
+      end
+      code << "end\n"
+
+      pf.meta_eval code
+    end
+
+    # call-seq:
+    #    Pattern.create_format_method( pf )
+    #
+    # This method will create the +format+ method in the given Pattern
+    # Layout _pf_ based on the configured format pattern specified by the
+    # user.
+    #
+    def self.create_format_method( pf )
+      # Create the format(event) method
+      code = "undef :format if method_defined? :format\n"
+      code << "def format( event )\nsprintf(\""
+      pattern = pf.pattern.dup
+      args = []
+
+      while true
+        m = DIRECTIVE_RGXP.match(pattern)
+        code << m[1] unless m[1].empty?
+
+        case m[3]
+        when '%'; code << '%%'
+        when *DIRECTIVE_TABLE.keys
+          code << m[2] + 's'
+          args << DIRECTIVE_TABLE[m[3]]
+        when nil; break
+        else
+          raise ArgumentError, "illegal format character - '#{m[3]}'"
+        end
+
+        break if m[4].empty?
+        pattern = m[4]
+      end
+
+      code << '"'
+      code << ', ' + args.join(', ') unless args.empty?
+      code << ")\n"
+      code << "end\n"
+
+      pf.meta_eval code
+    end
+    # :startdoc:
+
+    # call-seq:
+    #    Pattern.new( opts )
+    #
+    # Creates a new Pattern layout using the following options.
+    #
+    #    :pattern       =>  "[%d] %-5l -- %c : %m\n"
+    #    :date_pattern  =>  "%Y-%m-%d %H:%M:%S"
+    #    :date_method   =>  'usec' or 'to_s'
+    #
+    # If used, :date_method will supersede :date_pattern.
+    #
+    def initialize( opts = {} )
+      super
+      @created_at = Time.now
+
+      @date_pattern = opts.getopt(:date_pattern)
+      @date_method = opts.getopt(:date_method)
+      @date_pattern = ISO8601 if @date_pattern.nil? and @date_method.nil?
+
+      @pattern = opts.getopt(:pattern,
+          "[%d] %-#{::Logging::MAX_LEVEL_LENGTH}l -- %c : %m\n")
+
+      Pattern.create_date_format_methods(self)
+      Pattern.create_format_method(self)
+    end
+
+    attr_reader :pattern, :date_pattern, :date_method
+
+    # call-seq:
+    #    appender.pattern = "[%d] %-5l -- %c : %m\n"
+    #
+    # Set the message formatting pattern to be used by the layout.
+    #
+    def pattern=( var )
+      @pattern = var
+      Pattern.create_format_method(self)
+    end
+
+    # call-seq:
+    #    appender.date_pattern = "%Y-%m-%d %H:%M:%S"
+    #
+    # Set the date formatting pattern to be used when outputting timestamps
+    # in the log messages.
+    #
+    def date_pattern=( var )
+      @date_pattern = var
+      Pattern.create_date_format_methods(self)
+    end
+
+    # call-seq:
+    #    appender.date_method = 'to_s'
+    #    appender.date_method = :usec
+    #
+    # Set the date method to be used when outputting timestamps in the log
+    # messages. If a date method is configured, the output of that method
+    # will be used in leu of the date pattern.
+    #
+    def date_method=( var )
+      @date_method = var
+      Pattern.create_date_format_methods(self)
+    end
+
+    # :stopdoc:
+
+    # call-seq:
+    #    meta_eval( code )
+    #
+    # Evaluates the given string of _code_ if the singleton class of this
+    # Pattern Layout object.
+    #
+    def meta_eval( code )
+      meta = class << self; self end
+      meta.class_eval code
+    end
+    # :startdoc:
+
+  end  # class Pattern
+end  # module Layouts
+end  # module Logging
+
+# EOF

data/lib/logging/log_event.rb

@@ -0,0 +1,50 @@
+# $Id$
+
+module Logging
+
+  # This class defines a logging event.
+  #
+  class LogEvent
+
+    # :stopdoc:
+
+    # Regular expression used to parse out caller information
+    #
+    # * $1 == filename
+    # * $2 == line number
+    # * $3 == method name (might be nil)
+    CALLER_RGXP = %r/([\.\/\(\)\w]+):(\d+)(?::in `(\w+)')?/o
+    # :startdoc:
+
+    # call-seq:
+    #    LogEvent.new( logger, level, [data], trace )
+    #
+    # Creates a new log event with the given _logger_ name, numeric _level_,
+    # array of _data_ from the user to be logged, and boolean _trace_ flag.
+    # If the _trace_ flag is set to +true+ then Kernel::caller will be
+    # invoked to get the execution trace of the logging method.
+    #
+    def initialize( logger, level, data, trace )
+      @logger = logger
+      @level = level
+      @data = data
+      @file = @line = @method = ''
+
+      if trace
+        t = Kernel.caller[2]
+        return if t.nil?
+
+        m = CALLER_RGXP.match(t)
+        @file = m[1]
+        @line = m[2]
+        @method = m[3] unless m[3].nil?
+      end
+    end
+
+    attr_accessor :logger, :level, :data
+    attr_reader :file, :line, :method
+
+  end  # class LogEvent
+end  # module Logging
+
+# EOF

data/lib/logging/logger.rb

@@ -0,0 +1,388 @@
+# $Id$
+
+require 'thread'
+
+module Logging
+
+  # The +Logger+ class is the primary interface to the +Logging+ framework.
+  # It provides the logging methods that will be called from user methods,
+  # and it generates logging events that are sent to the appenders (the
+  # appenders take care of sending the log events to the logging
+  # destinations -- files, sockets, etc).
+  #
+  # +Logger+ instances are obtained from the +Repository+ and should
+  # not be directly created by users.
+  #
+  # Example:
+  #
+  #    log = Logging::Logger['my logger']
+  #    log.add_appenders( Logging::Appender.stdout )   # append to STDOUT
+  #    log.level = :info                               # log 'info' and above
+  #
+  #    log.info 'starting foo operation'
+  #    ...
+  #    log.info 'finishing foo operation'
+  #    ...
+  #    log.fatal 'unknown exception', exception
+  #
+  class Logger
+
+    @mutex = Mutex.new  # :nodoc:
+
+    class << self
+
+      # call-seq:
+      #    Logger.root
+      #
+      # Returns the root logger.
+      #
+      def root
+        ::Logging::Repository.instance[:root]
+      end
+
+      # :stopdoc:
+
+      # Overrides the new method such that only one Logger will be created
+      # for any given logger name.
+      #
+      def new( *args )
+        return super if args.empty?
+
+        repo = ::Logging::Repository.instance
+        name = repo.to_key(args.shift)
+
+        @mutex.synchronize do
+          logger = repo[name]
+          if logger.nil?
+            logger = super(name, *args)
+            repo[name] = logger
+          end
+          logger
+        end
+      end
+      alias :[] :new
+
+      # This is where the actual logging methods are defined. Two methods
+      # are created for each log level. The first is a query method used to
+      # determine if that perticular logging level is enabled. The second is
+      # the actual logging method that accepts a list of objects to be
+      # logged or a block. If a block is given, then the object returned
+      # from the block will be logged.
+      #
+      # Example
+      #
+      #    log = Logging::Logger['my logger']
+      #    log.level = :warn
+      #
+      #    log.info?                               # => false
+      #    log.warn?                               # => true
+      #    log.warn 'this is your last warning'
+      #    log.fatal 'I die!', exception
+      #
+      #    log.debug do
+      #      # expensive method to construct log message
+      #      msg
+      #    end
+      #
+      def define_log_methods( logger )
+        ::Logging::LEVELS.each do |name,num|
+          code =  "undef :#{name}  if method_defined? :#{name}\n"
+          code << "undef :#{name}? if method_defined? :#{name}?\n"
+
+          if logger.level > num
+            code << <<-CODE
+              def #{name}?( ) false end
+              def #{name}( data = nil ) false end
+            CODE
+          else
+            code << <<-CODE
+              def #{name}?( ) true end
+              def #{name}( data = nil )
+                data = yield if block_given?
+                log_event(::Logging::LogEvent.new(@name, #{num}, data, @trace))
+                true
+              end
+            CODE
+          end
+
+          logger.meta_eval code
+        end
+      end
+      # :startdoc:
+
+    end  # class << self
+
+    attr_reader :level, :name, :parent, :additive, :trace
+
+    # call-seq:
+    #    Logger.new( name )
+    #    Logger[name]
+    #
+    # Returns the logger identified by _name_.
+    #
+    # When _name_ is a +String+ or a +Symbol+ it will be used "as is" to
+    # retrieve the logger. When _name_ is a +Class+ the class name will be
+    # used to retrieve the logger. When _name_ is an object the name of the
+    # object's class will be used to retrieve the logger.
+    #
+    # Example:
+    #
+    #   obj = MyClass.new
+    #
+    #   log1 = Logger.new(obj)
+    #   log2 = Logger.new(MyClass)
+    #   log3 = Logger['MyClass']
+    #
+    #   log1.object_id == log2.object_id         # => true
+    #   log2.object_id == log3.object_id         # => true
+    #
+    def initialize( name )
+      case name
+      when String
+        raise(ArgumentError, "logger must have a name") if name.empty?
+      else raise(ArgumentError, "logger name must be a String") end
+
+      repo = ::Logging::Repository.instance
+      @name = name
+      @parent = repo.parent(name)
+      @appenders = []
+      @additive = true
+      @trace = false
+      self.level = @parent.level
+
+      repo.children(name).each {|c| c.parent = self}
+    end
+
+    # call-seq:
+    #    log <=> other
+    #
+    # Compares this logger by name to another logger. The normal return codes
+    # for +String+ objects apply.
+    #
+    def <=>( other )
+      case other
+      when self; 0
+      when ::Logging::RootLogger; 1
+      when ::Logging::Logger; @name <=> other.name
+      else raise ArgumentError, 'expecting a Logger instance' end
+    end
+
+    # call-seq:
+    #    log << "message"
+    #
+    # Log the given message without any formatting and without performing any
+    # level checks. The message is logged to all appenders. The message is
+    # passed up the logger tree if this logger's additivity is +true+.
+    #
+    def <<( msg )
+      @appenders.each {|a| a << msg}
+      @parent << msg if @additive
+    end
+
+    # call-seq:
+    #    add( severity, message = nil ) {block}
+    #
+    # Log a message if the given severity is high enough.  This is the generic
+    # logging method.  Users will be more inclined to use #debug, #info, #warn,
+    # #error, and #fatal.
+    #
+    # <b>Message format</b>: +message+ can be any object, but it has to be
+    # converted to a String in order to log it. The Logging::format_as
+    # method is used to determine how objects chould be converted to
+    # strings. Generally, +inspect+ is used.
+    #
+    # A special case is an +Exception+ object, which will be printed in
+    # detail, including message, class, and backtrace.
+    #
+    # If a _message_ is not given, then the return value from the block is
+    # used as the message to log. This is useful when creating the actual
+    # message is an expensive operation. This allows the logger to check the
+    # severity against the configured level before actually constructing the
+    # message.
+    #
+    # This method returns +true+ if the message was logged, and +false+ is
+    # returned if the message was not logged.
+    #
+    def add( lvl, data = nil )
+      lvl = Integer(lvl)
+      return false if lvl < level
+
+      data = yield if block_given?
+      log_event(::Logging::LogEvent.new(@name, lvl, data, @trace))
+      true
+    end
+
+    # call-seq:
+    #    additive = true
+    #
+    # Sets the additivity of the logger. Acceptable values are +true+,
+    # 'true', +false+, 'false', or +nil+. In this case +nil+ does not
+    # change the additivity
+    #
+    def additive=( val )
+      @additive = case val
+                  when true, 'true'; true
+                  when false, 'false'; false
+                  when nil; @additive
+                  else raise ArgumentError, 'expecting a boolean' end
+    end
+
+    # call-seq:
+    #    trace = true
+    #
+    # Sets the tracing of the logger. Acceptable values are +true+,
+    # 'true', +false+, 'false', or +nil+. In this case +nil+ does not
+    # change the tracing.
+    #
+    def trace=( val )
+      @trace = case val
+               when true, 'true'; true
+               when false, 'false'; false
+               when nil; @trace
+               else raise ArgumentError, 'expecting a boolean' end
+    end
+
+    # call-seq:
+    #    level = :all
+    #
+    # Set the level for this logger. The level can be either a +String+, a
+    # +Symbol+, or a +Fixnum+. An +ArgumentError+ is raised if this is not
+    # the case.
+    #
+    # There are two special levels -- "all" and "off". The former will
+    # enable log messages from this logger. The latter will disable all log
+    # messages from this logger.
+    #
+    # Setting the logger level to +nil+ will cause the parent's logger level
+    # to be used.
+    #
+    # Example:
+    #
+    #    log.level = :debug
+    #    log.level = "INFO"
+    #    log.level = 4
+    #    log.level = 'off'
+    #    log.level = :all
+    #
+    # These prodcue an +ArgumentError+
+    #
+    #    log.level = Object
+    #    log.level = -1
+    #    log.level = 1_000_000_000_000
+    #
+    def level=( level )
+      lvl = case level
+            when String, Symbol; ::Logging::level_num(level)
+            when Fixnum; level
+            when nil; @parent.level
+            else
+              raise ArgumentError,
+                    "level must be a String, Symbol, or Integer"
+            end
+      if lvl.nil? or lvl < 0 or lvl > ::Logging::LEVELS.length
+        raise ArgumentError, "unknown level was given '#{level}'"
+      end
+
+      @level = lvl
+      ::Logging::Logger.define_log_methods(self)
+      @level
+    end
+
+    # call-seq:
+    #    appenders = app
+    #
+    # Clears the current list of appenders and replaces them with _app_,
+    # where _app_ can be either a single appender or an array of appenders.
+    #
+    def appenders=( args )
+      @appenders.clear
+      add_appenders(*args) unless args.nil?
+    end
+
+    # call-seq:
+    #    add_appenders( appenders )
+    #
+    # Add the given _appenders_ to the list of appenders, where _appenders_
+    # can be either a single appender or an array of appenders.
+    #
+    def add_appenders( *args )
+      args.flatten.each do |arg|
+        o = arg.kind_of?(::Logging::Appender) ? arg : ::Logging::Appender[arg]
+        raise ArgumentError, "unknown appender '#{arg}'" if o.nil?
+        @appenders << o unless @appenders.include?(o)
+      end
+      self
+    end
+
+    # call-seq:
+    #    remove_appenders( appenders )
+    #
+    # Remove the given _appenders_ from the list of appenders. The appenders
+    # to remove can be identified either by name using a +String+ or by
+    # passing the appender instance. _appenders_ can be a single appender or
+    # an array of appenders.
+    #
+    def remove_appenders( *args )
+      args.flatten.each do |arg|
+        @appenders.delete_if do |a|
+          case arg
+          when String; arg == a.name
+          when ::Logging::Appender; arg.object_id == a.object_id
+          else
+            raise ArgumentError, "#{arg.inspect} is not a 'Logging::Appender'"
+          end
+        end
+      end
+      self
+    end
+
+    # call-seq:
+    #    clear_appenders
+    #
+    # Remove all appenders from this logger.
+    #
+    def clear_appenders( ) @appenders.clear end
+
+
+    protected
+
+    # call-seq:
+    #    parent = ParentLogger
+    #
+    # Set the parent logger for this logger. This method will be invoked by
+    # the +Repository+ class when a parent or child is added to the
+    # hierarchy.
+    #
+    def parent=( parent ) @parent = parent end
+
+    # call-seq:
+    #    log_event( event )
+    #
+    # Send the given _event_ to the appenders for logging, and pass the
+    # _event_ up to the parent if additive mode is enabled. The log level has
+    # already been checked before this method is called.
+    #
+    def log_event( event )
+      @appenders.each {|a| a.append(event)}
+      @parent.log_event(event) if @additive
+    end
+
+    # :stopdoc:
+
+    # call-seq:
+    #    meta_eval( code )
+    #
+    # Evaluates the given string of _code_ if the singleton class of this
+    # Logger object.
+    #
+    def meta_eval( code )
+      meta = class << self; self end
+      meta.class_eval code
+    end
+    public :meta_eval
+    # :startdoc:
+
+  end  # class Logger
+end  # module Logging
+
+# EOF