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

FreeBSD Manual Pages


home | help
Apache::Config::PreproUser Contributed Perl DocumentApache::Config::Preproc(3)

       Apache::Config::Preproc - Preprocess Apache configuration files

	   use Apache::Config::Preproc;

	   $x =	new Apache::Config::Preproc '/path/to/httpd.conf',
		    -expand => [ qw(include compact macro ifmodule ifdefine) ]
		    or die $Apache::Admin::Config::ERROR;

       Apache::Config::Preproc reads and parses	Apache configuration file,
       expanding the syntactic constructs selected by the -expand option.  In
       the simplest case, the argument to that option is a reference to	the
       list of names. Each name	in the list identifies a module	responsible
       for processing specific Apache configuration keywords. For convenience,
       most modules are	named after the	keyword	they process, so that, e.g.
       include is responsible for inclusion of the files listed	with Include
       and IncludeOptional statements. The list	of built-in module names

	   Removes empty lines and comments.

	   Expands Include and IncludeOptional statements by replacing them
	   with	the content of the corresponding files.

	   Expands the <IfModule> statements.

	   Expands the <IfDefine> statements.

	   Attaches file location information to each node in the parse	tree.

	   Expands the <Macro> statements.

       See the section MODULES for a detailed description of these modules.

       More expansions can be easily implemented by supplying a	corresponding
       expansion module	(see the section MODULE	INTERNALS below).

       If the -expand argument is not supplied,	the following default is used:

	   [ 'include' ]

       The rest	of methods is inherited	from Apache::Admin::Config.

       The package provides two	implementations	of the main preprocessing
       method.	The default implementation uses	only the documented methods of
       the base	Apache::Admin::Config class and	due to its deficiences shows
       the O(N**2) time	complexity.  The optimized implementations does	some
       introspection into the internals	of the base class, which allow it to
       reduce the time complexity to O(N).  Whenever possible, the optimized
       implementation is selected.  You	can, however, force using the
       particular implementation by supplying keywords to the "use" statement.
       To select the default implementation:

	   use Apache::Config::Preproc qw(:default);

       To select the optimized implementation:

	   use Apache::Config::Preproc qw(:optimized);

       See the source code for details.

	   $obj	= new Apache::Config::Preproc $file,
		 [-expand => $modlist],
		 [-indent => $integer],	['-create'], ['-no-comment-grouping'],

       Reads the Apache	configuration file from	$file and preprocesses it.
       The $file argument can be either	the file name or file handle.

       The keyword arguments are:

       -expand => $arrayref
	   Define what expansions are to be performed. $arrayref is a
	   reference to	array of module	names with optional arguments. To
	   supply arguments, use either	a list reference where the first
	   element is the module name and rest of elements are arguments, or a
	   hash	reference with the name	of the module as key and a reference
	   to the list of arguments as its value.  Consider, for example:

	       -expand => [ 'include', { ifmodule => { probe =>	1 } } ]

	       -expand => [ 'include', [ 'ifmodule', { probe =>	1 } ] ]

	   Both	constructs load	the include module with	no specific arguments,
	   and the ifmodule module with	the arguments probe => 1.

	   See the MODULES section for a discussion of built-in	modules	and
	   allowed arguments.

	   A missing -expand argument is equivalent to

	       -expand => [ 'include' ]

       Rest of arguments is the	same as	for the	Apache::Admin::Config

       -indent => $n
	   Enables reindentation of the	configuration content. The $n argument
	   is the indenting amount per level of	nesting. Negative value	means
	   indent with tab characters.

	   If present $file is a pathname of unexisting	file, don't return an

	   Disables grouping of	successive comments into one "comment" item.
	   Useless if the compact expansion is enabled.

	   Disables grouping of	successive empty lines into one	"blank"	item.
	   Useless if the compact expansion is enabled.

       All methods are inherited from Apache::Admin::Config.

       Additional methods:

       Returns the name	of the configuration file.

       Returns the list	of options passed to the constructor when creating the

       The preprocessing phases	to be performed	on the parsed configuration
       text are	defined	by the -expand argument. Internally, each name in its
       argument	list causes loading of a Perl module responsible for this
       particular phase.  Arguments to the constructor can be supplied using
       any of the following constructs:

	      {	NAME =>	[ ARG, ...] }


	      [	NAME, ARG, ... ]

       This section describes the built-in modules and their arguments.

       The compact module eliminates empty and comment lines. The constructor
       takes no	arguments.

       Processes Include and IncludeOptional statements	and replaces them with
       the contents of the files supplied in their argument. If	the latter is
       not an absolute file name, it is	searched in the	server root directory.

       The following keyword arguments can be used to set the default server
       root directory:

       server_root => DIR
	   Sets	default	server root value to DIR.

       probe =>	LISTREF	| 1
	   Determines the default server root value by analyzing the output of
	   httpd -V. If	LISTREF	is given, it contains alternative pathnames of
	   the Apache httpd binary. Otherwise,

	       probe =>	1

	   is a	shorthand for

	       probe =>	[qw(/usr/sbin/httpd /usr/sbin/apache2)]

       When the	ServerRoot statement is	seen, its value	overwrites any
       previously set server root directory.

       Processes IfModule statements. If the statement's argument evaluates to
       true, it	is replaced by the statements inside it. Otherwise, it is
       removed.	 Nested	statements are allowed.	The LoadModule statements are
       examined	in order to evaluate the argument.

       The constructor understands the following arguments:

       preloaded => LISTREF
	   Supplies a list of preloaded	module names. You can use this
	   argument to pass a list of modules linked statically	in your
	   version of httpd.

       probe =>	LISTREF	| 1
	   Provides an alternative way of handling statically linked Apache
	   modules.  If	LISTREF	is given, each its element is treated as the
	   pathname of the Apache httpd	binary.	The first of them that is
	   found is run	with the -l option to list the statically linked
	   modules, and	its output is parsed.

	   The option

	       probe =>	1

	   is a	shorthand for

	       probe =>	[qw(/usr/sbin/httpd /usr/sbin/apache2)]

       Eliminates the Define and UnDefine statements and expands the
       <IfDefine> statements in	the Apache configuration parse tree. Optional
       arguments to the	constructor are	treated	as the names of	symbols	to
       define (similar to the httpd -D options). Example:

	   -expand => [	{ ifdefine => [	qw(SSL FOREGROUND) ] } ]

       Attaches	to each	node in	the parse tree a Text::Locus object which
       describes the location of the corresponding statement in	the source
       file.  The location for each node can be	accessed via the locus method.
       E.g. the	following prints location and type of each statement:

	   $x =	new Apache::Config::Preproc '/etc/httpd.conf',
					    -expand => [ qw(locus) ];

	   foreach ($x->select)	{
	       print $_->locus

       See Text::Locus for a detailed discussion of the	locus object and its

       Processes Macro and Use statements (see mod_macro).  Macro statements
       are removed. Each Use statement is replaced by the expansion of the
       macro named in its argument.

       The constructor accepts the following arguments:

       keep => $listref
	   List	of macro names to exclude from expanding. Each <Macro> and Use
	   statement with a name from $listref as its first argument will be
	   retained in the parse tree.

	   As a	syntactic sugar, $listref can also be a	scalar value. This is
	   convenient when a single macro name is to be	retained.

       Each keyword phase listed in the	-expand	array causes loading of	the
       package Apache::Config::Preproc::phase.	This package must inherit from
       Apache::Config::Preproc::Expand and overload at least the expand
       method.	See the	description of Apache::Config::Preproc::Expand for a
       detailed	description.

	   my $obj = new Apache::Config::Preproc('/etc/httpd/httpd.conf',
			  -expand => [qw(compact include ifmodule macro)],
			  -indent => 4)	or die $Apache::Admin::Config::ERROR;
	   print $obj->dump_raw

       This snippet loads the Apache configuration from	file
       /etc/httpd/httpd.conf, performs all the built-in	expansions, and	prints
       the result on standard output, using 4 character	indent for each
       additional level	of nesting.








perl v5.32.0			  2020-01-23	    Apache::Config::Preproc(3)


Want to link to this manual page? Use this URL:

home | help