- NAME
- Synopsis
- Description
- API
  - args
  - as_hash
  - as_string
  - conftree
  - directive
  - filename
  - first_child
  - line_num
  - lookup
  - next
  - parent
- See Also
- Copyright
- Authors

# NAME

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

# 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;
             }
         }
     }

# Description

`Apache2::Directive` provides the Perl API for manipulating the Apache configuration tree

# API

`Apache2::Directive` provides the following functions and/or methods:

## `args`

Get the arguments for the current directive:

    $args = $node->args();

obj: `$node` ( `Apache2::Directive object` )
ret: `$args` ( string )

  Arguments are separated by a whitespace in the string.

since: 2.0.00

For example, in 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;

`$args` now contains the string "-M/opt/lib -M/usr/local/lib -wT"

## `as_hash`

Get a hash representation of the configuration tree, in a format suitable for inclusion in <Perl> sections.

    $config_hash = $conftree->as_hash();

obj: `$conftree` ( `Apache2::Directive object` )

  The config tree to stringify

ret: `$config_hash` ( HASH reference )
since: 2.0.00

For example: in 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;

`$hash` now is:

    {
      'SetHandler'  => 'perl-script',
      'PerlHandler' => 'Test::Module',
    }

## `as_string`

Get a string representation of the configuration node, in httpd.conf format.

    $string = $node->as_string();

obj: `$node` ( `Apache2::Directive object` )

  The config tree to stringify

ret: `$string` ( string )
since: 2.0.00

For example: in 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;

`$string` is now:

    SetHandler perl-script
    PerlHandler Test::Module

## `conftree`

Get the root of the configuration tree:

    $conftree = Apache2::Directive::conftree();

obj: `Apache2::Directive` ( class name )
ret: `$conftree` ( `Apache2::Directive object` )
since: 2.0.00

## `directive`

Get the name of the directive in `$node`:

    $name = $node->directive();

obj: `$node` ( `Apache2::Directive object` )
ret: `$name` ( string )
since: 2.0.00

## `filename`

Get the filename the configuration node was created from:

    $filename = $node->filename();

obj: `$node` ( `Apache2::Directive object` )
ret: `$filename` ( string )
since: 2.0.00

For example:

    my $tree = Apache2::Directive::conftree();
    my $node = $tree->lookup('VirtualHost', 'example.com');
    my $filename = $node->filename;

`$filename` is now the full path to the httpd.conf that VirtualHost was defined in.

If the directive was added with `add_config()`, the filename will be the path to the httpd.conf that trigerred that Perl code.

## `first_child`

Get the first child node of this directive:

    $child_node = $node->first_child;

obj: `$node` ( `Apache2::Directive object` )
ret: `$child_node` ( `Apache2::Directive object` )

  Returns the first child node of `$node`, `undef` if there is none

since: 2.0.00

## `line_num`

Get the line number in a filename this node was created at:

    $lineno = $node->line_num();

obj: `$node` ( `Apache2::Directive object` )
arg1: `$lineno` (integer)
since: 2.0.00

## `lookup`

Get the node(s) matching a certain value.

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

obj: `$conftree` ( `Apache2::Directive object` )

  The config tree to stringify

arg1: `$directive` ( string )

  The name of the directive to search for

opt arg2: `args` ( string )

  Optional args to the directive to filter for

ret: `$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 `$directive` value, this method returns all nodes from that directive. For example:

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

  returns all nodes for `Alias` directives.

  If called with an extra `$args` argument, it returns only nodes where both the directive and the args matched. For example:

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

since: 2.0.00

## `next`

Get the next directive node in the tree:

    $next_node = $node->next();

obj: `$node` ( `Apache2::Directive object` )
ret: `$next_node` ( `Apache2::Directive object` )

  Returns the next sibling of `$node`, `undef` if there is none

since: 2.0.00

## `parent`

Get the parent node of this directive:

    $parent_node = $node->parent();

obj: `$node` ( `Apache2::Directive object` )
ret: `parent_node` ( `Apache2::Directive object` )

  Returns the parent of `$node`, `undef` if this node is the root node

since: 2.0.00

# See Also

mod_perl 2.0 documentation.

# Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

# Authors

The mod_perl development team and numerous contributors.