stas 2002/12/13 09:50:29
Modified: src/docs/2.0/user/config custom.pod
Log:
the custom configuration directives doc is almost complete
Revision Changes Path
1.3 +310 -117 modperl-docs/src/docs/2.0/user/config/custom.pod
Index: custom.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/config/custom.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- custom.pod 12 Dec 2002 10:17:27 -0000 1.2
+++ custom.pod 13 Dec 2002 17:50:29 -0000 1.3
@@ -7,8 +7,6 @@
This chapter explains how to create custom Apache configuration
directives in Perl.
-WARNING: This doc is under construction
-
=head1 Incentives
mod_perl provides several ways to pass custom configuration
@@ -167,16 +165,17 @@
the defaults described next.
These are the attributes that can be used to define the directives
-behavior:
+behavior: I<L<name|/C_name_>>, I<L<func|/C_func_>>,
+I<L<args_how|/C_args_how_>>, I<L<req_override|/C_req_override_>> and
+I<L<errmsg|/C_errmsg_>>. They are discussed in the following sections.
-=over
-=item * name
+=head3 C<name>
This is the only required attribute. And it declares the name of the
new directive as it'll be used in I<httpd.conf>.
-=item * func
+=head3 C<func>
The I<func> attribute expects a reference to a function or a function
name. This function is called by httpd every time it encounters the
@@ -198,13 +197,14 @@
as a name of a subroutine and it anticipates that it exists in that
package.
-=item * req_override
+=head3 C<req_override>
The I<> attribute defines the valid scope in which this directive can
appear. There are L<several
constants|/Directive_Scope_Definition_Constants> which map onto the
corresponding Apache macros. These constants should be imported from
-the C<Apache::Const> package.
+the C<L<Apache::Const|docs::2.0::api::mod_perl-2.0::Apache::Const>>
+package.
For example, to use the C<OR_ALL> constant, which allows directives to
be defined anywhere, first, it needs to be imported:
@@ -224,31 +224,33 @@
forbid it from ever being used in I<.htaccess> files:
This attribute is optional. If not supplied, the default value of
-C<Apache::OR_ALL> is used.
+C<L<Apache::OR_ALL|/C_Apache__OR_ALL_>> is used.
-=item * args_how
+=head3 C<args_how>
Directives can receive zero, one or many arguments. In order to help
Apache validate that the number of arguments is valid, the I<args_how>
attribute should be set to the desired value. Similar to the
-I<req_override> attribute, the C<Apache::Const> package provides
-special constants which map to the corresponding Apache macros. There
-are L<several constants|/Directive_Syntax_Definition_Constants> to
-choose from.
+I<L<req_override|/C_req_override_>> attribute, the
+C<L<Apache::Const|docs::2.0::api::mod_perl-2.0::Apache::Const>>
+package provides special constants which map to the corresponding
+Apache macros. There are L<several
+constants|/Directive_Syntax_Definition_Constants> to choose from.
In our example, the directive C<MyParameter> accepts one or more
-arguments, therefore we have the C<Apache::ITERATE> constant:
+arguments, therefore we have the
+C<L<Apache::ITERATE|/C_Apache__ITERATE_>> constant:
args_how => Apache::ITERATE,
This attribute is optional. If not supplied, the default value of
-C<Apache::TAKE1> is used.
+C<L<Apache::TAKE1|/C_Apache__TAKE1_>> is used.
META: the default may change to use a constant corresponding to the
I<func> prototype.
-=item * errmsg
+=head3 C<errmsg>
The I<errmsg> attribute provides a short but succinct usage statement
that summarizes the arguments that the directive takes. It's used by
@@ -261,23 +263,22 @@
errmsg => 'MyParameter Entry1 [Entry2 ... [EntryN]]',
This attribute is optional. If not supplied, the default value of will
-be a string based on the directive's I<name> and I<args_how>
-attributes.
+be a string based on the directive's I<L<name|/C_name_>> and
+I<L<args_how|/C_args_how_>> attributes.
-=back
=head2 Directive Scope Definition Constants
-The I<req_override> attribute specifies the configuration scope in
-which it's valid to use a given configuration directive. This
-attribute's value can be any of or a combination of the following
-constants:
+The I<L<req_override|/C_req_override_>> attribute specifies the
+configuration scope in which it's valid to use a given configuration
+directive. This attribute's value can be any of or a combination of
+the following constants:
(these constants are declared in I<httpd-2.0/include/http_config.h>.)
=head3 C<Apache::OR_NONE>
-The directive cannot be overriden by any of the C<AllowOverride>
+The directive cannot be overridden by any of the C<AllowOverride>
options.
=head3 C<Apache::OR_LIMIT>
@@ -331,7 +332,14 @@
Force directive to execute a command which would modify the
configuration (like including another file, or C<IFModule>).
-META: details???
+Normally, Apache first parses the configuration tree and then executes
+the directives it has encountered (e.g., C<SetEnv>). But there are
+directives that must be executed during the initial parsing, either
+because they affect the configuration tree (e.g., C<Include> may load
+extra configuration) or because they tell Apache about new directives
+(e.g., C<IfModule> or C<PerlLoadModule>, may load a module, which
+installs handlers for new directives). These directives must have the
+C<Apache::OR_EXEC_ON_READ> turned on.
=head3 C<Apache::OR_ALL>
@@ -342,11 +350,12 @@
=head2 Directive Callback Subroutine
-Depending on the value of the I<args_how> attribute the callback
-subroutine, specified with the I<func> attribute, will be called with
-two or more arguments. The first two arguments are always C<$self> and
-C<$parms>. A typical callback function which expects a single value
-(C<Apache::TAKE1>) might look like the following:
+Depending on the value of the I<L<args_how|/C_args_how_>> attribute
+the callback subroutine, specified with the I<L<func|/C_func_>>
+attribute, will be called with two or more arguments. The first two
+arguments are always C<$self> and C<$parms>. A typical callback
+function which expects a single value
+(C<L<Apache::TAKE1|/C_Apache__TAKE1_>>) might look like the following:
sub MyParam {
my($self, $parms, $arg) = @_;
@@ -396,9 +405,10 @@
=item 2
-C<$parms> is an I<Apache::CmdParms> object from which you can retrieve
-various other information about the configuration. For example to
-retrieve the server object:
+C<$parms> is an
+C<L<Apache::CmdParms|docs::2.0::api::mod_perl-2.0::Apache::CmdParms>>
+object from which you can retrieve various other information about the
+configuration. For example to retrieve the server object:
my $s = $parms->server;
@@ -408,8 +418,8 @@
=item 3
-The rest of the arguments whose number depends on the I<args_how>'s
-value are covered in L<the next
+The rest of the arguments whose number depends on the
+I<L<args_how|/C_args_how_>>'s value are covered in L<the next
section|/Directive_Syntax_Definition_Constants>.
=back
@@ -418,9 +428,10 @@
=head2 Directive Syntax Definition Constants
-The following values of the I<args_how> attribute define how many
-arguments and what kind of arguments directives can accept. These
-values are constants that can be imported from the C<Apache::Const>
+The following values of the I<L<args_how|/C_args_how_>> attribute
+define how many arguments and what kind of arguments directives can
+accept. These values are constants that can be imported from the
+C<L<Apache::Const|docs::2.0::api::mod_perl-2.0::Apache::Const>>
package. For example:
use Apache::Const -compile => qw(TAKE1 TAKE23);
@@ -458,8 +469,9 @@
=head3 C<Apache::TAKE3>
-This is like C<Apache::TAKE1> and C<Apache::TAKE2>, but the directive
-takes three mandatory arguments. For example:
+This is like C<L<Apache::TAKE1|/C_Apache__TAKE1_>> and
+C<L<Apache::TAKE2|/C_Apache__TAKE2_>>, but the directive takes three
+mandatory arguments. For example:
sub MyParameter {
my($self, $parms, @args) = @_;
@@ -479,8 +491,9 @@
=head3 C<Apache::TAKE23>
-C<Apache::TAKE23> is just like C<Apache::TAKE12>, except now there are
-two mandatory arguments and an optional third one.
+C<L<Apache::TAKE23|/C_Apache__TAKE23_>> is just like
+C<L<Apache::TAKE12|/C_Apache__TAKE12_>>, except now there are two
+mandatory arguments and an optional third one.
=head3 C<Apache::TAKE123>
@@ -528,16 +541,16 @@
=head3 C<Apache::RAW_ARGS>
-An I<args_how> of C<Apache::RAW_ARGS> instructs Apache to turn off
-parsing altogether. Instead it simply passes your callback function
-the line of text following the directive. Leading and trailing
-whitespace is stripped from the text, but it is not otherwise
-processed. Your callback can then do whatever processing it wishes to
-perform.
-
-This callback receives three arguments (similar to C<Apache::TAKE1>),
-the third of which is a string-valued scalar containing the text
-following the directive.
+An I<L<args_how|/C_args_how_>> of C<Apache::RAW_ARGS> instructs
+Apache to turn off parsing altogether. Instead it simply passes your
+callback function the line of text following the directive. Leading
+and trailing whitespace is stripped from the text, but it is not
+otherwise processed. Your callback can then do whatever processing it
+wishes to perform.
+
+This callback receives three arguments (similar to
+C<L<Apache::TAKE1|/C_Apache__TAKE1_>>), the third of which is a
+string-valued scalar containing the text following the directive.
sub MyParameter {
my($self, $parms, $val) = @_;
@@ -545,28 +558,31 @@
}
If this mode is used to implement a custom "container" directive, the
-attribute I<req_override> needs to OR C<Apache::EXEC_ON_READ>. e.g.:
+attribute I<L<req_override|/C_req_override_>> needs to OR
+C<L<Apache::OR_EXEC_ON_READ|/C_Apache__OR_EXEC_ON_READ_>>. e.g.:
- req_override => Apache::OR_ALL | Apache::EXEC_ON_READ,
+ req_override => Apache::OR_ALL | Apache::OR_EXEC_ON_READ,
META: complete the details, which are new to 2.0.
There is one other trick to making configuration containers work. In
-order to be recogized as a valid directive, the I<name> attribute must
-contain the leading C<E<lt>>. This token will be stripped by the code
-that handes the custom directive callbacks to Apache. For example:
+order to be recognized as a valid directive, the I<L<name|/C_name_>>
+attribute must contain the leading C<E<lt>>. This token will be
+stripped by the code that handles the custom directive callbacks to
+Apache. For example:
name => '<MyContainer',
One other trick that is not required, but can provide some more user
friendliness is to provide a handler for the container end token. In
our example, the Apache configuration gears will never see the
-C<E<lt>/MyContainerE<gt>> token, as our C<Apache::RAW_ARGS> handler
-will read in that line and stop reading when it is seen. However in
-order to catch cases in which the C<E<lt>/MyContainerE<gt>> text
-appears without a preceding C<E<lt>MyContainerE<gt>> opening section,
-we need to turn the end token into a directive that simply reports an
-error and exits. For example:
+C<E<lt>/MyContainerE<gt>> token, as our
+C<L<Apache::RAW_ARGS|/C_Apache__RAW_ARGS_>> handler will read in that
+line and stop reading when it is seen. However in order to catch
+cases in which the C<E<lt>/MyContainerE<gt>> text appears without a
+preceding C<E<lt>MyContainerE<gt>> opening section, we need to turn
+the end token into a directive that simply reports an error and
+exits. For example:
{
name => '</MyContainer>',
@@ -581,7 +597,7 @@
die "$EndToken outside a <MyContainer> container\n";
}
-Now, should the server admin misplace the container end token, the
+Now, should the server administrator misplace the container end token, the
server will not start, complaining with this error message:
Syntax error on line 54 of httpd.conf:
@@ -628,7 +644,7 @@
configuration values, which are populated by directive callbacks,
invoked when the I<httpd.conf> and the I<.htaccess> files are parsed
and the corresponding directive are encountered. It's possible to
-prepopulate the hash entries when the data structure is created, e.g.,
+pre-populate the hash entries when the data structure is created, e.g.,
to provide reasonable default values for cases where they weren't set
in the configuration file. To accomplish that the optional
C<L<SERVER_CREATE|/C_SERVER_CREATE_>> and
@@ -638,7 +654,7 @@
container has any ancestor containers. If that's the case, it allows
mod_perl to call special merging functions, which decide whether
configurations in the parent containers should be inherited, appended
-or overriden in the child container. The custom configuration module
+or overridden in the child container. The custom configuration module
can supply custom merging functions
C<L<SERVER_MERGE|/C_SERVER_MERGE_>> and C<L<DIR_MERGE|/C_DIR_MERGE_>>,
which can override the default behavior. If these functions are not
@@ -651,21 +667,25 @@
C<SERVER_CREATE> is called once for the main server, and once more for
each virtual host defined in I<httpd.conf>. It's called with two
arguments: C<$class>, the package name it was created in and C<$parms>
-the already familiar C<Apache::CmdParms> object. The object is
-expected to return a reference to a blessed hash, which will be used
-by configuration directive callbacks to set the values passed by the
-user in the configuration file. But it's possible to preset some
-values here:
-
-For example:
+the already familiar
+C<L<Apache::CmdParms|docs::2.0::api::mod_perl-2.0::Apache::CmdParms>>
+object. The object is expected to return a reference to a blessed
+hash, which will be used by configuration directives callbacks to set
+the values assigned in the configuration file. But it's possible to
+preset some values here:
+
+For example, in the following example the object assigns a default
+value, which can be overridden during merge if a the directive was used
+to assign a custom value:
package MyApache::MyParameters;
...
+ use Apache::Module ();
+ use Apache::CmdParms ();
our @APACHE_MODULE_COMMANDS = (...);
...
sub SERVER_CREATE {
my($class, $parms) = @_;
- #warn "$class->SERVER_CREATE\n";
return bless {
name => __PACKAGE__,
}, $class;
@@ -673,8 +693,28 @@
To retrieve that value later, you can use:
- my $srv_cfg = $self->get_config($s);
- print $srv_cfg->{name}
+ use Apache::Module ();
+ ...
+ my $srv_cfg = Apache::Module->get_config('MyApache::MyParameters', $s);
+ print $srv_cfg->{name};
+
+If a request is made to a resource inside a virtual host, C<$srv_cfg>
+will contain the object of the virtual host's server. To reach the
+main server's configuration object use:
+
+ use Apache::Module ();
+ use Apache::Server ();
+ use Apache::ServerUtil ();
+ ...
+ if ($s->is_virtual) {
+ my $base_srv_cfg = Apache::Module->get_config('MyApache::MyParameters',
+ Apache->server);
+ print $base_srv_cfg->{name};
+ }
+
+If the function C<SERVER_CREATE> is not supplied by the module, a
+function that returns a blessed into the current package reference to
+a hash is used.
=head3 C<SERVER_MERGE>
@@ -684,59 +724,94 @@
default behavior, which simply overrides the main server's
configuration.
-The custom subroutine accepts two arguments: C<$base>, the reference
-to the main server configuration object, and C<$add>, the reference to
-a virtual host configuration object. It's expected to return a similar
-object after performing the merge of the two objects it has received.
+The custom subroutine accepts two arguments: C<$base>, a blessed
+reference to the main server configuration object, and C<$add>, a
+blessed reference to a virtual host configuration object. It's
+expected to return a blessed object after performing the merge of the
+two objects it has received. Here is the skeleton of a merging
+function:
-The following example implements different merging rules for different
-keys.
+ sub merge {
+ my($base, $add) = @_;
+ my %mrg = ();
+ # code to merge %$base and %$add
+ return bless \%mrg, ref($base);
+ }
+
+The section L<Merging at Work|/Merging_at_Work> provides an extensive
+example of a merging function.
- package MyApache::MyParametersMath;
+=head3 C<DIR_CREATE>
+
+Similarly to C<L<SERVER_CREATE|/C_SERVER_CREATE_>>, this optional
+function, is used to create an object for the directory resource. If
+the function is not supplied mod_perl will use an empty hash variable
+as an object.
+
+Just like C<L<SERVER_CREATE|/C_SERVER_CREATE_>>, it's called once for
+the main server and one more time for each virtual host. In addition
+it'll be called once more for each resource (C<E<lt>LocationE<gt>>,
+C<E<lt>DirectoryE<gt>> and others). All this happens during the
+startup. At request time it might be called for each parsed
+I<.htaccess> file and for each resource defined in it.
+
+The C<DIR_CREATE> function's skeleton is identical to
+C<SERVER_CREATE>. Here is an example:
+
+ package MyApache::MyParameters;
...
+ use Apache::Module ();
+ use Apache::CmdParms ();
our @APACHE_MODULE_COMMANDS = (...);
...
- sub SERVER_MERGE {
- my($base, $add) = @_;
- #warn "$class->SERVER_CREATE\n";
- my %mrg = %$base;
- for my $key (keys %$add) {
- if ($key eq 'Plus') {
- $mrg{$key} = $base->{$key}||0 + $add->{$key};
- }
- else ($key eq 'Minus') {
- $mrg{$key} = $base->{$key}||0 - $add->{$key};
- }
- else {
- $mrg{$key} = $add->{$key}; # override
- }
- $mrg{$_} = $_ eq 'Append' ?
- }
- for (keys %$base, keys
- return
+ sub DIR_CREATE {
+ my($class, $parms) = @_;
return bless {
- name => __PACKAGE__,
+ foo => 'bar',
}, $class;
}
-=head3 C<DIR_CREATE>
+To retrieve that value later, you can use:
+
+ use Apache::Module ();
+ ...
+ my $dir_cfg = Apache::Module->get_config('MyApache::MyParameters',
+ $s, $r->per_dir_config);
+ print $dir_cfg->{foo};
+
+The only difference in the retrieving the directory configuration
+object. Here the third argument C<$r-E<gt>per_dir_config> tells
+C<L<Apache::Module|docs::2.0::api::mod_perl-2.0::Apache::Module>> to
+get the directory configuration object.
=head3 C<DIR_MERGE>
+Similarly to C<L<SERVER_MERGE|/C_SERVER_MERGE_>>, C<DIR_MERGE> merges
+the ancestor and the current node's directory configuration objects.
+At the server startup C<DIR_MERGE> is called once for each virtual
+host. At request time, the merging of the objects of resources, their
+sub-resources and the virtual host/main server merge happens. Apache
+caches the products of merges, so you may see certain merges happening
+only once.
- NotifyError [On Off]
- NotifyErrorEmail email_address
+The section L<Merging Order Consequences|/Merging_Order_Consequences>
+discusses in detail the merging order.
+The section L<Merging at Work|/Merging_at_Work> provides an extensive
+example of a merging function.
=head1 Examples
=head2 Merging at Work
In the following example we are going to demonstrate in details how
-merging works, by showing various merging technique.
-
+merging works, by showing various merging techniques.
+Here is an example Perl module, which, when loaded, installs four
+custom directives into Apache.
+ #file:MyApache/CustomDirectives.pm
+ #---------------------------------
package MyApache::CustomDirectives;
use strict;
@@ -767,7 +842,8 @@
my($key, $self, $parms, $arg) = @_;
$self->{$key} = $arg;
unless ($parms->path) {
- my $srv_cfg = Apache::Module->get_config($self, $parms->server);
+ my $srv_cfg = Apache::Module->get_config($self,
+ $parms->server);
$srv_cfg->{$key} = $arg;
}
}
@@ -776,7 +852,8 @@
my($key, $self, $parms, $arg) = @_;
push @{ $self->{$key} }, $arg;
unless ($parms->path) {
- my $srv_cfg = Apache::Module->get_config($self, $parms->server);
+ my $srv_cfg = Apache::Module->get_config($self,
+ $parms->server);
push @{ $srv_cfg->{$key} }, $arg;
}
}
@@ -795,7 +872,8 @@
@{ $base->{$key}||[] }, @{ $add->{$key}||[] };
}
elsif ($key eq 'MyAppend') {
- $mrg{$key} = join " ", grep defined, $base->{$key},
$add->{$key};
+ $mrg{$key} = join " ", grep defined, $base->{$key},
+ $add->{$key};
}
else {
# override mode
@@ -807,10 +885,60 @@
return bless \%mrg, ref($base);
}
-
1;
__END__
+It's probably a good idea to specify all the attributes for the
+C<@APACHE_MODULE_COMMANDS> entries, but here for simplicity we have
+only assigned to the I<L<name|/C_name_>> directive, which is a
+must. Since all our directives take a single argument,
+C<L<Apache::TAKE1|/C_Apache__TAKE1_>>, the default
+I<L<args_how|/C_args_how_>>, is what we need. We also allow the
+directives to appear anywhere, so
+C<L<Apache::OR_ALL|/C_Apache__OR_ALL_>>, the default for
+I<L<req_override|/C_req_override_>>, is good for us as well.
+
+We use the same callback for the directives C<MyPlus>, C<MyAppend> and
+C<MyOverride>, which simply assigns the specified value to the hash
+entry with the key of the same name as the directive.
+
+The C<MyList> directive's callback stores the value in the list, a
+reference to which is stored in the hash, again using the name of the
+directive as the key. This approach is usually used when the directive
+is of type C<L<Apache::ITERATE|/C_Apache__ITERATE_>>, so you may have
+more than one value of the same kind inside a single container. But in
+our example we choose to have it of the type
+C<L<Apache::TAKE1|/C_Apache__TAKE1_>>.
+
+In both callbacks in addition to storing the value in the current
+I<directory> configuration, if the value is configured in the main
+server or the virtual host (which is when C<$parms-E<gt>path> is
+false), we also store the data in the same way in the server
+configuration object. This is done in order to be able to query the
+values assigned at the server and virtual host levels, when the
+request is made to one of the sub-resources. We will show how to
+access that information in a moment.
+
+Finally we use the same merge function for merging directory and
+server configuration objects. For the key C<MyPlus> (remember we have
+used the same key name as the name of the directive), the merging
+function performs, the obvious, summation of the ancestor's merged
+value (base) and the current resource's value (add). C<MyAppend> joins
+the values into a string, C<MyList> joins the lists and finally
+C<MyOverride> (the default) overrides the value with the current one
+if any. Notice that all four merging methods take into account that
+the values in the ancestor or the current configuration object might
+be unset, which is the case when the directive wasn't used by all
+ancestors or for the current resource.
+
+At the end of the merging, a blessed reference to the merged hash is
+returned. The reference is blessed into the same class, as the base or
+the add objects, which is C<MyApache::CustomDirectives> in our
+example. That hash is used as the merged ancestor's object for a
+sub-resource of the resource that has just undergone merging.
+
+Next we supply the following I<httpd.conf> configuration section, so
+we can demonstrate the features of this example:
PerlLoadModule MyApache::CustomDirectives
MyPlus 5
@@ -843,6 +971,37 @@
PerlResponseHandler MyApache::CustomDirectivesTest
</Location>
+C<PerlLoadModule> loads the Perl module C<MyApache::CustomDirectives>
+and then installs a new Apache module named
+C<MyApache::CustomDirectives>, using the callbacks provided by the
+Perl module. In our example functions C<SERVER_CREATE> and
+C<DIR_CREATE> aren't provided, so by default an empty hash will be
+created to represent the configuration object for the merging
+functions. If we don't provide merging functions, Apache will simply
+skip the merging. Though you must provide a callback function for each
+directive you add.
+
+After installing the new module, we add a virtual host container,
+containing two resources (which at other times called locations,
+directories, sections, etc.), one being a sub-resource of the other,
+plus one another resource which resides in the main server.
+
+We assign different values in all four containers, but the last
+one. Here we refer to the four containers as I<MainServer>, I<VHost>,
+I<Dir> and I<SubDir>, and use these names as values for all
+configuration directives, but C<MyPlus>, to make it easier understand
+the outcome of various merging methods and the merging order. In the
+last container used by C<E<lt>Location /custom_directives_testE<gt>>,
+we don't specify any directives so we can verify that all the values
+are inherited from the main server.
+
+For all three resources we are going to use the same response handler,
+which will dump the values of configuration objects that in its
+reach. As we will see that different resources will see see certain
+things identically, while others differently. So here it the handler:
+
+ #file:MyApache/CustomDirectivesTest.pm
+ #-------------------------------------
package MyApache::CustomDirectivesTest;
use strict;
@@ -886,7 +1045,9 @@
for my $sec (sort keys %secs) {
$r->print("\nSection $sec\n");
for my $k (sort keys %{ $secs{$sec}||{} }) {
- my $v = exists $secs{$sec}->{$k} ? $secs{$sec}->{$k} : 'UNSET';
+ my $v = exists $secs{$sec}->{$k}
+ ? $secs{$sec}->{$k}
+ : 'UNSET';
$v = '[' . (join ", ", map {qq{"$_"}} @$v) . ']'
if ref($v) eq 'ARRAY';
$r->printf("%-10s : %s\n", $k, $v);
@@ -899,8 +1060,18 @@
1;
__END__
+The handler is relatively simple. It retrieves the current resource
+(directory) and the server's configuration objects. If the server is a
+virtual host, it also retrieves the main server's configuration
+object. Once these objects are retrieved, we simply dump the contents
+of these objects, so we can verify that our merging worked
+correctly. Of course we nicely format the data that we print, taking a
+special care of array references, which we know is the case with the
+key I<MyList>, but we use a generic code, since Perl tells us when a
+reference is a list.
-
+It's a show time. First we issue a request to a resource residing in
+the main server:
% GET http://localhost:8002/custom_directives_test/
@@ -918,7 +1089,13 @@
MyOverride : MainServer
MyPlus : 5
+Since we didn't have any directives in that resource's configuration,
+we confirm that our merge worked correctly and the directory
+configuration object contains the same data as its ancestor, the main
+server. In this case the merge has simply inherited the values from
+its ancestor.
+The next request is for the resource residing in the virtual host:
% GET http://localhost:8081/custom_directives_test/
@@ -942,6 +1119,17 @@
MyOverride : Dir
MyPlus : 10
+That's where the real fun starts. We can see that the merge worked
+correctly in the virtual host, and so it did inside the
+C<E<lt>LocationE<gt>> resource. It's easy to see that C<MyAppend> and
+C<MyList> are correct, the same for C<MyOverride>. For C<MyPlus>, we
+have to work harder and perform some math. Inside the virtual host we
+have main(5)+vhost(2)=7, and inside the first resource
+vhost_merged(7)+resource(3)=10.
+
+So far so good, the last request is made to the sub-resource of the
+resource we have requested previously:
+
% GET http://localhost:8081/custom_directives_test/subdir/
Processing by virtual host.
@@ -964,7 +1152,12 @@
MyOverride : SubDir
MyPlus : 11
-
+No surprises here. By comparing the configuration sections and the
+outcome, it's clear that the merging is correct for most
+directives. The only harder verification is for C<MyPlus>, all we need
+to do is to add 1 to 10, which was the result we saw in the previous
+request, or to do it from scratch, summing up all the ancestors of
+this sub-resource: 5+2+3+1=11.
=head3 Merging Entries Whose Values Are References
@@ -1013,7 +1206,7 @@
((base_srv -> vhost) -> (section -> subsection))
A product of subsections merge (which happen during the request) is
-merged with the product of the server and vhost merge (which happens
+merged with the product of the server and virtual host merge (which happens
at the startup time). This change was done to improve the
configuration merging performance.
@@ -1032,7 +1225,7 @@
</Location>
The merged configuration for a request
-I<http://localhost/:8001/section/subsection> will see:
+I<http://localhost:8001/section/subsection> will see:
(5 ** 4) ** (3 ** 2) = 1.45519152283669e+25
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
