pod/perlform.pod

   1 =head1 NAME
   2
   3 perlform - Perl formats
   4
   5 =head1 DESCRIPTION
   6
   7 Perl has a mechanism to help you generate simple reports and charts.  To
   8 facilitate this, Perl helps you code up your output page
   9 close to how it will look when it's printed.  It can keep
  10 track of things like how many lines on a page, what page you're on, when to
  11 print page headers, etc.  Keywords are borrowed from FORTRAN:
  12 format() to declare and write() to execute; see their entries in
  13 L<perlfunc>.  Fortunately, the layout is much more legible, more like
  14 BASIC's PRINT USING statement.  Think of it as a poor man's nroff(1).
  15
  16 Formats, like packages and subroutines, are declared rather than executed,
  17 so they may occur at any point in your program.  (Usually it's best to
  18 keep them all together though.) They have their own namespace apart from
  19 all the other "types" in Perl.  This means that if you have a function
  20 named "Foo", it is not the same thing as having a format named "Foo".
  21 However, the default name for the format associated with a given
  22 filehandle is the same as the name of the filehandle.  Thus, the default
  23 format for STDOUT is name "STDOUT", and the default format for filehandle
  24 TEMP is name "TEMP".  They just look the same.  They aren't.
  25
  26 Output record formats are declared as follows:
  27
  28     format NAME =
  29     FORMLIST
  30     .
  31
  32 If name is omitted, format "STDOUT" is defined.  FORMLIST consists of a
  33 sequence of lines, each of which may be of one of three types:
  34
  35 =over 4
  36
  37 =item 1.
  38
  39 A comment, indicated by putting a '#' in the first column.
  40
  41 =item 2.
  42
  43 A "picture" line giving the format for one output line.
  44
  45 =item 3.
  46
  47 An argument line supplying values to plug into the previous picture line.
  48
  49 =back
  50
  51 Picture lines are printed exactly as they look, except for certain fields
  52 that substitute values into the line.  Each field in a picture line starts
  53 with either "@" (at) or "^" (caret).  These lines do not undergo any kind
  54 of variable interpolation.  The at field (not to be confused with the array
  55 marker @) is the normal kind of field; the other kind, caret fields, are used
  56 to do rudimentary multi-line text block filling.  The length of the field
  57 is supplied by padding out the field with multiple "<", ">", or "|"
  58 characters to specify, respectively, left justification, right
  59 justification, or centering.  If the variable would exceed the width
  60 specified, it is truncated.
  61
  62 As an alternate form of right justification, you may also use "#"
  63 characters (with an optional ".") to specify a numeric field.  This way
  64 you can line up the decimal points.  If any value supplied for these
  65 fields contains a newline, only the text up to the newline is printed.
  66 Finally, the special field "@*" can be used for printing multi-line,
  67 non-truncated values; it should appear by itself on a line.
  68
  69 The values are specified on the following line in the same order as
  70 the picture fields.  The expressions providing the values should be
  71 separated by commas.  The expressions are all evaluated in a list context
  72 before the line is processed, so a single list expression could produce
  73 multiple list elements.  The expressions may be spread out to more than
  74 one line if enclosed in braces.  If so, the opening brace must be the first
  75 token on the first line.
  76
  77 Picture fields that begin with ^ rather than @ are treated specially.
  78 With a # field, the field is blanked out if the value is undefined.  For
  79 other field types, the caret enables a kind of fill mode.  Instead of an
  80 arbitrary expression, the value supplied must be a scalar variable name
  81 that contains a text string.  Perl puts as much text as it can into the
  82 field, and then chops off the front of the string so that the next time
  83 the variable is referenced, more of the text can be printed.  (Yes, this
  84 means that the variable itself is altered during execution of the write()
  85 call, and is not returned.)  Normally you would use a sequence of fields
  86 in a vertical stack to print out a block of text.  You might wish to end
  87 the final field with the text "...", which will appear in the output if
  88 the text was too long to appear in its entirety.  You can change which
  89 characters are legal to break on by changing the variable C<$:> (that's
  90 $FORMAT_LINE_BREAK_CHARACTERS if you're using the English module) to a
  91 list of the desired characters.
  92
  93 Using caret fields can produce variable length records.  If the text
  94 to be formatted is short, you can suppress blank lines by putting a
  95 "~" (tilde) character anywhere in the line.  The tilde will be translated
  96 to a space upon output.  If you put a second tilde contiguous to the
  97 first, the line will be repeated until all the fields on the line are
  98 exhausted.  (If you use a field of the at variety, the expression you
  99 supply had better not give the same value every time forever!)
 100
 101 Top-of-form processing is by default handled by a format with the
 102 same name as the current filehandle with "_TOP" concatenated to it.
 103 It's triggered at the top of each page.  See L<perlfunc/write>.
 104
 105 Examples:
 106
 107  # a report on the /etc/passwd file
 108  format STDOUT_TOP =
 109                          Passwd File
 110  Name                Login    Office   Uid   Gid Home
 111  ------------------------------------------------------------------
 112  .
 113  format STDOUT =
 114  @<<<<<<<<<<<<<<<<<< @||||||| @<<<<<<@>>>> @>>>> @<<<<<<<<<<<<<<<<<
 115  $name,              $login,  $office,$uid,$gid, $home
 116  .
 117
 118
 119  # a report from a bug report form
 120  format STDOUT_TOP =
 121                          Bug Reports
 122  @<<<<<<<<<<<<<<<<<<<<<<<     @|||         @>>>>>>>>>>>>>>>>>>>>>>>
 123  $system,                      $%,         $date
 124  ------------------------------------------------------------------
 125  .
 126  format STDOUT =
 127  Subject: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 128           $subject
 129  Index: @<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 130         $index,                       $description
 131  Priority: @<<<<<<<<<< Date: @<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 132            $priority,        $date,   $description
 133  From: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 134        $from,                         $description
 135  Assigned to: @<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 136               $programmer,            $description
 137  ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 138                                       $description
 139  ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 140                                       $description
 141  ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 142                                       $description
 143  ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 144                                       $description
 145  ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<...
 146                                       $description
 147  .
 148
 149 It is possible to intermix print()s with write()s on the same output
 150 channel, but you'll have to handle $- ($FORMAT_LINES_LEFT)
 151 yourself.
 152
 153 =head2 Format Variables
 154
 155 The current format name is stored in the variable C<$~> ($FORMAT_NAME),
 156 and the current top of form format name is in C<$^> ($FORMAT_TOP_NAME).
 157 The current output page number is stored in C<$%> ($FORMAT_PAGE_NUMBER),
 158 and the number of lines on the page is in C<$=> ($FORMAT_LINES_PER_PAGE).
 159 Whether to autoflush output on this handle is stored in C<$|>
 160 ($OUTPUT_AUTOFLUSH).  The string output before each top of page (except
 161 the first) is stored in C<$^L> ($FORMAT_FORMFEED).  These variables are
 162 set on a per-filehandle basis, so you'll need to select() into a different
 163 one to affect them:
 164
 165     select((select(OUTF),
 166             $~ = "My_Other_Format",
 167             $^ = "My_Top_Format"
 168            )[0]);
 169
 170 Pretty ugly, eh?  It's a common idiom though, so don't be too surprised
 171 when you see it.  You can at least use a temporary variable to hold
 172 the previous filehandle: (this is a much better approach in general,
 173 because not only does legibility improve, you now have intermediary
 174 stage in the expression to single-step the debugger through):
 175
 176     $ofh = select(OUTF);
 177     $~ = "My_Other_Format";
 178     $^ = "My_Top_Format";
 179     select($ofh);
 180
 181 If you use the English module, you can even read the variable names:
 182
 183     use English;
 184     $ofh = select(OUTF);
 185     $FORMAT_NAME     = "My_Other_Format";
 186     $FORMAT_TOP_NAME = "My_Top_Format";
 187     select($ofh);
 188
 189 But you still have those funny select()s.  So just use the FileHandle
 190 module.  Now, you can access these special variables using lower-case
 191 method names instead:
 192
 193     use FileHandle;
 194     format_name     OUTF "My_Other_Format";
 195     format_top_name OUTF "My_Top_Format";
 196
 197 Much better!
 198
 199 =head1 NOTES
 200
 201 Since the values line may contain arbitrary expressions (for at fields,
 202 not caret fields), you can farm out more sophisticated processing
 203 to other functions, like sprintf() or one of your own.  For example:
 204
 205     format Ident =
 206         @<<<<<<<<<<<<<<<
 207         &commify($n)
 208     .
 209
 210 To get a real at or caret into the field, do this:
 211
 212     format Ident =
 213     I have an @ here.
 214             "@"
 215     .
 216
 217 To center a whole line of text, do something like this:
 218
 219     format Ident =
 220     @|||||||||||||||||||||||||||||||||||||||||||||||
 221             "Some text line"
 222     .
 223
 224 There is no builtin way to say "float this to the right hand side
 225 of the page, however wide it is."  You have to specify where it goes.
 226 The truly desperate can generate their own format on the fly, based
 227 on the current number of columns, and then eval() it:
 228
 229     $format  = "format STDOUT = \n";
 230              . '^' . '<' x $cols . "\n";
 231              . '$entry' . "\n";
 232              . "\t^" . "<" x ($cols-8) . "~~\n";
 233              . '$entry' . "\n";
 234              . ".\n";
 235     print $format if $Debugging;
 236     eval $format;
 237     die $@ if $@;
 238
 239 Which would generate a format looking something like this:
 240
 241  format STDOUT =
 242  ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 243  $entry
 244          ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~
 245  $entry
 246  .
 247
 248 Here's a little program that's somewhat like fmt(1):
 249
 250  format =
 251  ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~
 252  $_
 253
 254  .
 255
 256  $/ = '';
 257  while (<>) {
 258      s/\s*\n\s*/ /g;
 259      write;
 260  }
 261
 262 =head2 Footers
 263
 264 While $FORMAT_TOP_NAME contains the name of the current header format,
 265 there is no corresponding mechanism to automatically do the same thing
 266 for a footer.  Not knowing how big a format is going to be until you
 267 evaluate it is one of the major problems.  It's on the TODO list.
 268
 269 Here's one strategy:  If you have a fixed-size footer, you can get footers
 270 by checking $FORMAT_LINES_LEFT before each write() and print the footer
 271 yourself if necessary.
 272
 273 Here's another strategy; open a pipe to yourself, using C<open(MESELF, "|-")>
 274 (see L<perlfunc/open()>) and always write() to MESELF instead of
 275 STDOUT.  Have your child process massage its STDIN to rearrange
 276 headers and footers however you like.  Not very convenient, but doable.
 277
 278 =head2 Accessing Formatting Internals
 279
 280 For low-level access to the formatting mechanism.  you may use formline()
 281 and access C<$^A> (the $ACCUMULATOR variable) directly.
 282
 283 For example:
 284
 285     $str = formline <<'END', 1,2,3;
 286     @<<<  @|||  @>>>
 287     END
 288
 289     print "Wow, I just stored `$^A' in the accumulator!\n";
 290
 291 Or to make an swrite() subroutine which is to write() what sprintf()
 292 is to printf(), do this:
 293
 294     use Carp;
 295     sub swrite {
 296         croak "usage: swrite PICTURE ARGS" unless @_;
 297         my $format = shift;
 298         $^A = "";
 299         formline($format,@_);
 300         return $^A;
 301     }
 302
 303     $string = swrite(<<'END', 1, 2, 3);
 304  Check me out
 305  @<<<  @|||  @>>>
 306  END
 307     print $string;
 308
 309 =head1 WARNING
 310
 311 Lexical variables (declared with "my") are not visible within a
 312 format unless the format is declared within the scope of the lexical
 313 variable.  (They weren't visible at all before version 5.001.)  Furthermore,
 314 lexical aliases will not be compiled correctly: see
 315 L<perlfunc/my> for other issues.