/ 
Apache-ConfigParser-1.02
River stage one • 3 direct dependents • 3 total dependents
/ Apache::ConfigParser

NAME

Apache::ConfigParser - Load Apache configuration files

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

The Apache::ConfigParser module is used to load an Apache configuration file to allow programs to determine Apache's configuration directives and contexts. 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 from Tree::DAG_Node are also available. 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 contexts 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})

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:

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 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

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

AUTHOR

Blair Zajac <blair@orcaware.com>.

COPYRIGHT

Copyright (C) 2001-2005 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.