GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Apache::Config::Preproc(3) User Contributed Perl Documentation Apache::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 follows:
compact
Removes empty lines and comments.
include
Expands Include and IncludeOptional statements by replacing them with the content of the corresponding files.
ifmodule
Expands the <IfModule> statements.
ifdefine
Expands the <IfDefine> statements.
locus
Attaches file location information to each node in the parse tree.
macro
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'],
          ['-no-blank-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 constructor:

-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.
-create
If present $file is a pathname of unexisting file, don't return an error.
-no-comment-grouping
Disables grouping of successive comments into one "comment" item. Useless if the compact expansion is enabled.
-no-blank-grouping
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 object.

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, ...] }

or

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

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.

Apache::Admin::Config

Apache::Config::Preproc::compact

Apache::Config::Preproc::ifdefine

Apache::Config::Preproc::ifmodule

Apache::Config::Preproc::include

Apache::Config::Preproc::locus

Apache::Config::Preproc::macro

2021-02-10 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.