NAME

Apache::ConfigParser::Directive - An Apache directive or start context

SYNOPSIS

use Apache::ConfigParser::Directive;

# Create a new empty directive.
my $d = Apache::ConfigParser::Directive->new;

# Make it a ServerRoot directive.
# ServerRoot /etc/httpd
$d->name('ServerRoot');
$d->value('/etc/httpd');

# A more complicated directive.  Value automatically splits the
# argument into separate elements.  It treats elements in "'s as a
# single element.
# LogFormat "%h %l %u %t \"%r\" %>s %b" common
$d->name('LogFormat');
$d->value('"%h %l %u %t \"%r\" %>s %b" common');

# Get a string form of the name.
# Prints 'logformat'.
print $d->name, "\n";

# Get a string form of the value.
# Prints '"%h %l %u %t \"%r\" %>s %b" common'.
print $d->value, "\n";

# Get the values separated into individual elements.  Whitespace
# separated elements that are enclosed in "'s are treated as a
# single element.  Protected quotes, \", are honored to not begin or
# end a value element.  In this form protected "'s, \", are no
# longer protected.
my @value = $d->get_value_array;
scalar @value == 2;		# There are two elements in this array.
$value[0] eq '%h %l %u %t \"%r\" %>s %b';
$value[1] eq 'common';

# The array form can also be set.  Change style of LogFormat from a
# common to a referer style log.
$d->set_value_array('%{Referer}i -> %U', 'referer');

# This is equivalent.
$d->value('"%{Referer}i -> %U" referer');

# There are also an equivalent pair of values that are called
# 'original' that can be accessed via orig_value,
# get_orig_value_array and set_orig_value_array.
$d->orig_value('"%{User-agent}i" agent');
$d->set_orig_value_array('%{User-agent}i', 'agent');
@value = $d->get_orig_value_array;
scalar @value == 2;		# There are two elements in this array.
$value[0] eq '%{User-agent}i';
$value[1] eq 'agent';

# You can set undef values for the strings.
$d->value(undef);

DESCRIPTION

The Apache::ConfigParser::Directive module is a subclass of Tree::DAG_Node, which provides methods to represents nodes in a tree. Each node is a single Apache configuration directive or root node for a context, such as <Directory> or <VirtualHost>. All of the methods in that module are available here. This module adds some additional methods that make it easier to represent Apache directives and contexts.

This module holds a directive or context:

name
value in string form
value in array form
a separate value termed 'original' in string form
a separate value termed 'original' in array form
the filename where the directive was set
the line number in the filename where the directive was set

The 'original' value is separate from the non-'original' value and the methods to operate on the two sets of values have distinct names. The 'original' value can be used to store the original value of a directive while the non-'directive' value can be a modified form, such as changing the CustomLog filename to make it absolute. The actual use of these two distinct values is up to the caller as this module does not link the two in any way.

METHODS

The following methods are available:

$d = Apache::ConfigParser::Directive->new;

This creates a brand new Apache::ConfigParser::Directive object.

It is not recommended to pass any arguments to new to set the internal state and instead use the following methods.

There actually is no new method in the Apache::ConfigParser::Directive module. Instead, due to Apache::ConfigParser::Directive being a subclass of Tree::DAG_Node, Tree::DAG_Node::new will be used.

$d->name

$d->name($name)

In the first form get the directive or context's name. In the second form set the new name of the directive or context to the lowercase version of $name and return the original name.

$d->value

$d->value($value)

In the first form get the directive's value in string form. In the second form, return the previous directive value in string form and set the new directive value to $value. $value can be set to undef.

If the value is being set, then $value is saved so another call to value will return $value. If $value is defined, then $value is also parsed into an array of elements that can be retrieved with the value_array_ref or get_value_array methods. The parser separates elements by whitespace, unless whitespace separated elements are enclosed by "'s. Protected quotes, \", are honored to not begin or end a value element.

$d->orig_value

$d->orig_value($value)

Identical behavior as value, except that this applies to a the 'original' value. Use orig_value_ref or get_orig_value_array to get the value elements.

$d->value_array_ref

$d->value_array_ref(\@array)

In the first form get a reference to the value array. This can return an undefined value if an undefined value was passed to value or an undefined reference was passed to value_array_ref. In the second form value_array_ref sets the value array and value string. Both forms of value_array_ref return the original array reference.

If you modify the value array reference after getting it and do not use value_array_ref set_value_array to set the value, then the string returned from value will not be consistent with the array.

$d->orig_value_array_ref

$d->orig_value_array_ref(\@array)

Identical behavior as value_array_ref, except that this applies to the 'original' value.

$d->get_value_array

Get the value array elements. If the value was set to an undefined value using value, then get_value_array will return an empty list in a list context, an undefined value in a scalar context, or nothing in a void context.

$d->get_orig_value_array

This has the same behavior of get_value_array except that it operates on the 'original' value.

$d->set_value_array(@values)

Set the value array elements. If no elements are passed in, then the value will be defined but empty and a following call to get_value_array will return an empty array. This returns the value of the array before this method was called.

After setting the value elements with this method, the string returned from calling value is a concatenation of each of the elements so that the output could be used for an Apache configuration file. If any elements contain whitespace, then the "'s are placed around the element as the element is being concatenated into the value string and if any elements contain a " or a \, then a copy of the element is made and the character is protected, i.e. \" or \\, and then copied into the value string.

$d->set_orig_value_array(@values)

This has the same behavior as set_value_array except that it operates on the 'original' value.

Note on $d->value_is_path, $d->value_is_abs_path, $d->value_is_rel_path, $d->orig_value_is_path, $d->orig_value_is_abs_path and $d->orig_value_is_rel_path

These six methods are very similar. They all check if the directive can take a file or directory path value argument in the appropriate index in the value array and then check the value. For example, the LoadModule directive, i.e.

LoadModule cgi_module libexec/mod_cgi.so

does not take a path element in its first (index 0) value array element.

If there is no argument supplied to the method call, then the directive checks the first element of the value array that can legally contain path. For LoadModule, it would check element 1. You could pass 0 to the method to check the first indexed value of LoadModule, but it would always return false, because index 0 does not contain a path.

These are the differences between the methods:

1) The methods beginning with the string 'value_is' apply to the current value in the directive while the methods beginning with the string 'orig_value_is' apply to the original value of the directive.

2) The methods '*value_is_path' test if the directive value is a path, either absolute or relative. The methods '*value_is_abs_path' test if the path if an absolute path, and the methods '*value_is_rel_path' test if the path is not an absolute path.

$d->value_is_path

$d->value_is_path($index_into_value_array)

Returns true if $d's directive can take a file or directory path in the specified value array element (indexed by $index_into_value_array or the first path element for the particular directive if $index_into_value_array is not provided) and if the value is either an absolute or relative file or directory path. Both the directive name and the value is checked, because some directives such as ErrorLog, can take values that are not paths (i.e. a piped command or syslog:facility). The /dev/null equivalent for the operating system is not treated as a path, since on some operating systems the /dev/null equivalent is not a file, such as nul on Windows.

The method actually does not check if its value is a path, rather it checks if the value does not match all of the other possible non-path values for the specific directive because different operating systems have different path formats, such as Unix, Windows and Macintosh.

$d->orig_value_is_path

$d->orig_value_is_path($index_into_value_array)

This has the same behavior as $d->value_is_path except the results are applicable to $d's 'original' value array.

$d->value_is_abs_path

$d->value_is_abs_path($index_into_value_array)

Returns true if $d's directive can take a file or directory path in the specified value array element (indexed by $index_into_value_array or the first path element for the particular directive if $index_into_value_array is not provided) and if the value is an absolute file or directory path. Both the directive name and the value is checked, because some directives such as ErrorLog, can take values that are not paths (i.e. a piped command or syslog:facility). The /dev/null equivalent for the operating system is not treated as a path, since on some operating systems the /dev/null equivalent is not a file, such as nul on Windows.

The method actually does not check if its value is a path, rather it checks if the value does not match all of the other possible non-path values for the specific directive because different operating systems have different path formats, such as Unix, Windows and Macintosh.

$d->orig_value_is_abs_path

$d->orig_value_is_abs_path($index_into_value_array)

This has the same behavior as $d->value_is_abs_path except the results are applicable to $d's 'original' value array.

$d->value_is_rel_path

$d->value_is_rel_path($index_into_value_array)

Returns true if $d's directive can take a file or directory path in the specified value array element (indexed by $index_into_value_array or the first path element for the particular directive if $index_into_value_array is not provided) and if the value is a relative file or directory path. Both the directive name and the value is checked, because some directives such as ErrorLog, can take values that are not paths (i.e. a piped command or syslog:facility). The /dev/null equivalent for the operating system is not treated as a path, since on some operating systems the /dev/null equivalent is not a file, such as nul on Windows.

The method actually does not check if its value is a path, rather it checks if the value does not match all of the other possible non-path values for the specific directive because different operating systems have different path formats, such as Unix, Windows and Macintosh.

$d->orig_value_is_rel_path

$d->orig_value_is_rel_path($index_into_value_array)

This has the same behavior as $d->value_is_rel_path except the results are applicable to $d's 'original' value array.

$d->filename

$d->filename($filename)

In the first form get the filename where this particular directive or context appears. In the second form set the new filename of the directive or context and return the original filename.

$d->line_number

$d->line_number($line_number)

In the first form get the line number where the directive or context appears in a filename. In the second form set the new line number of the directive or context and return the original line number.

EXPORTED VARIABLES

The following variables are exported via @EXPORT_OK.

DEV_NULL

The string representation of the null device on this operating system.

DEV_NULL_LC

The lowercase version of DEV_NULL.

is_dev_null($path)

On a case sensitive system, compares $path to DEV_NULL and on a case insensitive system, compares lc($path) to DEV_NULL_LC.

%directive_value_takes_abs_path

This hash is keyed by the lowercase version of a directive name. This hash is keyed by all directives that accept a file or directory path value as its first value array element. The hash value is a subroutine reference to pass the value array element containing the file, directory, pipe or syslog entry to. If a hash entry exists for a particular entry, then the directive name can take either a relative or absolute path to either a file or directory. The hash does not distinguish between directives that take only filenames, only directories or both, and it does not distinguish if the directive takes only absolute, only relative or both types of paths.

The hash value for the lowercase directive name is a subroutine reference. The subroutine returns 1 if its only argument is a path and 0 otherwise. The /dev/null equivalent (File::Spec->devnull) for the operating system being used is not counted as a path, since on some operating systems the /dev/null equivalent is not a filename, such as nul on Windows.

The subroutine actually does not check if its argument is a path, rather it checks if the argument does not match one of the other possible non-path values for the specific directive because different operating systems have different path formats, such as Unix, Windows and Macintosh. For example, ErrorLog can take a filename, such as

ErrorLog /var/log/httpd/error_log

or a piped command, such as

ErrorLog "| cronolog /var/log/httpd/%Y/%m/%d/error.log"

or a syslog entry of the two forms:

ErrorLog syslog
ErrorLog syslog:local7

The particular subroutine for ErrorLog checks if the value is not equal to File::Spec->devnull, does not begin with a | or does not match syslog(:[a-zA-Z0-9]+)?.

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

This hash is used by value_is_path and orig_value_is_path.

This is a list of directives and any special values to check for as of Apache 1.3.20 with the addition of IncludeOptional from 2.4.x.

AccessConfig
AgentLog          check for "| prog"
AuthDBGroupFile
AuthDBMGroupFile
AuthDBMUserFile
AuthDBUserFile
AuthDigestFile
AuthGroupFile
AuthUserFile
CacheRoot
CookieLog
CoreDumpDirectory
CustomLog         check for "| prog"
Directory
DocumentRoot
ErrorLog          check for "| prog", or syslog or syslog:facility
Include
IncludeOptional
LoadFile
LoadModule
LockFile
MimeMagicFile
MMapFile
PidFile
RefererLog        check for "| prog"
ResourceConfig
RewriteLock
ScoreBoardFile
ScriptLog
ServerRoot
TransferLog       check for "| prog"
TypesConfig

%directive_value_takes_rel_path

This hash is keyed by the lowercase version of a directive name. This hash contains only those directive names that can accept both relative and absolute file or directory names. The hash value is a subroutine reference to pass the value array element containing the file, directory, pipe or syslog entry to. The hash does not distinguish between directives that take only filenames, only directories or both.

The hash value for the lowercase directive name is a subroutine reference. The subroutine returns 1 if its only argument is a path and 0 otherwise. The /dev/null equivalent (File::Spec->devnull) for the operating system being used is not counted as a path, since on some operating systems the /dev/null equivalent is not a filename, such as nul on Windows.

The subroutine actually does not check if its argument is a path, rather it checks if the argument does not match one of the other possible non-path values for the specific directive because different operating systems have different path formats, such as Unix, Windows and Macintosh. For example, ErrorLog can take a filename, such as

ErrorLog /var/log/httpd/error_log

or a piped command, such as

ErrorLog "| cronolog /var/log/httpd/%Y/%m/%d/error.log"

or a syslog entry of the two forms:

ErrorLog syslog
ErrorLog syslog:local7

The particular subroutine for ErrorLog checks if the value is not equal to File::Spec->devnull, does not begin with a | or does not match syslog(:[a-zA-Z0-9]+)?.

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

This hash is used by value_is_rel_path and orig_value_is_rel_path.

This is a list of directives and any special values to check for as of Apache 1.3.20 with the addition of IncludeOptional from 2.4.x.

AccessFileName is not a key in the hash because, while its value is one or more relative paths, the ServerRoot is never prepended to it as the AccessFileName values are looked up in every directory of the path to the document being requested.

AccessConfig
AuthGroupFile
AuthUserFile
CookieLog
CustomLog         check for "| prog"
ErrorLog          check for "| prog", or syslog or syslog:facility
Include
IncludeOptional
LoadFile
LoadModule
LockFile
MimeMagicFile
PidFile
RefererLog        check for "| prog"
ResourceConfig
ScoreBoardFile
ScriptLog
TransferLog       check for "| prog"
TypesConfig

%directive_value_path_element_pos

This hash holds the indexes into the directive value array for the value or values that can contain either absolute or relative file or directory paths. This hash is keyed by the lowercase version of a directive name. The hash value is a string representing an integer. The string can take two forms:

/^\d+$/   The directive has only one value element indexed by \d+
          that takes a file or directory path.

/^-\d+$/  The directive takes any number of file or directory path
          elements beginning with the abs(\d+) element.

For example:

# CustomLog logs/access_log common
$directive_value_path_element_pos{customlog}  eq '0';

# LoadFile modules/mod_env.so libexec/mod_mime.so
$directive_value_path_element_pos{loadfile}   eq '-0';

# LoadModule env_module modules/mod_env.so
$directive_value_path_element_pos{loadmodule} eq '1';

# PidFile logs/httpd.pid
$directive_value_path_element_pos{pidfile}    eq '0';

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.