=head1 NAME
Apache2::Directive - Perl API for manipulating the Apache configuration tree
=head1 Synopsis
use Apache2::Directive ();
my $tree = Apache2::Directive::conftree();
my $documentroot = $tree->lookup('DocumentRoot');
my $vhost = $tree->lookup('VirtualHost', 'localhost:8000');
my $servername = $vhost->{'ServerName'};
use Data::Dumper;
print Dumper $tree->as_hash;
my $node = $tree;
while ($node) {
print $node->as_string;
#do something with $node
my $directive = $node->directive;
my $args = $node->args;
my $filename = $node->filename;
my $line_num = $node->line_num;
if (my $kid = $node->first_child) {
$node = $kid;
}
elsif (my $next = $node->next) {
$node = $next;
}
else {
if (my $parent = $node->parent) {
$node = $parent->next;
}
else {
$node = undef;
}
}
}
=head1 Description
C<Apache2::Directive> provides the Perl API for manipulating the Apache
configuration tree
=head1 API
C<Apache2::Directive> provides the following functions and/or methods:
=head2 C<args>
Get the arguments for the current directive:
$args = $node->args();
=over 4
=item obj: C<$node>
( C<L<Apache2::Directive object|docs::2.0::api::Apache2::Directive>> )
=item ret: C<$args> ( string )
Arguments are separated by a whitespace in the string.
=item since: 2.0.00
=back
For example, in F<httpd.conf>:
PerlSwitches -M/opt/lib -M/usr/local/lib -wT
And later:
my $tree = Apache2::Directive::conftree();
my $node = $tree->lookup('PerlSwitches');
my $args = $node->args;
C<$args> now contains the string "-M/opt/lib -M/usr/local/lib -wT"
=head2 C<as_hash>
Get a hash representation of the configuration tree, in a format
suitable for inclusion in E<lt>PerlE<gt> sections.
$config_hash = $conftree->as_hash();
=over 4
=item obj: C<$conftree>
( C<L<Apache2::Directive object|docs::2.0::api::Apache2::Directive>> )
The config tree to stringify
=item ret: C<$config_hash> ( HASH reference )
=item since: 2.0.00
=back
For example: in F<httpd.conf>:
<Location /test>
SetHandler perl-script
PerlHandler Test::Module
</Location>
And later:
my $tree = Apache2::Directive::conftree();
my $node = $tree->lookup('Location', '/test/');
my $hash = $node->as_hash;
C<$hash> now is:
{
'SetHandler' => 'perl-script',
'PerlHandler' => 'Test::Module',
}
=head2 C<as_string>
Get a string representation of the configuration node, in
F<httpd.conf> format.
$string = $node->as_string();
=over 4
=item obj: C<$node>
( C<L<Apache2::Directive object|docs::2.0::api::Apache2::Directive>> )
The config tree to stringify
=item ret: C<$string> ( string )
=item since: 2.0.00
=back
For example: in F<httpd.conf>:
<Location /test>
SetHandler perl-script
PerlHandler Test::Module
</Location>
And later:
my $tree = Apache2::Directive::conftree();
my $node = $tree->lookup('Location', '/test/');
my $string = $node->as_string;
C<$string> is now:
SetHandler perl-script
PerlHandler Test::Module
=head2 C<conftree>
Get the root of the configuration tree:
$conftree = Apache2::Directive::conftree();
=over 4
=item obj: C<Apache2::Directive> ( class name )
=item ret: C<$conftree>
( C<L<Apache2::Directive object|docs::2.0::api::Apache2::Directive>> )
=item since: 2.0.00
=back
=head2 C<directive>
Get the name of the directive in C<$node>:
$name = $node->directive();
=over 4
=item obj: C<$node>
( C<L<Apache2::Directive object|docs::2.0::api::Apache2::Directive>> )
=item ret: C<$name> ( string )
=item since: 2.0.00
=back
=head2 C<filename>
Get the F<filename> the configuration node was created from:
$filename = $node->filename();
=over 4
=item obj: C<$node>
( C<L<Apache2::Directive object|docs::2.0::api::Apache2::Directive>> )
=item ret: C<$filename> ( string )
=item since: 2.0.00
=back
For example:
my $tree = Apache2::Directive::conftree();
my $node = $tree->lookup('VirtualHost', 'example.com');
my $filename = $node->filename;
C<$filename> is now the full path to the F<httpd.conf> that
VirtualHost was defined in.
If the directive was added with
C<L<add_config()|docs::2.0::api::Apache2::ServerUtil/C_add_config_>>,
the filename will be the path to the F<httpd.conf> that trigerred
that Perl code.
=head2 C<first_child>
Get the first child node of this directive:
$child_node = $node->first_child;
=over 4
=item obj: C<$node>
( C<L<Apache2::Directive object|docs::2.0::api::Apache2::Directive>> )
=item ret: C<$child_node>
( C<L<Apache2::Directive object|docs::2.0::api::Apache2::Directive>> )
Returns the first child node of C<$node>, C<undef> if there is none
=item since: 2.0.00
=back
=head2 C<line_num>
Get the line number in a F<filename> this node was created at:
$lineno = $node->line_num();
=over 4
=item obj: C<$node>
( C<L<Apache2::Directive object|docs::2.0::api::Apache2::Directive>> )
=item arg1: C<$lineno> (integer)
=item since: 2.0.00
=back
=head2 C<lookup>
Get the node(s) matching a certain value.
$node = $conftree->lookup($directive, $args);
@nodes = $conftree->lookup($directive, $args);
=over 4
=item obj: C<$conftree>
( C<L<Apache2::Directive object|docs::2.0::api::Apache2::Directive>> )
The config tree to stringify
=item arg1: C<$directive> ( string )
The name of the directive to search for
=item opt arg2: C<args> ( string )
Optional args to the directive to filter for
=item ret: C<$string> ( string / ARRAY of HASH refs )
In LIST context, it returns all matching nodes.
In SCALAR context, it returns only the first matching node.
If called with only C<$directive> value, this method returns all nodes
from that directive. For example:
@Alias = $conftree->lookup('Alias');
returns all nodes for C<Alias> directives.
If called with an extra C<$args> argument, it returns only nodes where
both the directive and the args matched. For example:
$VHost = $tree->lookup('VirtualHost', '_default_:8000');
=item since: 2.0.00
=back
=head2 C<next>
Get the next directive node in the tree:
$next_node = $node->next();
=over 4
=item obj: C<$node>
( C<L<Apache2::Directive object|docs::2.0::api::Apache2::Directive>> )
=item ret: C<$next_node>
( C<L<Apache2::Directive object|docs::2.0::api::Apache2::Directive>> )
Returns the next sibling of C<$node>, C<undef> if there is none
=item since: 2.0.00
=back
=head2 C<parent>
Get the parent node of this directive:
$parent_node = $node->parent();
=over 4
=item obj: C<$node>
( C<L<Apache2::Directive object|docs::2.0::api::Apache2::Directive>> )
=item ret: C<parent_node>
( C<L<Apache2::Directive object|docs::2.0::api::Apache2::Directive>> )
Returns the parent of C<$node>, C<undef> if this node is the root node
=item since: 2.0.00
=back
=head1 See Also
L<mod_perl 2.0 documentation|docs::2.0::index>.
=head1 Copyright
mod_perl 2.0 and its core modules are copyrighted under
The Apache Software License, Version 2.0.
=head1 Authors
L<The mod_perl development team and numerous
contributors|about::contributors::people>.
=cut