NAME

SYNOPSIS

  use Apache::ConfigParser;

  # Create a new empty parser.
  my $c1 = Apache::ConfigParser->new;

  # Load an Apache configuration file.
  my $rc = $c1->parse_file('/etc/httpd/conf/httpd.conf');

  # If there is an error in parsing the configuration file, then $rc
  # will be false and an error string will be available.
  if (not $rc) {
    print $c1->errstr, "\n";
  }

  # Get the root of a tree that represents the configuration file.
  # This is an Apache::ConfigParser::Directive object.
  my $root = $c1->root;

  # Get all of the directives and starting of context's.
  my @directives = $root->daughters;

  # Get the first directive's name.
  my $d_name = $directives[0]->name;

  # This directive appeared in this file, which may be in an Include'd
  # or IncludeOptional'd file.
  my $d_filename = $directives[0]->filename;

  # And it begins on this line number.
  my $d_line_number = $directives[0]->line_number;

  # Find all the CustomLog entries, regardless of context.
  my @custom_logs = $c1->find_down_directive_names('CustomLog');

  # Get the first CustomLog.
  my $custom_log = $custom_logs[0];

  # Get the value in string form.
  $custom_log_args = $custom_log->value;

  # Get the value in array form already split.
  my @custom_log_args = $custom_log->get_value_array;

  # Get the same array but a reference to it.
  my $customer_log_args = $custom_log->value_array_ref;

  # The first value in a CustomLog is the filename of the log.
  my $custom_log_file = $custom_log_args->[0];

  # Get the original value before the path has been made absolute.
  @custom_log_args   = $custom_log->get_orig_value_array;
  $customer_log_file = $custom_log_args[0];

  # Here is a more complete example to load an httpd.conf file and add
  # a new VirtualHost directive to it.
  #
  # The Apache::ConfigParser object contains a reference to a
  # Apache::ConfigParser::Directive object, which can be obtained by
  # using Apache::ConfigParser->root.  The root node is a
  # Apache::ConfigParser::Directive which ISA Tree::DAG_Node (that is
  # Apache::ConfigParser::Directive's @ISA contains Tree::DAG_Node).
  # So to get the root node and add a new directive to it, it could be
  # done like this:

  my $c                = Apache::ConfigParser->new;
  my $rc               = $c->parse_file('/etc/httpd.conf');
  my $root             = $c->root;
  my $new_virtual_host = $root->new_daughter;
  $new_virtual_host->name('VirtualHost');
  $new_virtual_host->value('*');

  # The VirtualHost is called a "context" that contains other
  # Apache::ConfigParser::Directive's:

  my $server_name = $new_virtual_host->new_daughter;
  $server_name->name('ServerName');
  $server_name->value('my.hostname.com');

DESCRIPTION

Apache does a great job of checking Apache configuration files for errors and this modules leaves most of that to Apache. This module does minimal configuration file checking. The module currently checks for:

Start and end context names match

The module checks if the start and end context names match. If the end context name does not match the start context name, then it is ignored. The module does not even check if the configuration contexts have valid names.

PARSING

Line continuation is treated exactly as Apache 1.3.20. Line continuation occurs only when the line ends in [^\\]\\\r?\n. If the line ends in two \'s, then it will replace the two \'s with one \ and not continue the line.

METHODS

$c = Apache::ConfigParser->new

$c = Apache::ConfigParser->new({options})

Create a new "Apache::ConfigParser" object that stores the content of an Apache configuration file. The first optional argument is a reference to a hash that contains options to new.

The currently recognized options are:

$c->DESTROY

There is an explicit DESTROY method for this class to destroy the tree, since it has cyclical references.

$c->parse_file($filename)

This method takes a filename and adds it to the already loaded configuration file inside the object. If a previous Apache configuration file was loaded either with new or parse_file and the configuration file did not close all of its contexts, such as <VirtualHost>, then the new configuration directives and contexts in $filename will be added to the existing context.

If there is a failure in parsing any portion of the configuration file, then this method returns undef and "$c->errstr" will contain a string explaining the error.

$c->root

Returns the root of the tree that represents the Apache configuration file. Each object here is a "Apache::ConfigParser::Directive".

$c->find_down_directive_names('directive', ...)

$c->find_down_directive_names($node, 'directive', ...)

In list context, returns the list all of $c's directives that match the directive names in $node and $node's children. In scalar context, returns the number of such directives. The level here is in a tree sense, not in the sense that some directives appear before or after $node in the configuration file. If $node is given, then the search searches $node and $node's children. If $node is not passed as an argument, then the search starts at the top of the tree and searches the whole configuration file.

The search for matching directive names is done without regards to case.

This is useful if you want to find all of the CustomLog's in the configuration file:

  my @logs = $c->find_down_directive_names('CustomLog');
    

$c->find_siblings_directive_names('directive', ...)

$c->find_siblings_directive_names($node, 'directive', ...)

In list context, returns the list of all $c's directives that match the directive names at the same level of $node, that is siblings of $node. In scalar context, returns the number of such directives. The level here is in a tree sense, not in the sense that some directives appear above or below $node in the configuration file. If $node is passed to the method and it is equal to "$c->tree" or if $node is not given, then the method will search through root's children.

This method will return $node as one of the matches if $node's directive name is one of the directive names passed to the method.

The search for matching directive names is done without regards to case.

$c->find_siblings_and_up_directive_names($node, 'directive', ...)

In list context, returns the list of all $c's directives that match the directive names at the same level of $node, that is siblings of $node and above $node. In scalar context, returns the number of such directives. The level here is in a tree sense, not in the sense that some directives appear before or after $node in the configuration file. In this method $node is a required argument because it does not make sense to check the root node. If $node does not have a parent node, then no siblings will be found. This method will return $node as one of the matches if $node's directive name is one of the directive names passed to the method.

The search for matching directive names is done without regards to case.

This is useful when you find an directive and you want to find an associated directive. For example, find all of the CustomLog's and find the associated ServerName.

  foreach my $log_node ($c->find_down_directive_names('CustomLog')) {
    my $log_filename = $log_node->name;
    my @server_names = $c->find_siblings_and_up_directive_names($log_node);
    my $server_name  = $server_names[0];
    print "ServerName for $log_filename is $server_name\n";
  }
    

$c->errstr

Return the error string associated with the last failure of any "Apache::ConfigParser" method. The string returned is not emptied when any method calls succeed, so a non-zero length string returned does not necessarily mean that the last method call failed.

$c->dump

Return an array of lines that represents the internal state of the tree.

SEE ALSO

AUTHOR

COPYRIGHT