NAME

Apache::ConfigParser - Load Apache configuration files

SYNOPSIS

  use Apache::ConfigParser;

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

  # Create a new parser and load a specific configuration file.
  my $c2 = Apache::ConfigParser->new('/etc/httpd/conf/httpd.conf');

  # Load a configuration file explicitly.
  $c1->parse_file('/etc/httpd/conf/httpd.conf');

  # 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
  # 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_at_and_down_option_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];

DESCRIPTION

The Apache::ConfigParser module is used to load an Apache configuration file to allow programs to determine Apache's configuration options. The resulting object contains a tree based structure using the Apache::ConfigParser::Directive class, which is a subclass of Tree::DAG_node, so all of the methods that enable tree based searches and modifications. The tree structure is used to represent the ability to nest sections, such as <VirtualHost>, <Directory>, etc.

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 options modules have valid names.

PARSING

Notes regarding parsing of configuration files.

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

The following methods are available:

$c = Apache::ConfigParser->new

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

$c = Apache::ConfigParser->new($filename)

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

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.

If $filename is given, then the contents of $filename will be loaded. If $filename cannot be be opened then $! will contain the error message for the failed open() and new will returns an empty list in a list content, an undefined value in a scalar context, or nothing in a void context.

The currently recognized options are:

pre_transform_path_sub => sub { }

pre_transform_path_sub => [sub { }, @args]

This allows the file or directory name for any directive that takes either a filename or directory name to be transformed by an arbitrary subroutine before it is made absolute with ServerRoot. This transformation is applied to any of the directives that appear in %Apache::ConfigParser::Directive::directive_value_takes_path that have a filename or directory value instead of a pipe or syslog value, i.e. "| cronolog" or "syslog:warning".

If the second form of pre_transform_path_sub is used with an array reference, then the first element of the array reference must be a subroutine reference followed by zero or more arbitrary arguments. Any array elements following the subroutine reference are passed to the specified subroutine.

The subroutine is passed the following arguments:

  Apache::ConfigParser object
  lowercase string of the configuration directive
  the file or directory name to transform
  @args

NOTE: Be careful, because this subroutine will be applied to ServerRoot and DocumentRoot, among other directives. See Apache::ConfigParser::Directive for the complete list of directives that pre_transform_path_sub is applied to. If you do not want the transformation applied to any specific directives, make sure to check the directive name and if you do not want to modify the filename, return the subroutine's third argument.

If the subroutine returns an undefined value or a value with 0 length, then it is replaced with <File::Spec->devnull> which is the appropriate 0 length file for the operating system. This is done to keep a value in the directive name since otherwise the directive may not work properly. For example, with the input

  CustomLog logs/access_log combined

and if pre_transform_path_sub were to replace 'logs/access_log' with '', then

  CustomLog combined

would no longer be a valid directive. Instead,

  CustomLog C<File::Spec->devnull> combined

would be appropriate for all systems.

post_transform_path_sub => sub { }

post_transform_path_sub => [sub { }, @args]

This allows the file or directory name for any directive that takes either a filename or directory name to be transformed by this subroutine after it is made absolute with ServerRoot. This transformation is applied to any of the directives that appear in %Apache::ConfigParser::Directive::directive_value_takes_path that have a filename or directory value instead of a pipe or syslog value, i.e. "| cronolog" or "syslog:warning".

If the second form of post_transform_path_sub is used with an array reference, then the first element of the array reference must be a subroutine reference followed by zero or more arbitrary arguments. Any array elements following the subroutine reference are passed to the specified subroutine.

The subroutine is passed the following arguments:

  Apache::ConfigParser object
  lowercase version of the configuration directive
  the file or directory name to transform
  @args

NOTE: Be careful, because this subroutine will be applied to ServerRoot and DocumentRoot, among other directives. See Apache::ConfigParser::Directive for the complete list of directives that post_transform_path_sub is applied to. If you do not want the transformation applied to any specific directives, make sure to check the directive name and if you do not want to modify the filename, return the subroutine's third argument.

If the subroutine returns an undefined value or a value with 0 length, then it is replaced with <File::Spec->devnull> which is the appropriate 0 length file for the operating system. This is done to keep a value in the directive name since otherwise the directive may not work properly. For example, with the input

  CustomLog logs/access_log combined

and if post_transform_path_sub were to replace 'logs/access_log' with '', then

  CustomLog combined

would no longer be a valid directive. Instead,

  CustomLog C<File::Spec->devnull> combined

would be appropriate for all systems.

One example of where the transformations is useful is when the Apache configuration directory on one host is NFS exported to another host and the remote host parses the configuration file using Apache::ConfigParser and the paths to the access logs must be transformed so that the remote host can properly find them.

$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 options in $filename will be added to the existing context. If $filename could not be opened, then $! will contain the reason for open's failure.

$c->root

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

$c->find_at_and_down_option_names('option', ...)

$c->find_at_and_down_option_names($node, 'option', ...)

In list context, returns the list all of $c options that match the option names listed at the level of $node and below. In scalar context, returns the number of such options. The level here is in a tree sense, not in the sense that some options appear $node in the configuration file. If $node is given, then the search is started at $node, includes $node and searches $node's children. If $node is not passed, then it starts at the top of the tree and searches the whole configuration file.

All of the option names are made lowercase.

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

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

$c->find_in_siblings_option_names('option', ...)

$c->find_in_siblings_option_names($node, 'option', ...)

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

All of the option names are made lowercase.

$c->find_in_siblings_and_up_option_names($node, 'option', ...)

In list context, returns the list of all $c options that match the option names at the same level of $node, that is siblings of $node, and above $node. In scalar context, returns the number of such options. The level here is in a tree sense, not in the sense that some options appear $node in the configuration file. In this method $node is a required option, because it does not make sense to check the root node.

All of the option names are made lowercase.

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

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

$c->dump

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

SEE ALSO

Apache::ConfigParser::Directive and Tree::DAG_Node.

AUTHOR

Blair Zajac <blair@orcaware.com>.

COPYRIGHT

Copyright (C) 2001 Blair Zajac. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.