sml-log4r 1.0.6

data/src/log4r/rdoc/logger

@@ -0,0 +1,175 @@
+= Loggers
+
+Loggers provide the interface for logging in Log4r. To create a logger,
+first come up with a name for it. Good choices include the name of the
+class using it, a service name, or the name of the file. 
+
+To create a logger named 'mylog':
+
+  Logger.new('mylog')
+
+After creating a logger, it is stashed in a repository. The logger may
+be retrieved at any time:
+
+  Logger['mylog']              # get mylog back
+
+It will return nil if the logger is not found. Alternatively, if an
+Exception is desired when a nonexistant logger is referenced, the Logger#get
+command can be used:
+
+  Logger.get('boguslog')       # raises NameError if it doesn't exist
+
+== Manipulating a Logger's Outputters
+
+Loggers start out with no outputters. They can be added using the
+Logger#add method or set directly by modifying the Loggers#outputters array:
+
+  mylog = Logger['mylog']
+
+  # assume we've created Outputters out1 through out4
+  mylog.outputters = out1, out2 
+  mylog.add(out3, out4)
+  mylog.each_outputter {|o| o.flush}
+  
+  # assume out5 through out7 have names 'out5' through 'out7' resp.
+  mylog.outputters = 'out5', 'out6'
+  mylog.add('out7')
+  mylog.remove('out5','out7')
+
+Please see log4r/outputter/outputter.rb and Log4r::Outputter for more about
+outputters.
+
+== Logging Methods
+
+To log something at a certain priority, use the logging method named
+after the lowercased priority level name:
+
+  mylog.warn "This is a message with priority WARN"
+  mylog.fatal "A FATAL message"
+
+Blocks can also be logged:
+
+  mylog.warn {"This is also a message with priority WARN"}
+  mylog.debug do
+    # some complicated string magic
+    return result
+  end
+
+The primary difference is that the block doesn't get called unless
+the Logger can log at that level. It is useful for doing computationaly
+expensive things at a log event.
+
+== Query Methods
+
+To ask Log4r whether it is capable of logging a certain level:
+
+  mylog.warn?   # are we logging WARN?
+  mylog.fatal?  # how about FATAL?
+
+Query methods and blocks accomplish the same thing:
+
+  mylog.warn "don't evaluate unless WARN is on" if mylog.warn?
+  mylog.warn {"don't evaluate unless WARN is on"}
+
+== What About the Special Levels?
+
+<tt>ALL</tt> and <tt>OFF</tt> can be querried, but not logged:
+
+  log.off?                    # true iff level is OFF
+  log.all?                    # true iff level is ALL
+  log.all "Try to log"        => Method not defined. (NameError)
+
+== Custom Levels and Method Names
+
+Suppose we've set up Log4r with the custom levels:
+
+  Foo < Bar < Baz
+
+As one might expect, the logging methods are named after them:
+
+  log.bar "something"        # log at custom level Bar
+  log.bar?                   # are we logging at level Bar?
+
+= Logger Inheritance
+
+Normally, when a logger is created, its parent is set to RootLogger.
+If a Logger's level isn't specified at creation, it will inherit the level 
+of its parent.
+
+To specify an ancestors of a logger besides RootLogger, include the names 
+of the ancestors in order of ancestry and delimited by 
+Log4r::Log4rConfig::LoggerPathDelimiter. For example, if the 
+delimiter is the default <tt>::</tt>, our logger is 'me' 
+and its ancestors are 'cain', 'grandpa', and 'pa', we create the logger 
+like so:
+
+  Logger.new('cain::grandpa::pa::me')
+
+This string is split into three compontents which can be used
+by a Formatter to avoid parsing the name:
+
+Logger#fullname::   The whole enchilada: 'cain::grandpa::pa::me'
+Logger#name::       Just 'me'
+
+To get this logger back from the repository,
+
+  Logger['cain::grandpa::pa::me']
+
+= Outputter Additivity
+
+By default, Logger Outputters are <b>additive</b>. This means that
+a log event will also be sent to all of a logger's ancestors. To 
+stop this behavior, set a logger's +additive+ to false.
+
+  Logger['foo'].additive = false
+
+A Logger's level, additivity and trace can be changed dynamically,
+but this is an expensive operation as the logging methods have to be
+redefined.
+
+= RootLogger
+
+Log4r::RootLogger is the ancestor of all loggers. Its level defines the global
+logging threshold. Any loggers created <b>after</b> RootLogger's level is
+set will not log below that level. By default, RootLogger's level is set
+to <tt>ALL</tt>
+
+RootLogger is a singleton which gets created automaticallay. It can be
+retrieved at any time with Logger.root, Logger.global,
+Logger['root'] or Logger['global'].
+
+== Global Level
+
+Suppose we want _everything_ to ignore events less than FATAL. We can
+accomplish this easily:
+
+  Logger.global.level = FATAL
+
+Just be sure to set this before any other Loggers or Outputters are defined.
+
+== RootLogger Does Nothing
+
+RootLogger itself behaves as if its level were permanently set to 
+<tt>OFF</tt>, thus making it a sort of null object.
+
+= XML Configuration
+
+Please see log4r/configurator.rb for an overview of XML configuratoin.
+
+It's easy to configure a Logger in XML. The following example should be
+sufficient:
+
+    ...
+    <logger name="papa::mylog" level="DEBUG" trace="true">
+      <additive>false</additive>
+      <outputter>stdout</outputter>
+      <outputters>stderr, dancer, doner, blitzen</outputters>
+    </logger>
+    <logger name="papa" outputters="stderr, stdout"/>
+    ...
+
+The element +outputter+ can occur multiple times, but cannot be an attribute 
+of +logger+. That is, it is not an <i>XML directive</i>. However, the element 
++outputters+ is an <i>XML directive</i>, as are all the others.
+
+For more examples, check the <tt>examples</tt> directory in the Log4r package.

data/src/log4r/rdoc/logserver

@@ -0,0 +1,85 @@
+= Remote Logging 
+
+Want to use Log4r over a network? No problem! A Log4r::RemoteOutputter will
+send its LogEvents to a Log4r::LogServer. These two classes are as easy to
+set up and use as the rest of Log4r. 
+
+== Use ROMP
+
+There is one catch though: ROMP is required to use this service. It is a
+DRb-like system with superb performance and better features. Get ROMP at 
+http://rubystuff.org/romp/
+
+== LogServer
+
+LogServer is simply a kind of Logger which embeds a ROMP::Server. Like a
+normal Logger, you can give it Outputters, set its level and so on. Its
+logging methods are accessible over a network and are called by a 
+RemoteOutputter on another host.
+
+=== LogServer Setup
+
+Setup is easy. First,
+
+  require 'log4r/logserver'
+
+The following sets up a LogServer named 'central' on localhost port 9999:
+
+  LogServer.new('central', 'tcpromp://localhost:9999')
+
+We manipulate it and give it outputters as normal:
+
+  serv = Logger['central']              # grab our new LogServer
+  serv.add 'stdout'                     # make it log to $stdout
+
+== RemoteOutputter
+
+RemoteOutputter is simply a kind of Outputter that embeds a ROMP::Client. When 
+RemoteOutputter gets a LogEvent, it will forward it to whatever LogServer it's 
+connected to. In essence, RemoteOutputter behaves like a Logger that is
+forwarding a LogEvent to another Logger (as is done in hierarchical logging).
+
+=== RemoteOutputter Setup
+
+First,
+
+  require 'log4r/outputter/remoteoutputter'
+
+Unlike typical outputters, RemoteOutputter doesn't do any formatting. That's
+up to the LogServer's outputters. Otherwise, RemoteOutputter can be
+set up as usual. The ROMP uri of the LogServer must be specified.
+
+  RemoteOutputter.new 'client', :uri=>'tcpromp://localhost:9999'
+
+=== Using RemoteOutputter
+
+Give our new RemoteOutputter to a logger:
+
+  mylog = Logger['mylog']
+  mylog.add 'client'
+
+Now, whenever mylog generates a LogEvent, LogServer should get a copy. Doing
+the following:
+
+  mylog.info "This is a message from 'mylog'"
+
+Produces this output on LogServer's console:
+
+  INFO mylog: This is a message from 'mylog'
+
+== XML Configuration
+
+RemoteOutputter is set up like normal Outputters. LogServer is set up
+like a normal Logger, but with an element name of logserver instead of
+logger:
+
+  <log4r_config>
+    <logserver name="name" uri="tcpromp://localhost:9999">
+    ...
+
+== Debugging
+
+It is recommended to set up a logger named 'log4r' on both the server and
+client to see what LogServer and RemoteOutputter are up to. Both of the classes
+use Log4r's internal logging to report any problems. See the section
+<b>What's Going on Inside?</b> in log4r.rb for more info.

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