perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ran...@apache.org
Subject svn commit: r159841 - in perl/modperl/docs/trunk/src/docs/2.0/devel/core: coding_style.pod explained.pod
Date Sat, 02 Apr 2005 22:53:43 GMT
Author: randyk
Date: Sat Apr  2 14:53:42 2005
New Revision: 159841

URL: http://svn.apache.org/viewcvs?view=rev&rev=159841
Log:
s/Apache/Apache2/

Modified:
    perl/modperl/docs/trunk/src/docs/2.0/devel/core/coding_style.pod
    perl/modperl/docs/trunk/src/docs/2.0/devel/core/explained.pod

Modified: perl/modperl/docs/trunk/src/docs/2.0/devel/core/coding_style.pod
URL: http://svn.apache.org/viewcvs/perl/modperl/docs/trunk/src/docs/2.0/devel/core/coding_style.pod?view=diff&r1=159840&r2=159841
==============================================================================
--- perl/modperl/docs/trunk/src/docs/2.0/devel/core/coding_style.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/devel/core/coding_style.pod Sat Apr  2 14:53:42 2005
@@ -221,7 +221,7 @@
 
   use IO::File ();
 
-(explain how to use Apache::Status to find imported/exported
+(explain how to use Apache2::Status to find imported/exported
 functions)
 
 =back

Modified: perl/modperl/docs/trunk/src/docs/2.0/devel/core/explained.pod
URL: http://svn.apache.org/viewcvs/perl/modperl/docs/trunk/src/docs/2.0/devel/core/explained.pod?view=diff&r1=159840&r2=159841
==============================================================================
--- perl/modperl/docs/trunk/src/docs/2.0/devel/core/explained.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/devel/core/explained.pod Sat Apr  2 14:53:42 2005
@@ -13,7 +13,7 @@
 In its pristine state the project is comprised of the following
 directories and files residing at the root directory of the project:
 
-  Apache-Test/      - test kit for mod_perl and Apache::* modules
+  Apache-Test/      - test kit for mod_perl and Apache2::* modules
   ModPerl-Registry/ - ModPerl::Registry sub-project
   build/            - utilities used during project build
   docs/             - documentation
@@ -50,20 +50,20 @@
 
 =head1 Directory xs/
 
-  Apache/                 - Apache specific XS code
-  APR/                    - APR specific XS code
-  ModPerl/                - ModPerl specific XS code
-  maps/                   - 
-  tables/                 - 
-  Makefile.PL             - 
-  modperl_xs_sv_convert.h - 
-  modperl_xs_typedefs.h   - 
-  modperl_xs_util.h       - 
-  typemap                 - 
+  Apache2/                 - Apache specific XS code
+  APR/                     - APR specific XS code
+  ModPerl/                 - ModPerl specific XS code
+  maps/                    - 
+  tables/                  - 
+  Makefile.PL              - 
+  modperl_xs_sv_convert.h  - 
+  modperl_xs_typedefs.h    - 
+  modperl_xs_util.h        - 
+  typemap                  - 
 
-=head2 xs/Apache, xs/APR and xs/ModPerl
+=head2 xs/Apache2, xs/APR and xs/ModPerl
 
-The I<xs/Apache>, I<xs/APR> and I<xs/ModPerl> directories include I<.h>
files which
+The I<xs/Apache2>, I<xs/APR> and I<xs/ModPerl> directories include I<.h>
files which
 have C and XS code in them. They all have the I<.h> extension because
 they are always C<#include-d>, never compiled into their own object
 file.  and only the file that C<#include-s> an I<.h> file from these
@@ -110,8 +110,8 @@
 
 If you need to skip certain unwanted C defines from being picked by
 the source scanning you can add them to the array
-C<$Apache::ParseSource::defines_unwanted> in
-I<lib/Apache/ParseSource.pm>.
+C<$Apache2::ParseSource::defines_unwanted> in
+I<lib/Apache2/ParseSource.pm>.
 
 Notice that I<source_scan> target is normally not run during the
 project build process, since the source scanning is not stable yet,
@@ -164,15 +164,15 @@
 =item * C<MODULE>
 
 the module name where the functions should be put.  e.g. C<MODULE
-Apache::Connection> will place the functions into 
-I<WrapXS/Apache/Connection.{pm,xs}>.
+Apache2::Connection> will place the functions into 
+I<WrapXS/Apache2/Connection.{pm,xs}>.
 
 =item * C<PACKAGE>
 
 the package name functions belong to, defaults to C<MODULE>.  The
 value of I<guess> indicates that package name should be guessed based
 on first argument found that maps to a Perl class.  If the value is
-not defined and the function's name starts with I<ap_> the C<Apache>
+not defined and the function's name starts with I<ap_> the C<Apache2>
 package will be used, if it starts with I<apr_> then the C<APR>
 package is used.
 
@@ -245,7 +245,7 @@
 details see: C<%ModPerl::MapUtil::disabled_map>.
 
 The return type can be specified before the C function name. It
-defaults to I<return_type> in C<{Apache,ModPerl}::FunctionTable>.
+defaults to I<return_type> in C<{Apache2,ModPerl}::FunctionTable>.
 
 META: DEFINE nuances
 
@@ -260,7 +260,7 @@
 =item * Argspec
 
 The argspec defaults to arguments in
-C<{Apache,ModPerl}::FunctionTable>.  Argument types can be specified
+C<{Apache2,ModPerl}::FunctionTable>.  Argument types can be specified
 to override those in the C<FunctionTable>.  Default values can be
 specified, e.g. C<arg=default_value>. Argspec of C<...> indicates
 I<passthru>, calling the function with C<(aTHX_ I32 items, SP **sp, SV
@@ -395,19 +395,19 @@
 about to develop, so refer to this code to see how the functions are
 invoked from Perl and what is returned:
 
-  file:t/response/TestApache/coredemo.pm
+  file:t/response/TestApache2/coredemo.pm
   ----------------------------------------
-  package TestApache::coredemo;
+  package TestApache2::coredemo;
   
   use strict;
   use warnings FATAL => 'all';
   
-  use Apache::Const -compile => 'OK';
+  use Apache2::Const -compile => 'OK';
   
   use Apache::Test;
   use Apache::TestUtil;
   
-  use Apache::CoreDemo;
+  use Apache2::CoreDemo;
   
   sub handler {
       my $r = shift;
@@ -418,27 +418,27 @@
       my $b = 3;
       my ($add, $subst);
   
-      $add = Apache::CoreDemo::print($a, $b);
+      $add = Apache2::CoreDemo::print($a, $b);
       t_debug "print";
       ok !$add;
   
-      $add = Apache::CoreDemo::add($a, $b);
+      $add = Apache2::CoreDemo::add($a, $b);
       ok t_cmp($a + $b, $add, "add");
   
-      $add = Apache::CoreDemo::add_sv($a, $b);
+      $add = Apache2::CoreDemo::add_sv($a, $b);
       ok t_cmp($a + $b, $add, "add: return sv");
   
-      $add = Apache::CoreDemo::add_sv_sv($a, $b);
+      $add = Apache2::CoreDemo::add_sv_sv($a, $b);
       ok t_cmp($a + $b, $add, "add: pass/return svs");
   
-      ($add, $subst) = @{ Apache::CoreDemo::add_subst($a, $b) };
+      ($add, $subst) = @{ Apache2::CoreDemo::add_subst($a, $b) };
       ok t_cmp($a + $b, $add,   "add_subst: add");
       ok t_cmp($a - $b, $subst, "add_subst: subst");
   
-      $subst = Apache::CoreDemo::subst_sp($a, $b);
+      $subst = Apache2::CoreDemo::subst_sp($a, $b);
       ok t_cmp($a - $b, $subst, "subst via SP");
   
-      Apache::OK;
+      Apache2::OK;
   }
   
   1;
@@ -446,18 +446,18 @@
 The first case is the simplest: pass two integer arguments, print
 these to the STDERR stream and return nothing:
 
-  file:xs/Apache/CoreDemo/Apache__CoreDemo.h
+  file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
   ----------------------------------------------
   static MP_INLINE
-  void mpxs_Apache__CoreDemo_print(int a, int b)
+  void mpxs_Apache2__CoreDemo_print(int a, int b)
   {
       fprintf(stderr, "%d, %d\n", a, b);
   }
 
   file:xs/maps/modperl_functions.map
   ----------------------------------
-  MODULE=Apache::CoreDemo
-   mpxs_Apache__CoreDemo_print
+  MODULE=Apache2::CoreDemo
+   mpxs_Apache2__CoreDemo_print
 
 Now let's say that the I<b> argument is optional and in case it wasn't
 provided, we want to use a default value, e.g. 0. In that case we
@@ -465,8 +465,8 @@
 
   file:xs/maps/modperl_functions.map
   ----------------------------------
-  MODULE=Apache::CoreDemo
-   mpxs_Apache__CoreDemo_print | | a, b=0
+  MODULE=Apache2::CoreDemo
+   mpxs_Apache2__CoreDemo_print | | a, b=0
 
 In the previous example, we didn't list the arguments in the map file
 since they were automatically retrieved from the source code. In this
@@ -476,40 +476,40 @@
 
 You may add an extra test that test teh default value assignment:
 
-      $add = Apache::CoreDemo::add($a);
+      $add = Apache2::CoreDemo::add($a);
       ok t_cmp($a + 0, $add, "add (b=0 default)");
 
 The second case: pass two integer arguments and return their sum:
 
-  file:xs/Apache/CoreDemo/Apache__CoreDemo.h
+  file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
   ----------------------------------------------
   static MP_INLINE
-  int mpxs_Apache__CoreDemo_add(int a, int b)
+  int mpxs_Apache2__CoreDemo_add(int a, int b)
   {
       return a + b;
   }
 
   file:xs/maps/modperl_functions.map
   ----------------------------------
-  MODULE=Apache::CoreDemo
-   mpxs_Apache__CoreDemo_add
+  MODULE=Apache2::CoreDemo
+   mpxs_Apache2__CoreDemo_add
 
 The third case is similar to the previous one, but we return the sum
 as as a Perl scalar. Though in C we say SV*, in the Perl space we will
 get a normal scalar:
 
-  file:xs/Apache/CoreDemo/Apache__CoreDemo.h
+  file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
   ----------------------------------------------
   static MP_INLINE
-  SV *mpxs_Apache__CoreDemo_add_sv(pTHX_ int a, int b)
+  SV *mpxs_Apache2__CoreDemo_add_sv(pTHX_ int a, int b)
   {
       return newSViv(a + b);
   }
 
   file:xs/maps/modperl_functions.map
   ----------------------------------
-  MODULE=Apache::CoreDemo
-   mpxs_Apache__CoreDemo_add_sv
+  MODULE=Apache2::CoreDemo
+   mpxs_Apache2__CoreDemo_add_sv
 
 In the second example the XSUB function was converting the returned
 I<int> value to a Perl scalar behind the scenes. In this example we
@@ -523,10 +523,10 @@
 argument list to the corresponding C variables, using the typemap
 definitions.
 
-  file:xs/Apache/CoreDemo/Apache__CoreDemo.h
+  file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
   ----------------------------------------------
   static MP_INLINE
-  SV *mpxs_Apache__CoreDemo_add_sv_sv(pTHX_ SV *a_sv, SV *b_sv)
+  SV *mpxs_Apache2__CoreDemo_add_sv_sv(pTHX_ SV *a_sv, SV *b_sv)
   {
       int a = (int)SvIV(a_sv);
       int b = (int)SvIV(b_sv);
@@ -536,8 +536,8 @@
 
   file:xs/maps/modperl_functions.map
   ----------------------------------
-  MODULE=Apache::CoreDemo
-   mpxs_Apache__CoreDemo_add_sv_sv
+  MODULE=Apache2::CoreDemo
+   mpxs_Apache2__CoreDemo_add_sv_sv
 
 So this example is the same simple case of addition, though we
 manually convert the Perl variables to C variables, perform the
@@ -549,10 +549,10 @@
 function returns. The fifth case demonstrates a function that returns
 the result of addition and substruction operations on its arguments:
 
-  file:xs/Apache/CoreDemo/Apache__CoreDemo.h
+  file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
   ----------------------------------------------
   static MP_INLINE
-  SV *mpxs_Apache__CoreDemo_add_subst(pTHX_ int a, int b)
+  SV *mpxs_Apache2__CoreDemo_add_subst(pTHX_ int a, int b)
   {
       AV *av = newAV();
   
@@ -564,18 +564,18 @@
 
   file:xs/maps/modperl_functions.map
   ----------------------------------
-  MODULE=Apache::CoreDemo
-   mpxs_Apache__CoreDemo_add_subst
+  MODULE=Apache2::CoreDemo
+   mpxs_Apache2__CoreDemo_add_subst
 
 If you look at the corresponding testing code:
 
-      ($add, $subst) = @{ Apache::CoreDemo::add_subst($a, $b) };
+      ($add, $subst) = @{ Apache2::CoreDemo::add_subst($a, $b) };
       ok t_cmp($a + $b, $add,   "add_subst: add");
       ok t_cmp($a - $b, $subst, "add_subst: subst");
 
 you can see that this technique comes at a price of needing to
 dereference the return value to turn it into a list. The actual code
-is very similar to the C<Apache::CoreDemo::add_sv> function which
+is very similar to the C<Apache2::CoreDemo::add_sv> function which
 was doing only the addition operation and returning a Perl
 scalar. Here we perform the addition and the substraction operation
 and push the two results into a previously created I<AV*> data
@@ -588,10 +588,10 @@
 notice that we still know that we are returning at compile time (zero
 or one arguments), I<int> in this example:
 
-  file:xs/Apache/CoreDemo/Apache__CoreDemo.h
+  file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
   ----------------------------------------------
   static MP_INLINE
-  int mpxs_Apache__CoreDemo_subst_sp(pTHX_ I32 items, SV **MARK, SV **SP)
+  int mpxs_Apache2__CoreDemo_subst_sp(pTHX_ I32 items, SV **MARK, SV **SP)
   {
       int a, b;
   
@@ -607,8 +607,8 @@
 
   file:xs/maps/modperl_functions.map
   ----------------------------------
-  MODULE=Apache::CoreDemo
-   mpxs_Apache__CoreDemo_subst_sp | | ...
+  MODULE=Apache2::CoreDemo
+   mpxs_Apache2__CoreDemo_subst_sp | | ...
 
 In the map file we use a special token C<...> which tells the XSUB
 constructor to pass C<items>, C<MARK> and C<SP> arguments to the
@@ -647,19 +647,19 @@
 one return value--something that C cannot handle via its return
 mechanism.
 
-Let's rewrite the function C<mpxs_Apache__CoreDemo_add_subst> from
+Let's rewrite the function C<mpxs_Apache2__CoreDemo_add_subst> from
 the earlier section to return two results instead of a reference to a
 list:
 
-  file:xs/Apache/CoreDemo/Apache__CoreDemo.h
+  file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
   ----------------------------------------------
-  static XS(MPXS_Apache__CoreDemo_add_subst_sp)
+  static XS(MPXS_Apache2__CoreDemo_add_subst_sp)
   {
       dXSARGS;
       int a, b;
       
       if (items != 2) {
-          Perl_croak(aTHX_ "usage: Apache::CoreDemo::add_subst_sp($a, $b)");
+          Perl_croak(aTHX_ "usage: Apache2::CoreDemo::add_subst_sp($a, $b)");
       }
       a = mp_xs_sv2_int(ST(0));
       b = mp_xs_sv2_int(ST(1));
@@ -683,8 +683,8 @@
 
   file:xs/maps/modperl_functions.map
   ----------------------------------
-  MODULE=Apache::CoreDemo
-  DEFINE_add_subst_sp | MPXS_Apache__CoreDemo_add_subst_sp | ...
+  MODULE=Apache2::CoreDemo
+  DEFINE_add_subst_sp | MPXS_Apache2__CoreDemo_add_subst_sp | ...
 
 The C<mpxs_> functions declare in the third column the arguments that
 they expect to receive (and optionally the default values). The
@@ -698,7 +698,7 @@
 documentation the Perl side arguments are listed. For example you can
 say:
 
-  DEFINE_add_subst_sp | MPXS_Apache__CoreDemo_add_subst_sp | x, y
+  DEFINE_add_subst_sp | MPXS_Apache2__CoreDemo_add_subst_sp | x, y
 
 In this function we manually manipulate the stack to retrieve the
 arguments passed on the Perl side and put the results back onto the
@@ -772,7 +772,7 @@
 
 Finally we test the function in the list and scalar contexts:
 
-  file:t/response/TestApache/coredemo.pm
+  file:t/response/TestApache2/coredemo.pm
   ----------------------------------------
   ...
   my $a = 7;
@@ -780,12 +780,12 @@
   my ($add, $subst);
   
   # list context
-  ($add, $subst) = Apache::CoreDemo::add_subst_sp($a, $b);
+  ($add, $subst) = Apache2::CoreDemo::add_subst_sp($a, $b);
   ok t_cmp($a + $b, $add,   "add_subst_sp list context: add");
   ok t_cmp($a - $b, $subst, "add_subst_sp list context: subst");
   
   # scalar context
-  $add = Apache::CoreDemo::add_subst_sp($a, $b);
+  $add = Apache2::CoreDemo::add_subst_sp($a, $b);
   ok t_cmp($a + $b, $add,   "add_subs_spt scalar context: add");
   ...
 
@@ -795,18 +795,18 @@
 interface for. For example let's take a simple macro which performs
 the power of function:
 
-  file:xs/Apache/CoreDemo/Apache__CoreDemo.h
+  file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
   ----------------------------------------------
-  #define mpxs_Apache__CoreDemo_power(x, y) pow(x, y)
+  #define mpxs_Apache2__CoreDemo_power(x, y) pow(x, y)
 
 To create the XS glue code we use the following entry in the map file:
 
   file:xs/maps/modperl_functions.map
   ----------------------------------
-  MODULE=Apache::CoreDemo
+  MODULE=Apache2::CoreDemo
   double:DEFINE_power | | double:x, double:y
 
-This works very similar to the C<MPXS_Apache__CoreDemo_add_subst_sp>
+This works very similar to the C<MPXS_Apache2__CoreDemo_add_subst_sp>
 function presented earlier. But since this is a macro the XS wrapper
 needs to know the types of the arguments and the return type, so these
 are added. The return type is added just before the function name and
@@ -816,12 +816,12 @@
 
 And of course finally we need to test that the function works in Perl:
 
-  file:t/response/TestApache/coredemo.pm
+  file:t/response/TestApache2/coredemo.pm
   ----------------------------------------
   ...
   my $a = 7;
   my $b = 3;
-  my $power = Apache::CoreDemo::power($a, $b);
+  my $power = Apache2::CoreDemo::power($a, $b);
   ok t_cmp($a ** $b, $power, "power macro");
   ...
 
@@ -835,15 +835,15 @@
 
 The map entry will look like:
 
-  MODULE=Apache::CoreDemo
+  MODULE=Apache2::CoreDemo
   char *:DEFINE_foo | | int:bar
 
 But there is no way to pass C<aTHX_> since this is a macro and it's an
 empty string with non-threaded Perls. Another macro comes to help:
 
-  file:xs/Apache/CoreDemo/Apache__CoreDemo.h
+  file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
   ----------------------------------------------
-  #define mpxs_Apache__CoreDemo_foo(x, y) foo(aTHX_ x, y)
+  #define mpxs_Apache2__CoreDemo_foo(x, y) foo(aTHX_ x, y)
 
 
 =head1 Wrappers for modperl_, apr_ and ap_ APIs
@@ -851,7 +851,7 @@
 If you already have a C function whose name starts from I<modperl_>,
 I<apr_> or I<ap_> and you want to do something before calling the real
 C function, you can write a XS wrapper using the same method as in the
-L<MPXS_Apache__CoreDemo_add_subst_sp
+L<MPXS_Apache2__CoreDemo_add_subst_sp
 |/Functions_Returning_Variable_Number_of_Values>. The only difference
 is that it'll be clearly seen in the map file that this is a wrapper
 for an existing C API.
@@ -889,13 +889,13 @@
 
   file:xs/maps/apr_functions.map
   ----------------------------------
-  MODULE=Apache::CoreDemo
+  MODULE=Apache2::CoreDemo
   modperl_power | MPXS_ | x, y | mypower
 
-and the Perl function will be called C<Apache::CoreDemo::mypower>.
+and the Perl function will be called C<Apache2::CoreDemo::mypower>.
 
 The C<MPXS_> wrapper's implementation is similar to
-L<MPXS_Apache__CoreDemo_add_subst_sp
+L<MPXS_Apache2__CoreDemo_add_subst_sp
 |/Functions_Returning_Variable_Number_of_Values>.
 
 =head1 MP_INLINE vs C Macros vs Normal Functions
@@ -1058,7 +1058,7 @@
 
 If you need to do some special handling while converting from C to
 Perl and back, you need to add the conversion functions to the
-I<xs/typemap> file. For example the C<Apache::RequestRec> objects need
+I<xs/typemap> file. For example the C<Apache2::RequestRec> objects need
 special handling, so you can see the special C<INPUT> and C<OUTPUT>
 typemappings for the corresponding C<T_APACHEOBJ> object type.
 
@@ -1093,7 +1093,7 @@
 =head2 Importing Constants and Enums into Perl API
 
 To I<import> httpd and APR constants and enums into Perl API, edit
-I<lib/Apache/ParseSource.pm>. To add a new type of C<DEFINE> constants
+I<lib/Apache2/ParseSource.pm>. To add a new type of C<DEFINE> constants
 adjust the C<%defines_wanted> variable, for C<enums> modify
 C<%enums_wanted>.
 
@@ -1124,7 +1124,7 @@
 C</_(t|e)$/>. For example I<ap_conn_keepalive_e> needs to be added as:
 
   my %enums_wanted = (
-      Apache => { map { $_, 1 } qw(conn_keepalive) },
+      Apache2 => { map { $_, 1 } qw(conn_keepalive) },
   );
 
 After adding/modifying the datastructures make sure to run C<make
@@ -1133,7 +1133,7 @@
 process. Simply grep I<xs/tables/current> for the wanted string. For
 example after adding I<apr_read_type_e> enum we can check:
 
-  % more xs/tables/current/Apache/ConstantsTable.pm
+  % more xs/tables/current/Apache2/ConstantsTable.pm
   ...
     'read_type' => [
       'APR_BLOCK_READ',



---------------------------------------------------------------------
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