1package Log::Log4perl::Config::BaseConfigurator;
2
3use warnings;
4use strict;
5
6################################################
7sub new {
8################################################
9    my($class, %options) = @_;
10
11    my $self = {
12        %options,
13               };
14
15    $self->file($self->{file}) if exists $self->{file};
16    $self->text($self->{text}) if exists $self->{text};
17
18    bless $self, $class;
19}
20
21################################################
22sub text {
23################################################
24    my($self, $text) = @_;
25
26        # $text is an array of scalars (lines)
27    if(defined $text) {
28        if(ref $text eq "ARRAY") {
29            $self->{text} = $text;
30        } else {
31            $self->{text} = [split "\n", $text];
32        }
33    }
34
35    return $self->{text};
36}
37
38################################################
39sub file {
40################################################
41    my($self, $filename) = @_;
42
43    open FILE, "<$filename" or die "Cannot open $filename ($!)";
44    $self->{text} = [<FILE>];
45    close FILE;
46}
47
48################################################
49sub parse {
50################################################
51    die __PACKAGE__ . "::parse() is a virtual method. " .
52        "It must be implemented " .
53        "in a derived class (currently: ", ref(shift), ")";
54}
55
561;
57
58__END__
59
60=head1 NAME
61
62Log::Log4perl::Config::BaseConfigurator - Configurator Base Class
63
64=head1 SYNOPSIS
65
66This is a virtual base class, all configurators should be derived from it.
67
68=head1 DESCRIPTION
69
70=head2 METHODS
71
72=over 4
73
74=item C<< new >>
75
76Constructor, typically called like
77
78    my $config_parser = SomeConfigParser->new(
79        file => $file,
80    );
81
82    my $data = $config_parser->parse();
83
84Instead of C<file>, the derived class C<SomeConfigParser> may define any
85type of configuration input medium (e.g. C<url =E<gt> 'http://foobar'>).
86It just has to make sure its C<parse()> method will later pull the input
87data from the medium specified.
88
89The base class accepts a filename or a reference to an array
90of text lines:
91
92=over 4
93
94=item C<< file >>
95
96Specifies a file which the C<parse()> method later parses.
97
98=item C<< text >>
99
100Specifies a reference to an array of scalars, representing configuration
101records (typically lines of a file). Also accepts a simple scalar, which it
102splits at its newlines and transforms it into an array:
103
104    my $config_parser = MyYAMLParser->new(
105        text => ['foo: bar',
106                 'baz: bam',
107                ],
108    );
109
110    my $data = $config_parser->parse();
111
112=back
113
114If either C<file> or C<text> parameters have been specified in the
115constructor call, a later call to the configurator's C<text()> method
116will return a reference to an array of configuration text lines.
117This will typically be used by the C<parse()> method to process the
118input.
119
120=item C<< parse >>
121
122Virtual method, needs to be defined by the derived class.
123
124=back
125
126=head2 Parser requirements
127
128=over 4
129
130=item *
131
132If the parser provides variable substitution functionality, it has
133to implement it.
134
135=item *
136
137The parser's C<parse()> method returns a reference to a hash of hashes (HoH).
138The top-most hash contains the
139top-level keywords (C<category>, C<appender>) as keys, associated
140with values which are references to more deeply nested hashes.
141
142=item *
143
144The C<log4perl.> prefix (e.g. as used in the PropertyConfigurator class)
145is stripped, it's not part in the HoH structure.
146
147=item *
148
149Each Log4perl config value is indicated by the C<value> key, as in
150
151    $data->{category}->{Bar}->{Twix}->{value} = "WARN, Logfile"
152
153=back
154
155=head2 EXAMPLES
156
157The following Log::Log4perl configuration:
158
159    log4perl.category.Bar.Twix        = WARN, Screen
160    log4perl.appender.Screen          = Log::Log4perl::Appender::File
161    log4perl.appender.Screen.filename = test.log
162    log4perl.appender.Screen.layout   = Log::Log4perl::Layout::SimpleLayout
163
164needs to be transformed by the parser's C<parse()> method
165into this data structure:
166
167    { appender => {
168        Screen  => {
169          layout => {
170            value  => "Log::Log4perl::Layout::SimpleLayout" },
171            value  => "Log::Log4perl::Appender::Screen",
172        },
173      },
174      category => {
175        Bar => {
176          Twix => {
177            value => "WARN, Screen" }
178        } }
179    }
180
181For a full-fledged example, check out the sample YAML parser implementation
182in C<eg/yamlparser>. It uses a simple YAML syntax to specify the Log4perl
183configuration to illustrate the concept.
184
185=head1 SEE ALSO
186
187Log::Log4perl::Config::PropertyConfigurator
188
189Log::Log4perl::Config::DOMConfigurator
190
191Log::Log4perl::Config::LDAPConfigurator (tbd!)
192
193=head1 AUTHOR
194
195Mike Schilli, <m@perlmeister.com>, 2004
196Kevin Goess, <cpan@goess.org> Jan-2003
197
198=cut
199