better document format code

add descriptions of:
    format op constants
    local vars
    code blocks
to generally make navigating the format code easier.
(Oh, and fix one incorrect indent).

No code changes.

Author: iabyn

form.h

@@ -1,27 +1,27 @@
 /*    form.h
  *
- *    Copyright (C) 1991, 1992, 1993, 2000, 2004 by Larry Wall and others
+ *    Copyright (C) 1991, 1992, 1993, 2000, 2004, 2011 by Larry Wall and others
  *
  *    You may distribute under the terms of either the GNU General Public
  *    License or the Artistic License, as specified in the README file.
  *
  */
 
-#define FF_END          0
-#define FF_LINEMARK     1
-#define FF_LITERAL      2
-#define FF_SKIP         3
-#define FF_FETCH        4
-#define FF_CHECKNL      5
-#define FF_CHECKCHOP    6
-#define FF_SPACE        7
-#define FF_HALFSPACE    8
-#define FF_ITEM         9
-#define FF_CHOP         10
-#define FF_LINEGLOB     11
-#define FF_DECIMAL      12
-#define FF_NEWLINE      13
-#define FF_BLANK        14
-#define FF_MORE         15
-#define FF_0DECIMAL     16
-#define FF_LINESNGL     17
+#define FF_END          0  /* tidy up, then return */
+#define FF_LINEMARK     1  /* start (or end) of a line */
+#define FF_LITERAL      2  /* append <arg> literal chars */
+#define FF_SKIP         3  /* skip <arg> chars in format */
+#define FF_FETCH        4  /* get next item and set field size to <arg> */
+#define FF_CHECKNL      5  /* find max len of item (up to \n) that fits field */
+#define FF_CHECKCHOP    6  /* like CHECKNL, but up to highest split point */
+#define FF_SPACE        7  /* append padding space (diff of field, item size) */
+#define FF_HALFSPACE    8  /* like FF_SPACE, but only append half as many */
+#define FF_ITEM         9  /* append a text item, while blanking ctrl chars */
+#define FF_CHOP         10 /* (for ^*) chop the current item */
+#define FF_LINEGLOB     11 /* process @*  */
+#define FF_DECIMAL      12 /* do @##, ^##, where <arg>=(precision|flags) */
+#define FF_NEWLINE      13 /* delete trailing spaces, then append \n */
+#define FF_BLANK        14 /* for arg==0: do '~'; for arg>0 : do '~~' */
+#define FF_MORE         15 /* replace long end of string with '...' */
+#define FF_0DECIMAL     16 /* like FF_DECIMAL but for 0### */
+#define FF_LINESNGL     17 /* process ^*  */

pp_ctl.c

@@ -523,23 +523,23 @@ PP(pp_formline)
 {
     dVAR; dSP; dMARK; dORIGMARK;
     register SV * const tmpForm = *++MARK;
-    SV *formsv;
-    register U32 *fpc;
-    register char *t;
-    const char *f;
+    SV *formsv;		    /* contains text of original format */
+    register U32 *fpc;	    /* format ops program counter */
+    register char *t;	    /* current append position in target string */
+    const char *f;	    /* current position in format string */
     register I32 arg;
-    register SV *sv = NULL;
-    const char *item = NULL;
-    I32 itemsize  = 0;
-    I32 fieldsize = 0;
-    I32 lines = 0;
-    bool chopspace = (strchr(PL_chopset, ' ') != NULL);
-    const char *chophere = NULL;
-    char *linemark = NULL;
+    register SV *sv = NULL; /* current item */
+    const char *item = NULL;/* string value of current item */
+    I32 itemsize  = 0;	    /* length of current item, possibly truncated */
+    I32 fieldsize = 0;	    /* width of current field */
+    I32 lines = 0;	    /* number of lines that have been output */
+    bool chopspace = (strchr(PL_chopset, ' ') != NULL); /* does $: have space */
+    const char *chophere = NULL; /* where to chop current item */
+    char *linemark = NULL;  /* pos of start of line in output */
     NV value;
-    bool gotsome = FALSE;
+    bool gotsome = FALSE;   /* seen at least one non-blank item on this line */
     STRLEN len;
-    STRLEN fudge;
+    STRLEN fudge;	    /* estimate of output size in bytes */
     bool item_is_utf8 = FALSE;
     bool targ_is_utf8 = FALSE;
     SV * nsv = NULL;
@@ -848,7 +848,7 @@ PP(pp_formline)
 		    const int ch = *t++ = *s++;
 		    if (iscntrl(ch))
 #else
-			if ( !((*t++ = *s++) & ~31) )
+		    if ( !((*t++ = *s++) & ~31) )
 #endif
 			    t[-1] = ' ';
 		}
@@ -4918,17 +4918,17 @@ S_doparseform(pTHX_ SV *sv)
     STRLEN len;
     register char *s = SvPV(sv, len);
     register char *send;
-    register char *base = NULL;
-    register I32 skipspaces = 0;
-    bool noblank   = FALSE;
-    bool repeat    = FALSE;
-    bool postspace = FALSE;
+    register char *base = NULL; /* start of current field */
+    register I32 skipspaces = 0; /* number of contiguous spaces seen */
+    bool noblank   = FALSE; /* ~ or ~~ seen on this line */
+    bool repeat    = FALSE; /* ~~ seen on this line */
+    bool postspace = FALSE; /* a text field may need right padding */
     U32 *fops;
     register U32 *fpc;
-    U32 *linepc = NULL;
+    U32 *linepc = NULL;	    /* position of last FF_LINEMARK */
     register I32 arg;
-    bool ischop;
-    bool unchopnum = FALSE;
+    bool ischop;	    /* it's a ^ rather than a @ */
+    bool unchopnum = FALSE; /* at least one @ (i.e. non-chop) num field seen */
     int maxops = 12; /* FF_LINEMARK + FF_END + 10 (\0 without preceding \n) */
     MAGIC *mg = NULL;
     SV *sv_copy;
@@ -5061,7 +5061,7 @@ S_doparseform(pTHX_ SV *sv)
 
 	    base = s - 1;
 	    *fpc++ = FF_FETCH;
-	    if (*s == '*') {
+	    if (*s == '*') { /*  @* or ^*  */
 		s++;
 		*fpc++ = 2;  /* skip the @* or ^* */
 		if (ischop) {
@@ -5070,7 +5070,7 @@ S_doparseform(pTHX_ SV *sv)
 		} else
 		    *fpc++ = FF_LINEGLOB;
 	    }
-	    else if (*s == '#' || (*s == '.' && s[1] == '#')) {
+	    else if (*s == '#' || (*s == '.' && s[1] == '#')) { /* @###, ^### */
 		arg = ischop ? 512 : 0;
 		base = s - 1;
 		while (*s == '#')
@@ -5103,7 +5103,7 @@ S_doparseform(pTHX_ SV *sv)
 		*fpc++ = (U16)arg;
                 unchopnum |= ! ischop;
 	    }
-	    else {
+	    else {				/* text field */
 		I32 prespace = 0;
 		bool ismore = FALSE;
 
@@ -5130,7 +5130,7 @@ S_doparseform(pTHX_ SV *sv)
 		*fpc++ = ischop ? FF_CHECKCHOP : FF_CHECKNL;
 
 		if (prespace)
-		    *fpc++ = (U16)prespace;
+		    *fpc++ = (U16)prespace; /* add SPACE or HALFSPACE */
 		*fpc++ = FF_ITEM;
 		if (ismore)
 		    *fpc++ = FF_MORE;