---
name: "Log::Handler::Config"
section: "3pm"
platform: "linux"
package: "liblog-handler-perl"
version: "0.90-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Log::Handler::Config"
---

# Log::Handler::Config(3pm)

The main config loader.

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