/ 
Log-Handler-0.40
River stage two • 30 direct dependents • 42 total dependents
/ Log::Handler::Config

NAME

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

SYNOPSIS

use Log::Handler;

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

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

Or

use Log::Handler;
use Log::Handler::Config;

my $conf = Log::Handler::Config->config(
    config  => 'file.conf',
    plugin  => 'YAML',
    section => 'section-name',
);

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

while ( my ($type, $config) = each %$conf ) {
    $log->add($type => $config);
}

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>
        <mylog>
            config = file.log
            minlevel = 0
            maxlevel = 7
        </mylog>
    </file>
</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} );

Note that the section mylog is used as an alias. Later you access the output with

my $file_output = $log->output('mylog');

PLUGINS

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

EXAMPLES

Config structure

For each output object it must exist a own section. Here a example as hash:

my %config = (

    # the configuration for a file

    file => {
        foo => {
            config => 'file1.log',
            maxlevel => 'info',
            minlevel => 'warn',
        },
        bar => {
            config => 'file2.log',
            maxlevel => 'error',
            minlevel => 'emergency',
        }
    }

    # the configuration for email

    email => {
        foo =>
            host     => 'foo.example',
            from     => 'me@me.example',
            to       => 'you@foo.example',
            maxlevel => 'error',
            minlevel => 'emergency',
        },

        # and_so_on ...
    }
);

You can store your configuration to a file and loads it. There are different config plugins available.

A default section

If your configuration contains a default section then this parameters are used for all other sections. Example:

my %config = (
    # the configuration for a file
    file => {
        default => {
            mode     => 'append',
        },
        foo => {
            config => 'file1.log',
            maxlevel => 'info',
            minlevel => 'warn',
        },
        bar => {
            config => 'file2.log',
            maxlevel => 'error',
            minlevel => 'emergency',
        },
        baz => {
            config => 'file3.log',
            maxlevel => 'debug',
            minlevel => 'debug',
            mode     => 'trunc',
        },
    },
    # the configuration for dbi
    dbi => {
        ...
    }
);

The option mode is set to append for the log file file1.log and file2.log. The configuration for file3.log will be set to trunc.

Examples for the config plugins

Config::General

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

YAML

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

Config::Properties

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

Load the config from a certain section

The config (Config::General)

<output>
    <file>
        <default>
            newline        = 1
            permissions    = 0640
            timeformat     = %b %d %H:%M:%S
            fileopen       = 1
            reopen         = 1
            mode           = append
            message_layout = "%T %H[%P] [%L] %S: %m"
            debug_mode     = 2
        </default>

        <common>
            config = example.log
            maxlevel = info
            minlevel = warn
        </common>

        <error>
            config = example-error.log
            maxlevel = warn
            minlevel = emergency
        </error>

        <debug>
            config = example-debug.log
            maxlevel = debug
            minlevel = debug
        </debug>
    </file>
</output>

Load the config

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

Simple configuration without a certain section

The config (Config::General)

<file>
    <default>
        newline        = 1
        permissions    = 0640
        timeformat     = %b %d %H:%M:%S
        fileopen       = 1
        reopen         = 1
        mode           = append
        message_layout = "%T %H[%P] [%L] %S: $m"
        debug_mode     = 2
    </default>

    <common>
        config = example.log
        maxlevel = info
        minlevel = warn
    </common>

    <error>
        config = example-error.log
        maxlevel = warn
        minlevel = emergency
    </error>

    <debug>
        config = example-debug.log
        maxlevel = debug
        minlevel = debug
    </debug>
</file>

Load the config

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

The config as hash

$log->config(
    config => {
        file => {
            default => {
                newline        => 1,
                permissions    => '0640',
                timeformat     => '%b %d %H:%M:%S',
                fileopen       => 1,
                reopen         => 1,
                mode           => 'append
                message_layout => '%T %H[%P] [%L] %S: %m',
                debug_mode     => 2,
            },
            common => {
                config => 'example.log',
                maxlevel => 'info',
                minlevel => 'warn',
            },
            error => {
                config => 'example-error.log',
                maxlevel => 'warn',
                minlevel => 'emergency',
            },
            debug => {
                config => 'example-debug.log',
                maxlevel => 'debug',
                minlevel => 'debug',
            },
        }
    }
);

Configuration for different outputs

<output>
    <file>
        <default>
            newline        = 1
            permissions    = 0640
            timeformat     = %b %d %H:%M:%S
            fileopen       = 1
            reopen         = 1
            mode           = append
            message_layout = "%T %H[%P] [%L] %S: %m"
            debug_mode     = 2
        </default>

        <common>
            config = example.log
            maxlevel = info
            minlevel = warn
        </common>

        <error>
            config = example-error.log
            maxlevel = warn
            minlevel = emergency
        </error>
    </file>
</output>

PREREQUISITES

Carp
Params::Validate
UNIVERSAL::require

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 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.