liblog-handler-perl 0.88-1 / usr / share / perl5 / Log / Handler / Config.pm

=head1 NAME

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

=head1 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',
    );

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

=head1 PLUGINS

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

If the extension is not defined then C<Config::General> is used by default.

=head1 METHODS

=head2 config()

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

The following options are valid:

=over 4

=item B<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);

=item B<plugin>

With this option it's possible to say which plugin you want to use.
Maybe you want to use the file extension C<conf> with C<YAML>, which
is reserved for the plugin C<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'
    );

=item B<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 C<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} );

=back

=head1 PLUGINS

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

=head1 EXAMPLES

=head2 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',
        },
    });

=head2 Examples for the config plugins

=head3 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>

=head3 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'

=head3 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'

=head1 PREREQUISITES

    Carp
    Params::Validate

=head1 EXPORTS

No exports.

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

=head1 AUTHOR

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

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

=cut

package Log::Handler::Config;

use strict;
use warnings;
our $VERSION = '0.09';

use Carp;
use File::Spec;
use Params::Validate;

sub config {
    my $self   = shift;
    my $params = $self->_validate(@_);
    my $config = $self->_get_config($params);

    if (ref($config) ne 'HASH') {
        croak "Bad config structure!";
    }

    # Structure:
    #   $log_config{file} = [ \%a, \%b, \%c ]
    #   $log_config{dbi}  = [ \%a, \%b, \%c ]
    my %log_config;

    foreach my $type (keys %$config) {
        my $output = $config->{$type};
        my $ref = ref($output);

        if ($ref eq 'HASH') {
            push @{$log_config{$type}}, $self->_get_hash_config($output);
        } elsif ($ref eq 'ARRAY') {
            push @{$log_config{$type}}, @$output;
        } else {
            croak "Bad config structure for '$type'";
        }
    }

    return \%log_config;
}

#
# private stuff
#

sub _get_config {
    my ($self, $params) = @_;
    my $config = ();
    my $plugin = $params->{plugin};

    if (ref($params->{config})) {
        $config = $params->{config};
    } elsif ($params->{config}) {
        eval "require $plugin";
        if ($@) {
            croak "unable to load plugin '$plugin' - $@";
        }
        $config = $plugin->get_config($params->{config});
    }

    if ($params->{section}) {
        return $config->{ $params->{section} };
    }

    return $config;
}

sub _get_hash_config {
    my ($self, $config) = @_;
    my @config  = ();
    my %default = ();

    if (exists $config->{default}) {
        %default = %{ $config->{default} };
    }

    foreach my $alias (keys %$config) {
        next if $alias eq "default";
        my $param = $config->{$alias};

        if (ref($param) ne 'HASH') {
            push @config, $config;
            last;
        }

        $param->{alias} = $alias;
        my %config = (%default, %$param);
        push @config, \%config;
    }

    return @config;
}

sub _validate {
    my $self = shift;

    my %options = Params::Validate::validate(@_, {
        config => {
            type => Params::Validate::SCALAR
                  | Params::Validate::HASHREF
                  | Params::Validate::ARRAYREF,
            optional => 1,
        },
        plugin => {
            type => Params::Validate::SCALAR,
            optional => 1,
        },
        section => {
            type => Params::Validate::SCALAR,
            optional => 1,
        },
    });

    my $ref = ref($options{config});

    if ($ref ne 'HASH') {
        if ($ref eq 'ARRAY') {
            $options{config} = File::Spec->catfile(@{$options{config}});
        }

        if (!$options{plugin}) {
            if ($options{config} =~ /\.ya{0,1}ml\z/) {
                $options{plugin} = 'Log::Handler::Plugin::YAML';
            } elsif ($options{config} =~ /\.(?:props|jc(?:onf|fg))\z/) {
                $options{plugin} = 'Log::Handler::Plugin::Config::Properties';
            } else {
                $options{plugin} = 'Log::Handler::Plugin::Config::General';
            }
        }
    }

    return \%options;
}

1;