Log/Log4perl/AutoCategorize version 0.0081
========================================


Log::Log4perl::AutoCategorize is a wrapper module for Log::Log4perl;
it provides a different interface for (what I perceive as) better
usability.  There are several more mature alternatives which you
should check out for comparison;

  # 1. search for Stealth Loggers in POD
  use Log::Log4perl qw(:easy);
  Log::Log4perl->easy_init($ERROR);

  # 2.
  use Log::Log4perl::Filter;


INTERFACE AND FEATURES

0. You should be familiar with Log::Log4perl

1. Log::Log4perl::AutoCategorize automatically creates the logging
categories based upon the client package name, subroutine name, and
line number.  It does this by using caller().

2. In order to support the optimization phase, AutoCategorize requires
use of a specific coding style:

 ie: Class->method();

The optimization avoids the repeated cost of AUTOLOAD(), saving ~40%,
and yielding performance comparable to unadorned Log::Log4perl.

3. Because typing Log::Log4perl::AutoCategorize->debug() is so
tedious, the package provides an alias facility, so that you can say:

   use Log::Log4perl::AutoCategorize ( alias => 'myLogger');
   myLogger->debug("foo", { a=>1, b=>2 });

I tend to use 'Logger' as the official alias (and shorthand)
throughout the doc.

4. To support test-coverage analysis, this module catalogs every
lexical usage of Logger methods, tracks their invocation (by their
category, which is unique) during the program execution, and reports
the info at the END.  Invocations which, based on the Log::Log4perl
config, are active (ie producing log output) have their count
incremented, disabled ones are decremented.  Calls that are never
reached are also separately reported.


INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

DEPENDENCIES

This module requires these other modules and libraries:

  Log::Log4perl - my class is just a wrapper around this
  optimizer - cuts runtime by ~ 40%
  Data::Dumper - logs structured data with this
  YAML (tbd) - optional replacment for Data::Dumper

Since this module requires optimizer.pm, it also requires B::Generate
and 5.8.  This is unlikely to change, unless youre able to convince
the authors/maintaners of those modules to backport them.

That said, you can add an __END__ above the use optimizer line, and it
should work on 5.6, though I havent tried this.


ACKNOWLEDGMENTS

  (hey, this is my 1st soapbox, um, module ;-)

  Mike Schilli for writing an efficient standards-based logger thats
  better than what Java has.  Simon Cozens & Arthur Bergman for
  optimizer.pm.  Larry Wall, pumpkings, p5p, CPAN authors for building
  perl and the great resources and community around it.

COPYRIGHT AND LICENCE

  Copyright (C) 2003 Jim Cromie <jcromie@cpan.org>

  This library is free software; you can redistribute it
  and/or modify it under the same terms as Perl itself.