Add comment to the top of most .c files explaining their purpose

p4raw-id: //depot/perl@23176

33 files changed, 451 insertions, 206 deletions

diff --git a/deb.c b/deb.c
index f268216287..21688c3fd6 100644
--- a/deb.c
+++ b/deb.c
@@ -13,6 +13,11 @@
  * have seen more than thou knowest, Gray Fool."  --Denethor
  */
 
+/*
+ * This file contains various utilites for producing debugging output
+ * (mainly related to  displaying the stack)
+ */
+
 #include "EXTERN.h"
 #define PERL_IN_DEB_C
 #include "perl.h"
diff --git a/doio.c b/doio.c
index a551d05819..70b35359c4 100644
--- a/doio.c
+++ b/doio.c
@@ -15,6 +15,11 @@
  * chattering, into calmer and more level reaches."
  */
 
+/* This file contains functions that do the actual I/O on behalf of ops.
+ * For example, pp_print() calls the do_print() function in this file for
+ * each argument needing printing.
+ */
+
 #include "EXTERN.h"
 #define PERL_IN_DOIO_C
 #include "perl.h"
diff --git a/doop.c b/doop.c
index 73b05f5780..c0c1ef4163 100644
--- a/doop.c
+++ b/doop.c
@@ -12,6 +12,11 @@
  * "'So that was the job I felt I had to do when I started,' thought Sam."
  */
 
+/* This file contains some common functions needed to carry out certain
+ * ops. For example both pp_schomp() and pp_chomp() - scalar and array
+ * chomp operations - call the function do_chomp() found in this file.
+ */
+
 #include "EXTERN.h"
 #define PERL_IN_DOOP_C
 #include "perl.h"
diff --git a/dump.c b/dump.c
index 533dd7825d..f80416b8bd 100644
--- a/dump.c
+++ b/dump.c
@@ -13,6 +13,13 @@
  * it has not been hard for me to read your mind and memory.'"
  */
 
+/* This file contains utility routines to dump the contents of SV and OP
+ * structures, as used by comand-line options like -Dt and -Dx, and
+ * by Devel::Peek.
+ *
+ * It also holds the debugging version of the  runops function.
+ */
+
 #include "EXTERN.h"
 #define PERL_IN_DUMP_C
 #include "perl.h"
diff --git a/gv.c b/gv.c
index d1ba5a378a..2c6641d6f6 100644
--- a/gv.c
+++ b/gv.c
@@ -19,6 +19,15 @@
 
 /*
 =head1 GV Functions
+
+A GV is a structure which corresponds to to a Perl typeglob, ie *foo.
+It is a structure that holds a pointer to a scalar, an array, a hash etc,
+corresponding to $foo, @foo, %foo.
+
+GVs are usually found as values in stashes (symbol table hashes) where
+Perl stores its global variables.
+
+=cut
 */
 
 #include "EXTERN.h"
diff --git a/hv.c b/hv.c
index 502856ee71..d3b86edd41 100644
--- a/hv.c
+++ b/hv.c
@@ -14,6 +14,16 @@
 
 /* 
 =head1 Hash Manipulation Functions
+
+A HV structure represents a Perl hash. It consists mainly of an array
+of pointers, each of which points to a linked list of HE structures. The
+array is indexed by the hash function of the key, so each linked list
+represents all the hash entries with the same hash value. Each HE contains
+a pointer to the actual value, plus a pointer to a HEK structure which
+holds the key and hash value.
+
+=cut
+
 */
 
 #include "EXTERN.h"
diff --git a/locale.c b/locale.c
index 6f5f016667..a73c5d68d2 100644
--- a/locale.c
+++ b/locale.c
@@ -18,6 +18,10 @@
  * nef aear, si nef aearon!
  */
 
+/* utility functions for handling locale-specific stuff like what
+ * character represents the decimal point.
+ */
+
 #include "EXTERN.h"
 #define PERL_IN_LOCALE_C
 #include "perl.h"
@@ -560,6 +564,7 @@ Perl_init_i18nl14n(pTHX_ int printwarn)
  * The real transformed data begins at offset sizeof(collationix).
  * Please see sv_collxfrm() to see how this is used.
  */
+
 char *
 Perl_mem_collxfrm(pTHX_ const char *s, STRLEN len, STRLEN *xlen)
 {
diff --git a/malloc.c b/malloc.c
index e5f58e4611..6d5635228a 100644
--- a/malloc.c
+++ b/malloc.c
@@ -6,6 +6,12 @@
  * "'The Chamber of Records,' said Gimli. 'I guess that is where we now stand.'"
  */
 
+/* This file contains Perl's own implementation of the malloc library.
+ * It is used if Configure decides that, on your platform, Perl's
+ * version is better than the OS's, or if you give Configure the
+ * -Dusemymalloc command-line option.
+ */
+
 /*
   Here are some notes on configuring Perl's malloc.  (For non-perl
   usage see below.)
diff --git a/mg.c b/mg.c
index 0feb7daf8c..ec9817fd5e 100644
--- a/mg.c
+++ b/mg.c
@@ -15,6 +15,24 @@
 
 /*
 =head1 Magical Functions
+
+"Magic" is special data attached to SV structures in order to give them
+"magical" properties.  When any Perl code tries to read from, or assign to,
+an SV marked as magical, it calls the 'get' or 'set' function associated
+with that SV's magic. A get is called prior to reading an SV, in order to
+give it a chance to update its interval value (get on $. writes the line
+number of the last read filehandle into to the SV's IV slot), while
+set is called after an SV has been written to, in order to allow it to make
+use of it's changed value (set on $/ copies the SV's new value to the
+PL_rs global variable).
+
+Magic is implemented as a linked list of MAGIC structures attached to the
+SV. Each MAGIC struct holds the type of the magic, a pointer to an array
+of functions that implement the get(), set(), length() etc functions,
+plus space for some flags and pointers. For example, a tied variable has
+a MAGIC structure that contains a pointer to the object associated with the
+tie.
+
 */
 
 #include "EXTERN.h"
diff --git a/miniperlmain.c b/miniperlmain.c
index 4e9e5e889e..3cc25f80f9 100644
--- a/miniperlmain.c
+++ b/miniperlmain.c
@@ -12,6 +12,15 @@
  * "The Road goes ever on and on, down from the door where it began."
  */
 
+/* This file contains the main() function for the perl interpreter.
+ * Note that miniperlmain.c contains main() for the 'miniperl' binary,
+ * while perlmain.c contains main() for the 'perl' binary.
+ *
+ * Miniperl is like perl except that does not support dynamic loading,
+ * and in fact is used to build the dynamic modules need for the 'real'
+ * perl execuable.
+ */
+
 #ifdef OEMVS
 #ifdef MYMALLOC
 /* sbrk is limited to first heap segement so make it big */
diff --git a/numeric.c b/numeric.c
index 6a0b6c353f..a6d9c90844 100644
--- a/numeric.c
+++ b/numeric.c
@@ -15,6 +15,12 @@
 
 /*
 =head1 Numeric functions
+
+This file contains all the stuff needed by perl for manipulating numeric
+values, including such things as replacements for the OS's atof() function
+
+=cut
+
 */
 
 #include "EXTERN.h"
diff --git a/op.c b/op.c
index ea714ebee9..1d9a7350d2 100644
--- a/op.c
+++ b/op.c
@@ -16,6 +16,30 @@
  * either way, as the saying is, if you follow me."  --the Gaffer
  */
 
+/* This file contains the functions that create, manipulate and optimize
+ * the OP structures that hold a compiled perl program.
+ *
+ * A Perl program is compiled into a tree of OPs. Each op contains
+ * structural pointers (eg to its siblings and the next op in the
+ * execution sequence), a pointer to the function that would execute the
+ * op, plus any data specific to that op. For example, an OP_CONST op
+ * points to the pp_const() function and to an SV containing the constant
+ * value. When pp_const() is executed, its job is to push that SV onto the
+ * stack.
+ *
+ * OPs are mainly created by the newFOO() functions, which are mainly
+ * called from the parser (in perly.y) as the code is parsed. For example
+ * the Perl code $a + $b * $c would cause the equivalent of the following
+ * to be called (oversimplifying a bit):
+ *
+ *  newBINOP(OP_ADD, flags,
+ *	newSVREF($a),
+ *	newBINOP(OP_MULTIPLY, flags, newSVREF($b), newSVREF($c))
+ *  )
+ *
+ * Note that during the build of miniperl, a temporary copy of this file
+ * is made, called opmini.c.
+ */
 
 #include "EXTERN.h"
 #define PERL_IN_OP_C
diff --git a/pad.c b/pad.c
index 8b5f86a03e..dc220f5f1b 100644
--- a/pad.c
+++ b/pad.c
@@ -22,6 +22,11 @@
 /*
 =head1 Pad Data Structures
 
+This file contains the functions that create and manipluate scratchpads,
+which are array-of-array data structures attached to a CV (ie a sub)
+and which store lexical variables and opcode temporay and per-thread
+values.
+
 =for apidoc m|AV *|CvPADLIST|CV *cv
 CV's can have CvPADLIST(cv) set to point to an AV.
 
diff --git a/perl.c b/perl.c
index 99be074547..ff0fbf7294 100644
--- a/perl.c
+++ b/perl.c
@@ -12,6 +12,12 @@
  * "A ship then new they built for him/of mithril and of elven glass" --Bilbo
  */
 
+/* This file contains the top-level functions that are used to create, use
+ * and destroy a perl interpreter, plus the functions used by XS code to
+ * call back into perl. Note that it does not contain the actual main()
+ * function of the interpreter; that can be found perlmain.c
+ */
+
 /* PSz 12 Nov 03
  * 
  * Be proud that perl(1) may proclaim:
diff --git a/perlio.c b/perlio.c
index 35a982ecc1..466bd17d5d 100644
--- a/perlio.c
+++ b/perlio.c
@@ -9,6 +9,12 @@
  * over passes, and through long dales, and across many streams.
  */
 
+/* This file contains the functions needed to implement PerlIO, which
+ * is Perl's private replacement for the C stdio library. This is used
+ * by default unless you compile with -Uuseperlio or run with
+ * PERLIO=:stdio (but don't do this unless you know what you're doing)
+ */
+
 /*
  * If we have ActivePerl-like PERL_IMPLICIT_SYS then we need a dTHX to get
  * at the dispatch tables, even when we do not need it for other reasons.
diff --git a/perly.act b/perly.act
index 9c5405eb24..5ad8ba3b87 100644
--- a/perly.act
+++ b/perly.act
@@ -1,56 +1,56 @@
 case 2:
-#line 88 "perly.y"
+#line 97 "perly.y"
     { yyval.ival = yyvsp[-1].ival; newPROG(block_end(yyvsp[-1].ival,yyvsp[0].opval)); ;}
     break;
 
   case 3:
-#line 93 "perly.y"
+#line 102 "perly.y"
     { if (PL_copline > (line_t)yyvsp[-3].ival)
 			      PL_copline = (line_t)yyvsp[-3].ival;
 			  yyval.opval = block_end(yyvsp[-2].ival, yyvsp[-1].opval); ;}
     break;
 
   case 4:
-#line 99 "perly.y"
+#line 108 "perly.y"
     { yyval.ival = block_start(TRUE); ;}
     break;
 
   case 5:
-#line 103 "perly.y"
+#line 112 "perly.y"
     {
 		    PL_expect = XSTATE; yyval.ival = block_start(TRUE);
 		;}
     break;
 
   case 6:
-#line 110 "perly.y"
+#line 119 "perly.y"
     { if (PL_copline > (line_t)yyvsp[-3].ival)
 			      PL_copline = (line_t)yyvsp[-3].ival;
 			  yyval.opval = block_end(yyvsp[-2].ival, yyvsp[-1].opval); ;}
     break;
 
   case 7:
-#line 116 "perly.y"
+#line 125 "perly.y"
     { yyval.ival = block_start(FALSE); ;}
     break;
 
   case 8:
-#line 120 "perly.y"
+#line 129 "perly.y"
     { yyval.ival = PL_savestack_ix; ;}
     break;
 
   case 9:
-#line 124 "perly.y"
+#line 133 "perly.y"
     { yyval.opval = Nullop; ;}
     break;
 
   case 10:
-#line 126 "perly.y"
+#line 135 "perly.y"
     { yyval.opval = yyvsp[-1].opval; ;}
     break;
 
   case 11:
-#line 128 "perly.y"
+#line 137 "perly.y"
     {   LEAVE_SCOPE(yyvsp[-1].ival);
 			    yyval.opval = append_list(OP_LINESEQ,
 				(LISTOP*)yyvsp[-2].opval, (LISTOP*)yyvsp[0].opval);
@@ -59,12 +59,12 @@ case 2:
     break;
 
   case 12:
-#line 137 "perly.y"
+#line 146 "perly.y"
     { yyval.opval = newSTATEOP(0, yyvsp[-1].pval, yyvsp[0].opval); ;}
     break;
 
   case 14:
-#line 140 "perly.y"
+#line 149 "perly.y"
     { if (yyvsp[-1].pval != Nullch) {
 			      yyval.opval = newSTATEOP(0, yyvsp[-1].pval, newOP(OP_NULL, 0));
 			    }
@@ -76,90 +76,90 @@ case 2:
     break;
 
   case 15:
-#line 149 "perly.y"
+#line 158 "perly.y"
     { yyval.opval = newSTATEOP(0, yyvsp[-2].pval, yyvsp[-1].opval);
 			  PL_expect = XSTATE; ;}
     break;
 
   case 16:
-#line 155 "perly.y"
+#line 164 "perly.y"
     { yyval.opval = Nullop; ;}
     break;
 
   case 17:
-#line 157 "perly.y"
+#line 166 "perly.y"
     { yyval.opval = yyvsp[0].opval; ;}
     break;
 
   case 18:
-#line 159 "perly.y"
+#line 168 "perly.y"
     { yyval.opval = newLOGOP(OP_AND, 0, yyvsp[0].opval, yyvsp[-2].opval); ;}
     break;
 
   case 19:
-#line 161 "perly.y"
+#line 170 "perly.y"
     { yyval.opval = newLOGOP(OP_OR, 0, yyvsp[0].opval, yyvsp[-2].opval); ;}
     break;
 
   case 20:
-#line 163 "perly.y"
+#line 172 "perly.y"
     { yyval.opval = newLOOPOP(OPf_PARENS, 1, scalar(yyvsp[0].opval), yyvsp[-2].opval); ;}
     break;
 
   case 21:
-#line 165 "perly.y"
+#line 174 "perly.y"
     { yyval.opval = newLOOPOP(OPf_PARENS, 1, yyvsp[0].opval, yyvsp[-2].opval);;}
     break;
 
   case 22:
-#line 167 "perly.y"
+#line 176 "perly.y"
     { yyval.opval = newFOROP(0, Nullch, (line_t)yyvsp[-1].ival,
 					Nullop, yyvsp[0].opval, yyvsp[-2].opval, Nullop); ;}
     break;
 
   case 23:
-#line 173 "perly.y"
+#line 182 "perly.y"
     { yyval.opval = Nullop; ;}
     break;
 
   case 24:
-#line 175 "perly.y"
+#line 184 "perly.y"
     { (yyvsp[0].opval)->op_flags |= OPf_PARENS; yyval.opval = scope(yyvsp[0].opval); ;}
     break;
 
   case 25:
-#line 177 "perly.y"
+#line 186 "perly.y"
     { PL_copline = (line_t)yyvsp[-5].ival;
 			    yyval.opval = newCONDOP(0, yyvsp[-3].opval, scope(yyvsp[-1].opval), yyvsp[0].opval);
 			    PL_hints |= HINT_BLOCK_SCOPE; ;}
     break;
 
   case 26:
-#line 184 "perly.y"
+#line 193 "perly.y"
     { PL_copline = (line_t)yyvsp[-6].ival;
 			    yyval.opval = block_end(yyvsp[-4].ival,
 				   newCONDOP(0, yyvsp[-3].opval, scope(yyvsp[-1].opval), yyvsp[0].opval)); ;}
     break;
 
   case 27:
-#line 188 "perly.y"
+#line 197 "perly.y"
     { PL_copline = (line_t)yyvsp[-6].ival;
 			    yyval.opval = block_end(yyvsp[-4].ival,
 				   newCONDOP(0, yyvsp[-3].opval, scope(yyvsp[-1].opval), yyvsp[0].opval)); ;}
     break;
 
   case 28:
-#line 195 "perly.y"
+#line 204 "perly.y"
     { yyval.opval = Nullop; ;}
     break;
 
   case 29:
-#line 197 "perly.y"
+#line 206 "perly.y"
     { yyval.opval = scope(yyvsp[0].opval); ;}
     break;
 
   case 30:
-#line 202 "perly.y"
+#line 211 "perly.y"
     { PL_copline = (line_t)yyvsp[-6].ival;
 			    yyval.opval = block_end(yyvsp[-4].ival,
 				   newSTATEOP(0, yyvsp[-7].pval,
@@ -168,7 +168,7 @@ case 2:
     break;
 
   case 31:
-#line 208 "perly.y"
+#line 217 "perly.y"
     { PL_copline = (line_t)yyvsp[-6].ival;
 			    yyval.opval = block_end(yyvsp[-4].ival,
 				   newSTATEOP(0, yyvsp[-7].pval,
@@ -177,26 +177,26 @@ case 2:
     break;
 
   case 32:
-#line 214 "perly.y"
+#line 223 "perly.y"
     { yyval.opval = block_end(yyvsp[-6].ival,
 				 newFOROP(0, yyvsp[-9].pval, (line_t)yyvsp[-8].ival, yyvsp[-5].opval, yyvsp[-3].opval, yyvsp[-1].opval, yyvsp[0].opval)); ;}
     break;
 
   case 33:
-#line 217 "perly.y"
+#line 226 "perly.y"
     { yyval.opval = block_end(yyvsp[-4].ival,
 				 newFOROP(0, yyvsp[-8].pval, (line_t)yyvsp[-7].ival, mod(yyvsp[-6].opval, OP_ENTERLOOP),
 					  yyvsp[-3].opval, yyvsp[-1].opval, yyvsp[0].opval)); ;}
     break;
 
   case 34:
-#line 221 "perly.y"
+#line 230 "perly.y"
     { yyval.opval = block_end(yyvsp[-4].ival,
 				 newFOROP(0, yyvsp[-7].pval, (line_t)yyvsp[-6].ival, Nullop, yyvsp[-3].opval, yyvsp[-1].opval, yyvsp[0].opval)); ;}
     break;
 
   case 35:
-#line 225 "perly.y"
+#line 234 "perly.y"
     { OP *forop;
 			  PL_copline = (line_t)yyvsp[-9].ival;
 			  forop = newSTATEOP(0, yyvsp[-10].pval,
@@ -214,119 +214,119 @@ case 2:
     break;
 
   case 36:
-#line 240 "perly.y"
+#line 249 "perly.y"
     { yyval.opval = newSTATEOP(0, yyvsp[-2].pval,
 				 newWHILEOP(0, 1, (LOOP*)Nullop,
 					    NOLINE, Nullop, yyvsp[-1].opval, yyvsp[0].opval)); ;}
     break;
 
   case 37:
-#line 247 "perly.y"
+#line 256 "perly.y"
     { yyval.opval = Nullop; ;}
     break;
 
   case 39:
-#line 253 "perly.y"
+#line 262 "perly.y"
     { (void)scan_num("1", &yylval); yyval.opval = yylval.opval; ;}
     break;
 
   case 41:
-#line 259 "perly.y"
+#line 268 "perly.y"
     { yyval.opval = invert(scalar(yyvsp[0].opval)); ;}
     break;
 
   case 42:
-#line 264 "perly.y"
+#line 273 "perly.y"
     { yyval.opval = yyvsp[0].opval; intro_my(); ;}
     break;
 
   case 43:
-#line 268 "perly.y"
+#line 277 "perly.y"
     { yyval.opval = yyvsp[0].opval; intro_my(); ;}
     break;
 
   case 44:
-#line 272 "perly.y"
+#line 281 "perly.y"
     { yyval.opval = yyvsp[0].opval; intro_my(); ;}
     break;
 
   case 45:
-#line 276 "perly.y"
+#line 285 "perly.y"
     { yyval.opval = yyvsp[0].opval; intro_my(); ;}
     break;
 
   case 46:
-#line 281 "perly.y"
+#line 290 "perly.y"
     { yyval.pval = Nullch; ;}
     break;
 
   case 48:
-#line 287 "perly.y"
+#line 296 "perly.y"
     { yyval.ival = 0; ;}
     break;
 
   case 49:
-#line 289 "perly.y"
+#line 298 "perly.y"
     { yyval.ival = 0; ;}
     break;
 
   case 50:
-#line 291 "perly.y"
+#line 300 "perly.y"
     { yyval.ival = 0; ;}
     break;
 
   case 51:
-#line 293 "perly.y"
+#line 302 "perly.y"
     { yyval.ival = 0; ;}
     break;
 
   case 52:
-#line 295 "perly.y"
+#line 304 "perly.y"
     { yyval.ival = 0; ;}
     break;
 
   case 53:
-#line 299 "perly.y"
+#line 308 "perly.y"
     { newFORM(yyvsp[-2].ival, yyvsp[-1].opval, yyvsp[0].opval); ;}
     break;
 
   case 54:
-#line 302 "perly.y"
+#line 311 "perly.y"
     { yyval.opval = yyvsp[0].opval; ;}
     break;
 
   case 55:
-#line 303 "perly.y"
+#line 312 "perly.y"
     { yyval.opval = Nullop; ;}
     break;
 
   case 56:
-#line 308 "perly.y"
+#line 317 "perly.y"
     { newMYSUB(yyvsp[-4].ival, yyvsp[-3].opval, yyvsp[-2].opval, yyvsp[-1].opval, yyvsp[0].opval); ;}
     break;
 
   case 57:
-#line 313 "perly.y"
+#line 322 "perly.y"
     { newATTRSUB(yyvsp[-4].ival, yyvsp[-3].opval, yyvsp[-2].opval, yyvsp[-1].opval, yyvsp[0].opval); ;}
     break;
 
   case 58:
-#line 317 "perly.y"
+#line 326 "perly.y"
     { yyval.ival = start_subparse(FALSE, 0); ;}
     break;
 
   case 59:
-#line 321 "perly.y"
+#line 330 "perly.y"
     { yyval.ival = start_subparse(FALSE, CVf_ANON); ;}
     break;
 
   case 60:
-#line 325 "perly.y"
+#line 334 "perly.y"
     { yyval.ival = start_subparse(TRUE, 0); ;}
     break;
 
   case 61:
-#line 329 "perly.y"
+#line 338 "perly.y"
     { STRLEN n_a; char *name = SvPV(((SVOP*)yyvsp[0].opval)->op_sv,n_a);
 			  if (strEQ(name, "BEGIN") || strEQ(name, "END")
 			      || strEQ(name, "INIT") || strEQ(name, "CHECK"))
@@ -335,99 +335,99 @@ case 2:
     break;
 
   case 62:
-#line 338 "perly.y"
+#line 347 "perly.y"
     { yyval.opval = Nullop; ;}
     break;
 
   case 64:
-#line 344 "perly.y"
+#line 353 "perly.y"
     { yyval.opval = Nullop; ;}
     break;
 
   case 65:
-#line 346 "perly.y"
+#line 355 "perly.y"
     { yyval.opval = yyvsp[0].opval; ;}
     break;
 
   case 66:
-#line 348 "perly.y"
+#line 357 "perly.y"
     { yyval.opval = Nullop; ;}
     break;
 
   case 67:
-#line 353 "perly.y"
+#line 362 "perly.y"
     { yyval.opval = yyvsp[0].opval; ;}
     break;
 
   case 68:
-#line 355 "perly.y"
+#line 364 "perly.y"
     { yyval.opval = Nullop; ;}
     break;
 
   case 69:
-#line 359 "perly.y"
+#line 368 "perly.y"
     { yyval.opval = yyvsp[0].opval; ;}
     break;
 
   case 70:
-#line 360 "perly.y"
+#line 369 "perly.y"
     { yyval.opval = Nullop; PL_expect = XSTATE; ;}
     break;
 
   case 71:
-#line 364 "perly.y"
+#line 373 "perly.y"
     { package(yyvsp[-1].opval); ;}
     break;
 
   case 72:
-#line 368 "perly.y"
+#line 377 "perly.y"
     { CvSPECIAL_on(PL_compcv); /* It's a BEGIN {} */ ;}
     break;
 
   case 73:
-#line 370 "perly.y"
+#line 379 "perly.y"
     { utilize(yyvsp[-6].ival, yyvsp[-5].ival, yyvsp[-3].opval, yyvsp[-2].opval, yyvsp[-1].opval); ;}
     break;
 
   case 74:
-#line 375 "perly.y"
+#line 384 "perly.y"
     { yyval.opval = newLOGOP(OP_AND, 0, yyvsp[-2].opval, yyvsp[0].opval); ;}
     break;
 
   case 75:
-#line 377 "perly.y"
+#line 386 "perly.y"
     { yyval.opval = newLOGOP(yyvsp[-1].ival, 0, yyvsp[-2].opval, yyvsp[0].opval); ;}
     break;
 
   case 76:
-#line 379 "perly.y"
+#line 388 "perly.y"
     { yyval.opval = newLOGOP(OP_DOR, 0, yyvsp[-2].opval, yyvsp[0].opval); ;}
     break;
 
   case 78:
-#line 385 "perly.y"
+#line 394 "perly.y"
     { yyval.opval = yyvsp[-1].opval; ;}
     break;
 
   case 79:
-#line 387 "perly.y"
+#line 396 "perly.y"
     { yyval.opval = append_elem(OP_LIST, yyvsp[-2].opval, yyvsp[0].opval); ;}
     break;
 
   case 81:
-#line 393 "perly.y"
+#line 402 "perly.y"
     { yyval.opval = convert(yyvsp[-2].ival, OPf_STACKED,
 				prepend_elem(OP_LIST, newGVREF(yyvsp[-2].ival,yyvsp[-1].opval), yyvsp[0].opval) ); ;}
     break;
 
   case 82:
-#line 396 "perly.y"
+#line 405 "perly.y"
     { yyval.opval = convert(yyvsp[-4].ival, OPf_STACKED,
 				prepend_elem(OP_LIST, newGVREF(yyvsp[-4].ival,yyvsp[-2].opval), yyvsp[-1].opval) ); ;}
     break;
 
   case 83:
-#line 399 "perly.y"
+#line 408 "perly.y"
     { yyval.opval = convert(OP_ENTERSUB, OPf_STACKED,
 				append_elem(OP_LIST,
 				    prepend_elem(OP_LIST, scalar(yyvsp[-5].opval), yyvsp[-1].opval),
@@ -435,14 +435,14 @@ case 2:
     break;
 
   case 84:
-#line 404 "perly.y"
+#line 413 "perly.y"
     { yyval.opval = convert(OP_ENTERSUB, OPf_STACKED,
 				append_elem(OP_LIST, scalar(yyvsp[-2].opval),
 				    newUNOP(OP_METHOD, 0, yyvsp[0].opval))); ;}
     break;
 
   case 85:
-#line 408 "perly.y"
+#line 417 "perly.y"
     { yyval.opval = convert(OP_ENTERSUB, OPf_STACKED,
 				append_elem(OP_LIST,
 				    prepend_elem(OP_LIST, yyvsp[-1].opval, yyvsp[0].opval),
@@ -450,7 +450,7 @@ case 2:
     break;
 
   case 86:
-#line 413 "perly.y"
+#line 422 "perly.y"
     { yyval.opval = convert(OP_ENTERSUB, OPf_STACKED,
 				append_elem(OP_LIST,
 				    prepend_elem(OP_LIST, yyvsp[-3].opval, yyvsp[-1].opval),
@@ -458,60 +458,60 @@ case 2:
     break;
 
   case 87:
-#line 418 "perly.y"
+#line 427 "perly.y"
     { yyval.opval = convert(yyvsp[-1].ival, 0, yyvsp[0].opval); ;}
     break;
 
   case 88:
-#line 420 "perly.y"
+#line 429 "perly.y"
     { yyval.opval = convert(yyvsp[-3].ival, 0, yyvsp[-1].opval); ;}
     break;
 
   case 89:
-#line 422 "perly.y"
+#line 431 "perly.y"
     { yyvsp[0].opval = newANONATTRSUB(yyvsp[-1].ival, 0, Nullop, yyvsp[0].opval); ;}
     break;
 
   case 90:
-#line 424 "perly.y"
+#line 433 "perly.y"
     { yyval.opval = newUNOP(OP_ENTERSUB, OPf_STACKED,
 				 append_elem(OP_LIST,
 				   prepend_elem(OP_LIST, yyvsp[-2].opval, yyvsp[0].opval), yyvsp[-4].opval)); ;}
     break;
 
   case 93:
-#line 438 "perly.y"
+#line 447 "perly.y"
     { yyval.opval = newBINOP(OP_GELEM, 0, yyvsp[-4].opval, scalar(yyvsp[-2].opval));
 			    PL_expect = XOPERATOR; ;}
     break;
 
   case 94:
-#line 441 "perly.y"
+#line 450 "perly.y"
     { yyval.opval = newBINOP(OP_AELEM, 0, oopsAV(yyvsp[-3].opval), scalar(yyvsp[-1].opval)); ;}
     break;
 
   case 95:
-#line 443 "perly.y"
+#line 452 "perly.y"
     { yyval.opval = newBINOP(OP_AELEM, 0,
 					ref(newAVREF(yyvsp[-4].opval),OP_RV2AV),
 					scalar(yyvsp[-1].opval));;}
     break;
 
   case 96:
-#line 447 "perly.y"
+#line 456 "perly.y"
     { yyval.opval = newBINOP(OP_AELEM, 0,
 					ref(newAVREF(yyvsp[-3].opval),OP_RV2AV),
 					scalar(yyvsp[-1].opval));;}
     break;
 
   case 97:
-#line 451 "perly.y"
+#line 460 "perly.y"
     { yyval.opval = newBINOP(OP_HELEM, 0, oopsHV(yyvsp[-4].opval), jmaybe(yyvsp[-2].opval));
 			    PL_expect = XOPERATOR; ;}
     break;
 
   case 98:
-#line 454 "perly.y"
+#line 463 "perly.y"
     { yyval.opval = newBINOP(OP_HELEM, 0,
 					ref(newHVREF(yyvsp[-5].opval),OP_RV2HV),
 					jmaybe(yyvsp[-2].opval));
@@ -519,7 +519,7 @@ case 2:
     break;
 
   case 99:
-#line 459 "perly.y"
+#line 468 "perly.y"
     { yyval.opval = newBINOP(OP_HELEM, 0,
 					ref(newHVREF(yyvsp[-4].opval),OP_RV2HV),
 					jmaybe(yyvsp[-2].opval));
@@ -527,184 +527,184 @@ case 2:
     break;
 
   case 100:
-#line 464 "perly.y"
+#line 473 "perly.y"
     { yyval.opval = newUNOP(OP_ENTERSUB, OPf_STACKED,
 				   newCVREF(0, scalar(yyvsp[-3].opval))); ;}
     break;
 
   case 101:
-#line 467 "perly.y"
+#line 476 "perly.y"
     { yyval.opval = newUNOP(OP_ENTERSUB, OPf_STACKED,
 				   append_elem(OP_LIST, yyvsp[-1].opval,
 				       newCVREF(0, scalar(yyvsp[-4].opval)))); ;}
     break;
 
   case 102:
-#line 472 "perly.y"
+#line 481 "perly.y"
     { yyval.opval = newUNOP(OP_ENTERSUB, OPf_STACKED,
 				   append_elem(OP_LIST, yyvsp[-1].opval,
 					       newCVREF(0, scalar(yyvsp[-3].opval)))); ;}
     break;
 
   case 103:
-#line 476 "perly.y"
+#line 485 "perly.y"
     { yyval.opval = newUNOP(OP_ENTERSUB, OPf_STACKED,
 				   newCVREF(0, scalar(yyvsp[-2].opval))); ;}
     break;
 
   case 104:
-#line 482 "perly.y"
+#line 491 "perly.y"
     { yyval.opval = newASSIGNOP(OPf_STACKED, yyvsp[-2].opval, yyvsp[-1].ival, yyvsp[0].opval); ;}
     break;
 
   case 105:
-#line 484 "perly.y"
+#line 493 "perly.y"
     { yyval.opval = newBINOP(yyvsp[-1].ival, 0, scalar(yyvsp[-2].opval), scalar(yyvsp[0].opval)); ;}
     break;
 
   case 106:
-#line 486 "perly.y"
+#line 495 "perly.y"
     {   if (yyvsp[-1].ival != OP_REPEAT)
 				scalar(yyvsp[-2].opval);
 			    yyval.opval = newBINOP(yyvsp[-1].ival, 0, yyvsp[-2].opval, scalar(yyvsp[0].opval)); ;}
     break;
 
   case 107:
-#line 490 "perly.y"
+#line 499 "perly.y"
     { yyval.opval = newBINOP(yyvsp[-1].ival, 0, scalar(yyvsp[-2].opval), scalar(yyvsp[0].opval)); ;}
     break;
 
   case 108:
-#line 492 "perly.y"
+#line 501 "perly.y"
     { yyval.opval = newBINOP(yyvsp[-1].ival, 0, scalar(yyvsp[-2].opval), scalar(yyvsp[0].opval)); ;}
     break;
 
   case 109:
-#line 494 "perly.y"
+#line 503 "perly.y"
     { yyval.opval = newBINOP(yyvsp[-1].ival, 0, scalar(yyvsp[-2].opval), scalar(yyvsp[0].opval)); ;}
     break;
 
   case 110:
-#line 496 "perly.y"
+#line 505 "perly.y"
     { yyval.opval = newBINOP(yyvsp[-1].ival, 0, scalar(yyvsp[-2].opval), scalar(yyvsp[0].opval)); ;}
     break;
 
   case 111:
-#line 498 "perly.y"
+#line 507 "perly.y"
     { yyval.opval = newBINOP(yyvsp[-1].ival, 0, scalar(yyvsp[-2].opval), scalar(yyvsp[0].opval)); ;}
     break;
 
   case 112:
-#line 500 "perly.y"
+#line 509 "perly.y"
     { yyval.opval = newBINOP(yyvsp[-1].ival, 0, scalar(yyvsp[-2].opval), scalar(yyvsp[0].opval)); ;}
     break;
 
   case 113:
-#line 502 "perly.y"
+#line 511 "perly.y"
     { yyval.opval = newRANGE(yyvsp[-1].ival, scalar(yyvsp[-2].opval), scalar(yyvsp[0].opval));;}
     break;
 
   case 114:
-#line 504 "perly.y"
+#line 513 "perly.y"
     { yyval.opval = newLOGOP(OP_AND, 0, yyvsp[-2].opval, yyvsp[0].opval); ;}
     break;
 
   case 115:
-#line 506 "perly.y"
+#line 515 "perly.y"
     { yyval.opval = newLOGOP(OP_OR, 0, yyvsp[-2].opval, yyvsp[0].opval); ;}
     break;
 
   case 116:
-#line 508 "perly.y"
+#line 517 "perly.y"
     { yyval.opval = newLOGOP(OP_DOR, 0, yyvsp[-2].opval, yyvsp[0].opval); ;}
     break;
 
   case 117:
-#line 510 "perly.y"
+#line 519 "perly.y"
     { yyval.opval = bind_match(yyvsp[-1].ival, yyvsp[-2].opval, yyvsp[0].opval); ;}
     break;
 
   case 118:
-#line 515 "perly.y"
+#line 524 "perly.y"
     { yyval.opval = newUNOP(OP_NEGATE, 0, scalar(yyvsp[0].opval)); ;}
     break;
 
   case 119:
-#line 517 "perly.y"
+#line 526 "perly.y"
     { yyval.opval = yyvsp[0].opval; ;}
     break;
 
   case 120:
-#line 519 "perly.y"
+#line 528 "perly.y"
     { yyval.opval = newUNOP(OP_NOT, 0, scalar(yyvsp[0].opval)); ;}
     break;
 
   case 121:
-#line 521 "perly.y"
+#line 530 "perly.y"
     { yyval.opval = newUNOP(OP_COMPLEMENT, 0, scalar(yyvsp[0].opval));;}
     break;
 
   case 122:
-#line 523 "perly.y"
+#line 532 "perly.y"
     { yyval.opval = newUNOP(OP_POSTINC, 0,
 					mod(scalar(yyvsp[-1].opval), OP_POSTINC)); ;}
     break;
 
   case 123:
-#line 526 "perly.y"
+#line 535 "perly.y"
     { yyval.opval = newUNOP(OP_POSTDEC, 0,
 					mod(scalar(yyvsp[-1].opval), OP_POSTDEC)); ;}
     break;
 
   case 124:
-#line 529 "perly.y"
+#line 538 "perly.y"
     { yyval.opval = newUNOP(OP_PREINC, 0,
 					mod(scalar(yyvsp[0].opval), OP_PREINC)); ;}
     break;
 
   case 125:
-#line 532 "perly.y"
+#line 541 "perly.y"
     { yyval.opval = newUNOP(OP_PREDEC, 0,
 					mod(scalar(yyvsp[0].opval), OP_PREDEC)); ;}
     break;
 
   case 126:
-#line 539 "perly.y"
+#line 548 "perly.y"
     { yyval.opval = newANONLIST(yyvsp[-1].opval); ;}
     break;
 
   case 127:
-#line 541 "perly.y"
+#line 550 "perly.y"
     { yyval.opval = newANONLIST(Nullop); ;}
     break;
 
   case 128:
-#line 543 "perly.y"
+#line 552 "perly.y"
     { yyval.opval = newANONHASH(yyvsp[-2].opval); ;}
     break;
 
   case 129:
-#line 545 "perly.y"
+#line 554 "perly.y"
     { yyval.opval = newANONHASH(Nullop); ;}
     break;
 
   case 130:
-#line 547 "perly.y"
+#line 556 "perly.y"
     { yyval.opval = newANONATTRSUB(yyvsp[-3].ival, yyvsp[-2].opval, yyvsp[-1].opval, yyvsp[0].opval); ;}
     break;
 
   case 131:
-#line 553 "perly.y"
+#line 562 "perly.y"
     { yyval.opval = dofile(yyvsp[0].opval); ;}
     break;
 
   case 132:
-#line 555 "perly.y"
+#line 564 "perly.y"
     { yyval.opval = newUNOP(OP_NULL, OPf_SPECIAL, scope(yyvsp[0].opval)); ;}
     break;
 
   case 133:
-#line 557 "perly.y"
+#line 566 "perly.y"
     { yyval.opval = newUNOP(OP_ENTERSUB,
 			    OPf_SPECIAL|OPf_STACKED,
 			    prepend_elem(OP_LIST,
@@ -715,7 +715,7 @@ case 2:
     break;
 
   case 134:
-#line 565 "perly.y"
+#line 574 "perly.y"
     { yyval.opval = newUNOP(OP_ENTERSUB,
 			    OPf_SPECIAL|OPf_STACKED,
 			    append_elem(OP_LIST,
@@ -727,14 +727,14 @@ case 2:
     break;
 
   case 135:
-#line 574 "perly.y"
+#line 583 "perly.y"
     { yyval.opval = newUNOP(OP_ENTERSUB, OPf_SPECIAL|OPf_STACKED,
 			    prepend_elem(OP_LIST,
 				scalar(newCVREF(0,scalar(yyvsp[-2].opval))), Nullop)); dep();;}
     break;
 
   case 136:
-#line 578 "perly.y"
+#line 587 "perly.y"
     { yyval.opval = newUNOP(OP_ENTERSUB, OPf_SPECIAL|OPf_STACKED,
 			    prepend_elem(OP_LIST,
 				yyvsp[-1].opval,
@@ -742,77 +742,77 @@ case 2:
     break;
 
   case 141:
-#line 590 "perly.y"
+#line 599 "perly.y"
     { yyval.opval = newCONDOP(0, yyvsp[-4].opval, yyvsp[-2].opval, yyvsp[0].opval); ;}
     break;
 
   case 142:
-#line 592 "perly.y"
+#line 601 "perly.y"
     { yyval.opval = newUNOP(OP_REFGEN, 0, mod(yyvsp[0].opval,OP_REFGEN)); ;}
     break;
 
   case 143:
-#line 594 "perly.y"
+#line 603 "perly.y"
     { yyval.opval = yyvsp[0].opval; ;}
     break;
 
   case 144:
-#line 596 "perly.y"
+#line 605 "perly.y"
     { yyval.opval = localize(yyvsp[0].opval,yyvsp[-1].ival); ;}
     break;
 
   case 145:
-#line 598 "perly.y"
+#line 607 "perly.y"
     { yyval.opval = sawparens(yyvsp[-1].opval); ;}
     break;
 
   case 146:
-#line 600 "perly.y"
+#line 609 "perly.y"
     { yyval.opval = sawparens(newNULLLIST()); ;}
     break;
 
   case 147:
-#line 602 "perly.y"
+#line 611 "perly.y"
     { yyval.opval = yyvsp[0].opval; ;}
     break;
 
   case 148:
-#line 604 "perly.y"
+#line 613 "perly.y"
     { yyval.opval = yyvsp[0].opval; ;}
     break;
 
   case 149:
-#line 606 "perly.y"
+#line 615 "perly.y"
     { yyval.opval = yyvsp[0].opval; ;}
     break;
 
   case 150:
-#line 608 "perly.y"
+#line 617 "perly.y"
     { yyval.opval = yyvsp[0].opval; ;}
     break;
 
   case 151:
-#line 610 "perly.y"
+#line 619 "perly.y"
     { yyval.opval = newUNOP(OP_AV2ARYLEN, 0, ref(yyvsp[0].opval, OP_AV2ARYLEN));;}
     break;
 
   case 152:
-#line 612 "perly.y"
+#line 621 "perly.y"
     { yyval.opval = yyvsp[0].opval; ;}
     break;
 
   case 153:
-#line 614 "perly.y"
+#line 623 "perly.y"
     { yyval.opval = newSLICEOP(0, yyvsp[-1].opval, yyvsp[-4].opval); ;}
     break;
 
   case 154:
-#line 616 "perly.y"
+#line 625 "perly.y"
     { yyval.opval = newSLICEOP(0, yyvsp[-1].opval, Nullop); ;}
     break;
 
   case 155:
-#line 618 "perly.y"
+#line 627 "perly.y"
     { yyval.opval = prepend_elem(OP_ASLICE,
 				newOP(OP_PUSHMARK, 0),
 				    newLISTOP(OP_ASLICE, 0,
@@ -821,7 +821,7 @@ case 2:
     break;
 
   case 156:
-#line 624 "perly.y"
+#line 633 "perly.y"
     { yyval.opval = prepend_elem(OP_HSLICE,
 				newOP(OP_PUSHMARK, 0),
 				    newLISTOP(OP_HSLICE, 0,
@@ -831,217 +831,217 @@ case 2:
     break;
 
   case 157:
-#line 631 "perly.y"
+#line 640 "perly.y"
     { yyval.opval = yyvsp[0].opval; ;}
     break;
 
   case 158:
-#line 633 "perly.y"
+#line 642 "perly.y"
     { yyval.opval = newUNOP(OP_ENTERSUB, 0, scalar(yyvsp[0].opval)); ;}
     break;
 
   case 159:
-#line 635 "perly.y"
+#line 644 "perly.y"
     { yyval.opval = newUNOP(OP_ENTERSUB, OPf_STACKED, scalar(yyvsp[-2].opval)); ;}
     break;
 
   case 160:
-#line 637 "perly.y"
+#line 646 "perly.y"
     { yyval.opval = newUNOP(OP_ENTERSUB, OPf_STACKED,
 			    append_elem(OP_LIST, yyvsp[-1].opval, scalar(yyvsp[-3].opval))); ;}
     break;
 
   case 161:
-#line 640 "perly.y"
+#line 649 "perly.y"
     { yyval.opval = newUNOP(OP_ENTERSUB, OPf_STACKED,
 			    append_elem(OP_LIST, yyvsp[0].opval, scalar(yyvsp[-1].opval))); ;}
     break;
 
   case 162:
-#line 643 "perly.y"
+#line 652 "perly.y"
     { yyval.opval = newOP(yyvsp[0].ival, OPf_SPECIAL);
 			    PL_hints |= HINT_BLOCK_SCOPE; ;}
     break;
 
   case 163:
-#line 646 "perly.y"
+#line 655 "perly.y"
     { yyval.opval = newLOOPEX(yyvsp[-1].ival,yyvsp[0].opval); ;}
     break;
 
   case 164:
-#line 648 "perly.y"
+#line 657 "perly.y"
     { yyval.opval = newUNOP(OP_NOT, 0, scalar(yyvsp[0].opval)); ;}
     break;
 
   case 165:
-#line 650 "perly.y"
+#line 659 "perly.y"
     { yyval.opval = newOP(yyvsp[0].ival, 0); ;}
     break;
 
   case 166:
-#line 652 "perly.y"
+#line 661 "perly.y"
     { yyval.opval = newUNOP(yyvsp[-1].ival, 0, yyvsp[0].opval); ;}
     break;
 
   case 167:
-#line 654 "perly.y"
+#line 663 "perly.y"
     { yyval.opval = newUNOP(yyvsp[-1].ival, 0, yyvsp[0].opval); ;}
     break;
 
   case 168:
-#line 656 "perly.y"
+#line 665 "perly.y"
     { yyval.opval = newUNOP(OP_ENTERSUB, OPf_STACKED,
 			    append_elem(OP_LIST, yyvsp[0].opval, scalar(yyvsp[-1].opval))); ;}
     break;
 
   case 169:
-#line 659 "perly.y"
+#line 668 "perly.y"
     { yyval.opval = newOP(yyvsp[0].ival, 0); ;}
     break;
 
   case 170:
-#line 661 "perly.y"
+#line 670 "perly.y"
     { yyval.opval = newOP(yyvsp[-2].ival, 0); ;}
     break;
 
   case 171:
-#line 663 "perly.y"
+#line 672 "perly.y"
     { yyval.opval = newUNOP(OP_ENTERSUB, OPf_STACKED,
 				scalar(yyvsp[0].opval)); ;}
     break;
 
   case 172:
-#line 666 "perly.y"
+#line 675 "perly.y"
     { yyval.opval = newOP(yyvsp[-2].ival, OPf_SPECIAL); ;}
     break;
 
   case 173:
-#line 668 "perly.y"
+#line 677 "perly.y"
     { yyval.opval = newUNOP(yyvsp[-3].ival, 0, yyvsp[-1].opval); ;}
     break;
 
   case 174:
-#line 670 "perly.y"
+#line 679 "perly.y"
     { yyval.opval = pmruntime(yyvsp[-3].opval, yyvsp[-1].opval, Nullop); ;}
     break;
 
   case 175:
-#line 672 "perly.y"
+#line 681 "perly.y"
     { yyval.opval = pmruntime(yyvsp[-5].opval, yyvsp[-3].opval, yyvsp[-1].opval); ;}
     break;
 
   case 178:
-#line 679 "perly.y"
+#line 688 "perly.y"
     { yyval.opval = my_attrs(yyvsp[-1].opval,yyvsp[0].opval); ;}
     break;
 
   case 179:
-#line 681 "perly.y"
+#line 690 "perly.y"
     { yyval.opval = localize(yyvsp[0].opval,yyvsp[-1].ival); ;}
     break;
 
   case 180:
-#line 686 "perly.y"
+#line 695 "perly.y"
     { yyval.opval = sawparens(yyvsp[-1].opval); ;}
     break;
 
   case 181:
-#line 688 "perly.y"
+#line 697 "perly.y"
     { yyval.opval = sawparens(newNULLLIST()); ;}
     break;
 
   case 182:
-#line 690 "perly.y"
+#line 699 "perly.y"
     { yyval.opval = yyvsp[0].opval; ;}
     break;
 
   case 183:
-#line 692 "perly.y"
+#line 701 "perly.y"
     { yyval.opval = yyvsp[0].opval; ;}
     break;
 
   case 184:
-#line 694 "perly.y"
+#line 703 "perly.y"
     { yyval.opval = yyvsp[0].opval; ;}
     break;
 
   case 185:
-#line 699 "perly.y"
+#line 708 "perly.y"
     { yyval.opval = Nullop; ;}
     break;
 
   case 186:
-#line 701 "perly.y"
+#line 710 "perly.y"
     { yyval.opval = yyvsp[0].opval; ;}
     break;
 
   case 187:
-#line 705 "perly.y"
+#line 714 "perly.y"
     { yyval.opval = Nullop; ;}
     break;
 
   case 188:
-#line 707 "perly.y"
+#line 716 "perly.y"
     { yyval.opval = yyvsp[0].opval; ;}
     break;
 
   case 189:
-#line 709 "perly.y"
+#line 718 "perly.y"
     { yyval.opval = yyvsp[-1].opval; ;}
     break;
 
   case 190:
-#line 715 "perly.y"
+#line 724 "perly.y"
     { PL_in_my = 0; yyval.opval = my(yyvsp[0].opval); ;}
     break;
 
   case 191:
-#line 719 "perly.y"
+#line 728 "perly.y"
     { yyval.opval = newCVREF(yyvsp[-1].ival,yyvsp[0].opval); ;}
     break;
 
   case 192:
-#line 723 "perly.y"
+#line 732 "perly.y"
     { yyval.opval = newSVREF(yyvsp[0].opval); ;}
     break;
 
   case 193:
-#line 727 "perly.y"
+#line 736 "perly.y"
     { yyval.opval = newAVREF(yyvsp[0].opval); ;}
     break;
 
   case 194:
-#line 731 "perly.y"
+#line 740 "perly.y"
     { yyval.opval = newHVREF(yyvsp[0].opval); ;}
     break;
 
   case 195:
-#line 735 "perly.y"
+#line 744 "perly.y"
     { yyval.opval = newAVREF(yyvsp[0].opval); ;}
     break;
 
   case 196:
-#line 739 "perly.y"
+#line 748 "perly.y"
     { yyval.opval = newGVREF(0,yyvsp[0].opval); ;}
     break;
 
   case 197:
-#line 744 "perly.y"
+#line 753 "perly.y"
     { yyval.opval = scalar(yyvsp[0].opval); ;}
     break;
 
   case 198:
-#line 746 "perly.y"
+#line 755 "perly.y"
     { yyval.opval = scalar(yyvsp[0].opval);  ;}
     break;
 
   case 199:
-#line 748 "perly.y"
+#line 757 "perly.y"
     { yyval.opval = scope(yyvsp[0].opval); ;}
     break;
 
   case 200:
-#line 751 "perly.y"
+#line 760 "perly.y"
     { yyval.opval = yyvsp[0].opval; ;}
     break;
 
diff --git a/perly.h b/perly.h
index c780f10ca7..e92ca95091 100644
--- a/perly.h
+++ b/perly.h
@@ -164,7 +164,7 @@
 
 #endif /* PERL_CORE */
 #if ! defined (YYSTYPE) && ! defined (YYSTYPE_IS_DECLARED)
-#line 21 "perly.y"
+#line 30 "perly.y"
 typedef union YYSTYPE {
     I32	ival;
     char *pval;
diff --git a/perly.tab b/perly.tab
index d26cc2c4f5..981e6ba653 100644
--- a/perly.tab
+++ b/perly.tab
@@ -163,27 +163,27 @@ static const short yyrhs[] =
 /* YYRLINE[YYN] -- source line where rule number YYN was defined.  */
 static const unsigned short yyrline[] =
 {
-       0,    86,    86,    92,    99,   103,   109,   116,   120,   124,
-     125,   127,   136,   138,   139,   148,   154,   156,   158,   160,
-     162,   164,   166,   173,   174,   176,   183,   187,   195,   196,
-     201,   207,   213,   216,   220,   223,   239,   247,   248,   253,
-     254,   258,   263,   267,   271,   275,   281,   282,   286,   288,
-     290,   292,   294,   298,   302,   303,   307,   312,   317,   321,
-     325,   329,   338,   339,   344,   345,   347,   352,   354,   359,
-     360,   363,   368,   367,   374,   376,   378,   380,   384,   386,
-     388,   392,   395,   398,   403,   407,   412,   417,   419,   422,
-     421,   430,   431,   435,   440,   442,   446,   450,   453,   458,
-     463,   466,   471,   475,   481,   483,   485,   489,   491,   493,
-     495,   497,   499,   501,   503,   505,   507,   509,   514,   516,
-     518,   520,   522,   525,   528,   531,   538,   540,   542,   544,
-     546,   552,   554,   556,   564,   573,   577,   585,   586,   587,
-     588,   589,   591,   593,   595,   597,   599,   601,   603,   605,
-     607,   609,   611,   613,   615,   617,   623,   630,   632,   634,
-     636,   639,   642,   645,   647,   649,   651,   653,   655,   658,
-     660,   662,   665,   667,   669,   671,   673,   674,   678,   680,
-     685,   687,   689,   691,   693,   698,   700,   705,   706,   708,
-     714,   718,   722,   726,   730,   734,   738,   743,   745,   747,
-     750
+       0,    95,    95,   101,   108,   112,   118,   125,   129,   133,
+     134,   136,   145,   147,   148,   157,   163,   165,   167,   169,
+     171,   173,   175,   182,   183,   185,   192,   196,   204,   205,
+     210,   216,   222,   225,   229,   232,   248,   256,   257,   262,
+     263,   267,   272,   276,   280,   284,   290,   291,   295,   297,
+     299,   301,   303,   307,   311,   312,   316,   321,   326,   330,
+     334,   338,   347,   348,   353,   354,   356,   361,   363,   368,
+     369,   372,   377,   376,   383,   385,   387,   389,   393,   395,
+     397,   401,   404,   407,   412,   416,   421,   426,   428,   431,
+     430,   439,   440,   444,   449,   451,   455,   459,   462,   467,
+     472,   475,   480,   484,   490,   492,   494,   498,   500,   502,
+     504,   506,   508,   510,   512,   514,   516,   518,   523,   525,
+     527,   529,   531,   534,   537,   540,   547,   549,   551,   553,
+     555,   561,   563,   565,   573,   582,   586,   594,   595,   596,
+     597,   598,   600,   602,   604,   606,   608,   610,   612,   614,
+     616,   618,   620,   622,   624,   626,   632,   639,   641,   643,
+     645,   648,   651,   654,   656,   658,   660,   662,   664,   667,
+     669,   671,   674,   676,   678,   680,   682,   683,   687,   689,
+     694,   696,   698,   700,   702,   707,   709,   714,   715,   717,
+     723,   727,   731,   735,   739,   743,   747,   752,   754,   756,
+     759
 };
 #endif
 
diff --git a/perly.y b/perly.y
index 9224537979..5d1b19fd77 100644
--- a/perly.y
+++ b/perly.y
@@ -12,6 +12,15 @@
  * All that is gold does not glitter, not all those who wander are lost.'
  */
 
+/* This file holds the grammar for the Perl language. If edited, you need
+ * to run regen_perly.pl, which re-creates the files perly.h, perly.tab
+ * and perly.act which are derived from this.
+ *
+ * The main job of of this grammar is to call the various newFOO()
+ * functions in op.c to build a syntax tree of OP structs.
+ * It relies in the lexer in toke.c to do the tokenizing.
+ */
+
 /*  Make the parser re-entrant. */
 
 %pure_parser
diff --git a/pp.c b/pp.c
index 2b38805a10..f58306d0bb 100644
--- a/pp.c
+++ b/pp.c
@@ -13,6 +13,13 @@
  * and no knowing what you'll find around a corner.  And Elves, sir!" --Samwise
  */
 
+/* This file contains general pp ("push/pop") functions that execute the
+ * opcodes that make up a perl program. A typical pp function expects to
+ * find its arguments on the stack, and usually pushes its results onto
+ * the stack, hence the 'pp' terminology. Each OP structure contains
+ * a pointer to the relevant pp_foo() function.
+ */
+
 #include "EXTERN.h"
 #define PERL_IN_PP_C
 #include "perl.h"
diff --git a/pp_ctl.c b/pp_ctl.c
index c8dd1aebe0..7fd4c4ed2d 100644
--- a/pp_ctl.c
+++ b/pp_ctl.c
@@ -17,6 +17,17 @@
  * And whither then?  I cannot say.
  */
 
+/* This file contains control-oriented pp ("push/pop") functions that
+ * execute the opcodes that make up a perl program. A typical pp function
+ * expects to find its arguments on the stack, and usually pushes its
+ * results onto the stack, hence the 'pp' terminology. Each OP structure
+ * contains a pointer to the relevant pp_foo() function.
+ *
+ * Control-oriented means things like pp_enteriter() and pp_next(), which
+ * alter the flow of control of the program.
+ */
+
+
 #include "EXTERN.h"
 #define PERL_IN_PP_CTL_C
 #include "perl.h"
diff --git a/pp_hot.c b/pp_hot.c
index 752a267bd8..98cad17db7 100644
--- a/pp_hot.c
+++ b/pp_hot.c
@@ -16,6 +16,19 @@
  *                     Fire, Foes!  Awake!
  */
 
+/* This file contains 'hot' pp ("push/pop") functions that
+ * execute the opcodes that make up a perl program. A typical pp function
+ * expects to find its arguments on the stack, and usually pushes its
+ * results onto the stack, hence the 'pp' terminology. Each OP structure
+ * contains a pointer to the relevant pp_foo() function.
+ *
+ * By 'hot', we mean common ops whose execution speed is critical.
+ * By gathering them together into a single file, we encourage
+ * CPU cache hits on hot code. Also it could be taken as a warning not to
+ * change any code in this file unless you're sure it won't affect
+ * performance.
+ */
+
 #include "EXTERN.h"
 #define PERL_IN_PP_HOT_C
 #include "perl.h"
diff --git a/pp_pack.c b/pp_pack.c
index d7ebf3d074..427269f355 100644
--- a/pp_pack.c
+++ b/pp_pack.c
@@ -16,6 +16,17 @@
  * some salt.
  */
 
+/* This file contains pp ("push/pop") functions that
+ * execute the opcodes that make up a perl program. A typical pp function
+ * expects to find its arguments on the stack, and usually pushes its
+ * results onto the stack, hence the 'pp' terminology. Each OP structure
+ * contains a pointer to the relevant pp_foo() function.
+ *
+ * This particular file just contains pp_pack() and pp_unpack(). See the
+ * other pp*.c files for the rest of the pp_ functions.
+ */
+
+
 #include "EXTERN.h"
 #define PERL_IN_PP_PACK_C
 #include "perl.h"
diff --git a/pp_sort.c b/pp_sort.c
index 3cabed805e..0cb4795ea6 100644
--- a/pp_sort.c
+++ b/pp_sort.c
@@ -13,6 +13,17 @@
  *   rear!'  the slave-driver shouted. 'Three files up. And stay there...
  */
 
+/* This file contains pp ("push/pop") functions that
+ * execute the opcodes that make up a perl program. A typical pp function
+ * expects to find its arguments on the stack, and usually pushes its
+ * results onto the stack, hence the 'pp' terminology. Each OP structure
+ * contains a pointer to the relevant pp_foo() function.
+ *
+ * This particular file just contains pp_sort(), which is complex
+ * enough to merit its own file! See the other pp*.c files for the rest of
+ * the pp_ functions.
+ */
+
 #include "EXTERN.h"
 #define PERL_IN_PP_SORT_C
 #include "perl.h"
diff --git a/pp_sys.c b/pp_sys.c
index 4432a47676..b615d4ab5f 100644
--- a/pp_sys.c
+++ b/pp_sys.c
@@ -15,6 +15,15 @@
  * a rumour and a trouble as of great engines throbbing and labouring.
  */
 
+/* This file contains system pp ("push/pop") functions that
+ * execute the opcodes that make up a perl program. A typical pp function
+ * expects to find its arguments on the stack, and usually pushes its
+ * results onto the stack, hence the 'pp' terminology. Each OP structure
+ * contains a pointer to the relevant pp_foo() function.
+ *
+ * By 'system', we mean ops which interact with the OS, such as pp_open().
+ */
+
 #include "EXTERN.h"
 #define PERL_IN_PP_SYS_C
 #include "perl.h"
diff --git a/regcomp.c b/regcomp.c
index 5388495588..796d8fe10f 100644
--- a/regcomp.c
+++ b/regcomp.c
@@ -5,6 +5,11 @@
  * "A fair jaw-cracker dwarf-language must be."  --Samwise Gamgee
  */
 
+/* This file contains functions for compiling a regular expresssion.  See
+ * also regexec.c which funnnily enough, contains functions for executing
+ * a regular expression.
+ */
+
 /* NOTE: this is derived from Henry Spencer's regexp code, and should not
  * confused with the original package (see point 3 below).  Thanks, Henry!
  */
diff --git a/regexec.c b/regexec.c
index 60276cb44d..d0d0ce7446 100644
--- a/regexec.c
+++ b/regexec.c
@@ -5,6 +5,11 @@
  * "One Ring to rule them all, One Ring to find them..."
  */
 
+/* This file contains functions for executing a regular expresssion.  See
+ * also regcomp.c which funnnily enough, contains functions for compiling
+ * a regular expression.
+ */
+
 /* NOTE: this is derived from Henry Spencer's regexp code, and should not
  * confused with the original package (see point 3 below).  Thanks, Henry!
  */
diff --git a/run.c b/run.c
index 3d48139d88..b98a76e9ab 100644
--- a/run.c
+++ b/run.c
@@ -8,6 +8,19 @@
  *
  */
 
+/* This file contains the main Perl opcode execution loop. It just
+ * calls the pp_foo() function associated with each op, and expects that
+ * function to return a pointer to the next op to be executed, or null if
+ * its the end of the sub or program or whatever.
+ *
+ * There is a similar loop in dump.c, Perl_runops_debug(), which does
+ * the same, but also checks for various debug flags each time round the
+ * loop.
+ *
+ * Why this function requires a file all of its own is anybody's guess.
+ * DAPM.
+ */
+
 #include "EXTERN.h"
 #define PERL_IN_RUN_C
 #include "perl.h"
diff --git a/scope.c b/scope.c
index 54d0ac1755..d5b8b7fbad 100644
--- a/scope.c
+++ b/scope.c
@@ -13,6 +13,13 @@
  * levels..."
  */
 
+/* This function contains functions to manipluate various of perl's stacks;
+ * in particular it contains code to push various types of things onto
+ * the savestack, then to pop them off and perform the correct restorative
+ * action for each one. This corresponds to the cleanup Perl does at
+ * each scope exit.
+ */
+
 #include "EXTERN.h"
 #define PERL_IN_SCOPE_C
 #include "perl.h"
diff --git a/taint.c b/taint.c
index 2c2e66e8ec..ec568be2cc 100644
--- a/taint.c
+++ b/taint.c
@@ -14,6 +14,9 @@
  * liar, Saruman, and a corrupter of men's hearts."  --Theoden
  */
 
+/* This file contains a few functions for handling data tainting in Perl
+ */
+
 #include "EXTERN.h"
 #define PERL_IN_TAINT_C
 #include "perl.h"
diff --git a/universal.c b/universal.c
index ef4d95badd..caab476386 100644
--- a/universal.c
+++ b/universal.c
@@ -14,6 +14,10 @@
  * beginning." --Gandalf, relating Gollum's story
  */
 
+/* This file contains the code that implements the functions in Perl's
+ * UNIVERSAL package, such as UNIVERSAL->can().
+ */
+
 #include "EXTERN.h"
 #define PERL_IN_UNIVERSAL_C
 #include "perl.h"
diff --git a/utf8.c b/utf8.c
index 6155fabe3c..260892439c 100644
--- a/utf8.c
+++ b/utf8.c
@@ -29,6 +29,11 @@ static char unees[] = "Malformed UTF-8 character (unexpected end of string)";
 /* 
 =head1 Unicode Support
 
+This file contains various utility functions for manipulating UTF8-encoded
+strings. For the uninitiated, this is a method of representing arbitrary
+Unicde characters as a variable number of bytes, in such a way that
+characters in the ASCII range are unmodifed, and a zero byte never appears.
+
 =for apidoc A|U8 *|uvuni_to_utf8_flags|U8 *d|UV uv|UV flags
 
 Adds the UTF-8 representation of the Unicode codepoint C<uv> to the end
diff --git a/util.c b/util.c
index b3375de4f0..02d65a683a 100644
--- a/util.c
+++ b/util.c
@@ -13,6 +13,12 @@
  * not content."  --Gandalf
  */
 
+/* This file contains assorted utility routines.
+ * Which is a polite way of saying any stuff that people couldn't think of
+ * a better place for. Amongst other things, it includes the warning and
+ * dieing stuff, plus wrappers for malloc code.
+ */
+
 #include "EXTERN.h"
 #define PERL_IN_UTIL_C
 #include "perl.h"