This package provides a basic logger mechanism.

## Overview

The {@link frysk.rsl} package provides the client with a baskc framework. The framework is designed to make logging of a programmers code easy and fast; it is not designed for flexibility.

## Reporting Interface

The log methods have two general forms, the first for calling from static methods and the second for calling from dynamic methods. The static method looks like:

    Log.log(String message, ...)

and the dynamic method:

    Log.log(Object self, String message, ...)

the logger calls then take alternating message strings and objects; for instance a typical use looks like:

    logger.log("myMethod an-arg", arg); // static
    logger.log(this, "myMethod an-arg", arg); // dynamic

## Output Format

The log message is displayed blank seperated with specific types formatted as follows:

Type | Format
--- | ---
char | The character in single quotes
int | Signed Decimal
long | Unsigned Hexadecimal

Object

Throwable | The throwable's and all causes's getMessage() wraped in << >>
String | The escaped string (control chars are converted escaped form))
Other | The Object's toString() wraped in << >>

[]The array elements formatted according to above
for instance:

    logger.log("int", 1, "long", (long)1, "string", "foo\t");
    ... int 1 long 0x1 string "foo\t"

(notice how casting can be used to select between decimal (int) and hex (long) specific formats.

## Command Line Option Syntax

The option parser expects the following syntax:

    OPTIONS ::= OPTION { "," OPTION }
    OPTION ::= LEVEL | PATH | LEVEL "=" PATH
    LEVEL ::= "FINE" | "FINEST" | ...
    PATH ::= ... path to package or class ...

For instance:

What | Effect
--- | ---
FINEST | Set all loggers to FINEST
frysk=FINEST | Set all frysk loggers to FINEST
frysk | Set all frysk loggers to the default logging level (FINE)
frysk.expunit.Expect=FINEST | Set the class, and all its sub-classes, to logging level FINEST
frysk=FINE,inua=FINEST | Set both the frysk and inua packages logging levels
java.lang.Object=FINE | Set anything that extends Object's (yes everything) to logging level FINE

## Completer

A completer is available for command-lines wanting to provide tab-completion of the known set of loggers.

## Implementing a Custom Log

Sometimes the data that needs to be printed is just too wierd a sequence to justify the addition of an additional log method. For those cases, a custom log sequence can be implemented vis:

    Log fine = ...;
    ...
    if (fine.logging())
      fine.prefix(this).print("why arg").print(arg).suffix();

## Comparison with Existing Loggers

The following differences between this logger and `log4j` and `java.util.Logging` are worth noting:

- class hierarchy is understood; consequently it is possible to manipulate the logging level of a class hierarchy
- logging is lock free (the print object does); consequently the overhead of a logging call is greatly reduced and the chance of deadlock is eliminated
- creating loggers and setting the log level uses a single global lock; since these calls occur during class initializaion which is typically serialized lock contention is not an issue
- log calls do not leak memory; for instance, constructs such as `"{0} arg {1}", new Object[] { this, new Integer(arg) }` are not necessary (java 5 improves this)
- the log interface is more limited; only a specific message call style and output format is possible