NAME

Log::Log4perl::Config::YamlConfigurator - Reads Log4perl YAML configurations

SYNOPSIS

use Log::Log4perl qw();
use YAML::PP      qw( Load );

use Log::Log4perl::Config::YamlConfigurator ();

( my $text = <<'EOT' ) =~ s/^ {2}//gm;
  ---
  rootLogger: INFO, SCREEN
  category:
    Foo:
      Bar:
        name: ${level}, SCREEN, FILE
        Baz: INFO, FILE
  additivity:
    Foo:
      Bar: 0
  appender:
    SCREEN: 
      name: Log::Log4perl::Appender::Screen
      layout: Log::Log4perl::Layout::SimpleLayout
    FILE: 
      name: Log::Log4perl::Appender::File
      filename: file.${DATE}.log
      mode: append
      create_at_logtime: 1
      layout:
        name: Log::Log4perl::Layout::PatternLayout::Multiline
        ConversionPattern: '%d{HH:mm:ss} %-5p [%M{3}, %L] - %m%n'
    STDERR: 
      name: Log::Log4perl::Appender::Screen
      stderr: 1
      utf8: 1
      layout: Log::Log4perl::Layout::SimpleLayout
EOT

# Create configurator object with external variables to be substituted
# while parsing
my $configurator = Log::Log4perl::Config::YamlConfigurator->new(
  data  => Load( $text ),
  subst => { level => 'DEBUG' }
);

# or

my $configurator = Log::Log4perl::Config::YamlConfigurator->new(
  text  => [ $text ],
  subst => { level => 'DEBUG' }
);

# Set environment variables to be substituted while parsing
local $ENV{ DATE } = '2026-05-05';

# Calls $configurator->parse implicitly
Log::Log4perl->init( $configurator );

# or

Log::Log4perl->init( undef, $configurator->parse );

my $appender = $configurator->create_appender_instance( 'STDERR' );

# Add appender to a given logger object
$logger->add_appender( $appender );

DESCRIPTION

This configurator class is a subclass of Log::Log4perl::Config::BaseConfigurator that is able to process Log4perl YAML configurations.

METHODS

new()

The constructor has two additional optional attributes data and subst.

The value of the data attribute is a specific Perl data structure: a HASH reference with the mandatory keys category, and appender. Optional keys are rootLogger, additivity, and some more. The HASH reference is usually the return value of a YAML::PP::Load() function call, if a Log4perl configuration is passed as a YAML stream to this function. Alternatively you may use the text attribute to pass the Log4perl YAML configuration directly to the constructor.

The value of the subst attribute is a HASH reference. The keys are variable names used for "Variable-Substitution" in Log::Log4perl.

parse()

The implementation of this abstract object method fulfills the "Parser-requirements" in Log::Log4perl::Config::BaseConfigurator. It does provide external variable (based on the subst attribute) and environment variable (based on "%ENV" in perlvar) substitution functionality.

create_appender_instance()

If you pass an appender name to this object method, it returns a Log::Log4perl::Appender object. This even works, if the appender is not bound to any logger (see "SYNOPSIS"). If the appender name is unknown the method call dies.

AUTHOR

Sven Willenbuecher <sven.willenbuecher@gmx.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2024-2026 by Sven Willenbuecher.

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