.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Config::BaseConfigurator 3"
.TH Config::BaseConfigurator 3 2026-08-14 "perl v5.42.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Log::Log4perl::Config::BaseConfigurator \- Configurator Base Class
.SH SYNOPSIS
.IX Header "SYNOPSIS"
This is a virtual base class, all configurators should be derived from it.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
.SS METHODS
.IX Subsection "METHODS"
.ie n .IP """new""" 4
.el .IP \f(CWnew\fR 4
.IX Item "new"
Constructor, typically called like
.Sp
.Vb 3
\&    my $config_parser = SomeConfigParser\->new(
\&        file => $file,
\&    );
\&
\&    my $data = $config_parser\->parse();
.Ve
.Sp
Instead of \f(CW\*(C`file\*(C'\fR, the derived class \f(CW\*(C`SomeConfigParser\*(C'\fR may define any 
type of configuration input medium (e.g. \f(CW\*(C`url => \*(Aqhttp://foobar\*(Aq\*(C'\fR).
It just has to make sure its \f(CWparse()\fR method will later pull the input
data from the medium specified.
.Sp
The base class accepts a filename or a reference to an array
of text lines:
.RS 4
.ie n .IP """file""" 4
.el .IP \f(CWfile\fR 4
.IX Item "file"
Specifies a file which the \f(CWparse()\fR method later parses.
.ie n .IP """text""" 4
.el .IP \f(CWtext\fR 4
.IX Item "text"
Specifies a reference to an array of scalars, representing configuration
records (typically lines of a file). Also accepts a simple scalar, which it 
splits at its newlines and transforms it into an array:
.Sp
.Vb 5
\&    my $config_parser = MyYAMLParser\->new(
\&        text => [\*(Aqfoo: bar\*(Aq,
\&                 \*(Aqbaz: bam\*(Aq,
\&                ],
\&    );
\&
\&    my $data = $config_parser\->parse();
.Ve
.RE
.RS 4
.Sp
If either \f(CW\*(C`file\*(C'\fR or \f(CW\*(C`text\*(C'\fR parameters have been specified in the 
constructor call, a later call to the configurator\*(Aqs \f(CWtext()\fR method
will return a reference to an array of configuration text lines.
This will typically be used by the \f(CWparse()\fR method to process the 
input.
.RE
.ie n .IP """parse""" 4
.el .IP \f(CWparse\fR 4
.IX Item "parse"
Virtual method, needs to be defined by the derived class.
.SS "Parser requirements"
.IX Subsection "Parser requirements"
.IP \(bu 4
If the parser provides variable substitution functionality, it has
to implement it.
.IP \(bu 4
The parser\*(Aqs \f(CWparse()\fR method returns a reference to a hash of hashes (HoH). 
The top\-most hash contains the
top\-level keywords (\f(CW\*(C`category\*(C'\fR, \f(CW\*(C`appender\*(C'\fR) as keys, associated
with values which are references to more deeply nested hashes.
.IP \(bu 4
The \f(CW\*(C`log4perl.\*(C'\fR prefix (e.g. as used in the PropertyConfigurator class)
is stripped, it\*(Aqs not part in the HoH structure.
.IP \(bu 4
Each Log4perl config value is indicated by the \f(CW\*(C`value\*(C'\fR key, as in
.Sp
.Vb 1
\&    $data\->{category}\->{Bar}\->{Twix}\->{value} = "WARN, Logfile"
.Ve
.SS EXAMPLES
.IX Subsection "EXAMPLES"
The following Log::Log4perl configuration:
.PP
.Vb 4
\&    log4perl.category.Bar.Twix        = WARN, Screen
\&    log4perl.appender.Screen          = Log::Log4perl::Appender::File
\&    log4perl.appender.Screen.filename = test.log
\&    log4perl.appender.Screen.layout   = Log::Log4perl::Layout::SimpleLayout
.Ve
.PP
needs to be transformed by the parser\*(Aqs \f(CWparse()\fR method 
into this data structure:
.PP
.Vb 10
\&    { appender => {
\&        Screen  => {
\&          layout => { 
\&            value  => "Log::Log4perl::Layout::SimpleLayout" },
\&            value  => "Log::Log4perl::Appender::Screen",
\&        },
\&      },
\&      category => { 
\&        Bar => { 
\&          Twix => { 
\&            value => "WARN, Screen" } 
\&        } }
\&    }
.Ve
.PP
For a full\-fledged example, check out the sample YAML parser implementation 
in \f(CW\*(C`eg/yamlparser\*(C'\fR. It uses a simple YAML syntax to specify the Log4perl 
configuration to illustrate the concept.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Log::Log4perl::Config::PropertyConfigurator
.PP
Log::Log4perl::Config::DOMConfigurator
.PP
Log::Log4perl::Config::LDAPConfigurator (tbd!)
.SH LICENSE
.IX Header "LICENSE"
Copyright 2002\-2026 by Mike Schilli <m@perlmeister.com>
and Kevin Goess <cpan@goess.org>.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.