perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From go...@apache.org
Subject cvs commit: modperl-docs/src/docs/2.0/user/config custom.pod
Date Tue, 09 Nov 2004 05:44:12 GMT
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__, \@directives);
  +  
     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__, \@directives);
     
     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__, \@directives);
  +  
     # 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__, \@directives);
     
     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__, \@directives);
  +
   =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__, \@directives);
     ...
     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__, \@directives);
     ...
     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__, \@directives);
     
     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: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message