mtn_log4r 1.1.11

data/examples/rrconfig.xml

@@ -0,0 +1,63 @@
+<!-- This is a real config file used by a game that I'm working on 
+     The Ruby file that loads this is rrsetup.rb -->
+<log4r_config>
+  <pre_config>
+    <!-- I like having a ton of levels. There are three extra for component
+         data, comp1..3 and one level for object dumps (DATA) -->
+    <custom_levels>
+      COMP3, COMP2, COMP1, DATA, DEBUG, INFO, WARN, ERROR, FATAL
+    </custom_levels>
+    <!-- change to ERROR when the game goes to production -->
+    <global level="ALL"/>
+  </pre_config>
+
+  <!-- Outputters -->
+
+  <!-- game.log records DEBUG and higher, so no game component data -->
+  <outputter name="gameout" type="FileOutputter" level="DEBUG">
+    <!-- I set the logpath from within the game. -->
+    <filename>#{logpath}/game.log</filename>
+  </outputter>
+  <!-- DATA level goes to its own special file. These log events are
+       too noisy for game.log and are not game components. Useful
+       for dumping lots of objects during development. -->
+  <outputter name="gamedata" type="FileOutputter" only_at="DATA">
+    <filename>#{logpath}/data.log</filename>
+    <!-- low-noise custom formatter for objects -->
+    <formatter type="CompFormatter"/>
+  </outputter>
+  <!-- Spit any errors to the console. They merit special attention -->
+  <outputter name="console" type="StderrOutputter" level="ERROR"/>
+  <!-- A separate log file for tracking game components, 
+       used for development. It logs ALL-->
+  <outputter name="componentout" type="FileOutputter">
+    <filename>#{logpath}/component.log</filename>
+    <formatter type="CompFormatter"/>
+  </outputter>
+
+  <!-- Loggers -->
+
+  <!-- 'game' is the main logger for the client-server framework -->
+  <logger name="game" level="DATA" additive="false" trace="true">
+    <outputters>gameout, gamedata, console</outputters>
+  </logger>
+  <!-- Notice how we have fine control over how each element logs.
+       The gui and controller are stable while the rest are being debugged. -->
+  <logger name="game::gui" level="ERROR" additive="true" trace="true"/>
+  <logger name="game::boardgui" level="DEBUG" additive="true" trace="false"/>
+  <logger name="game::server" level="DEBUG" additive="true" trace="true"/>
+  <logger name="game::client" level="DEBUG" additive="true" trace="true"/>
+  <logger name="game::controller" level="ERROR" additive="true" trace="false"/>
+
+  <!-- 'component' is the main logger for game objects. It's used in
+       development to track how the objects change with time. -->
+  <logger name="component" level="ALL" additive="false" trace="false">
+    <outputter>componentout</outputter>
+    <outputter>console</outputter>
+  </logger>
+  <logger name="component::board"/>
+  <logger name="component::tile"/>
+  <logger name="component::player"/>
+  <logger name="component::player::robot"/>
+ 
+</log4r_config>

data/examples/rrsetup.rb

@@ -0,0 +1,42 @@
+# This is a real config file used by a game that I'm working on
+# The XML config file is called rrconfig.xml
+
+$: << File.join('..','lib')
+require 'log4r'
+require 'log4r/configurator'
+include Log4r
+
+# How to format component data - low noise
+class CompFormatter < Formatter
+  def format(event)
+    buff = event.name + "> "
+    if event.data.kind_of?(String) then buff += event.data
+    else buff += event.data.inspect end
+    return buff + "\n"
+  end
+end
+
+# Set the logpath. Eventually, this will be determined from the environment.
+Configurator['logpath'] = './logs'
+Configurator.load_xml_file('rrconfig.xml')
+
+# the rest is an example
+
+Robot = {"name"=>"twonky", "row"=>"3", "col"=>"4"}
+
+def do_logging(log)
+log.comp3  Robot
+log.comp2 Robot
+log.comp1 Robot
+log.data "this is a piece of data".split
+log.debug "debugging"
+log.info "a piece of info"
+log.warn "Danger, Will Robinson, danger!"
+log.error "I dropped my Wookie! :(" 
+log.fatal "kaboom!"
+end
+
+Logger.each_logger {|logger| do_logging(logger)}
+
+# you can see the results onscreen and in logs/game.log
+# logs/data.log and logs/component.log

data/examples/simpleconfig.rb

@@ -0,0 +1,39 @@
+# Simple configuration example.
+# Where we configure just one logger and make it log to a file and stdout.
+
+# add the path to log4r if it isn't installed in a ruby path
+$: << File.join('..','lib')
+require "log4r"
+
+# First things first, get the root logger and set its level to WARN.
+# This makes the global level WARN. Later on, we can turn off all logging
+# by setting it to OFF right here (or dynamically if you prefer)
+Log4r::Logger.root.level = Log4r::WARN
+
+# Remember: By specifying a level, we are saying "Include this level and
+# anything worse." So in this case, we're logging WARN, ERROR and FATAL
+
+# create a logger
+log = Log4r::Logger.new("simpleconf")
+
+# We want to log to $stderr and a file ./tmp.log
+
+# Create an outputter for $stderr. It defaults to the root level WARN
+Log4r::StderrOutputter.new 'console'
+# for the file, we want to log only FATAL and ERROR and don't trunc
+Log4r::FileOutputter.new('logfile', 
+                         :filename=>'logs/simple.log', 
+                         :trunc=>false,
+                         :level=>Log4r::FATAL)
+
+# add the outputters (this method accepts outputter names or references)
+log.add('console','logfile')
+
+# Now let's try it out:
+log.debug "debugging"
+log.info "a piece of info"
+log.warn "Danger, Will Robinson, danger!"
+log.error "I dropped my Wookie! :("
+log.fatal "kaboom!"
+
+# now run this and compare output to ./tmp.log

data/examples/syslogcustom.rb

@@ -0,0 +1,52 @@
+# Suppose we don't like having 5 levels named DEBUG, INFO, etc.
+# Suppose we'd rather use 3 levels named Foo, Bar, and Baz.
+# Suppose we'd like to use these with syslog
+# Log4r allows you to rename the levels and their corresponding methods
+# in a painless way and then map those to corrisponding syslog levels
+# or have them all default to LOG_INFO
+# This file provides an example
+
+$: << '../lib'
+
+require 'log4r'
+require 'log4r/configurator'
+require 'log4r/formatter/patternformatter'
+require 'log4r/outputter/syslogoutputter'
+require 'syslog'
+include Log4r
+include Syslog::Constants
+
+# This is how we specify our levels
+Configurator.custom_levels "Foo", "Bar", "Baz"
+
+l = Logger.new('custom levels')
+slp = PatternFormatter.new( :pattern => '{%p} {%h} {%d} {%l} {%C} {%m}', :date_method => 'usec' )
+sl = SyslogOutputter.new( 'sysloggertest', 
+			 { :logopt => LOG_CONS | LOG_PID | LOG_PERROR,
+			   :facility => LOG_LOCAL7,
+			   :formatter => slp } )
+sl.map_levels_by_name_to_syslog( { "Foo" => "DEBUG", "Bar" => "INFO", "Baz" => "ALERT" } )
+l.add sl
+
+l.level = Foo
+puts l.foo?
+l.foo "This is foo"
+puts l.bar?
+l.bar "this is bar"
+puts l.baz?
+l.baz "this is baz"
+
+puts "Now change to Baz"
+
+l.level = Baz
+puts l.foo?
+l.foo {"This is foo"}
+puts l.bar?
+l.bar {"this is bar"}
+puts l.baz?
+l.baz {"this is baz"}
+
+l4r = Logger.new('log4r')
+l4r.add Log4r::Outputter.stderr
+
+Log4r::SyslogOutputter.new 'test'

data/examples/xmlconfig.rb

@@ -0,0 +1,25 @@
+# This is like moderateconfig.rb, but using an XML config
+# please look at moderate.xml
+
+$: << '../lib'
+
+require 'log4r'
+require 'log4r/configurator'
+include Log4r
+
+# set any runtime XML variables
+Configurator['logpath'] = './logs'
+# Load up the config file
+Configurator.load_xml_file('./moderate.xml')
+
+# now repeat what moderateconfig.rb does
+def do_logging(log)
+log.debug "debugging"
+log.info "a piece of info"
+log.warn "Danger, Will Robinson, danger!"
+log.error "I dropped my Wookie! :("
+log.fatal "kaboom!"
+end
+
+Logger.each_logger{|logger| do_logging(logger) }
+# stop here

data/examples/yaml.rb

@@ -0,0 +1,30 @@
+# Log4r can be configured using YAML. This example uses log4r_yaml.yaml
+
+$: << File.join('..','lib') # path if log4r is not installed
+require 'log4r'
+require 'log4r/yamlconfigurator'
+# we use various outputters, so require them, otherwise config chokes
+require 'log4r/outputter/datefileoutputter'
+require 'log4r/outputter/emailoutputter'
+require 'log4r/outputter/scribeoutputter'
+
+cfg = Log4r::YamlConfigurator # shorthand
+cfg['HOME'] = '.'      # the only parameter in the YAML, our HOME directory
+
+# load the YAML file with this
+cfg.load_yaml_file('log4r_yaml.yaml')
+
+# Method to log each of the custom levels
+def do_logging(log)
+  log.deb "This is DEB"
+  log.inf "This is INF"
+  log.prt "This is PRT"
+  log.wrn "This is WRN"
+  log.err "This is ERR"
+  log.fat "This is FAT"
+end
+
+# turn off the email outputter
+Log4r::Outputter['email'].level = Log4r::OFF
+# the other two outputters log to stderr and a timestamped file in ./logs
+do_logging( Log4r::Logger['mylogger'])

data/lib/log4r/GDC.rb

@@ -0,0 +1,41 @@
+# :include: rdoc/GDC
+#
+# == Other Info
+# 
+# Version:: $Id$
+# Author:: Colby Gutierrez-Kraybill <colby(at)astro.berkeley.edu>
+
+require 'monitor'
+
+module Log4r
+  GDCNAME = "log4rGDC"
+  $globalGDCLock = Monitor.new
+
+  # See log4r/GDC.rb
+  class GDC < Monitor
+    private_class_method :new
+
+    def self.clear()
+      Thread.main[GDCNAME] = ""
+    end
+
+    def self.get()
+      $globalGDCLock.synchronize do
+	if ( Thread.main[GDCNAME] == nil ) then
+	  Thread.main[GDCNAME] = $0
+	end
+      end
+      return Thread.main[GDCNAME]
+    end
+
+    def self.set( a_name )
+      if ( Thread.current != Thread.main ) then
+	raise "Can only initialize Global Diagnostic Context from Thread.main" 
+      end
+      $globalGDCLock.synchronize do
+	Thread.main[GDCNAME] = a_name
+      end
+    end
+  end
+end
+

data/lib/log4r/MDC.rb

@@ -0,0 +1,59 @@
+# :include: rdoc/MDC
+#
+# == Other Info
+# 
+# Version:: $Id$
+# Author:: Colby Gutierrez-Kraybill <colby(at)astro.berkeley.edu>
+
+require 'monitor'
+
+module Log4r
+  MDCNAME = "log4rMDC"
+  MDCNAMEMAXDEPTH = "log4rMDCMAXDEPTH"
+  $globalMDCLock = Monitor.new
+
+  # See log4r/MDC.rb
+  class MDC < Monitor
+    private_class_method :new
+
+    def self.check_thread_instance()
+      # need to interlock here, so that if
+      # another thread is entering this section
+      # of code before the main thread does,
+      # then the main thread copy of the MDC
+      # is setup before then attempting to clone
+      # it off
+      if ( Thread.current[MDCNAME] == nil ) then
+	$globalMDCLock.synchronize do 
+	  if ( Thread.main[MDCNAME] == nil ) then
+	    Thread.main[MDCNAME] = Hash.new
+	  end
+	  if ( Thread.current != Thread.main ) then
+	    Thread.current[MDCNAME] = Hash.new
+	    Thread.main[MDCNAME].each{ |k,v| Thread.current[MDCNAME][k] = v }
+	  end
+	end
+      end
+    end
+
+    def self.get( a_key )
+      self.check_thread_instance()
+      Thread.current[MDCNAME].fetch(a_key, "");
+    end
+
+    def self.get_context()
+      self.check_thread_instance()
+      return Thread.current[MDCNAME].clone
+    end
+
+    def self.put( a_key, a_value )
+      self.check_thread_instance()
+      Thread.current[MDCNAME][a_key] = a_value
+    end
+
+    def self.remove( a_key )
+      self.check_thread_instance()
+      Thread.current[MDCNAME].delete( a_key )
+    end
+  end
+end

data/lib/log4r/NDC.rb

@@ -0,0 +1,86 @@
+# :include: rdoc/NDC
+#
+# == Other Info
+# 
+# Version:: $Id$
+# Author:: Colby Gutierrez-Kraybill <colby(at)astro.berkeley.edu>
+
+module Log4r
+  NDCNAME = "log4rNDC"
+  NDCNAMEMAXDEPTH = "log4rNDCMAXDEPTH"
+  NDCDEFAULTMAXDEPTH = 256
+
+  # See log4r/NDC.rb
+  class NDC
+    private_class_method :new
+
+    def self.check_thread_instance()
+      if ( Thread.current[NDCNAME] == nil ) then
+	Thread.current[NDCNAME] = Array.new
+	Thread.current[NDCNAMEMAXDEPTH] = NDCDEFAULTMAXDEPTH
+      end
+    end
+
+    def self.clear()
+      self.check_thread_instance()
+      Thread.current[NDCNAME].clear
+    end
+
+    def self.clone_stack()
+      self.check_thread_instance()
+      return Thread.current[NDCNAME].clone
+    end
+
+    def self.get_depth()
+      self.check_thread_instance()
+      return Thread.current[NDCNAME].length
+    end
+
+    def self.inherit( a_stack )
+      if ( a_stack.class == Array ) then
+	if ( Thread.current[NDCNAME] != nil ) then
+	  Thread.current[NDCNAME].clear
+	  Thread.current[NDCNAME] = nil
+	end
+	Thread.current[NDCNAME] = a_stack
+      else
+	raise "Expecting Array in NDC.inherit"
+      end
+    end
+
+    def self.get()
+      self.check_thread_instance
+      return Thread.current[NDCNAME] * " "
+    end
+
+    def self.peek()
+      self.check_thread_instance()
+      return Thread.current[NDCNAME].last
+    end
+
+    def self.pop()
+      self.check_thread_instance()
+      return Thread.current[NDCNAME].pop
+    end
+
+    def self.push( value )
+      self.check_thread_instance()
+      if ( Thread.current[NDCNAME].length < Thread.current[NDCNAMEMAXDEPTH] ) then
+	Thread.current[NDCNAME].push( value )
+      end
+    end
+
+    def self.remove()
+      self.check_thread_instance()
+      Thread.current[NDCNAME].clear
+      Thread.current[NDCNAMEMAXDEPTH] = nil
+      Thread.current[NDCNAME] = nil
+    end
+
+    def self.set_max_depth( max_depth )
+      self.check_thread_instance()
+      Thread.current[NDCNAMEMAXDEPTH] = max_depth
+    end
+  end
+end
+

data/lib/log4r/base.rb

@@ -0,0 +1,74 @@
+# :nodoc:
+require "log4r/config"
+
+module Log4r
+  ALL = 0
+  LNAMES = ['ALL']
+
+  # Defines the log levels of the Log4r module at runtime. It is given
+  # either the default level spec (when root logger is created) or the
+  # user-specified level spec (when Logger.custom_levels is called).
+  #
+  # The last constant defined by this method is OFF. Other level-sensitive 
+  # parts of the code check to see if OFF is defined before deciding what 
+  # to do. The typical action would be to force the creation of RootLogger 
+  # so that the custom levels get loaded and business can proceed as usual.
+  #
+  # For purposes of formatting, a constant named MaxLevelLength is defined
+  # in this method. It stores the max level name string size.
+
+  def Log4r.define_levels(*levels) #:nodoc:
+    return if const_defined? :OFF
+    for i in 0...levels.size
+      name = levels[i].to_s
+      module_eval "#{name} = #{i} + 1; LNAMES.push '#{name}'"
+    end
+    module_eval %{
+      LNAMES.push 'OFF'
+      LEVELS = LNAMES.size
+      OFF = LEVELS - 1
+      MaxLevelLength = Log4rTools.max_level_str_size
+    }
+  end
+
+  # Some common functions 
+  class Log4rTools
+    # Raises ArgumentError if level argument is an invalid level. Depth
+    # specifies how many trace entries to remove.
+    def self.validate_level(level, depth=0)
+      unless valid_level?(level)
+        raise ArgumentError, "Log level must be in 0..#{LEVELS}",
+              caller[1..-(depth + 1)]
+      end
+    end
+    
+    def self.valid_level?(lev)
+      not lev.nil? and lev.kind_of?(Numeric) and lev >= ALL and lev <= OFF
+    end
+    
+    def self.max_level_str_size #:nodoc:
+      size = 0
+      LNAMES.each {|i| size = i.length if i.length > size}
+      size
+    end
+  
+    # Shortcut for decoding 'true', 'false', true, false or nil into a bool
+    # from a hash parameter. E.g., it looks for true/false values for
+    # the keys 'symbol' and :symbol.
+
+    def self.decode_bool(hash, symbol, default)
+      data = hash[symbol]
+      data = hash[symbol.to_s] if data.nil?
+      return case data
+        when 'true',true then true
+        when 'false',false then false
+        else default
+        end
+    end
+
+    # Splits comma-delimited lists with arbitrary \s padding
+    def self.comma_split(string)
+      string.split(/\s*,\s*/).collect {|s| s.strip}
+    end
+  end
+end

data/lib/log4r/config.rb

@@ -0,0 +1,9 @@
+# :nodoc:
+# Version:: $Id$
+
+module Log4r
+  module Log4rConfig #:nodoc:
+    LogLevels = ['DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL']
+    LoggerPathDelimiter = '::'
+  end    
+end