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

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

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

$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

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

AUTHOR

COPYRIGHT