log4r 1.0.6

data/src/log4r/rdoc/outputter

@@ -0,0 +1,108 @@
+= Outputters
+
+An Outputter is a logging destination with a particular way to format
+data. It has a level threshold and a flexible level mask.
+
+Outputters must have names.
+
+== Level Threshold
+
+Outputters have their own level thresholds that default to <tt>root</tt> 
+level. They will not write any log events with a rank less than their
+threshold.
+
+== Level Mask
+
+Alternatively, an Outputter can be told to log specific levels only:
+
+  o = StdoutOutputter.new 'console'
+  o.only_at DEBUG, FATAL         # only DEBUG and FATAL get written 
+
+== Outputter Repository
+
+When outputters are created, they store themselves in an Outputter
+repository similar to the Logger repository. 
+
+  StdoutOutputter.new 'console'   => Create 'console' outputter
+  Outputter['console']            => Get it back from the stash.
+
+== Formatter
+
+An outputter has a format defined by its Formatter. If no Formatter
+is specified, DefaultFormatter will be used.
+
+== Outputter is Abstract
+
+The basic Outputter class is both abstract and a null object.
+
+== Interesting Outputters
+
+* log4r/outputter/syslogoutputter.rb - Logs to syslog
+* log4r/outputter/emailoutputter.rb - Email logs
+* log4r/logserver.rb - For remote logging
+
+== Subclasses
+
+* Log4r::IOOutputter - for any IO object
+* Log4r::StdoutOutputter - $stdout
+* Log4r::StderrOutputter - $stderr
+* Log4r::FileOutputter - log to a file
+* Log4r::RollingFileOutputter - log to a file and split it as it grows
+* Log4r::SyslogOutputter - logs to syslog
+* Log4r::EmailOutputter - email logs
+* Log4r::RemoteOutputter - for remote logging
+
+== Default Outputters
+
+Two outputters named 'stdout' and 'stderr' are created automatically at
+the root level. They are nice shortcuts.
+
+  Outputter['stdout'] => 'stdout'
+  Outputter['stderr'] => 'stderr'
+  Outputter.stdout    => 'stdout'
+  Outputter.stderr    => 'stderr'
+
+== Configuring
+
+Outputters must have names and receive hash arguments. The parameter name
+for the hash args can be either a symbol or a string. All defined outputters
+accept <tt>:level</tt> and <tt>:formatter</tt> arguments. For arguments 
+specific to a convenience Outputter, please look at the class description.
+
+The level threshold, the levels to log at (only_at) and formatter can be
+changed dynamically using the <tt>=</tt> methods.
+
+As a collective example of all this, here are various ways to set up an 
+IOOutputter:
+
+  IOOutputter.new ExoticIO.new 'exotic', 'level' => WARN, 
+                  :formatter => MyFormatter.new
+  # an equivalent way:
+  o = IOOutputter.new ExoticIO.new 'exotic'
+  o.level = WARN
+  o.formatter = MyFormatter         # we can specify just the class
+  o.only_at = THIS, THAT
+
+== XML Configuration
+
+Specify outputters as children of <tt><log4r_config></tt>:
+
+  <log4r_config>
+    <outputter name="myout" type="Log4r::StdoutOutputter">
+      <only_at>DEBUG, INFO</only_at>
+    </outputter>
+    <outputter name="file" level="WARN">
+      <type>FileOutputter</type>
+      <filename>#{logpath}/file.log</filename>
+      <trunc>false</trunc>
+    </outputter>
+    ...
+
+As explained in log4r/configurator.rb, the hash arguments you would normally
+pass to <tt>new</tt> are specified as <i>XML parameters</i>.
+It is given an IO object to write 
+to, a Formatter to call, and, optionally, levels to write at.
+
+Outputters invoke print then flush on the wrapped IO object.
+If the IO chokes, the Outputter will close the IO and set its
+level to <tt>OFF</tt>.

data/src/log4r/rdoc/patternformatter

@@ -0,0 +1,128 @@
+= PatternFormatter
+
+PatternFormatter offers complete control over the appearance of
+Log4r log events without having to write custom Formatter classes.
+In order to take advantage of PatternFormatter, some familarity with
+Kernel#sprintf or the C printf function is recommended. For time formatting,
+please look at Time.strftime.
+
+PatternFormatter accepts three hash arguments:
+
+<tt>pattern</tt>::       Log event format string.
+<tt>date_pattern</tt>::  Date format string.
+<tt>date_method</tt>::   <tt>Time</tt> method to call (instead of using date_pattern).
+
+
+The <tt>pattern</tt> format string is something like "%l [%d] %80M", 
+which resembles a pattern one would normally pass to Kernel#sprintf. However, 
+the directives are specific to Log4r. Before we go on, let's cover some
+terminology.
+
+== Terminology
+
+[<b>%</b>]  The directive identifier. Everything after this up to and 
+            including one of the <em>directive letters</em> defines a 
+            <em>directive</em>.
+[<b>directive letter</b>]  
+  Letters in the set <tt>[cCdtmMl%]</tt>. These 
+  identify what kind of data we're interested in. 
+  They are detailed below.
+[<b>format directive</b>] 
+  The numbers and assorted symbols that appears 
+  between <b>%</b> and a <em>directive letter</em>
+  is a format directive. It is comprised of an
+  integer specifying the field width followed 
+  optionally by a period and an integer specifying 
+  the precision. The field width is the minimum 
+  number of characters to copy from the data string 
+  while the precision is the maximum number to copy. 
+  If the field width is preceded by a - sign, the 
+  data will be left-justified. Otherwise, it is 
+  right-justified.
+[<b>directive</b>]  
+  A statement that says, "I want this data to appear with 
+  this (optional) particular format." A directive starts 
+  with a <b>%</b> and is followed by a format directive and 
+  terminates in a directive letter.
+
+== What the Directive Letters mean
+
+[<b>c</b>]  Produces a logger's name. Fast.
+[<b>C</b>]  Produces a logger's full name. Fast.
+[<b>d</b>]  Produces the time in a format specified by <b>date_pattern</b> or
+            by <b>date_method</b>. If neither is specified, the default will 
+            be used (ISO8601). Slow.
+[<b>t</b>]  Produces the file and line number of the log event. The 
+            appearance varies by Ruby version, but it is the same output 
+            returned by Kernel#caller[0]. Slow.
+[<b>m</b>] The non-inspected log message. That is, to_s called on the object 
+           passed into a log method. Fast.
+[<b>M</b>] The message formatted by the <tt>format_object</tt> method in 
+           BasicFormatter. It will pretty-print Exceptions, print Strings
+           and inspect everything else. Slow.
+[<b>l</b>] The name of the level. That's l as in Lambda. Fast.
+[<b>%</b>] %% just prints a %. Any formatting is <em>probably</em> ignored. 
+           Fast.
+
+== Examples of directives:
+
+
+[<b>%d</b>]    Prints out the date according to our date_pattern or 
+               date_method. By default, it looks like this: 2001-01-12 13:15:50
+[<b>%.120m</b>]  Prints out at most 120 characters of the log message.
+[<b>%15t</b>]    Prints the execution trace and pads it on the left with 
+                 enough whitespace to make the whole thing 15 chars.
+
+== Pattern String
+
+A pattern string is simply a bunch of directives combined with the desired
+format. For instance, to show the level in brackets followed by the date
+and then the log message trimmed to 15 characters, we use the following
+pattern:
+ 
+  "[%l] %d :: %.15m"     #=>     [DEBUG] 2001-01-12 13:15:50 :: This is a messa
+ 
+To create a PatternFormatter with this format:
+ 
+  p = PatternFormatter.new(:pattern => "[%l] %d :: %.15m")
+ 
+== Formatting time
+ 
+To format time, do one of the following:
+ 
+* Specify a date_pattern
+* Specify what class method of Ruby's <tt>Time</tt> class to call.
+* Use the default format
+ 
+If neither date_pattern nor date_method is specified, the default date
+format will be used. Currently, that would be ISO8601,
+ 
+The date_pattern is exactly what one would pass to <tt>Time.strftime</tt>.
+To specify a date_pattern, pass
+<tt>:date_pattern=>"pattern"</tt> to PatternFormat.new.
+ 
+Alternatively, date_method can be specified to produce the output of
+a specific <tt>Time</tt> method, such as <tt>usec</tt> or <tt>to_s</tt> 
+or any other zero argument <tt>Time</tt> method that produces a time. More 
+precisely, the method to call will be invoked on <tt>Time.now</tt>. 
+To specify a date_method, pass <tt>:date_method=>'methodname'</tt> (or a 
+Symbol equivalent) to <tt>PatternFormatter.new</tt>.
+
+= XML Configuration
+
+As explained in log4r/configurator.rb, the hash arguments to PatternFormatter
+are <i>XML parameters</i>. Here's an example:
+
+  <formatter type="PatternFormatter" pattern="[%l] %d :: %.15m">
+    <date_method>usec</date_method>
+  </formatter>
+ 
+= Performace considerations
+ 
+The performance impact of using a particular directive letter is noted in
+the <b>What the Directives Letters mean</b> section.
+ 
+The performance impact of time formatting merits special attention. If you
+aren't aware yet, the Time class is kind of a kludge. Time.now.usec happens
+to be faster than Time.now. If you're concerned about performance, please
+profile the various time methods and patterns.

data/src/log4r/rdoc/syslogoutputter

@@ -0,0 +1,29 @@
+= SyslogOutputter
+
+A SyslogOutputter transforms a Log4r::LogEvent into a call to syslog().
+Since syslog has its own formatting system, log4r formatters are ignored. 
+
+== Usage
+
+To use, 
+
+  <tt>require 'log4r/outputter/syslogoutputter'</tt>
+
+An example,
+
+  require 'log4r'
+  require 'log4r/outputter/syslogoutputter'
+
+  syslog = Log4r::SyslogOutputter.new("name", 'logopt'=>#, 'facility'=>#)
+  syslog.err("this is an ERR message")
+
+The output in <tt>/var/logs/syslog</tt> (Debian) is,
+
+  Sep  3 11:43:06 tiphares sys[1603]: this is an ERR message
+
+The hash arguments +logoptions+ and +facility+ are passed to 
+<tt>Syslog.open</tt>. The
+defaults are <tt>LOG_PID | LOG_CONS</tt> and <tt>LOG_USER</tt> respectively.
+
+This is a first try implementation. It works well. Please report 
+any bugs and fixes.

data/src/log4r/rdoc/yamlconfigurator

@@ -0,0 +1,20 @@
+= Configuring Log4r with Log4r::YamlConfigurator
+
+The YamlConfigurator class allows one to set up Log4r via YAML.
+It is used almost exactly as Log4r::Configurator and has the same features,
+
+  ycfg = YamlConfigurator    # handy shorthand
+  ycfg['foo'] = bar          # replaces instances of #{foo} in the YAML with bar
+  ycfg.load_yaml_file('foo.yaml')
+
+Ruby 1.7 and 1.8 comes with a YAML parser. Hence, YAML can be used
+to configure Log4r out of the box.
+
+A comprehensive example of a Log4r YAML configuration is provided in the 
+examples directory.
+
+To use this class:
+
+  require 'log4r/yamlconfigurator'
+
+Thanks to Andreas Hund for making this possible.

data/src/log4r/repository.rb

@@ -0,0 +1,65 @@
+# :nodoc:
+# Version:: $Id: repository.rb,v 1.1.1.1 2004/03/19 03:31:07 fando Exp $
+
+require "singleton"
+
+module Log4r
+class Logger
+
+  # The repository stores a Hash of loggers keyed to their fullnames and
+  # provides a few functions to reduce the code bloat in log4r/logger.rb.
+  # This class is supposed to be transparent to end users, hence it is
+  # a class within Logger. If anyone knows how to make this private,
+  # let me know.
+  
+  class Repository # :nodoc:
+    include Singleton
+    attr_reader :loggers
+    
+    def initialize
+      @loggers = Hash.new
+    end
+
+    def self.[](fullname)
+      instance.loggers[fullname]
+    end
+
+    def self.[]=(fullname, logger)
+      instance.loggers[fullname] = logger
+    end
+  
+    # Retrieves all children of a parent
+    def self.all_children(parent)
+      # children have the parent name + delimiter in their fullname
+      daddy = parent.name + Private::Config::LoggerPathDelimiter
+      for fullname, logger in instance.loggers
+        yield logger if parent.is_root? || fullname =~ /#{daddy}/
+      end
+    end
+
+    # when new loggers are introduced, they may get inserted into
+    # an existing inheritance tree. this method
+    # updates the children of a logger to link their new parent
+    def self.reassign_any_children(parent)
+      for fullname, logger in instance.loggers
+        next if logger.is_root?
+        logger.parent = parent if logger.path =~ /^#{parent.fullname}$/
+      end
+    end
+    
+    # looks for the first defined logger in a child's path 
+    # or nil if none found (which will then be rootlogger)
+    def self.find_ancestor(path)
+      arr = path.split Log4rConfig::LoggerPathDelimiter
+      logger = nil
+      while arr.size > 0 do
+        logger = Repository[arr.join(Log4rConfig::LoggerPathDelimiter)]
+        break unless logger.nil?
+        arr.pop
+      end
+      logger
+    end
+
+  end
+end
+end

data/src/log4r/staticlogger.rb

@@ -0,0 +1,49 @@
+# :nodoc:
+module Log4r
+  class Logger
+    # Returns the root logger. Identical to Logger.global
+    def self.root; return RootLogger.instance end
+    # Returns the root logger. Identical to Logger.root
+    def self.global; return root end
+    
+    # Get a logger with a fullname from the repository or nil if logger
+    # wasn't found.
+
+    def self.[](_fullname)
+      # forces creation of RootLogger if it doesn't exist yet.
+      return RootLogger.instance if _fullname=='root' or _fullname=='global'
+      Repository[_fullname]
+    end
+
+    # Like Logger[] except that it raises NameError if Logger wasn't found.
+
+    def self.get(_fullname)
+      logger = self[_fullname]
+      if logger.nil?
+        raise NameError, "Logger '#{_fullname}' not found.", caller
+      end
+      logger
+    end
+
+    # Yields fullname and logger for every logger in the system.
+    def self.each
+      for fullname, logger in Repository.instance.loggers
+        yield fullname, logger
+      end
+    end
+
+    def self.each_logger
+      Repository.instance.loggers.each_value {|logger| yield logger}
+    end
+
+    # Internal logging for Log4r components. Accepts only blocks.
+    # To see such log events, create a logger named 'log4r' and give 
+    # it an outputter.
+
+    def self.log_internal(level=1)
+      internal = Logger['log4r']
+      return if internal.nil?
+      internal.send(LNAMES[level].downcase, yield)
+    end
+  end
+end

data/tests/README

@@ -0,0 +1,10 @@
+The unit tests are currently out of date. The examples actually provide
+a decent test suite for log4r. But the unit tests are still very important
+because of bounds-checking and a quicker turnaround for bug discovery.
+The unit files need to be converted to the new 'test/unit' paradigm.
+
+Because Log4r dynamically defines constants according to user preferences, 
+the unit testing can't all be done in one instance of ruby. It is planned
+to use popen to run each test that needs a clean ruby instance.
+
+The logs/ directory is where these tests dump generated log files.

data/tests/testall.rb

@@ -0,0 +1,6 @@
+$: << File.join("..", "src")
+
+# because constants are dynamically defined, some tests need to
+# be opened in a fresh instance of Ruby, hence the popens
+
+IO.popen("date") { |f| puts f.gets }

data/tests/testbase.rb

@@ -0,0 +1,49 @@
+$: << File.join("..","src")
+require "test/unit"
+require "log4r"
+include Log4r
+
+class TestBase < Test::Unit::TestCase
+  # check that LNAMES loads properly (it uses an eval to load)
+  def test_default_levels
+    Logger.root              # doing this loads the default levels
+    assert_equal(ALL,0)
+    assert_equal(DEBUG,1)
+    assert_equal(INFO,2)
+    assert_equal(WARN,3)
+    assert_equal(ERROR,4)
+    assert_equal(FATAL,5)
+    assert_equal(OFF,6)
+    assert_equal(LEVELS, 7)
+    assert_equal(LNAMES.size, 7)
+  end
+  # check bad input and bounds for validate_level
+  def test_validate_level
+    7.times{|i| assert_nothing_raised {Log4rTools.validate_level(i)} }
+    assert_raises(ArgumentError) {Log4rTools.validate_level(-1)}
+    assert_raises(ArgumentError) {Log4rTools.validate_level(LEVELS)}
+    assert_raises(ArgumentError) {Log4rTools.validate_level(String)}
+    assert_raises(ArgumentError) {Log4rTools.validate_level("bogus")}
+  end
+  # decode_bool turns a string 'true' into true and so on
+  def test_decode_bool
+    # when the key is a symbol :data
+    assert(Log4rTools.decode_bool({:data=> 'true'}   ,:data,false) == true)
+    assert(Log4rTools.decode_bool({:data=> true}     ,:data,false) == true)
+    assert(Log4rTools.decode_bool({:data=> 'false'}  ,:data,true) == false)
+    assert(Log4rTools.decode_bool({:data=> false}    ,:data,true) == false)
+    assert(Log4rTools.decode_bool({:data=> nil}      ,:data,true) == true)
+    assert(Log4rTools.decode_bool({:data=> nil}      ,:data,false) == false)
+    assert(Log4rTools.decode_bool({:data=> String}   ,:data,true) == true)
+    assert(Log4rTools.decode_bool({:data=> String}   ,:data,false) == false)
+    # now the key is a string 'data'
+    assert(Log4rTools.decode_bool({'data'=> 'true'}  ,:data,false) == true)
+    assert(Log4rTools.decode_bool({'data'=> true}    ,:data,false) == true)
+    assert(Log4rTools.decode_bool({'data'=> 'false'} ,:data,true) == false)
+    assert(Log4rTools.decode_bool({'data'=> false}   ,:data,true) == false)
+    assert(Log4rTools.decode_bool({'data'=> nil}     ,:data,true) == true)
+    assert(Log4rTools.decode_bool({'data'=> nil}     ,:data,false) == false)
+    assert(Log4rTools.decode_bool({'data'=> String}  ,:data,true) == true)
+    assert(Log4rTools.decode_bool({'data'=> String}  ,:data,false) == false)
+  end
+end