NAME

       Log::Dispatchouli::Global - a system for sharing a global, dynamically-scoped logger

VERSION

       version 2.015

DESCRIPTION

       Warning: This interface is still experimental.

       Log::Dispatchouli::Global is a framework for a global logger object. In your top-level programs that are
       actually executed, you'd add something like this:

         use Log::Dispatchouli::Global '$Logger' => {
           init => {
             ident     => 'My::Daemon',
             facility  => 'local2',
             to_stdout => 1,
           },
         };

       This will import a $Logger into your program, and more importantly will initialize it with a new
       Log::Dispatchouli object created by passing the value for the "init" parameter to Log::Dispatchouli's
       "new" method.

       Much of the rest of your program, across various libraries, can then just use this:

         use Log::Dispatchouli::Global '$Logger';

         sub whatever {
           ...

           $Logger->log("about to do something");

           local $Logger = $Logger->proxy({ proxy_prefix => "whatever: " });

           for (@things) {
             $Logger->log([ "doing thing %s", $_ ]);
             ...
           }
         }

       This eliminates the need to pass around what is effectively a global, while still allowing it to be
       specialized within certain contexts of your program.

       Warning!  Although you could just use Log::Dispatchouli::Global as your shared logging library, you
       almost certainly want to write a subclass that will only be shared amongst your application's classes.
       Log::Dispatchouli::Global is meant to be subclassed and shared only within controlled systems.  Remember,
       sharing your state with code you don't control is dangerous.

USING

       In general, you will either be using a Log::Dispatchouli::Global class to get a $Logger or to initialize
       it (and then get $Logger).  These are both demonstrated above.  Also, when importing $Logger you may
       request it be imported under a different name:

         use Log::Dispatchouli::Global '$Logger' => { -as => 'L' };

         $L->log( ... );

       There is only one class method that you are likely to use: "current_logger".  This provides the value of
       the shared logger from the caller's context, initializing it to a default if needed.  Even this method is
       unlikely to be required frequently, but it does allow users to see $Logger without importing it.

SUBCLASSING

       Before using Log::Dispatchouli::Global in your application, you should subclass it.  When you subclass
       it, you should provide the following methods:

   logger_globref
       This method should return a globref in which the shared logger will be stored.  Subclasses will be in
       their own package, so barring any need for cleverness, every implementation of this method can look like
       the following:

         sub logger_globref { no warnings 'once'; return \*Logger }

   default_logger
       If no logger has been initialized, but something tries to log, it gets the default logger, created by
       calling this method.

       The default implementation calls "new" on the "default_logger_class" with the result of
       "default_logger_args" as the arguments.

   default_logger_class
       This returns the class on which "new" will be called when initializing a logger, either from the "init"
       argument when importing or the default logger.

       Its default value is Log::Dispatchouli.

   default_logger_args
       If no logger has been initialized, but something tries to log, it gets the default logger, created by
       calling "new" on the "default_logger_class" and passing the results of calling this method.

       Its default return value creates a sink, so that anything logged without an initialized logger is lost.

   default_logger_ref
       This method returns a scalar reference in which the cached default value is stored for comparison.  This
       is used when someone tries to "init" the global.  When someone tries to initialize the global logger, and
       it's already set, then:

       •   if the current value is the same as the default, the new value is set

       •   if the current value is not the same as the default, we die

       Since you want the default to be isolated to your application's logger, the default behavior is default
       loggers are associated with the glob reference to which the default might be assigned.  It is unlikely
       that you will need to interact with this method.

COOKBOOK

   Common Logger Recipes
       Say you often use the same configuration for one kind of program, like automated tests.  You've already
       written your own subclass to get your own storage and defaults, maybe "MyApp::Logger".

       You can't just write a subclass with a different default, because if another class using the same global
       has set the global with its default, yours won't be honored.  You don't just want this new value to be
       the default, you want it to be the logger.  What you want to do in this case is to initialize your logger
       normally, then reexport it, like this:

         package MyApp::Logger::Test;
         use parent 'MyApp::Logger';

         use MyApp::Logger '$Logger' => {
           init => {
             ident    => "Tester($0)",
             to_self  => 1,
             facility => undef,
           },
         };

       This will set up the logger and re-export it, and will properly die if anything else attempts to
       initialize the logger to something else.

AUTHOR

       Ricardo SIGNES <rjbs@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2016 by Ricardo SIGNES.

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