=head1 NAME

Apache::Directive - Perl API for manipulating Apache configuration tree




=head1 Synopsis

  use Apache::Directive ();
  
  my $tree = Apache::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
  
      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<Apache::Directive> allows its users to search and navigate the
internal Apache configuration.

Internally, this information is stored in a tree structure. Each node
in the tree has a reference to its parent (if it's not the root), its
first child (if any), and to its next sibling.

B<All these methods are read-only>





=head1 API

C<Apache::Directive> provides the following functions and/or methods:





=head2 C<args> 

The arguments for the current directive, stored as a space separated
list

  $args      = $node->args();

=over 4

=item obj: C<$node>
( C<L<Apache::Directive object|docs::2.0::api::Apache::Directive>> )

=item ret: C<$args> ( string )

=item since: 1.99_12

=back



=head2 C<as_hash>

Returns 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<Apache::Directive object|docs::2.0::api::Apache::Directive>> )

The config tree to stringify

=item ret: C<$config_hash> (HASH)

=item since: 1.99_12

=back






=head2 C<as_string>

Returns a string representation of the configuration node, in
F<httpd.conf> format. This does not traverse down to sub-trees.

   $string = $node->as_string();

=over 4

=item obj: C<$node>
( C<L<Apache::Directive object|docs::2.0::api::Apache::Directive>> )

The config tree to stringify

=item ret: C<$string> ( string )

=item since: 1.99_12

=back



=head2 C<conftree>

Returns the root of the configuration tree.

  $tree = Apache::Directive->conftree();

=over 4

=item obj: C<Apache::Directive> (class name)

=item ret: C<$tree> ( C<L<Apache::Directive object|docs::2.0::api::Apache::Directive>> )

=item since: 1.99_12

=back





=head2 C<directive>

Returns the name of the directive in C<$node>.

  $name = $node->directive();

=over 4

=item obj: C<$node>
( C<L<Apache::Directive object|docs::2.0::api::Apache::Directive>> )

=item ret: C<$directive> ( string )

=item since: 1.99_12

=back





=head2 C<filename>

Returns the filename the configuration node was created from

  $filename = $node->filename();

=over 4

=item obj: C<$node>
( C<L<Apache::Directive object|docs::2.0::api::Apache::Directive>> )

=item ret: C<$filename> ( string )

=item since: 1.99_12

=back





=head2 C<first_child>

The first child node of this directive

  $subtree = $node->first_child;

=over 4

=item obj: C<$node>
( C<L<Apache::Directive object|docs::2.0::api::Apache::Directive>> )

=item ret: C<$child_node>
( C<L<Apache::Directive object|docs::2.0::api::Apache::Directive>> )

Returns the first child node of C<$node>, C<undef> if there is none

=item since: 1.99_12

=back




=head2 C<line_num>

Returns the line number in C<filename> this node was created from

  $lineno = $node->line_num();

=over 4

=item obj: C<$node>
( C<L<Apache::Directive object|docs::2.0::api::Apache::Directive>> )

=item arg1: C<$lineno> (integer)

=item since: 1.99_12

=back




=head2 C<lookup>

Returns node(s) matching a certain value.

  $node  = $conftree->lookup($directive, $args);
  @nodes = $conftree->lookup($directive, $args);

=over 4

=item obj: C<$conftree>
( C<L<Apache::Directive object|docs::2.0::api::Apache::Directive>> )

The config tree to stringify

=item arg1: C<$directive> ( string )

=item opt arg2: C<args> ( string )

=item ret: C<$string> ( string / ARRAY of HASHES )

In list context, it will return all matching nodes.

In scalar context, it will return only the first matching node.

If called with only C<$directive> value, this will return all nodes
from that directive. For example:

  @Alias = $conftree->lookup('Alias');

would return all nodes for Alias directives.

If called with an extra C<$args> argument, this will return only nodes
where both the directive and the args matched. For example:

  $VHost = $tree->lookup('VirtualHost', '_default_:8000');

=item since: 1.99_12

=back

If called with only one C<$directive> value, this will return all
nodes from that directive:

  @Alias = $tree->lookup('Alias');

Would return all nodes for Alias directives.

If called with an extra C<$args> argument, this will return only nodes
where both the directive and the args matched:

  $VHost = $tree->lookup('VirtualHosts', '_default_:8000');












=head2 C<next>

The next directive node in the tree

  $next_node = $node->next();

=over 4

=item obj: C<$node>
( C<L<Apache::Directive object|docs::2.0::api::Apache::Directive>> )

=item ret: C<$next_node>
( C<L<Apache::Directive object|docs::2.0::api::Apache::Directive>> )

Returns the next sibling of C<$node>, C<undef> if there is none

=item since: 1.99_12

=back






=head2 C<parent>

The parent node of this directive

  $parent_node = $node->parent();

=over 4

=item obj: C<$node> ( C<L<Apache::Directive object|docs::2.0::api::Apache::Directive>> )

=item ret: C<parent_node>
( C<L<Apache::Directive object|docs::2.0::api::Apache::Directive>> )

Returns the parent of C<$node>, C<undef> if this node is the root node

=item since: 1.99_12

=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

