filterfish-logging 0.9.8

data/History.txt

@@ -0,0 +1,176 @@
+== 0.9.8 / 2009-04-04 [rgh@roughage.com.au]
+
+1 Minor enhancement
+  - Allow the config to passed as a string.
+
+== 0.9.7 / 2009-03-17
+
+1 minor enhancement
+  - Added a StringIO appender
+1 bug fix
+  - Handling objects that cannot be dumped via YAML [Tim Galeckas]
+
+== 0.9.6 / 2009-02-02
+
+2 minor enhancements
+  - Ruby 1.9.1 compatability
+  - JRuby 1.1.5 compatability
+
+== 0.9.5 / 2009-01-25
+
+2 minor enhancements
+  - The pattern layout can output the current thread name
+    if set using Thread.current[:name]         [valodzka]
+  - Added buffered logging to all IO based loggers
+    (console, file, rolling file)
+1 bug fix
+  - Uncaught TimeoutError in the e-mail appender
+
+== 0.9.4 / 2008-10-04
+
+2 minor enhancements
+  - Flag to suppress exception backtraces from being logged
+  - Cleaning up color codes on Growl output
+4 bug fixes
+  - Child loggers were not being found in some cases
+  - RollingFileAppender fails to reopen the log file if
+    the log file is deleted.
+  - Fixed a copy/paste error in the YAML configurator
+  - Bug in the configurator where a nil object was being used
+
+== 0.9.3 / 2008-09-12
+
+2 minor enhancement
+  - Added a class for tracking basic statistics
+  - Will use the 'fastthread' gem if availble
+
+== 0.9.2 / 2008-09-03
+
+2 bug fixes
+  - Properly generates logger names for anonymous classes and
+    modules and meta-classes
+  - Fixed the rescue clause when 'turn' cannot be required
+
+== 0.9.1 / 2008-08-14
+
+1 minor enhancement
+  - added a method to show the logging configuration
+2 bug fixes
+  - checking for sync method on the IO streams before calling
+  - fixed the internal logging levels
+
+== 0.9.0 / 2008-07-16
+
+2 minor enhancement
+  - Exceptions from appenders are captured and logged
+  - Internal logger for the Logging framework (disabled by default)
+  - Added a DSL configuration format (more readable than YAML)
+1 bug fix
+  - Modules could not have their own logger instance
+
+== 0.8.0 / 2008-07-02
+
+1 minor enhancement
+  - Setting the log level of a parent will cause this level to
+    be propagated to the children
+1 bug fix
+  - Fixed error with the e-mail appender and missing hostname
+
+== 0.7.1 / 2008-02-25
+
+1 minor enhancement
+  - Removed dependency on the Lockfile gem (brought the ruby
+    file into the logging/stelan directory)
+1 bug fix
+  - Fixed bug with age based rolling: was not multi-process safe
+
+== 0.7.0 / 2008-02-12
+
+1 major enhancement
+  - Rails compatibility
+    * renamed Logger#add method to Logger#add_appenders
+    * renamed Logger#remove method to Logger#remove_appenders
+    * renamed Logger#clear method to Logger#clear_appenders
+    * added a new Logger#add method that conforms to the calling
+      semantics of the Ruby stdlib Logger 
+
+2 minor enhancements
+  - Speed improvements and test coverage
+  - Created a top-level Logging.init method that is used to
+    define the default logging levels
+
+1 bug fix
+  - Tweaked windows detection code
+
+== 0.6.3 / 2008-02-08
+
+2 minor enhancements
+  - YAML configuration now supports multiple keys -- i.e. development
+    or production or whatever
+  - Reorganized a lot of files so that requiring files is cleaner and
+    more deterministic
+
+== 0.6.2 / 2008-02-06
+
+2 bug fixes
+  - An extra e-mail was being pushed out when the e-mail
+    appender was closed
+  - Created an at_exit handler to close all appenders
+
+== 0.6.1 / 2008-01-01
+
+1 bug fix
+  - Fixed include order to avoid double loading when testing
+
+== 0.6.0 / 2007-12-26
+
+* Using the new 'getopt' method for handling option hashes
+* Rolling file appender is safe for multiple processes
+* Added an e-mail appender from Jeremy Hinegardner
+* Updated tests for the appenders
+
+== 0.5.3 / 2007-12-08
+
+* Fixed the quoting for messages sent to the growl appender
+
+== 0.5.2 / 2007-11-28
+
+* Updated the library to work with Ruby 1.9
+* Fixed coalescing with the growl appender
+
+== 0.5.1 / 2007-11-18
+
+* Fixed a bug on Windows when attempting to load the syslog library
+
+== 0.5.0 / 2007-11-18
+
+* Added the ability to log via the syslog daemon
+* Can send messages to the Growl notification system on Mac OS X
+* The Growl appender can coalesce messages of the same title/priority
+
+== 0.4.0 / 2007-03-21
+
+* Added a microsecond flag to the Pattern layout
+* All appenders write immediately upon receipt of a logging event
+* Added a basic logging method that returns a logger object configured in
+  the same manner as the standard Ruby logger
+* Fixed a bug caused by nil log messages
+
+== 0.3.1 / 2007-02-08
+
+* Bugfix Release
+
+== 0.3.0 / 2007-02-01
+
+* Remove the ability to log multiple objects from a single log method call
+
+== 0.2.0 / 2007-01-29
+
+* The "once every four years" release
+* Storage and retrieval of appenders by name
+* YAML configuration support
+* Rolling file appender
+
+== 0.1.0 / 2007-01-12
+
+* Birthday!

data/Manifest.txt

@@ -0,0 +1,54 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+data/logging.yaml
+lib/logging.rb
+lib/logging/appender.rb
+lib/logging/appenders/console.rb
+lib/logging/appenders/email.rb
+lib/logging/appenders/file.rb
+lib/logging/appenders/growl.rb
+lib/logging/appenders/io.rb
+lib/logging/appenders/rolling_file.rb
+lib/logging/appenders/syslog.rb
+lib/logging/config/yaml_configurator.rb
+lib/logging/layout.rb
+lib/logging/layouts/basic.rb
+lib/logging/layouts/pattern.rb
+lib/logging/log_event.rb
+lib/logging/logger.rb
+lib/logging/repository.rb
+lib/logging/root_logger.rb
+lib/logging/utils.rb
+tasks/ann.rake
+tasks/bones.rake
+tasks/gem.rake
+tasks/manifest.rake
+tasks/notes.rake
+tasks/post_load.rake
+tasks/rdoc.rake
+tasks/rubyforge.rake
+tasks/setup.rb
+tasks/svn.rake
+tasks/test.rake
+test/appenders/test_console.rb
+test/appenders/test_email.rb
+test/appenders/test_file.rb
+test/appenders/test_growl.rb
+test/appenders/test_io.rb
+test/appenders/test_rolling_file.rb
+test/appenders/test_syslog.rb
+test/benchmark.rb
+test/config/test_yaml_configurator.rb
+test/layouts/test_basic.rb
+test/layouts/test_pattern.rb
+test/setup.rb
+test/test_appender.rb
+test/test_layout.rb
+test/test_log_event.rb
+test/test_logger.rb
+test/test_logging.rb
+test/test_repository.rb
+test/test_root_logger.rb
+test/test_utils.rb

data/README.txt

@@ -0,0 +1,93 @@
+Logging
+    by Tim Pease
+
+* {Homepage}[http://logging.rubyforge.org/]
+* {Rubyforge Project}[http://rubyforge.org/projects/logging]
+* email tim dot pease at gmail dot com
+
+== DESCRIPTION
+
+Logging is a flexible logging library for use in Ruby programs based on the
+design of Java's log4j library. It features a hierarchical logging system,
+custom level names, multiple output destinations per log event, custom
+formatting, and more.
+
+== INSTALL
+
+   sudo gem install logging
+
+== EXAMPLE
+
+This example configures a logger to output messages in a format similar to the
+core ruby Logger class. Only log messages that are warnings or higher will be
+logged.
+
+   require 'logging'
+
+   logger = Logging.logger(STDOUT)
+   logger.level = :warn
+
+   logger.debug "this debug message will not be output by the logger"
+   logger.warn "this is your last warning"
+
+In this example, a single logger is crated that will append to STDOUT and to a
+file. Only log messages that are informational or higher will be logged.
+
+   require 'logging'
+
+   logger = Logging::Logger['example_logger']
+   logger.add_appenders(
+       Logging::Appender.stdout,
+       Logging::Appenders::File.new('example.log')
+   )
+   logger.level = :info
+
+   logger.debug "this debug message will not be output by the logger"
+   logger.info "just some friendly advice"
+
+The Logging library was created to allow each class in a program to have its
+own configurable logger. The logging level for a particular class can be
+changed independently of all other loggers in the system. This example shows
+the recommended way of accomplishing this.
+
+   require 'logging'
+
+   Logging::Logger['FirstClass'].level = :warn
+   Logging::Logger['SecondClass'].level = :debug
+
+   class FirstClass
+     def initialize
+       @log = Logging::Logger[self]
+     end
+
+     def some_method
+       @log.debug "some method was called on #{self.inspect}"
+     end
+   end
+
+   class SecondClass
+     def initialize
+       @log = Logging::Logger[self]
+     end
+
+     def another_method
+       @log.debug "another method was called on #{self.inspect}"
+     end
+   end
+
+== NOTES
+
+Although Logging is intended to supersede Log4r, it is not a one-to-one
+replacement for the Log4r library. Most notably is the difference in namespaces
+-- Logging vs. Log4r. Other differences include renaming Log4r::Outputter to
+Logging::Appender and renaming Log4r::Formatter to Logging::Layout. These
+changes were meant to bring the Logging class names more in line with the Log4j
+class names.
+
+== REQUIREMENTS
+
+Logging does not depend on any other installed libraries or gems.
+
+== LICENSE
+
+Ruby

data/Rakefile

@@ -0,0 +1,28 @@
+# $Id$
+
+load 'tasks/setup.rb'
+
+ensure_in_path 'lib'
+require 'logging'
+
+task :default => 'test:run'
+
+PROJ.name = 'logging'
+PROJ.summary = 'A flexible and extendable logging library for Ruby'
+PROJ.authors = 'Tim Pease'
+PROJ.email = 'tim.pease@gmail.com'
+PROJ.url = 'http://logging.rubyforge.org/'
+PROJ.rubyforge.name = 'logging'
+PROJ.rdoc.dir = 'doc/rdoc'
+#PROJ.rdoc.remote_dir = 'rdoc'
+PROJ.rdoc.remote_dir = ''
+PROJ.version = Logging::VERSION
+
+PROJ.exclude << %w[^tags$ ^tasks/archive ^coverage]
+PROJ.rdoc.exclude << '^data'
+PROJ.svn.path = ''
+
+depend_on 'flexmock'
+depend_on 'lockfile'
+
+# EOF

data/data/logging.yaml

@@ -0,0 +1,63 @@
+
+purpose    : TestA
+description: This is the 1st YAML doc
+say        : Hi
+
+---
+# *** YAML2LOGGING ***
+logging_config:
+  # define all pre config ...
+  pre_config:
+    define_levels:
+      - DEB
+      - INF
+      - PRT
+      - WRN
+      - ERR
+      - FAT
+    format_as   : inspect
+    root:
+      level     : WRN
+
+  # define all loggers ...
+  loggers:
+    - name      : mylogger
+      level     : DEB
+      additive  : false
+      trace     : false      
+      appenders:
+        - stderr
+        - logfile 
+
+    - name      : yourlogger
+      level     : INF 
+      appenders: 
+        - stderr
+        - logfile 
+
+  # define all appenders (incl. layouts)      
+  appenders:
+    - type          : Stderr
+      name          : stderr 
+      level         : DEB
+      layout:
+        type        : Basic
+        format_as   : string
+
+    - type          : File
+      name          : logfile
+      level         : DEB
+      filename      : 'tmp/temp.log'
+      truncate      : true
+      layout:
+        type        : Pattern
+        date_method : to_s
+        pattern     : '[%d] %l  %c : %m\n'
+  
+---
+purpose    : TestB
+description: This is the last YAML doc
+say        : Bye
+
+
+# EOF  

data/lib/logging.rb

@@ -0,0 +1,288 @@
+# $Id$
+
+# Equivalent to a header guard in C/C++
+# Used to prevent the class/module from being loaded more than once
+unless defined? Logging
+
+# TODO: internal logger for debugging
+# TODO: Windows Log Service appender
+
+#
+#
+module Logging
+
+  # :stopdoc:
+  VERSION = '0.7.1'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  WIN32 = %r/djgpp|(cyg|ms|bcc)win|mingw/ =~ RUBY_PLATFORM
+  LEVELS = {}
+  LNAMES = {}
+  # :startdoc:
+
+  class << self
+
+    # call-seq:
+    #    Logging.configure( filename )
+    #
+    # Configures the Logging framework using the configuration information
+    # found in the given file. The file extension should be either '.yaml'
+    # or '.yml' (XML configuration is not yet supported).
+    #
+    def configure( filename, *args )
+      ::Logging::Config::YamlConfigurator.load(filename, *args)
+    end
+
+    # call-seq:
+    #    Logging.logger( device, age = 7, size = 1048576 )
+    #    Logging.logger( device, age = 'weekly' )
+    #
+    # This convenience method returns a Logger instance configured to behave
+    # similarly to a core Ruby Logger instance.
+    #
+    # The _device_ is the logging destination. This can be a filename
+    # (String) or an IO object (STDERR, STDOUT, an open File, etc.). The
+    # _age_ is the number of old log files to keep or the frequency of
+    # rotation (+daily+, +weekly+, or +monthly+). The _size_ is the maximum
+    # logfile size and is only used when _age_ is a number.
+    #
+    # Using the same _device_ twice will result in the same Logger instance
+    # being returned. For example, if a Logger is created using STDOUT then
+    # the same Logger instance will be returned the next time STDOUT is
+    # used. A new Logger instance can be obtained by closing the previous
+    # logger instance.
+    #
+    #    log1 = Logging.logger(STDOUT)
+    #    log2 = Logging.logger(STDOUT)
+    #    log1.object_id == log2.object_id  #=> true
+    #
+    #    log1.close
+    #    log2 = Logging.logger(STDOUT)
+    #    log1.object_id == log2.object_id  #=> false
+    #
+    # The format of the log messages can be changed using a few optional
+    # parameters. The <tt>:pattern</tt> can be used to change the log
+    # message format. The <tt>:date_pattern</tt> can be used to change how
+    # timestamps are formatted. 
+    #
+    #    log = Logging.logger(STDOUT,
+    #              :pattern => "[%d] %-5l : %m\n",
+    #              :date_pattern => "%Y-%m-%d %H:%M:%S.%s")
+    #
+    # See the documentation for the Logging::Layouts::Pattern class for a
+    # full description of the :pattern and :date_pattern formatting strings.
+    #
+    def logger( *args )
+      opts = args.pop if args.last.instance_of?(Hash)
+      opts ||= Hash.new
+
+      dev = args.shift
+      keep = age = args.shift
+      size = args.shift
+
+      name = case dev
+             when String; dev
+             when File; dev.path
+             else dev.object_id.to_s end
+
+      repo = ::Logging::Repository.instance
+      return repo[name] if repo.has_logger? name
+
+      l_opts = {
+        :pattern => "%.1l, [%d #%p] %#{::Logging::MAX_LEVEL_LENGTH}l : %m\n",
+        :date_pattern => '%Y-%m-%dT%H:%M:%S.%s'
+      }
+      [:pattern, :date_pattern, :date_method].each do |o|
+        l_opts[o] = opts.delete(o) if opts.has_key? o
+      end
+      layout = ::Logging::Layouts::Pattern.new(l_opts)
+
+      a_opts = Hash.new
+      a_opts[:size] = size if size.instance_of?(Fixnum)
+      a_opts[:age]  = age  if age.instance_of?(String)
+      a_opts[:keep] = keep if keep.instance_of?(Fixnum)
+      a_opts[:filename] = dev if dev.instance_of?(String)
+      a_opts[:layout] = layout
+      a_opts.merge! opts
+
+      appender =
+          case dev
+          when String
+            ::Logging::Appenders::RollingFile.new(name, a_opts)
+          else 
+            ::Logging::Appenders::IO.new(name, dev, a_opts)
+          end
+
+      logger = ::Logging::Logger.new(name)
+      logger.add_appenders appender
+      logger.additive = false
+
+      class << logger
+        def close
+          @appenders.each {|a| a.close}
+          h = ::Logging::Repository.instance.instance_variable_get :@h
+          h.delete(@name)
+          class << self; undef :close; end
+        end
+      end
+
+      logger
+    end
+
+    # call-seq:
+    #    Logging.init( 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.init :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.init %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 init( *args )
+      args = %w(debug info warn error fatal) 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:
+    #    Logging.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 )
+      f = f.intern if f.instance_of? String
+
+      unless [:string, :inspect, :yaml].include? f
+        raise ArgumentError, "unknown object format '#{f}'"
+      end
+
+      module_eval "OBJ_FORMAT = :#{f}"
+    end
+
+    # Returns the version string for the library.
+    #
+    def version
+      VERSION
+    end
+
+    # Returns the library path for the module. If any arguments are given,
+    # they will be joined to the end of the libray path using
+    # <tt>File.join</tt>.
+    #
+    def libpath( *args )
+      args.empty? ? LIBPATH : ::File.join(LIBPATH, *args)
+    end
+
+    # Returns the lpath for the module. If any arguments are given,
+    # they will be joined to the end of the path using
+    # <tt>File.join</tt>.
+    #
+    def path( *args )
+      args.empty? ? PATH : ::File.join(PATH, *args)
+    end
+
+    # Utility method used to rquire all files ending in .rb that lie in the
+    # directory below this file that has the same name as the filename passed
+    # in. Optionally, a specific _directory_ name can be passed in such that
+    # the _filename_ does not have to be equivalent to the directory.
+    #
+    def require_all_libs_relative_to( fname, dir = nil )
+      dir ||= ::File.basename(fname, '.*')
+      search_me = ::File.expand_path(
+          ::File.join(::File.dirname(fname), dir, '*.rb'))
+
+      Dir.glob(search_me).sort.each {|rb| require rb}
+    end
+
+    # :stopdoc:
+    # Convert the given level into a connaconical form - a lowercase string.
+    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
+
+    # Convert the given level into a level number.
+    def level_num( level )
+      l = levelify level
+      case l
+      when 'all'; 0
+      when 'off'; LEVELS.length
+      else begin; Integer(l); rescue ArgumentError; LEVELS[l] end end
+    end
+    # :startdoc:
+  end
+end  # module Logging
+
+Logging.require_all_libs_relative_to(__FILE__)
+Logging.require_all_libs_relative_to(__FILE__, 'logging/config')
+
+# This exit handler will close all the appenders that exist in the system.
+# This is needed for closing IO streams and connections to the syslog server
+# or e-mail servers, etc.
+#
+at_exit {
+  Logging::Appender.instance_variable_get(:@appenders).values.each do |ap|
+    ap.close
+  end
+}
+
+end  # unless defined?
+
+# EOF