macro processor: implement the 'keep' list

* lib/Apache/Config/Preproc/macro.pm: Implement the retention list. Macros
from this list are exempt from expansion.
* lib/Apache/Config/Preproc.pm: Document changes to the macro processor
* t/04macro02.t: New test case.

3 files changed, 111 insertions, 38 deletions

diff --git a/lib/Apache/Config/Preproc.pm b/lib/Apache/Config/Preproc.pm
index 18f0be0..e4f97a3 100644
--- a/lib/Apache/Config/Preproc.pm
+++ b/lib/Apache/Config/Preproc.pm
@@ -153,13 +153,15 @@ The rest of methods is inherited from B<Apache::Admin::Config>.
 
 =head2 new
 
-    $obj = new Apache::Config::Preproc /path/to/file|handle,
-          [-expand => $modlist]
+    $obj = new Apache::Config::Preproc $file,
+          [-expand => $modlist],
           [-indent => $integer], ['-create'], ['-no-comment-grouping'],
           ['-no-blank-grouping']
 
-Reads the Apache configuration file and preprocesses it. Preprocessor-specific
-keywords are:
+Reads the Apache configuration file from I<$file> and preprocesses it.
+The I<$file> argument can be either the file name or file handle.
+
+The keyword arguments are:
 
 =over 4
 
@@ -192,42 +194,27 @@ Rest of arguments is the same as for the B<Apache::Admin::Config> constructor:
 
 =over 4    
     
-=item I<C</path/to/file>>
-
-Path to the configuration file to parse. If none given, create a new
-one.
-
-=item I<C<handle>>
-
-Instead of specify a path to a file, you can give a reference to an
-handle that point to an already openned file. You can do this like
-this :
+=item B<-indent> =E<gt> I<$n>
 
-    my $obj = new Apache::Admin::Config (\*MYHANDLE);
+Enables reindentation of the configuration content. The B<$n> argument
+is the indenting amount per level of nesting. Negative value means
+indent with tab characters.    
 
-=item I<B<-indent>> =E<gt> I<$integer>
+=item B<-create>
 
-If greater than 0, activates the indentation on added lines, the
-integer tell how many spaces you went per level of indentation
-(suggest 4). A negative value means padding with tabulation(s).
-
-=item I<B<-create>>
-
-If present and path to an unexisting file is given, don't return an
+If present I<$file> is a pathname of unexisting file, don't return an
 error.
 
-=item I<B<-no-comment-grouping>>
-
-When there are several successive comment-lines, if comment grouping
-is enabled only one comment item is created.
-
-If present, disable comment grouping at parsing time. Enabled by
-default.
+=item B<-no-comment-grouping>
 
-=item I<B<-no-blank-grouping>>
+Disables grouping of successive comments into one C<comment> item.
+Useless if the B<compact> expansion is enabled.    
 
-Same as comment grouping but for blank lines.
+=item B<-no-blank-grouping>
 
+Disables grouping of successive empty lines into one C<blank> item.
+Useless if the B<compact> expansion is enabled.    
+    
 =back
 
 =head1 METHODS
@@ -317,7 +304,20 @@ Processes B<Macro> and B<Use> statements (see B<mod_macro>).  B<Macro>
 statements are removed. Each B<Use> statement is replaced by the expansion
 of the macro named in its argument.
 
-The constructor takes no arguments.    
+The constructor accepts the following arguments:
+    
+=over 4
+
+=item B<keep =E<gt>> I<$listref>
+
+List of macro names to exclude from expanding. Each B<E<lt>MacroE<gt>> and
+B<Use> statement with a name from I<$listref> as its first argument will be
+retained in the parse tree.
+
+As a syntactic sugar, I<$listref> can also be a scalar value. This is
+convenient when a single macro name is to be retained.    
+
+=back
     
 =head1 MODULE INTERNALS 
 
diff --git a/lib/Apache/Config/Preproc/macro.pm b/lib/Apache/Config/Preproc/macro.pm
index ab97b62..c0538d0 100644
--- a/lib/Apache/Config/Preproc/macro.pm
+++ b/lib/Apache/Config/Preproc/macro.pm
@@ -5,8 +5,22 @@ use Text::ParseWords;
 use Carp;
 
 sub new {
-    croak "too many arguments" unless @_ == 2;
-    bless {}, shift
+    my $self = bless { keep => {} }, shift;
+    shift; # Skip the ref to tree root
+    croak "bad number of arguments: @_" if @_ % 2;
+    local %_ = @_;
+    my $v;
+    if ($v = delete $_{keep}) {
+	if (ref($v)) {
+	    croak "keep argument must be a scalar or listref"
+		unless ref($v) eq 'ARRAY';
+	} else {
+	    $v = [$v];
+	}
+	@{$self->{keep}}{@$v} = @$v;
+    }
+    croak "unrecognized arguments" if keys(%_);
+    return $self;
 }
 
 sub macro {
@@ -16,14 +30,15 @@ sub macro {
 
 sub install_macro {
     my ($self, $defn) = @_;
+    return 0 if $self->{keep}{$defn->name};
     $self->{macro}{$defn->name} = $defn;
+    return 1;
 }
 
 sub expand {
     my ($self, $d, $repl) = @_;
     if ($d->type eq 'section' && lc($d->name) eq 'macro') {
-	$self->install_macro(Apache::Config::Preproc::macro::defn->new($d));
-	return 1;
+	return $self->install_macro(Apache::Config::Preproc::macro::defn->new($d));
     } 
     if ($d->type eq 'directive' && lc($d->name) eq 'use') {
 	my ($name,@args) = parse_line(qr/\s+/, 0, $d->value);
@@ -101,12 +116,30 @@ Apache::Config::Preproc::macro - expand macro statements
     $x = new Apache::Config::Preproc '/path/to/httpd.conf',
                 -expand => [ qw(macro) ];
 
+    $x = new Apache::Config::Preproc '/path/to/httpd.conf',
+                -expand => [ { macro => [ keep => $listref ] } ];
+
 =head1 DESCRIPTION
 
 Processes B<Macro> and B<Use> statements (see B<mod_macro>) in the
 Apache configuration parse tree.
 
 B<Macro> statements are removed. Each B<Use> statement is replaced by the
-expansion of the macro named in its argument.    
+expansion of the macro named in its argument.
+
+The constructor accepts the following arguments:
 
+=over 4
+
+=item B<keep =E<gt>> I<$listref>
+
+List of macro names to exclude from expanding. Each B<E<lt>MacroE<gt>> and
+B<Use> statement with a name from I<$listref> as its first argument will be
+retained in the parse tree.
+
+As a syntactic sugar, I<$listref> can also be a scalar value. This is
+convenient when a single macro name is to be retained.    
+
+=back
+    
 =cut
diff --git a/t/04macro02.t b/t/04macro02.t
new file mode 100644
index 0000000..c582fe2
--- /dev/null
+++ b/t/04macro02.t
@@ -0,0 +1,40 @@
+# -*- perl -*-
+use lib qw(t lib);
+use strict;
+use Test;
+plan test => 1;
+
+use TestPreproc;
+
+my $obj = new TestPreproc -expand => [ { macro => [ keep => 'SSL' ] } ];
+ok($obj->dump_raw, $obj->dump_expect);
+__DATA__
+!>httpd.conf
+ServerName localhost
+<Macro SSL $domain>
+SSLEngine on
+SSLCertificateFile /etc/ssl/acme/$domain.pem
+</Macro>
+<Macro vhost $name $port $dir>
+<VirtualHost *:$port>
+ServerName $name
+DocumentRoot $dir
+Use SSL $name
+</VirtualHost>
+</Macro>
+
+Use vhost foo 80 /var/www/foo
+!=
+ServerName localhost
+<Macro SSL $domain>
+SSLEngine on
+SSLCertificateFile /etc/ssl/acme/$domain.pem
+</Macro>
+
+<VirtualHost *:80>
+ServerName foo
+DocumentRoot /var/www/foo
+Use SSL foo
+</VirtualHost>
+!$
+