Provide a base class for preprocessor modules.

* lib/Apache/Config/Preproc.pm (_preproc_section_default)
(_preproc_section_optimized): Use begin_section and
end_section instead of start and finish.
* lib/Apache/Config/Preproc/Expand.pm: New file.
* lib/Apache/Config/Preproc/compact.pm: Use the base class.
* lib/Apache/Config/Preproc/ifdefine.pm: Likewise.
* lib/Apache/Config/Preproc/ifmodule.pm: Likewise.
* lib/Apache/Config/Preproc/include.pm: Likewise.
* lib/Apache/Config/Preproc/locus.pm: Likewise.
* lib/Apache/Config/Preproc/macro.pm: Likewise.

9 files changed, 124 insertions, 82 deletions

diff --git a/Makefile.PL b/Makefile.PL
index 058045b..e36577e 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -11,6 +11,7 @@ WriteMakefile(NAME         => 'Apache::Config::Preproc',
 		  'Apache::Admin::Config' => '0.95',
 		  'File::Spec' => '3.39_02',
 		  'Text::ParseWords' => '3.27',
+		  'Text::Locus' => '1.01',  # FIXME: In fact, git HEAD
 		  'File::Spec' => 0,
 		  'IPC::Open3' => 0
       	      },
diff --git a/lib/Apache/Config/Preproc.pm b/lib/Apache/Config/Preproc.pm
index b6f6a57..d5e627f 100644
--- a/lib/Apache/Config/Preproc.pm
+++ b/lib/Apache/Config/Preproc.pm
@@ -110,7 +110,7 @@ sub _preproc_section_default {
     return unless @$modlist;
 
     foreach my $mod (@$modlist) {
-	$mod->can('start') && $mod->start($section);
+	$mod->begin_section($section);
     }
   OUTER:
     for (my $i = 0;
@@ -121,8 +121,7 @@ sub _preproc_section_default {
 	     };
 	     $section->select(-which => $i) }); ) {
 	foreach my $mod (@$modlist) {
-	    my @repl;
-	    if ($mod->expand($d, \@repl)) {
+	    if ($mod->expand($d, \my @repl)) {
 		my $prev = $d;
 		foreach my $r (@repl) {
 		    $prev = $section->add($r, -after => $prev);
@@ -137,7 +136,7 @@ sub _preproc_section_default {
 	$i++;
     }
     foreach my $mod (@$modlist) {
-	$mod->can('finish') && $mod->finish($section);
+	$mod->end_section($section);
     }
 }
 
@@ -154,13 +153,12 @@ sub _preproc_section_optimized {
     return unless @$modlist;
 
     foreach my $mod (@$modlist) {
-	$mod->can('start') && $mod->start($section);
+	$mod->begin_section($section);
     }
   OUTER:
     for (my $i = 0; defined(my $d = $section->get_nth($i)); ) {
 	foreach my $mod (@$modlist) {
-	    my @repl;
-	    if ($mod->expand($d, \@repl)) {
+	    if ($mod->expand($d, \my @repl)) {
 		$section->replace_inplace($i, @repl);
 		next OUTER;
 	    }
@@ -171,7 +169,7 @@ sub _preproc_section_optimized {
 	$i++;
     }
     foreach my $mod (@$modlist) {
-	$mod->can('finish') && $mod->finish($section);
+	$mod->end_section($section);
     }
 }
 
@@ -513,52 +511,10 @@ convenient when a single macro name is to be retained.
 =head1 MODULE INTERNALS 
 
 Each keyword I<phase> listed in the B<-expand> array causes loading of the
-module B<Apache::Config::Preproc::I<phase>>. This module must provide the
-following methods:
-
-=head2 new($conf, ...)
-
-Class constructor. The B<$conf> argument is the configuration file object
-(B<Apache::Config::Preproc>). Rest are constructor arguments provided with
-the module name in the B<-expand> list.    
-
-=head2 expand
-
-This method must perform actual expansion of a subtree of the parse tree.
-It is called as:
-
-    $phase->expand($subtree, $repl)
-
-Its arguments are:
-
-=over 4
-
-=item $subtree
-
-The subtree to be processed.
-
-=item $repl
-
-A reference to array of items (of the same type as I<$subtree>,
-i.e. B<Apache::Admin::Config> or B<Apache::Admin::Config::Tree>) where
-expansion is to be stored.
-
-=back
-
-The function returns true if it did process the I<$subtree>. In this case,
-the subtree will be removed from the parse tree and the items from B<@$repl>
-will be inserted in its place. Thus, to simply remove the I<$subtree> the
-B<expand> method must return true and not touch I<$repl>. For example, the
-following is the B<expand> method definition from the
-B<Apache::Config::Preproc::compact> module:
-
-    sub expand {
-	my ($self, $d, $repl) = @_;
-	return $d->type eq 'blank' || $d->type eq 'comment';
-    }
-
-Notice, that B<expand> does not need to recurse into section objects. This
-is taken care of by the caller.
+package B<Apache::Config::Preproc::I<phase>>.  This package must inherit
+from B<Apache::Config::Preproc::Expand> and overload at least the
+B<expand> method.  See the description of B<Apache::Config::Preproc::Expand>
+for a detailed description.
 
 =head1 EXAMPLE
 
diff --git a/lib/Apache/Config/Preproc/Expand.pm b/lib/Apache/Config/Preproc/Expand.pm
new file mode 100644
index 0000000..ed44a53
--- /dev/null
+++ b/lib/Apache/Config/Preproc/Expand.pm
@@ -0,0 +1,81 @@
+package Apache::Config::Preproc::Expand;
+use strict;
+use warnings;
+
+=head1 NAME
+
+Apache::Config::Preproc::Expand - base class for preprocessor modules
+
+=head1 DESCRIPTION
+
+=head1 CONSTRUCTOR
+
+    $obj = new($conf, ...) 
+
+The only required argument to the constructor is a reference to the
+B<Apache::Config::Preproc> object which controls the preprocessing.  The
+default constructor saves this reference in the object and makes it
+available via the B<conf> method.  Rest of arguments are specific for
+each particular expansion and are ignored by the default constructor.
+
+=cut
+
+sub new {
+    my ($class, $conf) = @_;
+    bless { _conf => $conf }, $class;
+}
+
+=head1 METHODS
+
+=head2 conf
+
+Returns the B<Apache::Config::Preproc> object which controls the
+preprocessing.  The module can use it in order to inspect the configuration
+parse tree.
+
+=cut
+
+sub conf { $_[0]->{_conf} };
+
+=head2 begin_section
+
+    $obj->begin_section($section);
+
+Invoked before running preprocessor expansions on a section.  The section
+(an instance of B<Apache::Admin::Config::Tree> or a derived class) is
+passed as the argument.
+
+Default implementation is a no-op.
+
+=cut
+
+sub begin_section {}
+
+=head2 end_section
+
+    $obj->end_section($section);
+
+Invoked when all preprocessor expansions are finished for a section.  The
+section (an instance of B<Apache::Admin::Config::Tree> or a derived class) is
+passed as the argument.
+
+Default implementation is a no-op.
+
+=cut
+
+sub end_section {}
+
+=head2 expand
+
+    $result = $obj->expand($node, \@items);
+
+Expands the configuration tree node B<$node>, places the resulting
+nodes to B<@items> and returns true.  Returns false if no expansion
+was done on the node.
+
+=cut
+
+sub expand {}
+
+1;
+
diff --git a/lib/Apache/Config/Preproc/compact.pm b/lib/Apache/Config/Preproc/compact.pm
index b309be3..06df4b6 100644
--- a/lib/Apache/Config/Preproc/compact.pm
+++ b/lib/Apache/Config/Preproc/compact.pm
@@ -1,18 +1,14 @@
 package Apache::Config::Preproc::compact;
+use parent 'Apache::Config::Preproc::Expand';
 use strict;
 use warnings;
 use Carp;
 
-our $VERSION = '1.02';
-
-sub new {
-    croak "too many arguments" unless @_ == 2;
-    bless {}, shift
-}
+our $VERSION = '1.03';
 
 sub expand {
-    my ($self, $d, $repl) = @_;
-    return $d->type eq 'blank' || $d->type eq 'comment';
+    my ($self, $d) = @_;
+    $d->type eq 'blank' || $d->type eq 'comment';
 }
 
 1;
diff --git a/lib/Apache/Config/Preproc/ifdefine.pm b/lib/Apache/Config/Preproc/ifdefine.pm
index 06e6445..ddfae3d 100644
--- a/lib/Apache/Config/Preproc/ifdefine.pm
+++ b/lib/Apache/Config/Preproc/ifdefine.pm
@@ -1,14 +1,14 @@
 package Apache::Config::Preproc::ifdefine;
+use parent 'Apache::Config::Preproc::Expand';
 use strict;
 use warnings;
 use Carp;
 
-our $VERSION = '1.02';
+our $VERSION = '1.03';
 
 sub new {
-    my $class = shift;
-    my $conf = shift;
-    my $self = bless {}, $class;
+    my ($class, $conf) = @_;
+    my $self = bless $class->SUPER::new($conf), $class;
     @{$self->{D}}{@_} = (1) x @_;
     return $self;
 }
diff --git a/lib/Apache/Config/Preproc/ifmodule.pm b/lib/Apache/Config/Preproc/ifmodule.pm
index b796ba9..96e2db8 100644
--- a/lib/Apache/Config/Preproc/ifmodule.pm
+++ b/lib/Apache/Config/Preproc/ifmodule.pm
@@ -1,15 +1,16 @@
 package Apache::Config::Preproc::ifmodule;
+use parent 'Apache::Config::Preproc::Expand';
 use strict;
 use warnings;
 use Carp;
 use IPC::Open3;
 
-our $VERSION = '1.02';
+our $VERSION = '1.03';
 
 sub new {
     my $class = shift;
     my $conf = shift;
-    my $self = bless { conf => $conf }, $class;
+    my $self = bless $class->SUPER::new($conf), $class;
     local %_ = @_;
     my $v;
     if ($v = delete $_{preloaded}) {
@@ -26,8 +27,6 @@ sub new {
     return $self;
 }
 
-sub conf { shift->{conf} }
-
 sub preloaded {
     my $self = shift;
     my $id = shift;
diff --git a/lib/Apache/Config/Preproc/include.pm b/lib/Apache/Config/Preproc/include.pm
index 32dafe9..8c9a604 100644
--- a/lib/Apache/Config/Preproc/include.pm
+++ b/lib/Apache/Config/Preproc/include.pm
@@ -1,4 +1,5 @@
 package Apache::Config::Preproc::include;
+use parent 'Apache::Config::Preproc::Expand';
 use strict;
 use warnings;
 use Apache::Admin::Config;
@@ -8,12 +9,13 @@ use Cwd 'abs_path';
 use IPC::Open3;
 use Carp;
 
-our $VERSION = '1.02';
+our $VERSION = '1.03';
 
 sub new {
     my $class = shift;
     my $conf = shift;
-    my $self = bless { context => [], conf => $conf }, $class;
+    my $self = bless $class->SUPER::new($conf), $class;
+    $self->{context} = [];
     local %_ = @_;
     $self->{server_root} = delete $_{server_root};
     if (my $v = delete $_{probe}) {
@@ -30,8 +32,6 @@ sub new {
     return $self;
 }
 
-sub conf { shift->{conf} }
-    
 sub server_root {
     my $self = shift;
     if (my $v = shift) {
diff --git a/lib/Apache/Config/Preproc/locus.pm b/lib/Apache/Config/Preproc/locus.pm
index f3ec42a..4db0d02 100644
--- a/lib/Apache/Config/Preproc/locus.pm
+++ b/lib/Apache/Config/Preproc/locus.pm
@@ -1,11 +1,18 @@
 package Apache::Config::Preproc::locus;
+use parent 'Apache::Config::Preproc::Expand';
 use strict;
 use warnings;
 use Text::Locus;
 
+our $VERSION = '1.03';
+
 sub new {
-    my ($class, $conf) = @_;
-    bless { filename => $conf->filename, line => 0, context => [] }, $class;
+    my $class = shift;
+    my $self = bless $class->SUPER::new(@_), $class;
+    $self->{filename} = $self->conf->filename;
+    $self->{line} = 0;
+    $self->{context} = [];
+    return $self;
 }
 
 sub filename { shift->{filename} }
@@ -21,7 +28,6 @@ sub context_pop {
     my $self = shift;
     if (my $ctx = pop @{$self->{context}}) {
 	($self->{filename}, $self->{line}) = @$ctx;
-#	$self->{line}++;
     }
 }
 
@@ -89,9 +95,9 @@ sub lcheck {
     }
 }
 
-sub finish {
+sub end_section {
     my ($self, $d) = @_;
-    if ($d->type eq 'section' && $self->lcheck($d)) {
+    if ($self->lcheck($d)) {
 	$self->lpop;
 	$self->{line}++;
 	if (my @lines = $d->locus->filelines($self->filename)) {
diff --git a/lib/Apache/Config/Preproc/macro.pm b/lib/Apache/Config/Preproc/macro.pm
index a8fcdc9..712043d 100644
--- a/lib/Apache/Config/Preproc/macro.pm
+++ b/lib/Apache/Config/Preproc/macro.pm
@@ -1,14 +1,17 @@
 package Apache::Config::Preproc::macro;
+use parent 'Apache::Config::Preproc::Expand';
 use strict;
 use warnings;
 use Text::ParseWords;
 use Carp;
 
-our $VERSION = '1.02';
+our $VERSION = '1.03';
 
 sub new {
-    my $self = bless { keep => {} }, shift;
-    shift; # Skip the ref to tree root
+    my $class = shift;
+    my $conf = shift;
+    my $self = bless $class->SUPER::new($conf), $class;
+    $self->{keep} = {};
     croak "bad number of arguments: @_" if @_ % 2;
     local %_ = @_;
     my $v;