Provided by: liblog-handler-perl_0.90-2_all bug

NAME

       Log::Handler::Config - The main config loader.

SYNOPSIS

           use Log::Handler;

           my $log = Log::Handler->new();

           # Config::General
           $log->config(config => 'file.conf');

           # Config::Properties
           $log->config(config => 'file.props');

           # YAML
           $log->config(config => 'file.yaml');

       Or

           use Log::Handler;

           my $log = Log::Handler->new();

           $log->config(
               config => 'file.conf'
               plugin => 'YAML',
           );

DESCRIPTION

       This module makes it possible to load the configuration from a file.  The configuration
       type is determined by the file extension. It's also possible to mix file extensions with
       another configuration types.

PLUGINS

           Plugin name             File extensions
           ------------------------------------------
           Config::General         cfg, conf
           Config::Properties      props, jcfg, jconf
           YAML                    yml, yaml

       If the extension is not defined then "Config::General" is used by default.

METHODS

   config()
       With this method it's possible to load the configuration for your outputs.

       The following options are valid:

       config
           With this option you can pass a file name or the configuration as a hash reference.

               $log->config(config => 'file.conf');
               # or
               $log->config(config => \%config);

       plugin
           With this option it's possible to say which plugin you want to use.  Maybe you want to
           use the file extension "conf" with "YAML", which is reserved for the plugin
           "Config::General".

           Examples:

               # this would use Config::General
               $log->config(
                   config => 'file.conf'
               );

               # this would force .conf with YAML
               $log->config(
                   config => 'file.conf',
                   plugin => 'YAML'
               );

       section
           If you want to write the configuration into a global configuration file then you can
           create a own section for the logger:

               <logger>
                   <file>
                       filename = file.log
                       minlevel = emerg
                       maxlevel = warning
                   </file>

                   <screen>
                       minlevel = emerg
                       maxlevel = debug
                   </screen>
               </logger>

               <another_script_config>
                   foo = bar
                   bar = baz
                   baz = foo
               </another_script_config>

           Now your configuration is placed in the "logger" section. You can load this section
           with

               $log->config(
                   config  => 'file.conf',
                   section => 'logger',
               );

               # or if you load the configuration yourself to %config

               $log->config(
                   config  => \%config,
                   section => 'logger',
               );

               # or just

               $log->config( config => $config{logger} );

PLUGINS

           Config::General     -  inspired by the well known apache config format
           Config::Properties  -  Java-style property files
           YAML                -  optimized for human readability

EXAMPLES

   Config structures
       A very simple configuration looks like:

           $log->config(config => {
               file => {
                   alias    => 'file1',
                   filename => 'file1.log',
                   maxlevel => 'info',
                   minlevel => 'warn',
               },
               screen => {
                   alias    => 'screen1',
                   maxlevel => 'debug',
                   minlevel => 'emerg',
               }
           });

       Now, if you want to add another file-output then you can pass the outputs with a array
       reference:

           $log->config(config => {
               file => [
                   {
                       alias    => 'file1,
                       filename => 'file1.log',
                       maxlevel => 'info',
                       minlevel => 'warn',
                   },
                   {
                       alias    => 'file2',
                       filename => 'file2.log',
                       maxlevel => 'error',
                       minlevel => 'emergency',
                   }
               ],
               screen => {
                   alias    => 'screen1',
                   maxlevel => 'debug',
                   minlevel => 'emerg',
               },
           });

       It's also possible to pass the outputs as a hash reference.  The hash keys "file1" and
       "file2" will be used as aliases.

           $log->config(config => {
               file => {
                   file1 => {
                       filename => 'file1.log',
                       maxlevel => 'info',
                       minlevel => 'warn',
                   },
                   file2 => {
                       filename => 'file2.log',
                       maxlevel => 'error',
                       minlevel => 'emergency',
                   }
               },
               screen => {
                   alias    => 'screen1',
                   maxlevel => 'debug',
                   minlevel => 'emerg',
               },
           });

       If you pass the configuration with the alias as a hash key then it's also possible to pass
       a section called "default". The options from this section will be used as defaults.

           $log->config(config => {
               file => {
                   default => { # defaults for all file-outputs
                       mode    => 'append',
                   },
                   file1 => {
                       filename => 'file1.log',
                       maxlevel => 'info',
                       minlevel => 'warn',
                   },
                   file2 => {
                       filename => 'file2.log',
                       maxlevel => 'error',
                       minlevel => 'emergency',
                   }
               },
               screen => {
                   alias    => 'screen1',
                   maxlevel => 'debug',
                   minlevel => 'emerg',
               },
           });

   Examples for the config plugins
       Config::General

           <file>
               alias = file1
               fileopen = 1
               reopen = 1
               permissions = 0640
               maxlevel = info
               minlevel = warn
               mode = append
               timeformat = %b %d %H:%M:%S
               debug_mode = 2
               filename = example.log
               message_layout = '%T %H[%P] [%L] %S: %m'
           </file>

       Or

           <file>
               <file1>
                   fileopen = 1
                   reopen = 1
                   permissions = 0640
                   maxlevel = info
                   minlevel = warn
                   mode = append
                   timeformat = %b %d %H:%M:%S
                   debug_mode = 2
                   filename = example.log
                   message_layout = '%T %H[%P] [%L] %S: %m'
               </file1>
           </file>

       YAML

           ---
           file:
             alias: file1
             debug_mode: 2
             filename: example.log
             fileopen: 1
             maxlevel: info
             minlevel: warn
             mode: append
             permissions: 0640
             message_layout: '%T %H[%P] [%L] %S: %m'
             reopen: 1
             timeformat: '%b %d %H:%M:%S'

       Or

           ---
           file:
             file1:
               debug_mode: 2
               filename: example.log
               fileopen: 1
               maxlevel: info
               minlevel: warn
               mode: append
               permissions: 0640
               message_layout: '%T %H[%P] [%L] %S: %m'
               reopen: 1
               timeformat: '%b %d %H:%M:%S'

       Config::Properties

           file.alias = file1
           file.reopen = 1
           file.fileopen = 1
           file.maxlevel = info
           file.minlevel = warn
           file.permissions = 0640
           file.mode = append
           file.timeformat = %b %d %H:%M:%S
           file.debug_mode = 2
           file.filename = example.log
           file.message_layout = '%T %H[%P] [%L] %S: %m'

       Or

           file.file1.alias = file1
           file.file1.reopen = 1
           file.file1.fileopen = 1
           file.file1.maxlevel = info
           file.file1.minlevel = warn
           file.file1.permissions = 0640
           file.file1.mode = append
           file.file1.timeformat = %b %d %H:%M:%S
           file.file1.debug_mode = 2
           file.file1.filename = example.log
           file.file1.message_layout = '%T %H[%P] [%L] %S: %m'

PREREQUISITES

           Carp
           Params::Validate

EXPORTS

       No exports.

REPORT BUGS

       Please report all bugs to <jschulz.cpan(at)bloonix.de>.

       If you send me a mail then add Log::Handler into the subject.

AUTHOR

       Jonny Schulz <jschulz.cpan(at)bloonix.de>.

COPYRIGHT

       Copyright (C) 2007-2009 by Jonny Schulz. All rights reserved.

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