Integrate with Sarathy.

[p5sagit/p5-mst-13.2.git] / pod / perlmod.pod

diff --git a/pod/perlmod.pod b/pod/perlmod.pod
index de94e71..0031d6e 100644 (file)
--- a/pod/perlmod.pod
+++ b/pod/perlmod.pod
@@ -165,9 +165,54 @@ This prints
 The C<*foo{THING}> notation can also be used to obtain references to the
 individual elements of *foo, see L<perlref>.
 
+Subroutine definitions (and declarations, for that matter) need
+not necessarily be situated in the package whose symbol table they
+occupy.  You can define a subroutine outside its package by
+explicitly qualifying the name of the subroutine:
+
+    package main;
+    sub Some_package::foo { ... }   # &foo defined in Some_package
+
+This is just a shorthand for a typeglob assignment at compile time:
+
+    BEGIN { *Some_package::foo = sub { ... } }
+
+and is I<not> the same as writing:
+
+    {
+       package Some_package;
+       sub foo { ... }
+    }
+
+In the first two versions, the body of the subroutine is
+lexically in the main package, I<not> in Some_package. So
+something like this:
+
+    package main;
+
+    $Some_package::name = "fred";
+    $main::name = "barney";
+
+    sub Some_package::foo {
+       print "in ", __PACKAGE__, ": \$name is '$name'\n";
+    }
+
+    Some_package::foo();
+
+prints:
+
+    in main: $name is 'barney'
+
+rather than:
+
+    in Some_package: $name is 'fred'
+
+This also has implications for the use of the SUPER:: qualifier
+(see L<perlobj>).
+
 =head2 Package Constructors and Destructors
 
-There are two special subroutine definitions that function as package
+Three special subroutines act as package
 constructors and destructors.  These are the C<BEGIN>, C<INIT>, and
 C<END> routines.  The C<sub> is optional for these routines.
 
@@ -180,6 +225,11 @@ files in time to be visible to the rest of the file.  Once a C<BEGIN>
 has run, it is immediately undefined and any code it used is returned to
 Perl's memory pool.  This means you can't ever explicitly call a C<BEGIN>.
 
+Similar to C<BEGIN> blocks, C<INIT> blocks are run just before the
+Perl runtime begins execution.  For example, the code generators
+documented in L<perlcc> make use of C<INIT> blocks to initialize
+and resolve pointers to XSUBs.
+
 An C<END> subroutine is executed as late as possible, that is, when
 the interpreter is being exited, even if it is exiting as a result of
 a die() function.  (But not if it's polymorphing into another program
@@ -199,11 +249,6 @@ implemented (and subject to change, since its inconvenient at best),
 both C<BEGIN> and<END> blocks are run when you use the B<-c> switch
 for a compile-only syntax check, although your main code is not.
 
-Similar to C<BEGIN> blocks, C<INIT> blocks are run just before the
-Perl runtime begins execution.  For example, the code generators
-documented in L<perlcc> make use of C<INIT> blocks to initialize
-and resolve pointers to XSUBs.
-
 =head2 Perl Classes
 
 There is no special class syntax in Perl, but a package may act