NAME
    Log::Dispatch::Configurator::Any - Configurator implementation with
    Config::Any

VERSION
    This document refers to version 1.0001 of
    Log::Dispatch::Configurator::Any

PURPOSE
    Use this module in combination with Log::Dispatch::Config to allow many
    formats of configuration file to be loaded, via the Config::Any module.

SYNOPSIS
    In the traditional Log::Dispatch::Config way:

     use Log::Dispatch::Config; # loads Log::Dispatch
     use Log::Dispatch::Configurator::Any;
      
 my $config = Log::Dispatch::Configurator::Any->new('log.yml');
     Log::Dispatch::Config->configure($config);
      
 # nearby piece of code
     my $log = Log::Dispatch::Config->instance;
     $log->alert('Hello, world!');

    Alternatively, without a config file on disk:

     use Log::Dispatch::Config; # loads Log::Dispatch
     use Log::Dispatch::Configurator::Any;
      
 my $confhash = {
         dispatchers => ['screen]',
         screen = {
             class => 'Log::Dispatch::Screen',
             min_level => 'debug',
         },
     };
      
 my $config = Log::Dispatch::Configurator::Any->new($confhash);
     Log::Dispatch::Config->configure($config);
      
 # nearby piece of code
     my $log = Log::Dispatch::Config->instance;
     $log->alert('Hello, world!');

DESCRIPTION
    Log::Dispatch::Config is a wrapper for Log::Dispatch and provides a way
    to configure Log::Dispatch objects with configuration files. Somewhat
    like a lite version of log4j and Log::Log4perl it allows multiple log
    destinations. The standard configuration file format for
    Log::Dispatch::Config is AppConfig.

    This module plugs in to Log::Dispatch::Config and allows the use of
    other file formats, in fact any format supported by the Config::Any
    module. As a bonus you can also pass in a configuration data structure
    instead of a file name.

USAGE
    Follow the examples in the "SYNOPSIS". If you are using an external
    configuration file, be aware that you are required to use a filename
    extension (e.g. ".yml" for YAML).

    Below are a couple of tips and tricks you may find useful.

  Fall-back default config
    Being able to use a configuration data structre instead of a file on
    disk is handy when you want to provide application defaults which the
    user then replaces with their own settings. For example you could have
    the following:

     my $defaults = {
         dispatchers => ['screen'],
         screen => {
             class     => 'Log::Dispatch::Screen',
             min_level => 'debug',
         },
     };
      
 my $config_file = '/etc/myapp_logging.conf';
     my $config = $ENV{MYAPP_LOGGING_CONFIG} || $ARGV[0] ||
         ( -e $config_file ? $config_file : $defaults);
     
 Log::Dispatch::Config->configure_and_watch(
         Log::Dispatch::Configurator::Any->new($config) );
     my $dispatcher = Log::Dispatch::Config->instance;

    With the above code, your application will check for a filename in an
    environment variable, then a filename as a command line argument, then
    check for a file on disk, and finally use its built-in defaults.

  Dealing with a "dispatchers" list
    Log::Dispatch::Config requires that a global setting "dispatchers" have
    a list value (i.e. your list of dispatchers). A few config file formats
    do not support list values at all, or list values at the global level
    (two examples being Config::Tiny and Config::General).

    This module allows you to have a small grace when there is only one
    dispatcher in use. Write the configuration file normally, and the
    single-item "dispatchers" value will automatically be promoted to a
    list. In other words:

     # myapp.ini
     dispatchers = screen
     
 # this becomes a config of:
     $config = { dispatchers => 'screen', ... };
     
 # so this module promotes it to:
     $config = { dispatchers => ['screen'], ... };

    If you want more than one dispatcher, you then need to use a config file
    format which supports these lists natively, I'm afraid. A good
    suggestion might be YAML.

AUTHOR
    Oliver Gorwits "<oliver.gorwits@oucs.ox.ac.uk>"

COPYRIGHT & LICENSE
    Copyright (c) The University of Oxford 2008.

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

