log4r 1.0.6

data/src/log4r/outputter/rollingfileoutputter.rb

@@ -0,0 +1,126 @@
+
+# :nodoc:
+# Version:: $Id: rollingfileoutputter.rb,v 1.1.1.1 2004/03/19 03:31:10 fando Exp $
+
+require "log4r/outputter/fileoutputter"
+require "log4r/staticlogger"
+
+module Log4r
+
+  # RollingFileOutputter - subclass of FileOutputter that rolls files on size
+  # or time. Additional hash arguments are:
+  #
+  # [<tt>:maxsize</tt>]   Maximum size of the file in bytes.
+  # [<tt>:trunc</tt>]	  Maximum age of the file in seconds.
+  class RollingFileOutputter < FileOutputter
+
+    attr_reader :count, :maxsize, :maxtime, :startTime#,i:baseFilename
+
+    def initialize(_name, hash={})
+      @count = 0
+      super(_name, hash)
+      if hash.has_key?(:maxsize) || hash.has_key?('maxsize') 
+        _maxsize = (hash[:maxsize] or hash['maxsize']).to_i
+        if _maxsize.class != Fixnum
+          raise TypeError, "Argument 'maxsize' must be an Fixnum", caller
+        end
+        if _maxsize == 0
+          raise TypeError, "Argument 'maxsize' must be > 0", caller
+        end
+        @maxsize = _maxsize
+      end
+      if hash.has_key?(:maxtime) || hash.has_key?('maxtime') 
+        _maxtime = (hash[:maxtime] or hash['maxtime']).to_i
+        if _maxtime.class != Fixnum
+          raise TypeError, "Argument 'maxtime' must be an Fixnum", caller
+        end
+        if _maxtime == 0
+          raise TypeError, "Argument 'maxtime' must be > 0", caller
+        end
+        @maxtime = _maxtime
+        @startTime = Time.now
+      end
+      @baseFilename = File.basename(@filename)
+      # roll immediately so all files are of the form "000001-@baseFilename"
+      roll
+      # initialize the file size counter
+      @datasize = 0
+    end
+
+    #######
+    private
+    #######
+
+    # perform the write
+    def write(data) 
+      # we have to keep track of the file size ourselves - File.size doesn't
+      # seem to report the correct size when the size changes rapidly
+      @datasize += data.size + 1 # the 1 is for newline
+      super
+      roll if requiresRoll
+    end
+
+    # construct a new filename from the count and baseFilname
+    def makeNewFilename
+      # note use of hard coded 6 digit counter width - is this enough files?
+      pad = "0" * (6 - @count.to_s.length) + count.to_s
+      newbase = @baseFilename.sub(/(\.\w*)$/, pad + '\1')
+      @filename = File.join(File.dirname(@filename), newbase)
+      Logger.log_internal {"File #{@filename} created"}
+    end 
+
+    # does the file require a roll?
+    def requiresRoll
+      if !@maxsize.nil? && @datasize > @maxsize
+        @datasize = 0
+        return true
+      end
+      if !@maxtime.nil? && (Time.now - @startTime) > @maxtime
+        @startTime = Time.now
+        return true
+      end
+      false
+    end 
+
+    # roll the file
+    def roll
+      begin
+        @out.close
+      rescue 
+        Logger.log_internal {
+          "RollingFileOutputter '#{@name}' could not close #{@filename}"
+        }
+      end
+      @count += 1
+      makeNewFilename
+      @out = File.new(@filename, (@trunc ? "w" : "a"))
+    end 
+
+  end
+
+end
+
+# this can be found in examples/fileroll.rb as well
+if __FILE__ == $0
+  require 'log4r'
+  include Log4r
+
+
+  timeLog = Logger.new 'WbExplorer'
+  timeLog.outputters = RollingFileOutputter.new("WbExplorer", { "filename" => "TestTime.log", "maxtime" => 10, "trunc" => true })
+  timeLog.level = DEBUG
+
+  100.times { |t|
+    timeLog.info "blah #{t}"
+    sleep(1.0)
+  }
+
+  sizeLog = Logger.new 'WbExplorer'
+  sizeLog.outputters = RollingFileOutputter.new("WbExplorer", { "filename" => "TestSize.log", "maxsize" => 16000, "trunc" => true })
+  sizeLog.level = DEBUG
+
+  10000.times { |t|
+    sizeLog.info "blah #{t}"
+  }
+
+end

data/src/log4r/outputter/staticoutputter.rb

@@ -0,0 +1,30 @@
+# :nodoc:
+module Log4r
+
+  class Outputter
+    # Retrieve an outputter.
+    def self.[](name)
+    out = @@outputters[name]
+      if out.nil?
+        return case name
+        when 'stdout' then StdoutOutputter.new 'stdout'
+        when 'stderr' then StderrOutputter.new 'stderr'
+        else nil end
+      end          
+      out
+    end
+    def self.stdout; Outputter['stdout'] end
+    def self.stderr; Outputter['stderr'] end
+    # Set an outputter.
+    def self.[]=(name, outputter)
+      @@outputters[name] = outputter
+    end
+    # Yields each outputter's name and reference.
+    def self.each
+      @@outputters.each {|name, outputter| yield name, outputter}
+    end
+    def self.each_outputter
+      @@outputters.each_value {|outputter| yield outputter}
+    end
+  end
+end

data/src/log4r/outputter/syslogoutputter.rb

@@ -0,0 +1,75 @@
+# :include: ../rdoc/syslogoutputter
+#
+# Version:: $Id: syslogoutputter.rb,v 1.1.1.1 2004/03/19 03:31:10 fando Exp $
+# Author:: Steve Lumos
+# Author:: Leon Torres
+
+require 'log4r/formatter/formatter'
+require 'log4r/outputter/outputter'
+require 'log4r/configurator'
+require 'syslog'
+
+module Log4r
+
+  # syslog needs to set the custom levels
+  if LNAMES.size > 1
+    raise LoadError, "Must let syslogger.rb define custom levels"
+  end
+  # tune log4r to syslog priorities
+  Configurator.custom_levels("DEBUG", "INFO", "NOTICE", "WARNING", "ERR", "CRIT", "ALERT", "EMERG")
+
+  class SyslogOutputter < Outputter
+    include Syslog::Constants
+
+    # maps log4r levels to syslog priorities (logevents never see ALL and OFF)
+    SYSLOG_LEVELS = [
+        nil, 
+        LOG_DEBUG, 
+        LOG_INFO, 
+        LOG_WARNING, 
+        LOG_ERR, 
+        LOG_CRIT, 
+        nil
+    ]
+
+    # There are 3 hash arguments
+    #
+    # [<tt>:ident</tt>]     syslog ident, defaults to _name
+    # [<tt>:logopt</tt>]    syslog logopt, defaults to LOG_PID | LOG_CONS
+    # [<tt>:facility</tt>]  syslog facility, defaults to LOG_USER
+    def initialize(_name, hash={})
+      super(_name, hash)
+      ident = (hash[:ident] or hash['ident'] or _name)
+      logopt = (hash[:logopt] or hash['logopt'] or LOG_PID | LOG_CONS).to_i
+      facility = (hash[:facility] or hash['facility'] or LOG_USER).to_i
+      @syslog = Syslog.open(ident, logopt, facility)
+    end
+
+    def closed?
+      return !@syslog.opened?
+    end
+    
+    def close
+      @syslog.close unless @syslog.nil?
+      @level = OFF
+      OutputterFactory.create_methods(self)
+      Logger.log_internal {"Outputter '#{@name}' closed Syslog and set to OFF"}
+    end
+
+    private
+
+    def canonical_log(logevent)
+      pri = SYSLOG_LEVELS[logevent.level]
+      o = logevent.data
+      if o.kind_of? Exception then
+        msg = "#{o.class} at (#{o.backtrace[0]}): #{o.message}"
+      elsif o.respond_to? :to_str then
+        msg = o.to_str
+      else
+        msg = o.inspect
+      end
+      
+      @syslog.log(pri, '%s', msg)
+    end
+  end
+end

data/src/log4r/rdoc/configurator

@@ -0,0 +1,243 @@
+= Configuring Log4r with Log4r::Configurator
+
+The Configurator class allows one to set up Log4r via XML.
+Additionally, Configurator contains methods to configure any Log4r 
+defaults. In particular, Configurator provides a method to
+customize the logging levels.
+
+Log4r is also configurable using YAML. For that, there is
+a class similar to Configurator called Log4r::YamlConfigurator. Please see
+log4r/yamlconfigurator.rb for details.
+
+REXML is required for XML configuration. Get REXML at 
+http://www.ruby-lang.org/en/raa-list.rhtml?name=REXML
+
+To use the Configurator class,
+
+  require 'log4r/configurator'
+
+== Custom Levels
+
+Suppose you want the following levels and ranks:
+
+  Foo < Bar < Baz
+
+This is easily accomplished:
+
+  Configurator.custom_levels('Foo', 'Bar', :Baz)
+
+The method accepts strings or symbols. However, custom levels must have names 
+that are valid for Ruby constants. Also, custom levels should be set before 
+anything else is done with Log4r, otherwise the default levels will be loaded.
+
+You can set custom levels in XML. That's covered in the following section.
+
+== XML Configuration
+
+If you have REXML, you can configure Log4r with XML.
+To do this, first write an XML configuration (which you can learn by
+studying this document and the examples provided in the distribution)
+and then load up the XML from within your program as follows:
+
+  Configurator.load_xml_file('/path/to/file.xml')
+
+The Log4r XML configuration system is very flexible and powerful. In fact,
+it is somewhat preferable to configuring Log4r in Ruby. In order to take
+full advantage of this feature, there are several concepts one must know.
+They are covered in the following three sections.
+
+=== Concept: XML Directives
+
+The expressive power of Ruby has enabled a feature I call 
+<i>XML directives</i>. An XML directive is a name-value pair belonging to 
+some element. It
+may be represented as an attribute (name="value") of the element, or
+as a child (<name>value</name>) of the element. Therefore, you are
+free to specify information about an object as either an attribute
+or an element. An example should clarify:
+
+  <object data="value"/>
+
+Is equivalent to:
+
+  <object>
+     <data>value</data>
+  </object>
+
+You can assume this behavior except where noted elsewhere in the API.
+
+=== Concept: XML Parameters
+
+A scheme which I call <i>XML parameters</i> enables one to utilize the XML 
+configuratin system for custom Outputters and Formatters.
+This requires <b>no</b> extra work on your part, so long as your objects 
+are set up using hash arguments and can decode string values. That is, once
+you've written a custom Outputter, it is automatically configurable in XML
+without having to write any extra code.
+
+An XML parameter is analogous to a hash argument to some object's <tt>new</tt>
+method. Consider these hash arguments to FileOutputter:
+
+  :filename => '/path/to/logs/my.log'
+  :trunc => 'true'
+
+We can specify them in XML like this:
+
+  <outputter type="FileOutputter" trunc="true">
+     <filename>/path/to/logs/my.log</filename>
+     ...
+
+The name of the element/attribute is just the name of the parameter. Note that
+the input will be a string, thus it's wise to convert the data in from 
+strings in any custom classes (to_i for integers, etc). Now let's suppose you 
+have defined a custom Outputter named MyOutputter with the following 
+additional hash args:
+
+  :myarg1 => 'foo'
+  :myarg2 => 123
+
+Automagically, you can configure your Outputter like so:
+
+  <outputter type="MyOutputter" myarg2="123">
+     <myarg1>foo</myarg1>
+     ...
+
+Isn't that nice? <tt>:-)</tt>
+
+=== Concept: Variable Substitution
+
+To kill the need for preprocessors, Configurator provides a means of variable 
+substitution for XML parameters at runtime. If you specify 
+<tt>#{foo}</tt> in an XML parameter value, Configurator will replace it with 
+the value of 'foo' in its parameter hashtable. The primary idea is that you 
+can figure stuff out in your program, 
+say the log path, and relay that information to the XML while it's being 
+loaded. Secondarily, it is a way to have aliases within an XML document.
+
+There are two ways to tell Configurator about these variables. The first
+method we'll cover is done within a Ruby program with Configurator[].
+
+  Configurator['logpath'] = '/path/to/logs'
+
+Thereafter, any occurence of <tt>#{logpath}</tt> in each and every XML 
+parameter will be substituted with '/path/to/logs'. For example:
+
+  <filename>#{logpath}/mylog.log</filename>
+
+Becomes,
+
+  <filename>/path/to/logs/mylog.log</filename>
+
+Aside from Configurator[], another way to define XML parameter variables
+is to define <tt>parameters</tt> under the <tt><pre_config></tt> element
+of an XML configuration:
+
+  <pre_config>
+     <parameter name="logpath" value="/path/to/logs'/>
+     <parameter name="other" value="somethingelse'/>
+     ...
+  </pre_config>
+
+Alternatively,
+
+  <pre_config>
+     <parameters>
+        <logpath>/path/to/logs</logpath>
+        <other>somethingelse</other>
+        ...
+     </parameters>
+     ...
+
+The end result is the same as using Configurator[]. However, this method
+is not dynamic. Configurator[] should be used when you want to set variables
+from within Ruby.
+
+= XML Grammar
+
+And now, here's the XML grammar we use to configure Log4r.
+
+== Root Element
+
+The root element is <tt><log4r_config></tt>. It can be embedded as a node of
+any other element in an XML file. For instance:
+
+  <my-xml-thing>
+     <customize-libraries>
+        <log4r_config>
+           <!-- log4r configuratin goes here -->
+        </log4r_config>
+        ...
+
+== Pre-config element
+
+The pre_config element is a child of log4r_config and contains:
+
+* 'custom_levels' element
+* 'global' element
+* 'parameters' element
+* any number of 'parameter' elements
+
+=== Pre_config: Custom Levels
+
+The custom_levels element is not an <i>XML directive</i> of pre_config. It
+<b>must</b> be specified like this:
+
+  <custom_levels>Foo, Bar, Baz</custom_levels>
+
+And <b>not</b> like this:
+
+  <!-- NOT SUPPORTED -->
+  <custom_levels levels="Foo, Bar, Baz"/>
+
+=== Pre_config: Global Level
+
+  <global level="DEBUG"/>
+
+or
+
+  <global><level>DEBUG</level></global>
+
+Here, level is an XML directive of global.
+
+=== Pre_config: Parameters
+
+Parameters are variables that will be substituted later on. Please
+see the <b>Concept: Variable Substitution</b> section above. Parameters 
+are <i>XML Directives</i>, which means they can be expressed using elements 
+or attributes. Here is an example:
+
+  <parameter name="param name 1" value="param value 1">
+  <parameter name="param name 2" value="param value 2">
+  ...
+  <parameters>
+     <param3>value3</param3>
+     <param4>value3</param4>
+     ...
+
+=== Pre_config: Complete Example
+
+   <log4r_config>
+
+      <pre_config>
+         <custom_levels>
+            Foo,Bar, Baz
+         </custom_levels>
+         <global level="Bar"/>
+         <parameters>
+            <logpath>/var/log/foo</logpath>
+            <mypattern>%l [%d] %m</mypattern>
+         </parameters>
+      </pre_config>
+
+      <!-- define some outputters and loggers -->
+      
+   </log4r_config>
+
+== Configuring Log4r Objects
+
+The XML configuration grammar for Loggers, Outputters and the like are 
+covered in the usage guidelines for those classes.
+
+== Order Doesn't Matter
+
+You can (it is hoped) define any of the XML objects in any order desired.