summaryrefslogtreecommitdiff
path: root/lib/Apache/Config/Preproc.pm
blob: 03ede82d5fd980e24741ba33147e4b783fe96558 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
package Apache::Config::Preproc;
use parent 'Apache::Admin::Config';
use strict;
use warnings;
use Carp;

our $VERSION = '1.01';

sub new {
    my $class = shift;
    my $file = shift;
    my $explist = Apache::Admin::Config::Tree::_get_arg(\@_, '-expand')
	|| [ qw(include) ];

    my $self = $class->SUPER::new($file, @_) or return;
    bless $self, $class;
    $self->{_options} = \@_;

    eval {
	return unless $self->_preproc($explist);
    };
    if ($@) {
	$Apache::Admin::Config::ERROR = $@;
	return;
    }
    
    return $self;
}

sub dequote {
    my ($self, $str) = @_;
    if ($str =~ s/^"(.*)"$/$1/) {
	$str =~ s/\\"/"/g;
    }
    return $str;
}

sub options { shift->{_options} }

sub _preproc {
    my ($self, $explist) = @_;

    return 1 unless @$explist;
    
    return $self->_preproc_section($self,
			  [ map {
			      my ($mod,@arg);
			      if (ref($_) eq 'HASH') {
				  ($mod,my $ref) = each %$_;
				  @arg = @$ref;
			      } elsif (ref($_) eq 'ARRAY') {
				  @arg = @$_;
				  $mod = shift @arg;
			      } else {
				  $mod = $_;
			      }
			      $mod = 'Apache::Config::Preproc::'.$mod;
			      (my $file = $mod) =~ s|::|/|g;
			      require $file . '.pm';
			      $mod->new($self, @arg)
			    } @$explist ]);
}

sub _preproc_section {
    my ($self, $section, $modlist) = @_;

  OUTER:
    for (my $i = 0; defined(my $d = $section->select(-which => $i)); ) {
	foreach my $mod (@$modlist) {
	    my @repl;
	    if ($mod->expand($d, \@repl)) {
		my $prev = $d;
		foreach my $r (@repl) {
		    $prev = $section->add($r, -after => $prev);
		}
		$d->unlink;
		next OUTER;
	    }
	    if ($d->type eq 'section') {
		$self->_preproc_section($d, $modlist);
	    }
	}
	$i++;
    }
    return 1;
}


1;
__END__

=head1 NAME

Apache::Config::Preproc - Preprocess Apache configuration files

=head1 SYNOPSIS

    use Apache::Config::Preproc;
    
    $x = new Apache::Config::Preproc '/path/to/httpd.conf',
             -expand => [ qw(include compact macro ifmodule ifdefine) ] 
             or die $Apache::Admin::Config::ERROR;

=head1 DESCRIPTION

B<Apache::Config::Preproc> reads and parses Apache configuration
file, expanding the syntactic constructs selected by the B<-expand> option.
In the simplest case, the argument to that option is a reference to the
list of names. Each name in the list identifies a module responsible for
processing specific Apache configuration keywords. For convenience, most
modules are named after the keyword they process, so that, e.g. B<include> is
responsible for inclusion of the files listed with B<Include> and
B<IncludeOptional> statements. The list of built-in module names follows:    

=over 4

=item B<compact>

Removes empty lines and comments.

=item B<include>

Expands B<Include> and B<IncludeOptional> statements by replacing them
with the content of the corresponding files.

=item B<ifmodule>

Expands the B<E<lt>IfModuleE<gt>> statements.

=item B<ifdefine>
    
Expands the B<E<lt>IfDefineE<gt>> statements.
    
=item B<macro>

Expands the B<E<lt>MacroE<gt>> statements.    

=back

See the section B<MODULES> for a detailed description of these modules.

More expansions can be easily implemented by supplying a corresponding
expansion module (see the section B<MODULE INTERNALS> below).

If the B<-expand> argument is not supplied, the following default is
used:

    [ 'include' ]
    
The rest of methods is inherited from B<Apache::Admin::Config>.

=head1 CONSTRUCTOR

=head2 new

    $obj = new Apache::Config::Preproc $file,
          [-expand => $modlist],
          [-indent => $integer], ['-create'], ['-no-comment-grouping'],
          ['-no-blank-grouping']

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

=item B<-expand> =E<gt> I<$arrayref>

Define what expansions are to be performed. B<$arrayref> is a reference to
array of module names with optional arguments. To supply arguments,
use either a list reference where the first element is the module
name and rest of elements are arguments, or a hash reference with the name
of the module as key and a reference to the list of arguments as its value.
Consider, for example:

    -expand => [ 'include', { ifmodule => { probe => 1 } } ]

    -expand => [ 'include', [ 'ifmodule', { probe => 1 } ] ]

Both constructs load the B<include> module with no specific arguments,
and the B<ifmodule> module with the arguments B<probe =E<gt> 1>.
    
See the B<MODULES> section for a discussion of built-in modules and allowed
arguments.    

A missing B<-expand> argument is equivalent to

    -expand => [ 'include' ]
    
=back

Rest of arguments is the same as for the B<Apache::Admin::Config> constructor:

=over 4    
    
=item B<-indent> =E<gt> I<$n>

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 B<-create>

If present I<$file> is a pathname of unexisting file, don't return an
error.

=item B<-no-comment-grouping>

Disables grouping of successive comments into one C<comment> item.
Useless if the B<compact> expansion is enabled.    

=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

All methods are inherited from B<Apache::Admin::Config>.
    
=head1 MODULES

The preprocessing phases to be performed on the parsed configuration text are
defined by the B<-expand> argument. Internally, each name in its argument
list causes loading of a Perl module responsible for this particular phase.
Arguments to the constructor can be supplied using any of the following
constructs:

       { NAME => [ ARG, ...] }

or

       [ NAME, ARG, ... ]

    
This section describes the built-in modules and their arguments.

=head2 compact

The B<compact> module eliminates empty and comment lines. The constructor
takes no arguments.    
    
=head2 include

Processes B<Include> and B<IncludeOptional> statements and replaces them
with the contents of the files supplied in their argument. If the latter
is not an absolute file name, it is searched in the server root directory.

The following keyword arguments can be used to set the default server root
directory:

=over 4

=item B<server_root =E<gt>> I<DIR>

Sets default server root value to I<DIR>.

=item B<probe =E<gt>> I<LISTREF> | B<1>

Determines the default server root value by analyzing the output of
B<httpd -V>. If I<LISTREF> is given, it contains alternative pathnames
of the Apache B<httpd> binary. Otherwise, 

    probe => 1

is a shorthand for

    probe => [qw(/usr/sbin/httpd /usr/sbin/apache2)]
        
=back

When the B<ServerRoot> statement is seen, its value overwrites any
previously set server root directory. 

=head2 ifmodule

Processes B<IfModule> statements. If the statement's argument evaluates to
true, it is replaced by the statements inside it. Otherwise, it is removed.
Nested statements are allowed. The B<LoadModule> statements are examined in
order to evaluate the argument.

The constructor understands the following arguments:

=over 4

=item B<preloaded =E<gt>> I<LISTREF>

Supplies a list of preloaded module names. You can use this argument to
pass a list of modules linked statically in your version of B<httpd>.

=item B<probe =E<gt>> I<LISTREF> | B<1>

Provides an alternative way of handling statically linked Apache modules.
If I<LISTREF> is given, each its element is treated as the pathname of
the Apache B<httpd> binary. The first of them that is found is run with
the B<-l> option to list the statically linked modules, and its output
is parsed.

The option

    probe => 1

is a shorthand for

    probe => [qw(/usr/sbin/httpd /usr/sbin/apache2)]

=back

=head2 ifdefine

Eliminates the B<Define> and B<UnDefine> statements and expands the
B<E<lt>IfDefineE<gt>> statements in the Apache configuration parse
tree. Optional arguments to the constructor are treated as the names
of symbols to define (similar to the B<httpd> B<-D> options). Example:   

    -expand => [ { ifdefine => [ qw(SSL FOREGROUND) ] } ]
    
=head2 macro

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 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 

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.

=head1 EXAMPLE

    my $obj = new Apache::Config::Preproc('/etc/httpd/httpd.conf',
                   -expand => [qw(compact include ifmodule macro)],
                   -indent => 4) or die $Apache::Admin::Config::ERROR;
    print $obj->dump_raw

This snippet loads the Apache configuration from file
F</etc/httpd/httpd.conf>, performs all the built-in expansions, and prints
the result on standard output, using 4 character indent for each additional
level of nesting.    

=head1 SEE ALSO

B<Apache::Admin::Config>(3).    
    
=cut
    
    
    

Return to:

Send suggestions and report system problems to the System administrator.