log4r-color 1.1.11

data/lib/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/lib/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/lib/log4r/rdoc/scribeoutputter

@@ -0,0 +1,16 @@
+= ScribeOutputter
+
+A ScribeOutputter transforms a Log4r::LogEvent into an event passed to Scribe. The user can configure the outputter with
+the host and port of the scribe scribe server.
+
+== Usage
+
+To use,
+  <tt>require 'log4r'</tt>
+
+An example,
+
+  require 'log4r'
+
+  logger = Log4r::ScribeOutputter.new('name', '127.0.0.1', 1463)
+  logger.debug("Hello World")

data/lib/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/lib/log4r/rdoc/win32eventoutputter

@@ -0,0 +1,7 @@
+= Win32EventOutputter
+
+THIS IS A DEVELOPMENT VERSION AND IS NOT READY FOR USE
+INFACT, IT MAY NEVER BE READY FOR USE, AS TRYING TO INTERACT
+WITH THE WIN32 EVENTLOG API REQUIRES USER INTERVENTION TO LOOKUP
+event_id AND category CODES THAT THIS LIBRARY CANNOT KNOW A PRIORI
+

data/lib/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/lib/log4r/repository.rb

@@ -0,0 +1,88 @@
+# :nodoc:
+# Version:: $Id$
+#
+# Using Thread.exclusive seems to be more efficient than using
+# a class wide instance of Sync.synchronize in ruby 1.8.6 - Colby
+#
+# Using Sync.synchronize, 5000 iterations:
+# real	3m55.493s user	3m45.557s sys	0m3.478s
+#
+# Using Thread.exclusive, 5000 iterations:
+# real	2m35.859s user	2m33.951s sys	0m1.224s
+#
+
+require 'monitor'
+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:
+      extend MonitorMixin
+      include Singleton
+      attr_reader :loggers
+
+      def initialize
+	@loggers = Hash.new
+      end
+
+      def self.[](fullname)
+	self.synchronize do
+	  instance.loggers[fullname]
+	end # exclusive
+      end
+
+      def self.[]=(fullname, logger)
+	self.synchronize do
+	  instance.loggers[fullname] = logger
+	end # exclusive
+      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
+	self.synchronize do
+	  for fullname, logger in instance.loggers
+	    yield logger if parent.is_root? || fullname =~ /#{daddy}/
+	  end
+	end # exclusive
+      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)
+	self.synchronize do
+	  for fullname, logger in instance.loggers
+	    next if logger.is_root?
+	    logger.parent = parent if logger.path =~ /^#{parent.fullname}$/
+	  end
+	end # exclusive
+      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
+	self.synchronize do
+	  while arr.size > 0 do
+	    logger = Repository[arr.join(Log4rConfig::LoggerPathDelimiter)]
+	    break unless logger.nil?
+	    arr.pop
+	  end
+	end # exclusive
+	logger
+      end
+
+    end # class Repository
+  end # class Logger
+end # Module Log4r
+

data/lib/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