logging 0.1.0

data/lib/logging/log_event.rb

@@ -0,0 +1,52 @@
+# $Id: log_event.rb 13 2007-01-15 17:19:37Z tim_pease $
+
+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(3)[0]
+        break 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,345 @@
+# $Id: logger.rb 15 2007-01-15 19:03:45Z tim_pease $
+
+require 'sync'
+require 'logging'
+require 'logging/appender'
+require 'logging/log_event'
+require 'logging/repository'
+
+
+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( Logging::Appenders::StdOut.new )   # 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 = Sync.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(:EX) 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}( *args ) false end
+            CODE
+          else
+            code << <<-CODE
+              def #{name}?( ) true end
+              def #{name}( *args )
+                args.push yield if block_given?
+                log_event(::Logging::LogEvent.new(@name, #{num}, args, @trace)) unless args.empty?
+                true
+              end
+            CODE
+          end
+
+          logger.meta_eval code
+        end
+      end
+      # :startdoc:
+
+    end  # class << self
+
+    attr_reader :level, :name, :parent
+    attr_accessor :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:
+    #    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(*args) unless args.nil?
+    end
+
+    #
+    # call-seq:
+    #    add( 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( *args )
+      args.each do |arg|
+        unless arg.kind_of? ::Logging::Appender
+          raise TypeError,
+                "#{arg.inspect} is not a kind of 'Logging::Appender'"
+        end
+        @appenders << arg unless @appenders.include? arg
+      end
+    end
+
+    #
+    # call-seq:
+    #    remove( 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( *args )
+      args.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 TypeError, "#{arg.inspect} is not a 'Logging::Appender'"
+          end
+        end
+      end
+    end
+
+    #
+    # call-seq:
+    #    clear
+    #
+    # Remove all appenders from this logger.
+    #
+    def clear( ) @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

data/lib/logging/repository.rb

@@ -0,0 +1,148 @@
+# $Id: repository.rb 13 2007-01-15 17:19:37Z tim_pease $
+
+require 'singleton'
+require 'logging/root_logger'
+
+
+module Logging
+
+  #
+  # The Repository is a hash that stores references to all Loggers
+  # that have been created. It provides methods to determine parent/child
+  # relationships between Loggers and to retrieve Loggers from the hash.
+  #
+  class Repository
+    include Singleton
+
+    PATH_DELIMITER = '::'  # :nodoc:
+
+    #
+    # nodoc:
+    #
+    # This is a singleton class -- use the +instance+ method to obtain the
+    # +Repository+ instance.
+    #
+    def initialize
+      @h = {:root => ::Logging::RootLogger.new}
+    end
+
+    #
+    # call-seq:
+    #    instance[name]
+    #
+    # Returns the +Logger+ named _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:
+    #
+    #   repo = Repository.instance
+    #   obj = MyClass.new
+    #
+    #   log1 = repo[obj]
+    #   log2 = repo[MyClass]
+    #   log3 = repo['MyClass']
+    #
+    #   log1.object_id == log2.object_id         # => true
+    #   log2.object_id == log3.object_id         # => true
+    #
+    def []( key ) @h[to_key(key)] end
+
+    #
+    # call-seq:
+    #    instance[name] = logger
+    #
+    # Stores the _logger_ under the given _name_.
+    #
+    # When _name_ is a +String+ or a +Symbol+ it will be used "as is" to
+    # store the logger. When _name_ is a +Class+ the class name will be
+    # used to store the logger. When _name_ is an object the name of the
+    # object's class will be used to store the logger.
+    #
+    def []=( key, val ) @h[to_key(key)] = val end
+
+    #
+    # call-seq:
+    #    fetch( name )
+    #
+    # Returns the +Logger+ named _name_. An +IndexError+ will be raised if
+    # the logger does not exist.
+    #
+    # 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.
+    #
+    def fetch( key ) @h.fetch(to_key(key)) end
+
+    #
+    # call-seq:
+    #    parent( key )
+    #
+    # Returns the parent logger for the logger identified by _key_ where
+    # _key_ follows the same identification rules described in
+    # +Repository#[]+. A parent is returned regardless of the
+    # existence of the logger referenced by _key_.
+    #
+    def parent( key )
+      key = to_key(key)
+      a = key.split PATH_DELIMITER
+
+      p = @h[:root]
+      while a.slice!(-1) and !a.empty?
+        k = a.join PATH_DELIMITER
+        if @h.has_key? k then p = @h[k]; break end
+      end
+      p
+    end
+
+    #
+    # call-seq:
+    #    children( key )
+    #
+    # Returns an array of the children loggers for the logger identified by
+    # _key_ where _key_ follows the same identification rules described in
+    # +Repository#[]+. Children are returned regardless of the
+    # existence of the logger referenced by _key_.
+    #
+    def children( key )
+      key = to_key(key)
+      depth = key.split(PATH_DELIMITER).length
+      rgxp = Regexp.new "^#{key}#{PATH_DELIMITER}"
+
+      a = @h.keys.map do |k|
+            if k =~ rgxp
+              l = @h[k]
+              d = l.parent.name.split(PATH_DELIMITER).length
+              if d <= depth then l else nil end
+            end
+          end
+      a.compact.sort
+    end
+
+    #
+    # call-seq:
+    #    to_key( key )
+    #
+    # Takes the given _key_ and converts it into a form that can be used to
+    # retrieve a logger from the +Repository+ hash.
+    #
+    # When _key_ is a +String+ or a +Symbol+ it will be returned "as is".
+    # When _key_ is a +Class+ the class name will be returned. When _key_ is
+    # an object the name of the object's class will be returned.
+    #
+    def to_key( key )
+      case key
+      when Symbol, String: key
+      when Class: key.name
+      when Object: key.class.name
+      end
+    end
+
+  end  # class Repository
+end  # module Logging
+
+# EOF