log4r 1.0.6

data/examples/logclient.rb

@@ -0,0 +1,25 @@
+# How to use RemoteOutputter. See logserver.rb first.
+
+$: << File.join('..','src')
+require 'log4r'
+require 'log4r/outputter/remoteoutputter'
+include Log4r
+
+Logger.new('log4r').add 'stdout'        # to see what's going on inside
+RemoteOutputter.new 'remote',           # make a RemoteOutputter
+    :uri=>'tcpromp://localhost:9999',   # where our LogServer is
+    :buffsize=>10                       # buffer 10 before sending to LogServer
+Logger.new('client').add('remote')      # give 'remote' to a 'client' Logger
+
+# we're done with setup, now let's log
+def log(l)
+  l.debug "debugging"
+  l.info "a piece of info"
+  l.warn "Danger, Will Robinson, danger!"
+  l.error "I dropped by Wookie! :("
+  l.fatal "kaboom!"
+end
+
+5.times { log(Logger['client']) }      # do a bunch of logging
+Logger['client'].info "Bye Bye from client!"
+Outputter['remote'].flush              # flush the RemoteOutputter

data/examples/logserver.rb

@@ -0,0 +1,18 @@
+# How to use LogServer
+
+$: << File.join('..','src')
+require 'log4r'
+require 'log4r/configurator'
+
+# XML configuration is simple enough to embed here
+xml = %(
+<log4r_config>
+  <logserver name="server" uri="tcpromp://localhost:9999">
+   <outputter>stdout</outputter>
+  </logserver>
+</log4r_config>
+)
+Log4r::Logger.new('log4r').add 'stdout'        # to see what's going on inside
+Log4r::Configurator.load_xml_string xml        # load it up
+sleep                                   
+# now run logclient.rb on another terminal

data/examples/moderate.xml

@@ -0,0 +1,29 @@
+<!-- the config file used by xmlconfig.rb -->
+<log4r_config>
+  <pre_config>
+    <global level="DEBUG"/>
+    <!-- we'll set serverlog in XML and logpath at runtime for illustration -->
+    <parameter name="serverlog" value="./logs/server.log"/>
+  </pre_config>
+
+  <!-- outputters, illustrating XML config flexibility -->
+  <outputter type="FileOutputter" name="server">
+    <filename>#{serverlog}</filename>
+    <trunc>false</trunc>
+  </outputter>
+  <outputter type="FileOutputter" name="client" 
+             filename="#{logpath}/client.log"/>
+  <outputter type="FileOutputter" name="gui" 
+             filename="#{logpath}/guidebug.log"/>
+  <outputter type="StderrOutputter" name="console" level="ERROR"/>
+
+  <!-- loggers -->
+
+  <logger name="server" level="ERROR" outputters="server, console"/>
+  <logger name="client" level="INFO"  outputters="client, console"/>
+  <logger name="client::gui" trace="true">
+    <level>DEBUG</level>
+    <outputter>gui</outputter>
+  </logger>
+
+</log4r_config> 

data/examples/moderateconfig.rb

@@ -0,0 +1,66 @@
+# Now, for something more complicted
+# Let's pretend this is the global config file for our app
+
+$: << File.join('..','src')
+require "log4r"
+
+include Log4r                   # include Log4r to make things simple
+
+Logger.root.level = DEBUG       # global level DEBUG
+
+# suppose we want to have loggers for a Server and a Client class
+# furthermore, we want the client gui to have its own logger. (You'll want
+# one logger per class or so.)
+# When the loggers are created, they are stored in a repository for further
+# retreival at any point using a hash method call: Logger['name']
+
+# server is stable, so only log ERROR and FATAL
+Logger.new("server", ERROR)
+# let's say we don't need the DEBUG junk for client logs
+Logger.new("client", INFO)
+# but we're still debugging the gui
+debugger = Logger.new("client::gui", DEBUG)
+debugger.trace = true     # we want to see where the log method was called
+
+# Guilog is a child of client. In this case, any log events to the gui
+# logger will also be logged to the client outputters. We can change
+# that behavior by setting guilogger's 'additive' to false, but not yet.
+
+# let's create the outputters
+FileOutputter.new('server', :filename=>'logs/server.log', :trunc => false)
+FileOutputter.new('client', :filename=>'logs/client.log')
+FileOutputter.new('gui', :filename=>'logs/guidebug.log')
+# additionally, we want ERROR and FATAL messages to go to stderr
+StderrOutputter.new('console', :level=>ERROR)
+
+# add the outputters
+Logger['server'].add 'server', 'console'
+Logger['client'].add 'client', 'console'
+Logger['client::gui'].add 'gui'  # gui will also write to client's outputters
+
+# That's it for config. Now let's use the loggers:
+
+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) }
+
+# You can dynamically change levels and turn off tracing:
+Logger['client'].level = OFF
+Logger['client::gui'].trace = false
+
+puts 'Only server should show Dynamic Change onscreen:'
+Logger.each_logger{|logger| logger.fatal "Dynamic change." }
+# logs/client.log file should not show "Dynamic change."
+# logs/guidebug.log should not show the trace at "Dynamic change."
+
+# we can also set our outputter to log only specified levels:
+
+Outputter['console'].only_at ERROR
+puts "Should only see ERROR next:"
+do_logging Logger['server']

data/examples/myformatter.rb

@@ -0,0 +1,23 @@
+# try out a custom formatter
+
+$: << '../src'
+
+require "log4r"
+
+class MyFormatter <  Log4r::Formatter
+  def format(event)
+    buff = "The level is #{event.level} and has "
+    buff += "name '#{Log4r::LNAMES[event.level]}'\n"
+    buff += "The logger is '#{event.name}' "
+    buff += "and the data type is #{event.data.class}\n"
+    buff += "Let's inspect the data:\n"
+    buff += event.data.inspect + "\n"
+    buff += "We were called at #{event.tracer[0]}\n\n"
+  end
+end
+
+log = Log4r::Logger.new('custom formatter')
+log.trace = true
+log.add Log4r::StdoutOutputter.new('stdout', :formatter=>MyFormatter)
+log.info [1, 2, 3, 4]
+log.error "A log statement"

data/examples/outofthebox.rb

@@ -0,0 +1,21 @@
+# Here's how to start using log4r right away
+$: << File.join('..','src')                   # path if log4r not installed
+require "log4r"
+
+Log = Log4r::Logger.new("outofthebox")        # create a logger
+Log.add Log4r::Outputter.stderr               # which logs to stdout
+
+# do some logging
+def do_logging
+ 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
+do_logging
+
+# now let's filter anything below WARN level (DEBUG and INFO)
+puts "-= Changing level to WARN =-"
+Log.level = Log4r::WARN
+do_logging

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('..','src')
+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('..','src')
+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/xmlconfig.rb

@@ -0,0 +1,25 @@
+# This is like moderateconfig.rb, but using an XML config
+# please look at moderate.xml
+
+$: << '../src'
+
+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('..','src') # 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'
+include Log4r
+
+cfg = 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
+Outputter['email'].level = OFF
+# the other two outputters log to stderr and a timestamped file in ./logs
+do_logging( Logger['mylogger'])

data/src/log4r.rb

@@ -0,0 +1,17 @@
+# :include: log4r/rdoc/log4r
+#
+# == Other Info
+#
+# Author::      Leon Torres
+# Version::     $Id: log4r.rb,v 1.1.1.1 2004/03/19 03:31:06 fando Exp $
+
+require "log4r/outputter/fileoutputter"
+require "log4r/outputter/consoleoutputters"
+require "log4r/outputter/staticoutputter"
+require "log4r/outputter/rollingfileoutputter"
+require "log4r/formatter/patternformatter"
+require "log4r/loggerfactory"
+
+module Log4r
+  Log4rVersion = [1, 0, 1].join '.'
+end

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