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.

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, so to get a string version, orig_value.

$d->value_is_path

Returns true if $d's directive can take a file or directory path as its value array element 0 and that element is a file or directory path. Both the directive name and the argument is checked, because some directives such as ErrorLog, can take values that are not paths (i.e. 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 argument is a path, rather it checks if the argument 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

Returns true if $d's directive can take a file or directory path as its `original' value array element 0 and that element is a file or directory path. This has the same semantics as value_is_path.

$d->value_is_abs_path

Returns true if $d's directive can take either an absolute or relative file or directory path as its value array element 0 and that element is an absolute file or directory path. Both the directive name and the argument is checked, because some directives such as ErrorLog, can take values that are not paths (i.e. 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.

Unlike value_is_path and orig_value_is_path, this method does check if the argument is in the format of a relative path that is used on the operating system running using this module.

$d->orig_value_is_abs_path

Returns true if $d's directive can take either an absolute or relative file or directory path as its `original' value array element 0 and that element is an absolute file or directory path. Has the same semantics as value_is_abs_path.

$d->value_is_rel_path

Returns true if $d's directive can take either an absolute or relative file or directory path as its value array element 0 and that element is a relative file or directory path. If a relative path name is given as a value to a directive that does not take relative file or directory names, such as AgentLog, then this subroutine will return 0 even though the path is relative. Both the directive name and the argument is checked, because some directives such as ErrorLog, can take values that are not paths (i.e. 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.

Unlike value_is_path and orig_value_is_path, this method does check if the argument is in the format of a relative path that is used on the operating system running using this module.

$d->orig_value_is_rel_path

Returns true if $d's directive can take either an absolute or relative file or directory path as its `original' value array element 0 and that element is a relative file or directory path. Has the same semantics as value_is_rel_path.

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

%directive_value_takes_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.

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

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.

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

AUTHOR

Blair Zajac <blair@orcaware.com>.

COPYRIGHT

To install Apache::ConfigParser, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Apache::ConfigParser

CPAN shell

perl -MCPAN -e shell
install Apache::ConfigParser

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)