sgeorgi-logging 1.4.2

data/lib/logging/config/configurator.rb

@@ -0,0 +1,188 @@
+
+module Logging::Config
+
+  # The Configurator class is used to configure the Logging framework
+  # using information found in a block of Ruby code. This block is evaluated
+  # in the context of the configurator's DSL.
+  #
+  class Configurator
+
+    class Error < StandardError; end  # :nodoc:
+
+    # call-seq:
+    #    Configuraotr.process( &block )
+    #
+    def self.process( &block )
+      new.load(&block)
+    end
+
+    # call-seq:
+    #    load { block }
+    #
+    # Loads the configuration from the _block_ and configures the Logging
+    # gem.
+    #
+    def load( &block )
+      raise Error, "missing configuration block" unless block
+
+      dsl = TopLevelDSL.new
+      dsl.instance_eval(&block)
+
+      pre_config dsl.__pre_config
+      ::Logging::Logger[:root]  # ensures the log levels are defined
+      appenders  dsl.__appenders
+      loggers    dsl.__loggers
+    end
+
+    # call-seq:
+    #    pre_config( config )
+    #
+    # Configures the logging levels, object format style, and root logging
+    # level.
+    #
+    def pre_config( config )
+      if config.nil?
+        ::Logging.init unless ::Logging.const_defined? 'MAX_LEVEL_LENGTH'
+        return
+      end
+
+      # define levels
+      levels = config[:levels]
+      ::Logging.init(levels) unless levels.nil?
+
+      # format as
+      format = config[:format_as]
+      ::Logging.format_as(format) unless format.nil?
+
+      # backtrace
+      value = config[:backtrace]
+      ::Logging.backtrace(value) unless value.nil?
+    end
+
+    # call-seq:
+    #    appenders( ary )
+    #
+    # Given an array of Appender configurations, this method will iterate
+    # over each and create the Appender(s).
+    #
+    def appenders( ary )
+      ary.each {|name, config| appender(name, config)}
+    end
+
+    # call-seq:
+    #    loggers( ary )
+    #
+    # Given an array of Logger configurations, this method will iterate over
+    # each and create the Logger(s).
+    #
+    def loggers( ary )
+      ary.each do |name, config|
+        l = Logging::Logger[name]
+        l.level     = config[:level] if config[:level]
+        l.additive  = config[:additive] if l.respond_to? :additive= 
+        l.trace     = config[:trace]
+        l.appenders = Array(config[:appenders]).
+                            map {|nm| ::Logging::Appenders[nm]}
+      end
+    end
+
+    # call-seq:
+    #    appender( name, config )
+    #
+    # Creates a new Appender based on the given _config_ options (a hash).
+    # The type of Appender created is determined by the 'type' option in the
+    # config. The remaining config options are passed to the Appender
+    # initializer.
+    #
+    # The config options can also contain a 'layout' option. This should be
+    # another set of options used to create a Layout for this Appender.
+    #
+    def appender( name, config )
+      type = config.delete(:type)
+      raise Error, "appender type not given for #{name.inspect}" if type.nil?
+
+      config[:layout] = layout(config[:layout]) if config.has_key? :layout
+
+      clazz = ::Logging::Appenders.const_get type
+      clazz.new(name, config)
+    rescue NameError => err
+      raise Error, "unknown appender class Logging::Appenders::#{type}"
+    end
+
+    # call-seq:
+    #    layout( config )
+    #
+    # Creates a new Layout based on the given _config_ options (a hash).
+    # The type of Layout created is determined by the 'type' option in the
+    # config. The remaining config options are passed to the Layout
+    # initializer.
+    #
+    def layout( config )
+      return ::Logging::Layouts::Basic.new if config.nil?
+
+      type = config.delete(:type)
+      raise Error, 'layout type not given' if type.nil?
+
+      clazz = ::Logging::Layouts.const_get type
+      clazz.new config
+    rescue NameError => err
+      raise Error, "unknown layout class Logging::Layouts::#{type}"
+    end
+
+    class DSL
+      instance_methods.each do |m|
+        undef_method m unless m[%r/^(__|object_id|instance_eval)/]
+      end
+
+      def self.process( &block )
+        dsl = new
+        dsl.instance_eval(&block)
+        dsl.__hash
+      end
+
+      def __hash
+        @hash ||= Hash.new
+      end
+
+      def method_missing( method, *args, &block )
+        args << DSL.process(&block) if block
+
+        key = method.to_sym
+        value = (1 == args.length ? args.first : args)
+        __store(key, value)
+      end
+
+      def __store( key, value )
+        __hash[key] = value
+      end
+    end
+
+    class TopLevelDSL < DSL
+      undef_method :method_missing
+
+      def initialize
+        @loggers = []
+        @appenders = []
+      end
+
+      def pre_config( &block )
+        __store(:preconfig, DSL.process(&block))
+      end
+
+      def logger( name, &block )
+        @loggers << [name, DSL.process(&block)]
+      end
+
+      def appender( name, &block )
+        @appenders << [name, DSL.process(&block)]
+      end
+
+      def __pre_config() __hash[:preconfig]; end
+      def __loggers() @loggers; end
+      def __appenders() @appenders; end
+    end
+
+  end  # class Configurator
+end  # module Logging::Config
+
+# EOF

data/lib/logging/config/yaml_configurator.rb

@@ -0,0 +1,191 @@
+
+module Logging::Config
+
+  # The YamlConfigurator class is used to configure the Logging framework
+  # using information found in a YAML file.
+  #
+  class YamlConfigurator
+
+    class Error < StandardError; end  # :nodoc:
+
+    class << self
+
+      # call-seq:
+      #    YamlConfigurator.load( file, key = 'logging_config' )
+      #
+      # Load the given YAML _file_ and use it to configure the Logging
+      # framework. The file can be either a filename, and open File, or an
+      # IO object. If it is the latter two, the File / IO object will not be
+      # closed by this method.
+      #
+      # The configuration will be loaded from the given _key_ in the YAML
+      # stream.
+      #
+      def load( file, key = 'logging_config' )
+        io, close = nil, false
+        case file
+        when String
+          io = File.open(file, 'r')
+          close = true
+        when IO
+          io = file
+        else
+          raise Error, 'expecting a filename or a File'
+        end
+
+        begin
+          new(io, key).load
+        ensure
+          io.close if close
+        end
+        nil
+      end
+    end  # class << self
+
+    # call-seq:
+    #    YamlConfigurator.new( io, key )
+    #
+    # Creates a new YAML configurator that will load the Logging
+    # configuration from the given _io_ stream. The configuration will be
+    # loaded from the given _key_ in the YAML stream.
+    #
+    def initialize( io, key  )
+      YAML.load_documents(io) do |doc|
+        @config = doc[key]
+        break if @config.instance_of?(Hash)
+      end
+
+      unless @config.instance_of?(Hash)
+        raise Error, "Key '#{key}' not defined in YAML configuration"
+      end
+    end
+
+    # call-seq:
+    #    load
+    #
+    # Loads the Logging configuration from the data loaded from the YAML
+    # file.
+    #
+    def load
+      pre_config @config['pre_config']
+      ::Logging::Logger[:root]  # ensures the log levels are defined
+      appenders @config['appenders']
+      loggers @config['loggers']
+    end
+
+    # call-seq:
+    #    pre_config( config )
+    #
+    # Configures the logging levels, object format style, and root logging
+    # level.
+    #
+    def pre_config( config )
+      # if no pre_config section was given, just create an empty hash
+      # we do this to ensure that some logging levels are always defined
+      config ||= Hash.new
+
+      # define levels
+      levels = config['define_levels']
+      ::Logging.init(levels) unless levels.nil?
+
+      # format as
+      format = config['format_as']
+      ::Logging.format_as(format) unless format.nil?
+
+      # backtrace
+      value = config['backtrace']
+      ::Logging.backtrace(value) unless value.nil?
+
+      # grab the root logger and set the logging level
+      root = ::Logging::Logger.root
+      if config.has_key?('root')
+        root.level = config['root']['level']
+      end
+    end
+
+    # call-seq:
+    #    appenders( ary )
+    #
+    # Given an array of Appender configurations, this method will iterate
+    # over each and create the Appender(s).
+    #
+    def appenders( ary )
+      return if ary.nil?
+
+      ary.each {|h| appender(h)}
+    end
+
+    # call-seq:
+    #    loggers( ary )
+    #
+    # Given an array of Logger configurations, this method will iterate over
+    # each and create the Logger(s).
+    #
+    def loggers( ary )
+      return if ary.nil?
+
+      ary.each do |config|
+        name = config['name']
+        raise Error, 'Logger name not given' if name.nil?
+
+        l = Logging::Logger.new name
+        l.level = config['level'] if config.has_key?('level')
+        l.additive = config['additive'] if l.respond_to? :additive=
+        l.trace = config['trace'] if l.respond_to? :trace=
+
+        if config.has_key?('appenders')
+          l.appenders = config['appenders'].map {|n| ::Logging::Appenders[n]}
+        end
+      end
+    end
+
+    # call-seq:
+    #    appender( config )
+    #
+    # Creates a new Appender based on the given _config_ options (a hash).
+    # The type of Appender created is determined by the 'type' option in the
+    # config. The remaining config options are passed to the Appender
+    # initializer.
+    #
+    # The config options can also contain a 'layout' option. This should be
+    # another set of options used to create a Layout for this Appender.
+    #
+    def appender( config )
+      return if config.nil?
+      config = config.dup
+
+      type = config.delete('type')
+      raise Error, 'Appender type not given' if type.nil?
+
+      name = config.delete('name')
+      raise Error, 'Appender name not given' if name.nil?
+
+      config['layout'] = layout(config.delete('layout'))
+
+      clazz = ::Logging::Appenders.const_get type
+      clazz.new(name, config)
+    end
+
+    # call-seq:
+    #    layout( config )
+    #
+    # Creates a new Layout based on the given _config_ options (a hash).
+    # The type of Layout created is determined by the 'type' option in the
+    # config. The remaining config options are passed to the Layout
+    # initializer.
+    #
+    def layout( config )
+      return if config.nil?
+      config = config.dup
+
+      type = config.delete('type')
+      raise Error, 'Layout type not given' if type.nil?
+
+      clazz = ::Logging::Layouts.const_get type
+      clazz.new config
+    end
+
+  end  # class YamlConfigurator
+end  # module Logging::Config
+
+# EOF

data/lib/logging/layout.rb

@@ -0,0 +1,117 @@
+ 
+module Logging
+
+# The +Layout+ class provides methods for formatting log events into a
+# string representation. Layouts are used by Appenders to format log
+# events before writing them to the logging destination.
+#
+# All other Layouts inherit from this class which provides stub methods.
+# Each subclass should provide a +format+ method. A layout can be used by
+# more than one +Appender+ so all the methods need to be thread safe.
+#
+class Layout
+
+  # call-seq:
+  #    Layout.new( :format_as => :string )
+  #
+  # Creates a new layout that will format objecs as strings using the
+  # given <tt>:format_as</tt> style. This can be one of <tt>:string</tt>,
+  # <tt>:inspect</tt>, or <tt>:yaml</tt>. These formatting commands map to
+  # the following object methods:
+  #
+  # * :string  => to_s
+  # * :inspect => inspect
+  # * :yaml    => to_yaml
+  #
+  # If the format is not specified then the global object format is used
+  # (see Logging#format_as). If the global object format is not specified
+  # then <tt>:string</tt> is used.
+  #
+  def initialize( opts = {} )
+    ::Logging.init unless ::Logging.const_defined? :MAX_LEVEL_LENGTH
+
+    default = ::Logging.const_defined?('OBJ_FORMAT') ?
+              ::Logging::OBJ_FORMAT : nil
+
+    f = opts.getopt(:format_as, default)
+    f = f.intern if f.instance_of? String
+
+    @obj_format = case f
+                  when :inspect, :yaml; f
+                  else :string end
+
+    b = opts.getopt(:backtrace, ::Logging.backtrace)
+    @backtrace = case b
+        when :on, 'on', true;    true
+        when :off, 'off', false; false
+        else
+          raise ArgumentError, "backtrace must be true or false"
+        end
+  end
+
+  # call-seq:
+  #    format( event )
+  #
+  # Returns a string representation of the given loggging _event_. It is
+  # up to subclasses to implement this method.
+  #
+  def format( event ) nil end
+
+  # call-seq:
+  #    header
+  #
+  # Returns a header string to be used at the beginning of a logging
+  # appender.
+  #
+  def header( ) '' end
+
+  # call-seq:
+  #    footer
+  #
+  # Returns a footer string to be used at the end of a logging appender.
+  #
+  def footer( ) '' end 
+
+  # call-seq:
+  #    format_obj( obj )
+  #
+  # Return a string representation of the given object. Depending upon
+  # the configuration of the logger system the format will be an +inspect+
+  # based represenation or a +yaml+ based representation.
+  #
+  def format_obj( obj )
+    case obj
+    when String; obj
+    when Exception 
+      str = "<#{obj.class.name}> #{obj.message}"
+      if @backtrace && !obj.backtrace.nil?
+        str << "\n\t" << obj.backtrace.join("\n\t")
+      end
+      str
+    when nil; "<#{obj.class.name}> nil"
+    else
+      str = "<#{obj.class.name}> "
+      str << case @obj_format
+             when :inspect; obj.inspect
+             when :yaml; try_yaml(obj)
+             else obj.to_s end
+      str
+    end
+  end
+
+  # call-seq:
+  #    try_yaml( obj )
+  #
+  # Attempt to format the _obj_ using yaml, but fall back to inspect style
+  # formatting if yaml fails.
+  #
+  def try_yaml( obj )
+    "\n#{obj.to_yaml}"
+  rescue TypeError
+    obj.inspect
+  end
+
+end  # class Layout
+end  # module Logging
+
+# EOF