gozer 2004/11/08 21:44:12
Modified: src/docs/2.0/api/Apache CmdParms.pod Const.pod Module.pod
src/docs/2.0/user/config custom.pod
Log:
Remove magicness of PerlLoadModule and implement Apache::Module::add()
for modules that implement their own configuration directives
Revision Changes Path
1.18 +9 -5 modperl-docs/src/docs/2.0/api/Apache/CmdParms.pod
Index: CmdParms.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/CmdParms.pod,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- CmdParms.pod 13 Sep 2004 22:17:03 -0000 1.17
+++ CmdParms.pod 9 Nov 2004 05:44:12 -0000 1.18
@@ -8,15 +8,18 @@
=head1 Synopsis
use Apache::CmdParms ();
+ use Apache::Module ();
use Apache::Const -compile => qw(NOT_IN_LOCATION);
- our @APACHE_MODULE_COMMANDS = (
+ my @directives = (
{
name => 'MyDirective',
cmd_data => 'some extra data',
},
);
+ Apache::Module::add(__PACKAGE__, [EMAIL PROTECTED]);
+
sub MyDirective {
my($self, $parms, $args) = @_;
@@ -35,8 +38,8 @@
# this command's directive object
$directive = $parms->directive;
- # the extra information passed thru cmd_data in
- # @APACHE_MODULE_COMMANDS
+ # the extra information passed thru cmd_data to
+ # Apache::Module::add()
$info = $parms->info;
# which methods are <Limit>ed ?
@@ -193,7 +196,7 @@
=head2 C<info>
The extra information passed through C<cmd_data> in
-C<L<@APACHE_MODULE_COMMANDS|docs::2.0::user::config::custom/C_cmd_data_>>.
+C<L<Apache::Module::add()|docs::2.0::api::Apache::Module/C_add_>>.
$info = $parms->info;
@@ -213,7 +216,7 @@
For example here is how to pass arbitrary information to a directive
subroutine:
- our @APACHE_MODULE_COMMANDS = (
+ my @directives = (
{
name => 'MyDirective1',
func => \&MyDirective,
@@ -225,6 +228,7 @@
cmd_data => 'Two',
},
);
+ Apache::Module::add(__PACKAGE__, [EMAIL PROTECTED]);
sub MyDirective {
my($self, $parms, $args) = @_;
1.28 +1 -1 modperl-docs/src/docs/2.0/api/Apache/Const.pod
Index: Const.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/Const.pod,v
retrieving revision 1.27
retrieving revision 1.28
diff -u -r1.27 -r1.28
--- Const.pod 17 Sep 2004 19:28:15 -0000 1.27
+++ Const.pod 9 Nov 2004 05:44:12 -0000 1.28
@@ -87,7 +87,7 @@
use Apache::Const -compile => qw(:cmd_how);
The C<:cmd_how> constants group is used in
-C<L<@APACHE_MODULE_COMMANDS|docs::2.0::user::config::custom/C_args_how_>>
+C<L<Apache::Module::add()|docs::2.0::api::Apache::Module/C_add_>>
and
C<L<$cmds-E<gt>args_how|docs::2.0::api::Apache::Command/C_args_how_>>.
1.25 +39 -0 modperl-docs/src/docs/2.0/api/Apache/Module.pod
Index: Module.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/Module.pod,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -r1.24 -r1.25
--- Module.pod 17 Sep 2004 00:07:23 -0000 1.24
+++ Module.pod 9 Nov 2004 05:44:12 -0000 1.25
@@ -9,6 +9,15 @@
use Apache::Module ();
+ #Define a configuration directive
+ my @directives = (
+ {
+ name => 'MyDirective',
+ }
+ );
+
+ Apache::Module::add(__PACKAGE__, [EMAIL PROTECTED]);
+
# iterate over the whole module list
for (my $modp = Apache::Module::top_module(); $modp; $modp = $modp->next) {
my $name = $modp->name;
@@ -62,6 +71,36 @@
=head1 API
C<Apache::Module> provides the following functions and/or methods:
+
+
+
+
+
+=head2 C<add>
+
+Add a module's custom configuration directive to Apache.
+
+ Apache::Module::add($package, $cmds);
+
+=over 4
+
+=item arg1: C<$package> ( string )
+
+the package of the module to add
+
+=item arg2: C<$cmds> ( ARRAY of HASH refs )
+
+the list of configuration directives to add
+
+=item ret: no return value
+
+=item since: 1.99_18
+
+=back
+
+See also L<Apache Server Configuration Customization in
+Perl|docs::2.0::user::config::custom>.
+
1.15 +32 -12 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.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- custom.pod 14 Sep 2004 20:47:23 -0000 1.14
+++ custom.pod 9 Nov 2004 05:44:12 -0000 1.15
@@ -91,7 +91,7 @@
use Apache::CmdParms ();
use Apache::Module ();
- our @APACHE_MODULE_COMMANDS = (
+ my @directives = (
{
name => 'MyParameter',
func => __PACKAGE__ . '::MyParameter',
@@ -103,6 +103,7 @@
name => 'MyOtherParameter',
},
);
+ Apache::Module::add(__PACKAGE__, [EMAIL PROTECTED]);
sub MyParameter {
my($self, $parms, @args) = @_;
@@ -125,12 +126,16 @@
The following sections discuss this and more advanced modules in
detail.
-A minimal configuration module is comprised of two groups of elements:
+A minimal configuration module is comprised of three groups of elements:
=over
-=item * A global array C<@APACHE_MODULE_COMMANDS> for declaring the
-new directives and their behavior.
+=item * An array C<L<@directives|/C__CMDS_>> for declaring the new
+directives and their behavior.
+
+=item * A call to
+C<L<Apache::Module::add()|docs::2.0::api::Apache::Module/C_add_>> to
+register the new directives with apache.
=item * A subroutine per each new directive, which is called when the
directive is seen
@@ -139,13 +144,13 @@
-=head2 C<@APACHE_MODULE_COMMANDS>
+=head2 C<@directives>
-C<@APACHE_MODULE_COMMANDS> is a global array of hash references. Each
+C<@directives> is an array of hash references. Each
hash represents a separate new configuration directive. In our example
we had:
- our @APACHE_MODULE_COMMANDS = (
+ my @directives = (
{
name => 'MyParameter',
func => __PACKAGE__ . '::MyParameter',
@@ -169,6 +174,10 @@
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.
+It is worth noting that in previous versions of mod_perl, it was
+necessary to call this variable @APACHE_MODULE_COMMANDS. It is not
+the case anymore, and we consistently use the name @directives in
+the documentation for clarity. It can be named anything at all.
=head3 C<name>
@@ -274,7 +283,7 @@
you to store arbitrary strings for later retrieval from your
directive handler. For instance:
- our @APACHE_MODULE_COMMANDS = (
+ my @directives = (
{
name => '<Location',
# func defaults to Redirect()
@@ -313,6 +322,14 @@
chosen for a reason - this is exactly how httpd core handles these
two directives.
+=head2 Registering the new directives
+
+Once the C<L<@directives|/C__CMDS_>> array is populated, it needs to be
+registered with apache using
+C<L<Apache::Module::add()|docs::2.0::api::Apache::Module/C_add_>>
+
+ Apache::Module::add(__PACKAGE__, [EMAIL PROTECTED]);
+
=head2 Directive Scope Definition Constants
The I<L<req_override|/C_req_override_>> attribute specifies the
@@ -780,7 +797,8 @@
...
use Apache::Module ();
use Apache::CmdParms ();
- our @APACHE_MODULE_COMMANDS = (...);
+ my @directives = (...);
+ Apache::Module::add(__PACKLAGE__, [EMAIL PROTECTED]);
...
sub SERVER_CREATE {
my($class, $parms) = @_;
@@ -860,7 +878,8 @@
...
use Apache::Module ();
use Apache::CmdParms ();
- our @APACHE_MODULE_COMMANDS = (...);
+ my @directives = (...);
+ Apache::Module::add(__PACKAGE__, [EMAIL PROTECTED]);
...
sub DIR_CREATE {
my($class, $parms) = @_;
@@ -921,12 +940,13 @@
use Apache::Const -compile => qw(OK);
- our @APACHE_MODULE_COMMANDS = (
+ my @directives = (
{ name => 'MyPlus' },
{ name => 'MyList' },
{ name => 'MyAppend' },
{ name => 'MyOverride' },
);
+ Apache::Module::add(__PACKAGE__, [EMAIL PROTECTED]);
sub MyPlus { set_val('MyPlus', @_) }
sub MyAppend { set_val('MyAppend', @_) }
@@ -987,7 +1007,7 @@
__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
+C<@directives> 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
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
