NAME

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

SYNOPSIS

use Apache::ConfigParser::Directive;

# Create a new emtpy 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 ement.
# 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 a 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->filename

$d->filename($filename)

In the first form get the filename where this pariticular 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.

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.