logging 0.1.0

data/README.txt

@@ -0,0 +1,11 @@
+--
+$Id: README.txt 12 2007-01-14 20:03:40Z tim_pease $
+++
+
+ = Logging
+
+ obtaining a logger
+ where to log
+ log statements
+ changing the log level
+ 

data/lib/logging.rb

@@ -0,0 +1,129 @@
+# $Id: logging.rb 12 2007-01-14 20:03:40Z tim_pease $
+
+require 'logging/repository'
+
+# require all appenders
+require 'logging/appenders/console'
+require 'logging/appenders/file'
+require 'logging/appenders/static_appender'
+
+# require all layouts
+require 'logging/layouts/basic'
+require 'logging/layouts/pattern'
+
+
+#
+#
+#
+module Logging
+
+  LEVELS = {}  # :nodoc:
+  LNAMES = {}  # :nodoc:
+
+  class << self
+    #
+    # call-seq:
+    #    define_levels( levels )
+    #
+    # Defines the levels available to the loggers. The _levels_ is an array
+    # of strings and symbols. Each element in the array is downcased and
+    # converted to a symbol; these symbols are used to create the logging
+    # methods in the loggers.
+    #
+    # The first element in the array is the lowest logging level. Setting the
+    # logging level to this value will enable all log messages. The last
+    # element in the array is the highest logging level. Setting the logging
+    # level to this value will disable all log messages except this highest
+    # level.
+    #
+    # This method should only be invoked once to configure the logging
+    # levels. It is automatically invoked with the default logging levels
+    # when the first logger is created.
+    #
+    # The levels "all" and "off" are reserved and will be ignored if passed
+    # to this method.
+    #
+    # Example:
+    #
+    #    Logging.define_levels :debug, :info, :warn, :error, :fatal
+    #    log = Logging::Logger['my logger']
+    #    log.level = :warn
+    #    log.warn 'Danger! Danger! Will Robinson'
+    #    log.info 'Just FYI'                        # => not logged
+    #
+    # or
+    #
+    #    Logging.define_levels %w(DEBUG INFO NOTICE WARNING ERR CRIT ALERT EMERG)
+    #    log = Logging::Logger['syslog']
+    #    log.level = :notice
+    #    log.warning 'This is your first warning'
+    #    log.info 'Just FYI'                        # => not logged
+    #
+    def define_levels( *args )
+      return nil if args.empty?
+
+      args.flatten!
+      levels = ::Logging::LEVELS.clear
+      names = ::Logging::LNAMES.clear
+
+      id = 0
+      args.each do |lvl|
+        lvl = levelify lvl
+        unless levels.has_key?(lvl) or lvl == 'all' or lvl == 'off'
+          levels[lvl] = id 
+          names[id] = lvl.upcase
+          id += 1
+        end
+      end
+
+      longest = names.values.inject {|x,y| (x.length > y.length) ? x : y}
+      module_eval "MAX_LEVEL_LENGTH = #{longest.length}"
+
+      levels.keys
+    end
+   
+    #
+    # call-seq:
+    #    format_as( obj_format )
+    #
+    # Defines the default _obj_format_ method to use when converting objects
+    # into string representations for logging. _obj_format_ 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
+    #
+    # An +ArgumentError+ is raised if anything other than +:string+,
+    # +:inspect+, +:yaml+ is passed to this method.
+    #
+    def format_as( f )
+      unless [:string, :inspect, :yaml].include? f
+        raise ArgumentError, "unknown object format '#{f}'"
+      end
+
+      module_eval "OBJ_FORMAT = :#{f}"
+    end
+
+    # :stopdoc:
+    def levelify( level )
+      case level
+      when String: level.downcase
+      when Symbol: level.to_s.downcase
+      else raise ArgumentError, "levels must be a String or Symbol" end
+    end
+
+    def level_num( level )
+      l = levelify level
+      case l
+      when 'all': 0
+      when 'off': LEVELS.length
+      else LEVELS[l] end
+    end
+    # :startdoc:
+  end
+
+end  # module Logging
+
+# EOF

data/lib/logging/appender.rb

@@ -0,0 +1,205 @@
+# $Id: appender.rb 12 2007-01-14 20:03:40Z tim_pease $
+
+require 'sync'
+require 'logging'
+require 'logging/logger'
+require 'logging/layout'
+require 'logging/layouts/basic'
+
+module Logging
+
+  #
+  # The +Appender+ class is provides methods for appending log events to a
+  # logging destination. The log events are formatted into strings using a
+  # Layout.
+  #
+  # All other Appenders inherit from this class which provides stub methods.
+  # Each subclass should provide a +write+ method that will write log
+  # messages to the logging destination.
+  #
+  # A private +sync+ method is provided for use by subclasses. It is used to
+  # synchronize writes to the logging destination, and can be used by
+  # subclasses to synchronize the closing or flushing of the logging
+  # destination.
+  #
+  class Appender
+
+    attr_reader :name, :layout, :level
+
+    #
+    # call-seq:
+    #    Appender.new( name )
+    #    Appender.new( name, :layout => layout )
+    #
+    # Creates a new appender using the given name. If no Layout is specified,
+    # then a Basic layout will be used. Any logging header supplied by the
+    # layout will be written to the logging destination when the Appender is
+    # created.
+    #
+    def initialize( name, opts = {} )
+      @name = name.to_s
+      @closed = false
+      @level = 0
+      self.layout = opts[:layout] if opts.include? :layout
+      @layout ||= ::Logging::Layouts::Basic.new
+
+      @sync = Sync.new
+      sync {write(@layout.header)}
+
+      ::Logging::Appender[@name] = self
+    end
+
+    #
+    # call-seq:
+    #    append( event )
+    #
+    # Write the given _event_ to the logging destination. The log event will
+    # be processed through the Layout associated with the Appender.
+    #
+    def append( event )
+      if @closed
+        raise RuntimeError,
+              "appender '<#{self.class.name}: #{@name}>' is closed"
+      end
+
+      sync {write(@layout.format(event))} unless @level > event.level
+      self
+    end
+
+    #
+    # call-seq:
+    #    appender << string
+    #
+    # Write the given _string_ to the logging destination "as is" -- no
+    # layout formatting will be performed.
+    #
+    def <<( str )
+      if @closed
+        raise RuntimeError,
+              "appender '<#{self.class.name}: #{@name}>' is closed"
+      end
+
+      sync {write(str)}
+      self
+    end
+
+    #
+    # call-seq:
+    #    level = :all
+    #
+    # Set the level for this appender; log events below this level will be
+    # ignored by this appender. 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 recording of all log events. The latter will disable the
+    # recording of all events.
+    #
+    # Example:
+    #
+    #    appender.level = :debug
+    #    appender.level = "INFO"
+    #    appender.level = 4
+    #    appender.level = 'off'
+    #    appender.level = :all
+    #
+    # These prodcue an +ArgumentError+
+    #
+    #    appender.level = Object
+    #    appender.level = -1
+    #    appender.level = 1_000_000_000_000
+    #
+    def level=( level )
+      lvl = case level
+            when String, Symbol: ::Logging::level_num(level)
+            when Fixnum: level
+            when nil: 0
+            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
+    end
+
+    #
+    # call-seq
+    #    appender.layout = Logging::Layouts::Basic.new
+    #
+    # Sets the layout to be used by this appender.
+    #
+    def layout=( layout )
+      unless layout.kind_of? ::Logging::Layout
+        raise TypeError,
+              "#{layout.inspect} is not a kind of 'Logging::Layout'"
+      end
+      @layout = layout
+    end
+
+    #
+    # call-seq:
+    #    close( footer = true )
+    #
+    # Close the appender and writes the layout footer to the logging
+    # destination if the _footer_ flag is set to +true+. Log events will
+    # no longer be written to the logging destination after the appender
+    # is closed.
+    #
+    def close( footer = true )
+      return self if @closed
+      @closed = true
+      sync {write(@layout.footer)} if footer
+      self
+    end
+
+    #
+    # call-seq:
+    #    closed?
+    #
+    # Returns +true+ if the appender has been closed; returns +false+
+    # otherwise. When an appender is closed, no more log events can be
+    # written to the logging destination.
+    #
+    def closed?( ) @closed end
+
+    #
+    # call-seq:
+    #    flush
+    #
+    # Call +flush+ to force an appender to write out any buffered log events.
+    # Similar to IO#flush, so use in a similar fashion.
+    #
+    def flush( ) self end
+
+
+    private 
+    #
+    # call-seq:
+    #    write( str )
+    #
+    # Writes the given string to the logging destination. Subclasses should
+    # provide an implementation of this method.
+    #
+    def write( str ) nil end
+
+    #
+    # call-seq:
+    #    sync { block }
+    #
+    # Obtains an exclusive lock, runs the block, and releases the lock when
+    # the block completes. This method is re-entrant so that a single thread
+    # can call +sync+ multiple times without hanging the thread.
+    #
+    def sync
+      if Thread.current == @sync.sync_ex_locker then yield
+      else @sync.synchronize(:EX) {yield} end
+    end
+
+  end  # class Appender
+end  # module Logging
+
+# EOF

data/lib/logging/appenders/console.rb

@@ -0,0 +1,47 @@
+# $Id: console.rb 2 2007-01-09 18:10:50Z tim_pease $
+
+require 'logging/appenders/io'
+
+module Logging
+module Appenders
+
+  #
+  # This class provides an Appender that can write to STDOUT.
+  #
+  class StdOut< ::Logging::Appenders::IO
+
+    #
+    # call-seq:
+    #    StdOut.new
+    #    StdOut.new( :layout => layout )
+    #
+    # Creates a new StdOut Appender. The name 'stdout' will always be used for
+    # this appender.
+    #
+    def initialize( opts = {} )
+      super('stdout', STDOUT, opts)
+    end
+  end  # class StdOut
+
+  #
+  # This class provides an Appender that can write to STDERR.
+  #
+  class StdErr< ::Logging::Appenders::IO
+
+    #
+    # call-seq:
+    #    StdErr.new
+    #    StdErr.new( :layout => layout )
+    #
+    # Creates a new StdErr Appender. The name 'stderr' will always be used for
+    # this appender.
+    #
+    def initialize( opts = {} )
+      super('stderr', STDERR, opts)
+    end
+  end  # class StdErr
+
+end  # module Appenders
+end  # module Logging
+
+# EOF

data/lib/logging/appenders/file.rb

@@ -0,0 +1,45 @@
+# $Id: file.rb 2 2007-01-09 18:10:50Z tim_pease $
+
+require 'logging/appenders/io'
+
+module Logging
+module Appenders
+
+  #
+  # This class provides an Appender that can write to a File.
+  #
+  class File < ::Logging::Appenders::IO
+
+    #
+    # call-seq:
+    #    File.new( filename )
+    #    File.new( filename, :truncate => true )
+    #    File.new( filename, :layout => layout )
+    #
+    # Creates a new File Appender that will use the given _filename_ as the
+    # logging destination. If the file does not already exist it will be
+    # created. If the :truncate option is set to +true+ then the file will be
+    # truncated before writing begins; otherwise, log messages will be appened
+    # to the file.
+    #
+    def initialize( filename, opts = {} )
+      mode = opts.delete(:truncate) ? 'w' : 'a'
+
+      if ::File.exist?(filename)
+        if not ::File.file?(filename)
+          raise StandardError, "#{filename} is not a regular file"
+        elsif not ::File.writable?(filename)
+          raise StandardError, "#{filename} is not writeable"
+        end
+      elsif not ::File.writable?(::File.dirname(filename))
+        raise StandardError, "#{::File.dirname(filename)} is not writable"
+      end
+
+      super(filename, ::File.new(filename, mode), opts)
+    end
+
+  end  # class FileAppender
+end  # module Appenders
+end  # module Logging
+
+# EOF

data/lib/logging/appenders/io.rb

@@ -0,0 +1,87 @@
+# $Id: io.rb 10 2007-01-12 18:57:07Z tim_pease $
+
+require 'logging/appender'
+
+module Logging
+module Appenders
+
+  #
+  # This class provides an Appender that can write to any IO stream
+  # configured for writing.
+  #
+  class IO < ::Logging::Appender
+
+    #
+    # call-seq:
+    #    IO.new( name, io )
+    #    IO.new( name, io, :layout => layout )
+    #
+    # Creates a new IO Appender using the given name that will use the _io_
+    # stream as the logging destination.
+    #
+    def initialize( name, io, opts = {} )
+      unless io.respond_to? :print
+        raise TypeError, "expecting an IO object but got '#{io.class.name}'"
+      end
+
+      @io = io
+      @io.sync = true
+
+      super(name, opts)
+    end
+
+    #
+    # call-seq:
+    #    close( footer = true )
+    #
+    # Close the appender and writes the layout footer to the logging
+    # destination if the _footer_ flag is set to +true+. Log events will
+    # no longer be written to the logging destination after the appender
+    # is closed.
+    #
+    def close( *args )
+      return self if @io.nil?
+      sync do
+        super(*args)
+        @io.close unless [STDIN, STDERR, STDOUT].include?(@io)
+        @io = nil
+      end
+      self
+    end
+
+    #
+    # call-seq:
+    #    flush
+    #
+    # Call +flush+ to force an appender to write out any buffered log events.
+    # Similar to IO#flush, so use in a similar fashion.
+    #
+    def flush
+      return self if @io.nil?
+      @io.flush
+      self
+    end
+
+
+    private
+    #
+    # call-seq:
+    #    write( str )
+    #
+    # Writes the given string to the IO stream. If an +IOError+ is detected,
+    # than this appender will be closed and the error reported.
+    #
+    def write( str )
+      begin
+        @io.print str
+      rescue IOError
+        close false
+        raise
+      end
+    end
+
+  end  # class IO
+end  # module Appenders
+end  # module Logging
+
+# EOF