sml-log4r 1.0.6

data/doc/dev/README.developers

@@ -0,0 +1,40 @@
+This document introduces interested developers to log4r development.
+
+
+HTML manual and site
+--------------------
+
+This is pieced together with a homebrewed content-template system. 
+doc/content has the actual contents, which are just three lines of metadata 
+and a bunch of <tr>s that are incorporated into a template. The only template 
+is doc/templates/main.html which is universal. To test the changes, run 
+bin/makedoc.rb directly and check the results in doc/index.html.
+
+
+Testing RDoc
+------------
+Either run bin/makerdoc.rb directly or,
+
+  cd src/
+  rdoc --op /tmp/rdoc --template kilmer --main log4r.rb
+
+
+Automated Builds
+----------------
+
+The build system is automated and relies on CVS and ruby. There are three main
+things that go on during build:
+
+1) bin/makedist.rb checks out a build to prepare for distribution and calls
+   other build scripts, then assembles the distribution into tgz and zip balls
+
+2) HTML manual is constructed by bin/makehtml.rb, called from makedist.rb
+
+3) RDoc is constructed by bin/makerdoc.rb, called from makedist.rb
+
+All system variables and configurable options are in bin/devconfig.rb.
+
+Essentially, the only thing that needs to be done to build packages for
+distribution is,
+
+  ruby makedist.rb <version-number>

data/doc/dev/checklist

@@ -0,0 +1,14 @@
+Distribution checklist:
+
+* DON'T FORGET: change install.rb when new src/ files are added
+* DON'T FORGET: change the log4r.gemspec file for same
+* Update the changelog
+* Update the README
+* Change any INSTALL instructions
+* Update the manuals and HTML
+* Modify what should not appear in the release (bin/prune.rb)
+* Run makedist.rb and check the integrity of the resulting tarballs
+  - Test installs
+  - Run the unit tests (cd tests; ruby runtest.rb)
+  - Run all the examples
+  - Browse the docs

data/doc/dev/things-to-do

@@ -0,0 +1,2 @@
+* Rewrite the RDoc in third person (no "you"s)
+* Trap any remaining parameters in the Configurators

data/doc/log4r.css

@@ -0,0 +1,111 @@
+body {
+	background-color: #FFFFFF;
+	font-family:sans-serif;
+}
+
+a:link { color:#014DA3 }
+a:active { color:#AA0000 }
+a:visited { color:#014DA3 }
+a:hoover { color:#AA0000 }
+
+.example {
+	font-family: monospace;
+	border:1px solid #007;
+	background:#FFFFFF;
+	margin:1em;
+}
+
+pre.box {
+	margin:0px 1em 1em 1em;
+	color:#AA0000;
+}
+
+.menu {
+	font-family:sans-serif;
+	font-size:10px;
+	border-left: 1px solid #AA0000;
+	border-right: 1px solid #AA0000;
+	border-bottom: 1px solid #AA0000;
+	background:#EEEEEE;
+	color:#AA0000;
+}
+
+.menutitle {
+  font-family:sans-serif;
+  font-size:medium;
+  color:#FFFFFF;
+  font-weight:bold;
+  background:#AA0000;
+  border-right: 1px solid #AA0000;
+  border-left: 1px solid #AA0000;
+  border-top: 1px solid #AA0000;
+  border-bottom: 1px solid #AA0000;
+}
+
+.menubuff {
+  font-family:sans-serif;
+  font-size:1px;
+  color:#000000;
+  border-left: 1px solid #AA0000;
+  border-right: 1px solid #AA0000;
+  font-weight:bold;
+  background-color: #99CCFF;
+  height:5;
+  padding-bottom: 0;
+}
+
+.contentbuff {
+	font-family:sans-serif;
+	font-size:10px;
+	border-left: 1px solid #AA0000;
+	border-right: 1px solid #AA0000;
+	font-weight:bold;
+	background-color: #99CCFF;
+  height:5;
+	padding-bottom: 0;
+}
+
+.header {
+	font-family:sans-serif;
+	color:#AA0000;
+}
+
+.content {
+  font-family:sans-serif;
+  font-size:medium;
+  color:#000000;
+  background:#EEEEEE;
+  border-right: 2px solid #AA0000;
+  border-left: 2px solid #AA0000;
+  border-bottom: 2px solid #AA0000;
+  padding-bottom: 5;
+  padding-right: 5;
+  padding-left: 5;
+  padding-top: 0;
+}
+.contenttitle {
+font-family:sans-serif;
+font-size:medium;
+color:#FFFFFF;
+font-weight:bold;
+background-color:#AA0000;
+border-left: 2px solid #AA0000;
+border-top: 1px solid #AA0000;
+border-right: 2px solid #AA0000;
+padding: 2;
+}
+
+.contentbuff {
+  font-family:sans-serif;
+  font-size:10px;
+  color:#014DA3;
+  border-left: 2px solid #AA0000;
+  border-right: 2px solid #AA0000;
+  font-weight:bold;
+  background-color:#99CCFF;
+  height:13;
+  padding-bottom: 0;
+}
+
+br { padding-bottom: 200 }
+

data/doc/old/manual.html

@@ -0,0 +1,348 @@
+<html>
+<head><title>Log4r - A Powerful Logger for Ruby</title></head>
+<body bgcolor="#FFFFFF">
+<h1><font color="#AA0000">Log4r - A Powerful Logger for Ruby</font></h1>
+Inspired by the
+<a href="http://jakarta.apache.org/log4j/docs/index.html">Apache Log4j</a>
+project
+<hr/>
+
+<h4>At a Glance</h4>
+
+<blockquote>
+Log4r features an extremely flexible logging library for Ruby.
+Killer features include a heiarchial logging system of any number of
+levels, logger inheritance, multiple output destinations, tracing, custom
+formatting and more. 
+<p>
+Log4r was inspired by the very excellent
+<a href="http://jakarta.apache.org/log4j/docs/index.html">
+Apache Log4j Project</a>
+. Log4r provides the defining features of Log4j and some of its own 
+features that just might make Log4j users envious. <code>;-)</code>
+<p/>
+The project is hosted on SourceForge: 
+<a href="http://sourceforge.net/projects/log4r/">
+http://sourceforge.net/projects/log4r/</a>
+</blockquote>
+
+<h4>Download</h4>
+
+<blockquote>
+Latest version is
+<a href="http://sourceforge.net/project/showfiles.php?group_id=43396">
+Log4r 0.9.8</a>. All versions are stable. Newer ones have more features.
+<p/>
+The
+<a href="rdoc/index.html">API is available</a>
+in a Javadoc-like format (thanks go to the 
+<a href="http://rdoc.sourceforge.net/">RDoc project</a>).
+</blockquote>
+
+
+<h4>But why?</h4>
+
+<blockquote>
+Please read the 
+<a href="http://jakarta.apache.org/log4j/docs/index.html">Introduction</a>
+to Apache Log4j for answers. Personally, I find
+that a logging system such as Log4r is essential when writing distributed
+applications, like for a game that has a client/server design. Also, the
+ability to leave logging statements in the code without commenting them out
+is quite handy.
+</blockquote>
+
+<h4>Features</h4>
+<blockquote>
+<dl>
+  <dt><b><font color="#AA0000">Easy to use</font></b></dt>
+	<dd><p/>
+	Thanks to Ruby, Log4r is an extremely simple tool to use. It should become
+	evident as you read further. <code>;)</code>
+	<p/></dd>
+  <dt><b><font color="#AA0000">Multiple loggers</font></b></dt>
+	<dd>
+	  <p/>
+	  You can have as many loggers as desired. Upon creation, they get stored
+		in a Singleton repository from which they can be retrieved at any point.
+<pre>
+  Log4r::Logger.new('mylogger')         # create a logger 'mylogger'
+  Log4r::Logger['mylogger']             # get 'mylogger' back
+</pre>
+  <p/>
+	</dd>
+  <dt><b><font color="#AA0000">Heiarchial logging</font></b></dt>
+	<dd>
+	  <p/>
+	  Log4r provides five levels of logging: 
+		<code>DEBUG, INFO, WARN, ERROR, FATAL</code>.
+		A logger with a certain level will not perform logging for all levels
+	  below it (less important, if you will). Hence, if a logger is set to
+		<code>WARN</code>, it won't log <code>DEBUG</code>, and 
+		<code>INFO</code> log events. 
+		<code>ALL</code> and <code>OFF</code> are special
+		boundary levels. Setting a logger to <code>ALL</code> will let it see evey log event
+		while setting it to <code>OFF</code> will disable all log events. It's not possible
+		to log at <code>ALL</code> and <code>OFF</code>.
+<pre>
+  include Log4r                      # include for brevity
+
+  log = Logger['mylogger']
+  log.level = WARN                   # set log level to Log4r::WARN
+
+  log.debug  "DEBUG log event"       # won't show up
+  log.info   "INFO log event"        # ditto
+  log.warn   "WARN log event"        # will show up, and all that follow
+  log.error  "ERROR log event"
+  log.fatal  "FATAL log event"
+</pre>
+  <br/>
+  You can dynamically reassign a logger's level if you want.
+		<p/>
+	</dd>
+	<dt><b><font color="#AA0000">Custom levels</font></b></dt>
+	<dd>
+	<p/>
+	  And now, something that will really make Log4j users envious: You can
+		change the number and names of the heiarchial logging levels easily.
+		Suppose we don't like having 5 levels named <code>DEBUG</code>, <code>INFO</code>, etc.
+		Instead, we want <code>Foo</code>, <code>Bar</code>, and <code>Baz</code>.
+		Here's how we do it:
+<pre>
+  Log4r::Logger.custom_levels 'Foo', 'Bar', 'Baz'
+</pre>
+<br/>
+Thereafter, the logging methods will be named after your custom levels:
+<p/>
+<pre>
+  log.level = Log4r::Bar 
+  log.foo?                               => false
+  log.bar?                               => true
+  log.bar "this is bar"                  => &lt;Bar&gt; this is bar
+  log.baz "this is baz"                  => &lt;Baz&gt; this is baz
+</pre>		
+	<p/>
+	</dd>
+  <dt><b><font color="#AA0000">Multiple output destinations</font></b></dt>
+	<dd>
+	<p/>
+	The second block of code won't do anything because <code>mylogger</code> does
+	not have anything to write to. In order to log somewhere, we have to
+	create an <b>Outputter</b> and assign it to our logger. We can give our
+	logger as many <code>Outputters</code> as we want:
+<pre>
+  # continuing from second block
+
+  f = FileOutputter.new(:filename =&gt; './tmp.log')
+  so = StdoutOutputter.new
+  se = StderrOutputter.new
+  ex = Outputter.new(ExoticIO.new)   # outputter with an IO of our own make
+  log.add(f, so, se, ex)
+  log.error "A test error"           # writes to all 4 IOs
+</pre>
+  <br/>
+	If an <code>IO</code> somehow chokes, the Outputter will set itself to
+	<code>OFF</code> and close the <code>IO</code>.
+	<p/>
+	</dd>
+	<dt><b><font color="#AA0000">Root logger, global threshold and Logger inheritance</font></b></dt>
+	<dd>
+	<p/>
+	A logger can inherit another logger. It turns out that every logger
+	that you create normally is a child of the <b>root</b> logger.
+	The <b>root</b> logger does two things: Provide the global logging level
+	and the default level for its immediate children.
+<pre>
+  Logger.root.level = ERROR       # set global level to ERROR
+  Logger.new("alog")              # alog inherits ERROR
+</pre>
+<br/>
+  From this point on, the only log events (by <b>alog</b> and <b>mylogger</b>)
+	that can show up are <code>ERROR</code> and <code>FATAL</code>.
+	<p/>
+	To have one logger inherit another, specify the name of the parent
+	in the argument to <code>Logger.new</code> as follows: 
+	<code>"parent::child"</code>. Specifying 'root' is optional. Because
+	of namespace collision concerns, you need to specify the full path
+  to the logger as in <code>foo::bar::baz</code>. The same thing must be done for
+	retrieving loggers from the repository:
+<pre>
+  Logger.new('mylogger::mychild')       # mychild is a child of mylogger
+  Logger['mylogger::mychild']           # get mychild back
+</pre>
+<br/>
+  A child logger that does not define its level during creation will inherit
+	the level of its parent.
+	<p/>
+	</dd>
+	<dt><b><font color="#AA0000">Outputter inheritance</font></b></dt>
+	<dd>
+	<p/>
+	In addition to level, a logger inherits the <code>Outputter</code>s of its
+	parent. That is, when <code>mychild</code> performs a logging event, it also
+	calls the appropriate logging event for <code>mylogger</code>. This behavior
+	is entirely optional and can be turned off by setting a logger's
+	<code>additive</code> to false:
+<pre>
+  Logger['mylogger::mychild'].additive = false
+</pre>
+ <br/>
+   Hencenforth, any logging events to mychild will not be sent to mylogger.
+	 The buck stops here.
+	<p/>
+	</dd>
+  <dt><b><font color="#AA0000">Custom formatting</font></b></dt>
+	<dd>
+	<p/>
+	By default, Log4r is capable of formatting any object passed to it
+	by calling its <code>inspect</code> method. It also pre-formats 
+	<code>Exceptions</code>.
+	Changing the way the data is formatted is just a matter of rolling up
+	your own <code>Formatter</code> class that defines the method <code>format</code>:
+<pre>
+  class MyFormatter < Formatter
+    def format(level, logger, tracer, data)
+      # level is the integer level of the log event
+      # logger is the logger that called it
+      # tracer is the execution stack returned by caller at the log event
+      # data is what was passed into a logging method
+    end
+  end
+
+  afile = FileOutputter.new(:file=>'./prettyformat')
+  afile.formatter = MyFormatter.new
+  # add it to 'mychild' dynamically
+  Logger['mylogger::mychild'].add afile
+</pre>
+<br/>
+Formatters are not inherited, they are assigned to specific outputters.
+	<p/>
+	</dd>
+<dt><b><font color="#AA0000">Tracing</font></b></dt>
+	<dd>
+	<p/>
+	By default, loggers don't record the execution stack. You can turn on
+	tracing by setting a logger's <code>trace</code> to <code>true</code>. It's up to the
+	<code>Formatter</code> to handle this information. <code>BasicFormatter</code> displays
+	the line number and file of the log event.
+	<p/>
+	</dd>
+  <dt><b><font color="#AA0000">Ways around parameter evaluation</font></b></dt>
+	<dd>
+	<p/>
+	Avoiding parameter evaluation at the log method invocation can be
+	critical at times. One way to do this is to pass the object in
+	and let the formatter inspect it. The formatter won't be called for
+	non-loggable levels. If parameter evaluation is unavoidable, you can 
+	querry the logger to see if it's logging at a 
+	particular level. The following querry methods are provided:
+<pre>
+  Logger.root.level          =&gt; ERROR
+  log = Logger['mylogger']
+  log.level                  =&gt; WARN
+  log.debug?                 =&gt; false
+  log.warn?                  =&gt; false
+  log.info?                  =&gt; false
+  log.error?                 =&gt; true
+  log.fatal?                 =&gt; true
+  log.off?                   =&gt; false   # true only if OFF is set
+  log.all?                   =&gt; false   # true only if ALL is set
+</pre>
+<p/>
+	</dd>
+	<dt><b><font color="#AA0000">Even more flexibility: Outputter thresholds</font></b></dt>
+	<dd>
+	<p/>
+	Sometimes it's prudent to fix a certain outputter's level in stone, or
+	keep it at some independent level with respect to any loggers. (Yes, you
+	can share an outputter among loggers.) This can be done fairly easily by
+	setting the level of the outputter:
+<pre>
+  # console log for mychild that filters out anything less important than ERROR
+	
+  screen = StdoutOutputter.new(:level=>ERROR)
+  Logger['mychild'].add(screen)
+</pre>
+<br/>
+  And that's not all, we can also tell an Outputter to log only specific
+	levels. Here's how:
+<p/>
+<pre>
+  # only DEBUG and FATAL on screen
+  screen.only_at DEBUG, FATAL
+</pre>
+	<p/>
+	</dd>
+<dt><b><font color="#AA0000">Thread safe</font></b></dt>
+	<dd>
+	<p/>
+	Logging is thread safe. The formatting and writing to an output are
+	synchronized by a simple mutex in each outputter.
+	<p/>
+	</dd>
+	<dt><b><font color="#AA0000">Fast enough!</font></b></dt>
+	<dd>
+	<p/>
+	Profiling has revealed that log4r is typically an order of magnitude or two
+	slower than log4j. However, this is still damn fast! In particular,
+	if a logger is set to <code>OFF</code>, the overhead of checking to 
+	see if
+	a log event should be logged nearly vanishes. This was accomplished by
+	dynamically redefining the unloggable logging methods to do nothing.
+	<p/>
+	I'd like to point out that if one needs to use something like log4r
+	in a performance-critical application, one should recondsider why Ruby
+	is being used at all. As far as anyone should be concerned, 
+	log4r is Fast Enough (TM) for casual and moderate use <code>:)</code>
+	<p/>
+	Of course, this doesn't mean that we shouldn't improve the performance 
+	of
+	log4r! When the time comes, it will be written as a C extension to Ruby.
+	<p/>
+	</dd>
+</dl>
+
+</blockquote>
+
+<h4>Gotchas</h4>
+
+If you are using Log4r, there are a few gotchas that you should be aware of:
+<ul>
+<li>Logger levels, tracing and additivity can be dynamically
+    redefined, but the changes won't be noticed by any children. That is, if
+		you set <code>root.level=OFF</code> after defining some loggers,
+		none of the loggers will change their level to <code>OFF</code>,
+</li>
+<li>However, if a parent changes its Outputters, its children will
+    recognize the change.
+</li>
+<li>Dynamically redefining levels, tracing and additivity is a costly
+operation. It's best to set up all your loggers in a config script and
+leave well enough alone. The dynamism is useful for debugging as you can
+toggel tracing and level from within the file you're working on.
+</li>
+<li>When an <code>Outputter</code>'s <code>IO</code> is closed, the
+<code>Outputter</code> changes its level to <code>OFF</code>
+</li>
+</ul>
+
+<h4>The Future</h4>
+<blockquote>
+Log4r is mostly done. It was written in about 3 days and does enough to be
+useful for most cases. There is still room for improvement performance-wise
+and maybe the C extension is nigh.
+</blockquote>
+
+<h4>Obligatory SourceForge Link</h4>
+<blockquote>
+<A href="http://sourceforge.net"> <IMG
+src="http://sourceforge.net/sflogo.php?group_id=43396" width="88" height="31"
+border="0" alt="SourceForge Logo"></A>
+</blockquote>
+<p/>
+<hr/>
+<i><a href="mailto:leon@to.ugcs.caltech.edu">leon@ugcs.caltech.edu</a></i>
+$Id: manual.html,v 1.1 2002/01/16 12:27:05 cepheus Exp $
+
+</body>
+</html>