add example for ${^GLOBAL_PHASE} and description to perlmod

Signed-off-by: Florian Ragwitz <rafl@debian.org>
[rafl@debian.org: Minor rewording based on input from TIMB]

diff --git a/pod/perlmod.pod b/pod/perlmod.pod
index 8679b53..9065586 100644 (file)
--- a/pod/perlmod.pod
+++ b/pod/perlmod.pod
@@ -294,6 +294,9 @@ value of the program.  Beware of changing C<$?> by accident (e.g. by
 running something via C<system>).
 X<$?>
 
+Inside of a C<END> block, the value of C<${^GLOBAL_PHASE}> will be
+C<"END">.
+
 C<UNITCHECK>, C<CHECK> and C<INIT> code blocks are useful to catch the
 transition between the compilation phase and the execution phase of
 the main program.
@@ -304,13 +307,21 @@ compilation units, as are string C<eval>s, code compiled using the
 C<(?{ })> construct in a regex, calls to C<do FILE>, C<require FILE>,
 and code after the C<-e> switch on the command line.
 
+C<BEGIN> and C<UNITCHECK> blocks are not directly related to the phase of
+the interpreter.  They can be created and executed during any phase.
+
 C<CHECK> code blocks are run just after the B<initial> Perl compile phase ends
 and before the run time begins, in LIFO order.  C<CHECK> code blocks are used
 in the Perl compiler suite to save the compiled state of the program.
 
+Inside of a C<CHECK> block, the value of C<${^GLOBAL_PHASE}> will be
+C<"CHECK">.
+
 C<INIT> blocks are run just before the Perl runtime begins execution, in
 "first in, first out" (FIFO) order.
 
+Inside of an C<INIT> block, the value of C<${^GLOBAL_PHASE}> will be C<"INIT">.
+
 The C<CHECK> and C<INIT> blocks in code compiled by C<require>, string C<do>,
 or string C<eval> will not be executed if they occur after the end of the
 main compilation phase; that can be a problem in mod_perl and other persistent

diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index d3684a1..f159832 100644 (file)
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -503,8 +503,49 @@ Not every program has to go through each of the possible phases, but
 transition from one phase to another can only happen in the order
 described in the above list.
 
-The patch also includes some basic tests, if you prefer actual working
-examples of how C<${^GLOBAL_PHASE}> behaves.
+An example of all of the phases Perl code can see:
+
+    BEGIN { print "compile-time: ${^GLOBAL_PHASE}\n" }
+
+    INIT  { print "init-time: ${^GLOBAL_PHASE}\n" }
+
+    CHECK { print "check-time: ${^GLOBAL_PHASE}\n" }
+
+    {
+        package Print::Phase;
+
+        sub new {
+            my ($class, $time) = @_;
+            return bless \$time, $class;
+        }
+
+        sub DESTROY {
+            my $self = shift;
+            print "$$self: ${^GLOBAL_PHASE}\n";
+        }
+    }
+
+    print "run-time: ${^GLOBAL_PHASE}\n";
+
+    my $runtime = Print::Phase->new(
+        "lexical variables are garbage collected before END"
+    );
+
+    END   { print "end-time: ${^GLOBAL_PHASE}\n" }
+
+    our $destruct = Print::Phase->new(
+        "package variables are garbage collected after END"
+    );
+
+This will print out
+
+    compile-time: START
+    check-time: CHECK
+    init-time: INIT
+    run-time: RUN
+    lexical variables are garbage collected before END: RUN
+    end-time: END
+    package variables are garbage collected after END: DESTRUCT
 
 This variable was added in Perl 5.13.7.