logging 0.4.0 → 0.5.0

data/History.txt

@@ -0,0 +1,32 @@
+== 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 tha 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 retrieveal of appenders by name
+* YAML configuration support
+* Rolling file appender
+
+== 0.1.0 / 2007-01-12
+
+* Birthday!

data/Manifest.txt

@@ -0,0 +1,46 @@
+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/file.rb
+lib/logging/appenders/growl.rb
+lib/logging/appenders/io.rb
+lib/logging/appenders/rolling_file.rb
+lib/logging/appenders/static_appender.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
+tasks/doc.rake
+tasks/gem.rake
+tasks/manifest.rake
+tasks/rubyforge.rake
+tasks/setup.rb
+tasks/test.rake
+tasks/website.rake
+test/appenders/test_console.rb
+test/appenders/test_file.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

data/README.txt

@@ -1,15 +1,89 @@
---
-$Id: README.txt 35 2007-03-21 19:32:32Z tim_pease $
-++
+Logging
 
- = Logging
+* {Homepage}[http://logging.rubyforge.org/]
+* {Rubyforge Project}[http://rubyforge.org/projects/logging]
+* email tim dot pease at gmail dot com
 
- A logging framework for Ruby in the spirit of Java's Log4j.
+== DESCRIPTION:
 
- Logging provides an easy to use logging system with fine-grained control over log statements, multiple logging destinations, rolling log files, user defined log levels and much more.
+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.
 
- obtaining a logger
- where to log
- log statements
- changing the log level
- 
+== 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.
+
+   reqruie 'logging'
+
+   logger = Logging::Logger['example_logger']
+   logger.add  Logging::Appender.stdout
+   logger.add  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,29 @@
+# $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.description = paragraphs_of('README.txt', 3).join("\n\n")
+PROJ.changes = paragraphs_of('History.txt', 0..1).join("\n\n")
+PROJ.rubyforge_name = 'logging'
+PROJ.rdoc_dir = 'doc/rdoc'
+#PROJ.rdoc_remote_dir = 'rdoc'
+PROJ.rdoc_remote_dir = ''
+PROJ.version = Logging::VERSION
+
+PROJ.exclude << '^(\.\/|\/)?website/output'
+PROJ.exclude << '^(\.\/|\/)?doc'
+PROJ.exclude << '^(\.\/|\/)?tags$'
+PROJ.rdoc_exclude << '^(\.\/|\/)?data'
+PROJ.rdoc_exclude << '^(\.\/|\/)?website'
+
+# EOF

data/lib/logging.rb

@@ -1,12 +1,14 @@
-# $Id: logging.rb 35 2007-03-21 19:32:32Z tim_pease $
+# $Id: logging.rb 47 2007-11-13 05:14:55Z tim_pease $
 
 require 'logging/repository'
 
 # require all appenders
 require 'logging/appenders/console'
 require 'logging/appenders/file'
+require 'logging/appenders/growl'
 require 'logging/appenders/rolling_file'
 require 'logging/appenders/static_appender'
+require 'logging/appenders/syslog'
 
 # require all layouts
 require 'logging/layouts/basic'
@@ -16,16 +18,17 @@ require 'logging/layouts/pattern'
 require 'logging/config/yaml_configurator'
 
 
-#
 #
 #
 module Logging
 
+  VERSION = '0.5.0'   # :nodoc:
+
   LEVELS = {}  # :nodoc:
   LNAMES = {}  # :nodoc:
 
   class << self
-    #
+
     # call-seq:
     #    Logging.configure( filename )
     #
@@ -40,7 +43,6 @@ module Logging
       else raise ArgumentError, 'unknown configuration file format' end
     end
 
-    #
     # call-seq:
     #    Logging.logger( device, age = 7, size = 1048576 )
     #    Logging.logger( device, age = 'weekly' )
@@ -137,7 +139,6 @@ module Logging
       logger
     end
 
-    #
     # call-seq:
     #    Logging.define_levels( levels )
     #
@@ -198,7 +199,6 @@ module Logging
       levels.keys
     end
    
-    #
     # call-seq:
     #    Logging.format_as( obj_format )
     #
@@ -225,6 +225,8 @@ module Logging
     end
 
     # :stopdoc:
+
+    # Convert the given level into a connaconical form - a lowercase string.
     def levelify( level )
       case level
       when String: level.downcase
@@ -232,6 +234,7 @@ module Logging
       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
@@ -239,6 +242,21 @@ module Logging
       when 'off': LEVELS.length
       else begin; Integer(l); rescue ArgumentError; LEVELS[l] end end
     end
+
+    # Helper method for retrieving options from a hash.
+    def options( opts = {} )
+      lambda do |*args|
+        keys, default, ignored = args
+        catch('opt') do
+          Array(keys).each do |key|
+            [key, key.to_s, key.to_s.intern].each do |key|
+              throw 'opt', opts[key] if opts.has_key?(key)
+            end
+          end
+          default
+        end
+      end
+    end
     # :startdoc:
   end
 

data/lib/logging/appender.rb

@@ -1,4 +1,4 @@
-# $Id: appender.rb 20 2007-01-26 20:18:42Z tim_pease $
+# $Id: appender.rb 37 2007-10-26 19:12:44Z tim_pease $
 
 require 'thread'
 require 'logging'
@@ -8,7 +8,6 @@ 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.
@@ -26,7 +25,6 @@ module Logging
 
     attr_reader :name, :layout, :level
 
-    #
     # call-seq:
     #    Appender.new( name )
     #    Appender.new( name, :layout => layout )
@@ -52,7 +50,6 @@ module Logging
       ::Logging::Appender[@name] = self
     end
 
-    #
     # call-seq:
     #    append( event )
     #
@@ -69,7 +66,6 @@ module Logging
       self
     end
 
-    #
     # call-seq:
     #    appender << string
     #
@@ -86,7 +82,6 @@ module Logging
       self
     end
 
-    #
     # call-seq:
     #    level = :all
     #
@@ -129,7 +124,6 @@ module Logging
       @level = lvl
     end
 
-    #
     # call-seq
     #    appender.layout = Logging::Layouts::Basic.new
     #
@@ -143,7 +137,6 @@ module Logging
       @layout = layout
     end
 
-    #
     # call-seq:
     #    close( footer = true )
     #
@@ -159,7 +152,6 @@ module Logging
       self
     end
 
-    #
     # call-seq:
     #    closed?
     #
@@ -169,7 +161,6 @@ module Logging
     #
     def closed?( ) @closed end
 
-    #
     # call-seq:
     #    flush
     #
@@ -180,7 +171,7 @@ module Logging
 
 
     private 
-    #
+
     # call-seq:
     #    write( str )
     #
@@ -189,7 +180,6 @@ module Logging
     #
     def write( str ) nil end
 
-    #
     # call-seq:
     #    sync { block }
     #

data/lib/logging/appenders/console.rb

@@ -1,16 +1,14 @@
-# $Id: console.rb 32 2007-02-22 23:32:17Z tim_pease $
+# $Id: console.rb 37 2007-10-26 19:12:44Z 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
+  class Stdout < ::Logging::Appenders::IO
 
-    #
     # call-seq:
     #    Stdout.new
     #    Stdout.new( :layout => layout )
@@ -24,12 +22,10 @@ module Appenders
     end
   end  # class Stdout
 
-  #
   # This class provides an Appender that can write to STDERR.
   #
-  class Stderr< ::Logging::Appenders::IO
+  class Stderr < ::Logging::Appenders::IO
 
-    #
     # call-seq:
     #    Stderr.new
     #    Stderr.new( :layout => layout )

data/lib/logging/appenders/file.rb

@@ -1,15 +1,13 @@
-# $Id: file.rb 27 2007-02-01 16:58:11Z tim_pease $
+# $Id: file.rb 46 2007-10-31 14:39:01Z tim_pease $
 
 require 'logging/appenders/io'
 
 module Logging::Appenders
 
-  #
   # This class provides an Appender that can write to a File.
   #
   class File < ::Logging::Appenders::IO
 
-    #
     # call-seq:
     #    File.new( name, :filename => 'file' )
     #    File.new( name, :filename => 'file', :truncate => true )
@@ -22,7 +20,7 @@ module Logging::Appenders
     # appened to the file.
     #
     def initialize( name, opts = {} )
-      @fn = opts.delete(:filename) || opts.delete('filename')
+      @fn = opts.delete(:filename) || opts.delete('filename') || name
       raise ArgumentError, 'no filename was given' if @fn.nil?
 
       mode = opts.delete(:truncate) || opts.delete('truncate')