Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Apache::ConfigParser(3User Contributed Perl DocumentatiApache::ConfigParser(3)

NAME
       Apache::ConfigParser - Load Apache configuration	files

SYNOPSIS
	 use Apache::ConfigParser;

	 # Create a new	empty parser.
	 my $c1	= Apache::ConfigParser->new;

	 # Load	an Apache configuration	file.
	 my $rc	= $c1->parse_file('/etc/httpd/conf/httpd.conf');

	 # If there is an error	in parsing the configuration file, then	$rc
	 # will	be false and an	error string will be available.
	 if (not $rc) {
	   print $c1->errstr, "\n";
	 }

	 # 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
	 # or IncludeOptional'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_down_directive_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];

	 # Here	is a more complete example to load an httpd.conf file and add
	 # a new VirtualHost directive to it.
	 #
	 # The Apache::ConfigParser object contains a reference	to a
	 # Apache::ConfigParser::Directive object, which can be	obtained by
	 # using Apache::ConfigParser->root.  The root node is a
	 # Apache::ConfigParser::Directive which ISA Tree::DAG_Node (that is
	 # Apache::ConfigParser::Directive's @ISA contains Tree::DAG_Node).
	 # So to get the root node and add a new directive to it, it could be
	 # done	like this:

	 my $c		      =	Apache::ConfigParser->new;
	 my $rc		      =	$c->parse_file('/etc/httpd.conf');
	 my $root	      =	$c->root;
	 my $new_virtual_host =	$root->new_daughter;
	 $new_virtual_host->name('VirtualHost');
	 $new_virtual_host->value('*');

	 # The VirtualHost is called a "context" that contains other
	 # Apache::ConfigParser::Directive's:

	 my $server_name = $new_virtual_host->new_daughter;
	 $server_name->name('ServerName');
	 $server_name->value('my.hostname.com');

DESCRIPTION
       The "Apache::ConfigParser" module is used to load an Apache
       configuration file to allow programs to determine Apache's
       configuration directives	and contexts.  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 from "Tree::DAG_Node" are
       also available.	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
	   contexts 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.

METHODS
       The following methods are available:

       $c = Apache::ConfigParser->new
       $c = Apache::ConfigParser->new({options})
	   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.

	   The currently recognized options are:

	   pre_transform_path_sub => sub { }
	   pre_transform_path_sub => [sub { }, @args]
	       This allows the file or directory name for any directive	that
	       takes either a filename or directory name to be transformed by
	       an arbitrary subroutine before it is made absolute with
	       ServerRoot.  This transformation	is applied to any of the
	       directives that appear in
	       %Apache::ConfigParser::Directive::directive_value_takes_path
	       that have a filename or directory value instead of a pipe or
	       syslog value, i.e. "| cronolog" or "syslog:warning".

	       If the second form of "pre_transform_path_sub" is used with an
	       array reference,	then the first element of the array reference
	       must be a subroutine reference followed by zero or more
	       arbitrary arguments.  Any array elements	following the
	       subroutine reference are	passed to the specified	subroutine.

	       The subroutine is passed	the following arguments:

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

	       NOTE: Be	careful, because this subroutine will be applied to
	       ServerRoot and DocumentRoot, among other	directives.  See
	       Apache::ConfigParser::Directive for the complete	list of
	       directives that "pre_transform_path_sub"	is applied to.	If you
	       do not want the transformation applied to any specific
	       directives, make	sure to	check the directive name and if	you do
	       not want	to modify the filename,	return the subroutine's	third
	       argument.

	       If the subroutine returns an undefined value or a value with 0
	       length, then it is replaced with	"File::Spec->devnull" which is
	       the appropriate 0 length	file for the operating system.	This
	       is done to keep a value in the directive	name since otherwise
	       the directive may not work properly.  For example, with the
	       input

		 CustomLog logs/access_log combined

	       and if "pre_transform_path_sub" were to replace
	       'logs/access_log' with '', then

		 CustomLog combined

	       would no	longer be a valid directive.  Instead,

		 CustomLog C<File::Spec->devnull> combined

	       would be	appropriate for	all systems.

	   post_transform_path_sub => sub { }
	   post_transform_path_sub => [sub { },	@args]
	       This allows the file or directory name for any directive	that
	       takes either a filename or directory name to be transformed by
	       this subroutine after it	is made	absolute with ServerRoot.
	       This transformation is applied to any of	the directives that
	       appear in
	       %Apache::ConfigParser::Directive::directive_value_takes_path
	       that have a filename or directory value instead of a pipe or
	       syslog value, i.e. "| cronolog" or "syslog:warning".

	       If the second form of "post_transform_path_sub" is used with an
	       array reference,	then the first element of the array reference
	       must be a subroutine reference followed by zero or more
	       arbitrary arguments.  Any array elements	following the
	       subroutine reference are	passed to the specified	subroutine.

	       The subroutine is passed	the following arguments:

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

	       NOTE: Be	careful, because this subroutine will be applied to
	       ServerRoot and DocumentRoot, among other	directives.  See
	       Apache::ConfigParser::Directive for the complete	list of
	       directives that "post_transform_path_sub" is applied to.	 If
	       you do not want the transformation applied to any specific
	       directives, make	sure to	check the directive name and if	you do
	       not want	to modify the filename,	return the subroutine's	third
	       argument.

	       If the subroutine returns an undefined value or a value with 0
	       length, then it is replaced with	"File::Spec->devnull" which is
	       the appropriate 0 length	file for the operating system.	This
	       is done to keep a value in the directive	name since otherwise
	       the directive may not work properly.  For example, with the
	       input

		 CustomLog logs/access_log combined

	       and if "post_transform_path_sub"	were to	replace
	       'logs/access_log' with '', then

		 CustomLog combined

	       would no	longer be a valid directive.  Instead,

		 CustomLog C<File::Spec->devnull> combined

	       would be	appropriate for	all systems.

	   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 directives	and contexts
	   in $filename	will be	added to the existing context.

	   If there is a failure in parsing any	portion	of the configuration
	   file, then this method returns undef	and "$c->errstr" will contain
	   a string explaining the error.

       $c->root
	   Returns the root of the tree	that represents	the Apache
	   configuration file.	Each object here is a
	   "Apache::ConfigParser::Directive".

       $c->find_down_directive_names('directive', ...)
       $c->find_down_directive_names($node, 'directive', ...)
	   In list context, returns the	list all of $c's directives that match
	   the directive names in $node	and $node's children.  In scalar
	   context, returns the	number of such directives.  The	level here is
	   in a	tree sense, not	in the sense that some directives appear
	   before or after $node in the	configuration file.  If	$node is
	   given, then the search searches $node and $node's children.	If
	   $node is not	passed as an argument, then the	search starts at the
	   top of the tree and searches	the whole configuration	file.

	   The search for matching directive names is done without regards to
	   case.

	   This	is useful if you want to find all of the CustomLog's in	the
	   configuration file:

	     my	@logs =	$c->find_down_directive_names('CustomLog');

       $c->find_siblings_directive_names('directive', ...)
       $c->find_siblings_directive_names($node,	'directive', ...)
	   In list context, returns the	list of	all $c's directives that match
	   the directive names at the same level of $node, that	is siblings of
	   $node.  In scalar context, returns the number of such directives.
	   The level here is in	a tree sense, not in the sense that some
	   directives appear above or below $node in the configuration file.
	   If $node is passed to the method and	it is equal to "$c->tree" or
	   if $node is not given, then the method will search through root's
	   children.

	   This	method will return $node as one	of the matches if $node's
	   directive name is one of the	directive names	passed to the method.

	   The search for matching directive names is done without regards to
	   case.

       $c->find_siblings_and_up_directive_names($node, 'directive', ...)
	   In list context, returns the	list of	all $c's directives that match
	   the directive names at the same level of $node, that	is siblings of
	   $node and above $node.  In scalar context, returns the number of
	   such	directives.  The level here is in a tree sense,	not in the
	   sense that some directives appear before or after $node in the
	   configuration file.	In this	method $node is	a required argument
	   because it does not make sense to check the root node.  If $node
	   does	not have a parent node,	then no	siblings will be found.	 This
	   method will return $node as one of the matches if $node's directive
	   name	is one of the directive	names passed to	the method.

	   The search for matching directive names is done without regards to
	   case.

	   This	is useful when you find	an directive and you want to find an
	   associated directive.  For example, find all	of the CustomLog's and
	   find	the associated ServerName.

	     foreach my	$log_node ($c->find_down_directive_names('CustomLog')) {
	       my $log_filename	= $log_node->name;
	       my @server_names	= $c->find_siblings_and_up_directive_names($log_node);
	       my $server_name	= $server_names[0];
	       print "ServerName for $log_filename is $server_name\n";
	     }

       $c->errstr
	   Return the error string associated with the last failure of any
	   "Apache::ConfigParser" method.  The string returned is not emptied
	   when	any method calls succeed, so a non-zero	length string returned
	   does	not necessarily	mean that the last method call failed.

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

perl v5.32.0			  2015-05-24	       Apache::ConfigParser(3)

NAME | SYNOPSIS | DESCRIPTION | PARSING | METHODS | SEE ALSO | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Apache::ConfigParser&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help