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.

EXPORTED VARIABLES

The following variables are exported via @EXPORT_OK.

%directive_takes_rel_path

This hash is keyed by the lowercase version of a directive name. The hash value is a subroutine reference. If a hash entry exists for a particular entry, then the directive name can take a relative path that may need to be made absolute. The subroutine takes a single variable which should be the potential file path entry and it returns 1 if the potential filename is a valid filename that can be made absolute, 0 otherwise.

For example, ErrorLog can take a filename, a piped command or a syslog:* entry. The particular subroutine for ErrorLog checks if the value is a filename.

On Windows, these subroutines return 0 if the value is 'nul'.

These subroutines do not remove any "'s before checking on the type of value.

This is a list of directives and any special values to check for as of Apache 1.3.20.

  AccessConfig
  AuthGroupFile
  AuthUserFile
  CookieLog
  CustomLog             check for "| command"
  ErrorLog              check for "| command" or syslog:
  Include
  LoadFile
  LoadModule
  LockFile
  MimeMagicFile
  PidFile
  RefererLog            check for "| command"
  ResourceConf
  ScoreBoardFile
  ScriptLog
  TransferLog           check for "| command"
  TypesConfig

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

This allows the file or directory name for any directive that is a filename or directory name to be transformed by this subroutine before it is made absolute with ServerRoot. This transformation is applied to any of the directives that appear in %directive_takes_rel_path.

The subroutine is passed the following arguments:

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

post_transform_path_sub => sub { }

This allows the file or directory name for any directive that is a filename or directory name to be transformed by this subroutine after it is made absolute with ServerRoot. This transformation is applied to the same directives as pre_transform_path_sub.

The subroutine is passed the following arguments:

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

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.