_learning perl_, ch11, 7.I.2002, nh

FORMATS
  (Practical Extraction and Report Language)
                            ^^^^^^
format defines a *constant* part and a *variable* part

1. defining a format
2. loading the data to be printed in the fields
3. invoking the format

1. Defining a Format
   ~~~~~~~~~~~~~~~~~
    * like a subroutine -- anywhere in your program (usually at end,
        before subroutine definitions)

    format formatname = 
    fieldline
    value_1, value_2, value_3
    fieldline
    value_1, value_2, value_3
    .

    * whitespace-sensitive!!
        (but not in lines with the fieldvalues)
    * can contain fieldholders for variable text:
        
        Hello, my name is @<<<            # l-justified, 4 characters
        $name
        
        I have $@######.## in the bank    # numeric
        $checking+$savings                # can use expressions here
        
    * lines with no fieldholders don't need to be followed by lines
        with fieldvalues.
    * text after the first \n is ignored
    
    
3. Invoking at Format
   ~~~~~~~~~~~~~~~~~~
    * use 'write' function -- parameters filehandle, format (same)
        write (ADDRESSLABEL);   # write output to A..LABEL format
    * function takes the name of a filehanldle and generates text for
        it using the current format for that filehandle
    * by default, the current format for a filehandle is a format with
        the same name
    * variable names have to be same names, too

    
   o  text fields
      -----------
         most fieldholders start with '@'
         following characters indicate type of field
         number of ch's (including '@') indicate length

         <<<<< left-justified
         >>>>> right-justified
         ||||| centered
         ##### fixed-precision numeric (optional decimal point)

      | 
      `-> can have multiline fields: with '@*'
            format STDOUT = 
            Text before ...
            @*
            $long_string
            ... text after

      |
      `-> filled fields
          -------------
            * wraps words around in paragraphs
            * starts with '^' instead of '@'
              
              format PEOPLE = 
              Name : @<<<<<<<<< Comment: ^<<<<<<<
                                         $comment
              ~                          ^<<<<<<<
                                         $comment
              ~                          ^<<<<<<<
                                         $comment
              .

          --> the '~' at the beginning of the line means, "don't
              print it if was just going to be whitespace anyhow."

              or just,

              format PEOPLE = 
              Name : @<<<<<<<<< Comment: ^<<<<<<<
                                         $comment
              ~~                         ^<<<<<<<
                                         $comment
              .

          --> the double ~ means, "just repeat until it's blank."
              
            
top-of-the-page format
~~~~~~~~~~~~~~~~~~~~~~
  paginates
  FORMATNAME_TOP (must have that _TOP suffix)
  default page-number variable is $%

    format ADDRESSLABEL_TOP =
    My addresses -- Page @<
                        $%
    .

  can be changed using $^ (see below)
                       ~~

changing defaults for formats
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      default for 'print' isn't always STDOUT -- it's the 
              *currently selected filehandle*
  which starts out at STDOUT, but can be changed with 'select'

  'select' takes one filehandle as an argument

  print "hello, world!\n";  # prints to STDOUT
  select(LOGFILE);          # selects new filehandle
  print "hi, logfile!\n";   # same as 'print LOGFILE "xxx";'
  select(STDOUT);           # back to STDOUT
  print "hi again.\n";      # prints to STDOUT

  select's return value is the old default:
    $oldfilehandle = select(LOGFILE);

  |
  `-> the format name for a particular filehandle can be changed by
      modifying the $~ variable
                    ^^
        $oldhandle = select REPORT;
        $~ = "SUMMARY";
        select ($oldhandle)
        write (REPORT);       # we get text out on the REPORT
                              # filehandle but using the SUMMARY
                              # format
  |
  `-> top-of-the-page format name can be changed using $^

  |
  `-> changing page length
      --------------------
          * default is 60
          * change it using $=
              (current pg length for currently selected filehandle)

        $old = select LOGFILE
        $= = 30;
        select $old;

  |
  `-> changing position on a page
      ---------------------------
          if you 'print' a few lines to your filehandle, that will
          mess things up, because perl only reads things that are
          'write'ed to it.

          change with $- variable.  (# of lines left on current pg)
                                     # at top-of-page, copied from $=
      
          write;                      # STDOUT format to STDOUT
          print "an extra line!\n";   # this goes to STDOUT
          $- --;                      # decrement $-;
          write;                      # takes modified $- into acc't.