stab at UNITCHECK blocks

Message-ID: <20061019120412.GA12290@the.earth.li>

p4raw-id: //depot/perl@29053

1 files changed, 36 insertions, 22 deletions

diff --git a/pod/perlmod.pod b/pod/perlmod.pod
index 513460943d..240630c685 100644
--- a/pod/perlmod.pod
+++ b/pod/perlmod.pod
@@ -258,12 +258,12 @@ rather than:
 This also has implications for the use of the SUPER:: qualifier
 (see L<perlobj>).
 
-=head2 BEGIN, CHECK, INIT and END
-X<BEGIN> X<CHECK> X<INIT> X<END>
+=head2 BEGIN, UNITCHECK, CHECK, INIT and END
+X<BEGIN> X<UNITCHECK> X<CHECK> X<INIT> X<END>
 
-Four specially named code blocks are executed at the beginning and at the end
-of a running Perl program.  These are the C<BEGIN>, C<CHECK>, C<INIT>, and
-C<END> blocks.
+Five specially named code blocks are executed at the beginning and at
+the end of a running Perl program.  These are the C<BEGIN>,
+C<UNITCHECK>, C<CHECK>, C<INIT>, and C<END> blocks.
 
 These code blocks can be prefixed with C<sub> to give the appearance of a
 subroutine (although this is not considered good style).  One should note
@@ -282,9 +282,10 @@ and such from other files in time to be visible to the rest of the compile
 and run time.  Once a C<BEGIN> has run, it is immediately undefined and any
 code it used is returned to Perl's memory pool.
 
-It should be noted that C<BEGIN> code blocks B<are> executed inside string
-C<eval()>'s.  The C<CHECK> and C<INIT> code blocks are B<not> executed inside
-a string eval, which e.g. can be a problem in a mod_perl environment.
+It should be noted that C<BEGIN> and C<UNITCHECK> code blocks B<are>
+executed inside string C<eval()>'s.  The C<CHECK> and C<INIT> code
+blocks are B<not> executed inside a string eval, which e.g. can be a
+problem in a mod_perl environment.
 
 An C<END> code block is executed as late as possible, that is, after
 perl has finished running the program and just before the interpreter
@@ -307,8 +308,15 @@ value of the program.  Beware of changing C<$?> by accident (e.g. by
 running something via C<system>).
 X<$?>
 
-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.
+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.
+
+C<UNITCHECK> blocks are run just after the unit which defined them has
+been compiled.  The main program file and each module it loads are
+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<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
@@ -331,26 +339,32 @@ The B<begincheck> program makes it all clear, eventually:
 
   # begincheck
 
-  print         " 8. Ordinary code runs at runtime.\n";
+  print         "10. Ordinary code runs at runtime.\n";
 
-  END { print   "14.   So this is the end of the tale.\n" }
-  INIT { print  " 5. INIT blocks run FIFO just before runtime.\n" }
-  CHECK { print " 4.   So this is the fourth line.\n" }
+  END { print   "16.   So this is the end of the tale.\n" }
+  INIT { print  " 7. INIT blocks run FIFO just before runtime.\n" }
+  UNITCHECK {
+    print       " 4.   And therefore before any CHECK blocks.\n"
+  }
+  CHECK { print " 6.   So this is the sixth line.\n" }
 
-  print         " 9.   It runs in order, of course.\n";
+  print         "11.   It runs in order, of course.\n";
 
   BEGIN { print " 1. BEGIN blocks run FIFO during compilation.\n" }
-  END { print   "13.   Read perlmod for the rest of the story.\n" }
-  CHECK { print " 3. CHECK blocks run LIFO at compilation's end.\n" }
-  INIT { print  " 6.   Run this again, using Perl's -c switch.\n" }
+  END { print   "15.   Read perlmod for the rest of the story.\n" }
+  CHECK { print " 5. CHECK blocks run LIFO after all compilation.\n" }
+  INIT { print  " 8.   Run this again, using Perl's -c switch.\n" }
 
-  print         "10.   This is anti-obfuscated code.\n";
+  print         "12.   This is anti-obfuscated code.\n";
 
-  END { print   "12. END blocks run LIFO at quitting time.\n" }
+  END { print   "14. END blocks run LIFO at quitting time.\n" }
   BEGIN { print " 2.   So this line comes out second.\n" }
-  INIT { print  " 7.   You'll see the difference right away.\n" }
+  UNITCHECK {
+   print " 3. UNITCHECK blocks run LIFO after each file is compiled.\n"
+  }
+  INIT { print  " 9.   You'll see the difference right away.\n" }
 
-  print         "11.   It merely _looks_ like it should be confusing.\n";
+  print         "13.   It merely _looks_ like it should be confusing.\n";
 
   __END__