sml-log4r 1.0.6

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.

data/src/log4r/rdoc/emailoutputter

@@ -0,0 +1,103 @@
+= EmailOutputter
+
+This is an experimental class that sends a number of formatted log events as 
+an RFC 822 email. It should work fine if Net:SMTP doesn't cause any 
+problems. Just in case, create a logger named 'log4r' and give it an 
+outputter to see the logging statements made by this class. If it fails to 
+send email, it will set itself to OFF and stop logging.
+
+In order to use it,
+
+  require 'log4r/outputter/emailoutputter'
+
+== SMTP Configuration
+
+All arguments to Net::SMTP.start are supported. Pass them as hash
+parameters to +new+. The to field is specified as a comma-delimited 
+list of emails (padded with \s* if desired).
+
+An example:
+
+  email_out = EmailOutputter.new 'email_out',
+                     :server=>'localhost',
+                     :port=>25,
+                     :domain=>'somewhere.com',
+                     :from=>'me@foo.bar',
+                     :to=>'them@foo.bar, me@foo.bar, bozo@clown.net',
+                     :subject=>'Log Report'
+
+== LogEvent Buffer
+
+EmailOutputter stores log messages in a buffer. When the buffer reaches a 
+certain number, the <tt>buffsize</tt>, it will send an email containing the 
+contents of the buffer. The default +buffsize+ is 100. To set +buffsize+,
+
+  email_out.buffsize = 1000   # set the buffsize to 1000
+
+== Flush To Send Email
+
+Flushing an EmailOutputter will mail out all the remaining LogEvents.
+This is convenient for systems that encapsulate the shutdown process. It's a 
+good idea to do this for all outputters,
+
+  Outputter.each_outputter {|o| o.flush}
+
+Alternatively, one can invoke flush on the outputter directly,
+  
+  email_out.flush
+
+It's also a good idea to notify the recepient of the email that
+the system is shutting down. Before flushing, log a message
+to the owner of this outputter,
+
+  log_with_email_out.info "The system is shutting down at #{Time.now}"
+
+== Format When?
+
+LogEvents may either be formatted as they come in or as the
+email is being composed. To do the former, specify a value of +true+
+to the hash parameter +formatfirst+. The default is to format 
+during email composition.
+
+  email_out.formatfirst = true     # format as soon as LogEvents are received
+
+== Immediate Notification
+
+EmailOutputter can be configured to flush and send the email whenever the
+logger sees a certain log priority. Use the +immediate_at+ hash parameter
+and specify the levels as a comma-delimited list (like an XML element).
+To trigger an email on FATAL and ERROR,
+
+  email_out.immediate_at = "FATAL, ERROR"   
+
+== Example
+
+A security logger sends email to several folks, buffering up to 25
+log events and sending immediates on CRIT and WARN
+
+  EmailOutputter.new 'security', 
+                     :to => 'bob@secure.net, frank@secure.net',
+                     :buffsize => 25,
+                     :immediate_at => 'WARN, CRIT'
+                     
+== XML Configuration
+
+See log4r/configurator.rb for details. Here's an example:
+
+  <outputter name="security" type="EmailOutputter"
+             buffsize="25" level="ALL">
+    <immediate_at>WARN, CRIT</immediate_at>
+    <server>localhost</server>
+    <from>me@secure.net</from>
+    <to>
+      bob@secure.net, frank@secure.net
+    </to>
+    ...
+  </outputter>
+
+== To Do
+
+This class could use some sophistication, in particular a means to compress
+the logs, a way to set the subject dynamically (probably via a block method),
+and a time trigger. When the time trigger is introduced, a +buffsize+
+of 0 should mean ignore +buffsize+ to determine when to send the email.

data/src/log4r/rdoc/formatter

@@ -0,0 +1,39 @@
+= Formatters
+
+Formatters are responsible for formatting LogEvent data.
+An Outputter owning a Formatter will invoke the 
+Log4r::Formatter#format method prior to writing.
+
+== Available Formatters
+
+* Log4r::BasicFormatter -  default
+* Log4r::PatternFormatter - most flexible. See log4r/formatter/patternformatter.rb
+* Log4r::SimpleFormatter - like BasicFormatter for Strings only (low noise)
+* Log4r::ObjectFormatter - for inspecting objects
+* Log4r::NullFormatter - twirls on its feet and does nothing
+
+= XML Configuration
+
+Specify the Formatter and its class (as +type+) under an 
+<tt><outputter></tt> directive:
+
+  <outputter name="someout" type="sometype">
+    <formatter type="Log4r::BasicFormatter"/>
+  </outputter>
+
+As explained in log4r/configurator.rb, the hash arguments you would normally
+pass to +new+ are specified as <i>XML parameters</i>. Only PatternFormatter
+has any of these.
+
+= Custom Formatting
+
+Building a custom Formatter is extremely easy. Just define a class
+that extends Formatter and override the Formatter#format method.
+Then give it to any interested Outputters. 
+
+If you're interested in setting up your custom formatters in XML,
+please take a look at log4r/configurator.rb.
+
+== Data Available
+
+See Log4r::LogEvent

data/src/log4r/rdoc/log4r

@@ -0,0 +1,89 @@
+= #{version} Log4r API Reference
+
+Welcome to the Log4r API reference. There are two classes of reference,
+the file overview and the class API. They are listed under Files and Classes
+respectively. File overviews cover the use of the Log4r API and some 
+implementation details, whereas class APIs detail the methods available to 
+the various objects.
+
+The code examples in this API assume:
+
+  include Log4r
+
+This file overview covers some of the major concepts in Log4r.
+
+
+== Log Levels
+
+Log4r provides as many levels of logging as desired. Logging levels
+are an ordered set of names ranked by priority. The more important a level is,
+the higher its priority and the more likely we want to see any data associated 
+with it. Log4r provides many ways to filter information by level.
+
+Loggers and Outputters have a level parameter which serves as a level 
+threshold. Any data below this threshold will be ignored by the Logger or
+Outputter. Additionally, Outputters can be set to mask out any particular
+level or collection of levels.
+
+By combining level thresholds with other Log4r features, one can direct any
+set of data to any destination desired in a way that is easy to visualize
+and configure.
+
+=== Default Levels
+
+The default log levels and their priority rankings are:
+
+  DEBUG < INFO < WARN < ERROR < FATAL
+
+=== Custom Levels
+
+You can have as many levels as you desire, with any naming scheme. Log4r
+will automatically define level constants and log method names after
+your custom specification.
+
+Please see log4r/configurator.rb for details.
+
+=== Boundary Levels
+
+There are two special levels, <tt>ALL</tt> and <tt>OFF</tt> which
+denote whether we are logging at all levels or at none. The priority 
+ranks with respect to the logging levels are as follows:
+
+  ALL < logging levels as defined by user < OFF
+
+Thus, setting the level to <tt>ALL</tt> will enable logging at all levels
+whereas <tt>OFF</tt> will turn off logging completely.
+
+== File Overviews
+
+For Loggers::        log4r/logger.rb
+For Outputters::     log4r/outputter/outputter.rb
+For Formatters::     log4r/formatter/formatter.rb
+For configuration::  log4r/configurator.rb
+
+== Principal Classes of Log4r
+
+* Log4r::Logger - Interface to logging
+* Log4r::Outputter - An output destination for a logger.
+* Log4r::Formatter - A means of formatting log data.
+* Log4r::Configurator - A means of configuring Log4r 
+
+== Convenience Classes
+
+Log4r provides several convenience Outputters and Formatters. Please
+look at the file overviews of those classes for more details.
+
+== Remote Logging
+
+Log4r provides a way to send log events over a network. See log4r/logserver.rb
+for details.
+
+== What's Going on Inside?
+
+Log4r has an internal logger which records much of what goes on inside. To see 
+the output, define a Logger named 'log4r' and give it an Outputter of some
+sort. It logs only at the lowest and highest priorities. That would be
+DEBUG and FATAL for the standard setup.
+
+It is essential to view this data when using certain classes, like 
+Log4r::LogServer and Log4r::EmailOutputter.