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