X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlmod.pod;h=994c3eb5dc477cc2798425f196e3cc4b44a487af;hb=7d30b5c4c60a798b772f5d7bd3b85d21016359c7;hp=de94e71ea2dd8103fc16c4623371dbc5e8355ad2;hpb=19799a22062ef658e4ac543ea06fa9193323512a;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlmod.pod b/pod/perlmod.pod
index de94e71..994c3eb 100644
--- a/pod/perlmod.pod
+++ b/pod/perlmod.pod
@@ -165,11 +165,56 @@ 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
-constructors and destructors.  These are the C<BEGIN>, C<INIT>, and
-C<END> routines.  The C<sub> is optional for these routines.
+Four special subroutines act as package constructors and destructors.
+These are the C<BEGIN>, C<CHECK>, C<INIT>, and C<END> routines.  The
+C<sub> is optional for these routines.
 
 A C<BEGIN> subroutine is executed as soon as possible, that is, the moment
 it is completely defined, even before the rest of the containing file
@@ -180,30 +225,37 @@ 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>.
 
-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
-via C<exec>, or being blown out of the water by a signal--you have to
-trap that yourself (if you can).)  You may have multiple C<END> blocks
-within a file--they will execute in reverse order of definition; that is:
-last in, first out (LIFO).
+An C<END> subroutine is executed as late as possible, that is, after
+perl has finished running the program and just before 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 via C<exec>, or
+being blown out of the water by a signal--you have to trap that yourself
+(if you can).)  You may have multiple C<END> blocks within a file--they
+will execute in reverse order of definition; that is: last in, first
+out (LIFO).  C<END> blocks are not executed when you run perl with the
+C<-c> switch.
 
 Inside an C<END> subroutine, C<$?> contains the value that the program is
 going to pass to C<exit()>.  You can modify C<$?> to change the exit
 value of the program.  Beware of changing C<$?> by accident (e.g. by
 running something via C<system>).
 
+Similar to C<BEGIN> blocks, C<INIT> blocks are run just before the
+Perl runtime begins execution, in "first in, first out" (FIFO) order.
+For example, the code generators documented in L<perlcc> make use of
+C<INIT> blocks to initialize and resolve pointers to XSUBs.
+
+Similar to C<END> blocks, C<CHECK> blocks are run just after the
+Perl compile phase ends and before the run time begins, in
+LIFO order.  C<CHECK> blocks are again useful in the Perl compiler
+suite to save the compiled state of the program.
+
 When you use the B<-n> and B<-p> switches to Perl, C<BEGIN> and
 C<END> work just as they do in B<awk>, as a degenerate case.  As currently
 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
@@ -234,7 +286,7 @@ create a file called F<Some/Module.pm> and start with this template:
 
     BEGIN {
         use Exporter   ();
-        use vars       qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
+        our ($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
 
         # set the version for version checking
         $VERSION     = 1.00;
@@ -249,10 +301,11 @@ create a file called F<Some/Module.pm> and start with this template:
         # as well as any optionally exported functions
         @EXPORT_OK   = qw($Var1 %Hashit &func3);
     }
-    use vars      @EXPORT_OK;
+    our @EXPORT_OK;
 
     # non-exported package globals go here
-    use vars      qw(@more $stuff);
+    our @more;
+    our $stuff;
 
     # initialize package globals, first exported ones
     $Var1   = '';