=pod

=head1 NAME

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

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

=head1 DESCRIPTION

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

=head1 METHODS

=head2 new()

The constructor has two additional optional attributes C<data> and C<subst>.

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

The value of the C<subst> attribute is a HASH reference. The keys are variable
names used for L<Log::Log4perl/Variable-Substitution>.

=head2 parse()

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

=head2 create_appender_instance()

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

=head1 AUTHOR

Sven Willenbuecher <sven.willenbuecher@gmx.de>

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

=cut
