1N/Aperlform - Perl formats
1N/APerl has a mechanism to help you generate simple reports and charts. To
1N/Afacilitate this, Perl helps you code up your output page close to how it
1N/Awill look when it's printed. It can keep track of things like how many
1N/Alines are on a page, what page you're on, when to print page headers,
1N/Aetc. Keywords are borrowed from FORTRAN: format() to declare and write()
1N/Ato execute; see their entries in L<perlfunc>. Fortunately, the layout is
1N/Amuch more legible, more like BASIC's PRINT USING statement. Think of it
1N/Aas a poor man's nroff(1).
1N/AFormats, like packages and subroutines, are declared rather than
1N/Aexecuted, so they may occur at any point in your program. (Usually it's
1N/Abest to keep them all together though.) They have their own namespace
1N/Aapart from all the other "types" in Perl. This means that if you have a
1N/Afunction named "Foo", it is not the same thing as having a format named
1N/A"Foo". However, the default name for the format associated with a given
1N/Afilehandle is the same as the name of the filehandle. Thus, the default
1N/Aformat for STDOUT is named "STDOUT", and the default format for filehandle
1N/ATEMP is named "TEMP". They just look the same. They aren't.
1N/AOutput record formats are declared as follows:
1N/AIf the name is omitted, format "STDOUT" is defined. A single "." in
1N/Acolumn 1 is used to terminate a format. FORMLIST consists of a sequence
1N/Aof lines, each of which may be one of three types:
1N/AA comment, indicated by putting a '#' in the first column.
1N/AA "picture" line giving the format for one output line.
1N/AAn argument line supplying values to plug into the previous picture line.
1N/APicture lines contain output field definitions, intermingled with
1N/Aliteral text. These lines do not undergo any kind of variable interpolation.
1N/AField definitions are made up from a set of characters, for starting and
1N/Aextending a field to its desired width. This is the complete set of
1N/Acharacters for field definitions:
1N/A @ start of regular field
1N/A ^ start of special field
1N/A < pad character for left adjustification
1N/A | pad character for centering
1N/A > pad character for right adjustificat
1N/A # pad character for a right justified numeric field
1N/A 0 instead of first #: pad number with leading zeroes
1N/A . decimal point within a numeric field
1N/A ... terminate a text field, show "..." as truncation evidence
1N/A @* variable width field for a multi-line value
1N/A ^* variable width field for next line of a multi-line value
1N/A ~ suppress line with all fields empty
1N/A ~~ repeat line until all fields are exhausted
1N/AEach field in a picture line starts with either "@" (at) or "^" (caret),
1N/Aindicating what we'll call, respectively, a "regular" or "special" field.
1N/AThe choice of pad characters determines whether a field is textual or
1N/Anumeric. The tilde operators are not part of a field. Let's look at
1N/Athe various possibilities in detail.
1N/AThe length of the field is supplied by padding out the field with multiple
1N/A"E<lt>", "E<gt>", or "|" characters to specify a non-numeric field with,
1N/Arespectively, left justification, right justification, or centering.
1N/AFor a regular field, the value (up to the first newline) is taken and
1N/Aprinted according to the selected justification, truncating excess characters.
1N/AIf you terminate a text field with "...", three dots will be shown if
1N/Athe value is truncated. A special text field may be used to do rudimentary
1N/Amulti-line text block filling; see L</Using Fill Mode> for details.
1N/A @<<<<<< @|||||| @>>>>>>
1N/A "left", "middle", "right"
1N/A=head2 Numeric Fields
1N/AUsing "#" as a padding character specifies a numeric field, with
1N/Aright justification. An optional "." defines the position of the
1N/Adecimal point. With a "0" (zero) instead of the first "#", the
1N/Aformatted number will be padded with leading zeroes if necessary.
1N/AA special numeric field is blanked out if the value is undefined.
1N/AIf the resulting value would exceed the width specified the field is
1N/Afilled with "#" as overflow evidence.
1N/A @### @.### @##.### @### @### ^####
1N/A 42, 3.1415, undef, 0, 10000, undef
1N/A 42 3.142 0.000 0 ####
1N/A=head2 The Field @* for Variable Width Multi-Line Text
1N/AThe field "@*" can be used for printing multi-line, nontruncated
1N/Avalues; it should (but need not) appear by itself on a line. A final
1N/Aline feed is chomped off, but all other characters are emitted verbatim.
1N/A=head2 The Field ^* for Variable Width One-line-at-a-time Text
1N/ALike "@*", this is a variable width field. The value supplied must be a
1N/Ascalar variable. Perl puts the first line (up to the first "\n") of the
1N/Atext into the field, and then chops off the front of the string so that
1N/Athe next time the variable is referenced, more of the text can be printed.
1N/AThe variable will I<not> be restored.
1N/A $text = "line 1\nline 2\nline 3";
1N/A=head2 Specifying Values
1N/AThe values are specified on the following format line in the same order as
1N/Athe picture fields. The expressions providing the values must be
1N/Aseparated by commas. They are all evaluated in a list context
1N/Abefore the line is processed, so a single list expression could produce
1N/Amultiple list elements. The expressions may be spread out to more than
1N/Aone line if enclosed in braces. If so, the opening brace must be the first
1N/Atoken on the first line. If an expression evaluates to a number with a
1N/Adecimal part, and if the corresponding picture specifies that the decimal
1N/Apart should appear in the output (that is, any picture except multiple "#"
1N/Acharacters B<without> an embedded "."), the character used for the decimal
1N/Apoint is B<always> determined by the current LC_NUMERIC locale. This
1N/Ameans that, if, for example, the run-time environment happens to specify a
1N/AGerman locale, "," will be used instead of the default ".". See
1N/AL<perllocale> and L<"WARNINGS"> for more information.
1N/A=head2 Using Fill Mode
1N/AOn text fields the caret enables a kind of fill mode. Instead of an
1N/Aarbitrary expression, the value supplied must be a scalar variable
1N/Athat contains a text string. Perl puts the next portion of the text into
1N/Athe field, and then chops off the front of the string so that the next time
1N/Athe variable is referenced, more of the text can be printed. (Yes, this
1N/Ameans that the variable itself is altered during execution of the write()
1N/Acall, and is not restored.) The next portion of text is determined by
1N/Aa crude line breaking algorithm. You may use the carriage return character
1N/A(C<\r>) to force a line break. You can change which characters are legal
1N/Ato break on by changing the variable C<$:> (that's
1N/A$FORMAT_LINE_BREAK_CHARACTERS if you're using the English module) to a
1N/Alist of the desired characters.
1N/ANormally you would use a sequence of fields in a vertical stack associated
1N/Awith the same scalar variable to print out a block of text. You might wish
1N/Ato end the final field with the text "...", which will appear in the output
1N/Aif the text was too long to appear in its entirety.
1N/A=head2 Suppressing Lines Where All Fields Are Void
1N/AUsing caret fields can produce lines where all fields are blank. You can
1N/Asuppress such lines by putting a "~" (tilde) character anywhere in the
1N/Aline. The tilde will be translated to a space upon output.
1N/A=head2 Repeating Format Lines
1N/AIf you put two contiguous tilde characters "~~" anywhere into a line,
1N/Athe line will be repeated until all the fields on the line are exhausted,
1N/Ai.e. undefined. For special (caret) text fields this will occur sooner or
1N/Alater, but if you use a text field of the at variety, the expression you
1N/Asupply had better not give the same value every time forever! (C<shift(@f)>
1N/Ais a simple example that would work.) Don't use a regular (at) numeric
1N/Afield in such lines, because it will never go blank.
1N/A=head2 Top of Form Processing
1N/ATop-of-form processing is by default handled by a format with the
1N/Asame name as the current filehandle with "_TOP" concatenated to it.
1N/A Name Login Office Uid Gid Home
1N/A ------------------------------------------------------------------
1N/A @<<<<<<<<<<<<<<<<<< @||||||| @<<<<<<@>>>> @>>>> @<<<<<<<<<<<<<<<<<
1N/A $name, $login, $office,$uid,$gid, $home
1N/A # a report from a bug report form
1N/A @<<<<<<<<<<<<<<<<<<<<<<< @||| @>>>>>>>>>>>>>>>>>>>>>>>
1N/A ------------------------------------------------------------------
1N/A Subject: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
1N/A Index: @<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
1N/A $index, $description
1N/A Priority: @<<<<<<<<<< Date: @<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
1N/A $priority, $date, $description
1N/A From: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
1N/A Assigned to: @<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
1N/A $programmer, $description
1N/A ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
1N/A ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
1N/A ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
1N/A ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
1N/A ~ ^<<<<<<<<<<<<<<<<<<<<<<<...
1N/AIt is possible to intermix print()s with write()s on the same output
1N/Achannel, but you'll have to handle C<$-> (C<$FORMAT_LINES_LEFT>)
1N/A=head2 Format Variables
1N/AThe current format name is stored in the variable C<$~> (C<$FORMAT_NAME>),
1N/Aand the current top of form format name is in C<$^> (C<$FORMAT_TOP_NAME>).
1N/AThe current output page number is stored in C<$%> (C<$FORMAT_PAGE_NUMBER>),
1N/Aand the number of lines on the page is in C<$=> (C<$FORMAT_LINES_PER_PAGE>).
1N/AWhether to autoflush output on this handle is stored in C<$|>
1N/A(C<$OUTPUT_AUTOFLUSH>). The string output before each top of page (except
1N/Athe first) is stored in C<$^L> (C<$FORMAT_FORMFEED>). These variables are
1N/Aset on a per-filehandle basis, so you'll need to select() into a different
1N/A select((select(OUTF),
1N/A $~ = "My_Other_Format",
1N/A $^ = "My_Top_Format"
1N/APretty ugly, eh? It's a common idiom though, so don't be too surprised
1N/Awhen you see it. You can at least use a temporary variable to hold
1N/Athe previous filehandle: (this is a much better approach in general,
1N/Abecause not only does legibility improve, you now have intermediary
1N/Astage in the expression to single-step the debugger through):
1N/A $ofh = select(OUTF);
1N/A $~ = "My_Other_Format";
1N/A $^ = "My_Top_Format";
1N/AIf you use the English module, you can even read the variable names:
1N/A use English '-no_match_vars';
1N/A $ofh = select(OUTF);
1N/A $FORMAT_NAME = "My_Other_Format";
1N/A $FORMAT_TOP_NAME = "My_Top_Format";
1N/ABut you still have those funny select()s. So just use the FileHandle
1N/Amodule. Now, you can access these special variables using lowercase
1N/Amethod names instead:
1N/A format_name OUTF "My_Other_Format";
1N/A format_top_name OUTF "My_Top_Format";
1N/ABecause the values line may contain arbitrary expressions (for at fields,
1N/Anot caret fields), you can farm out more sophisticated processing
1N/Ato other functions, like sprintf() or one of your own. For example:
1N/ATo get a real at or caret into the field, do this:
1N/ATo center a whole line of text, do something like this:
1N/A @|||||||||||||||||||||||||||||||||||||||||||||||
1N/AThere is no builtin way to say "float this to the right hand side
1N/Aof the page, however wide it is." You have to specify where it goes.
1N/AThe truly desperate can generate their own format on the fly, based
1N/Aon the current number of columns, and then eval() it:
1N/A $format = "format STDOUT = \n"
1N/A . '^' . '<' x $cols . "\n"
1N/A . "\t^" . "<" x ($cols-8) . "~~\n"
1N/A print $format if $Debugging;
1N/AWhich would generate a format looking something like this:
1N/A ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
1N/A ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~
1N/AHere's a little program that's somewhat like fmt(1):
1N/A ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~
1N/AWhile $FORMAT_TOP_NAME contains the name of the current header format,
1N/Athere is no corresponding mechanism to automatically do the same thing
1N/Afor a footer. Not knowing how big a format is going to be until you
1N/Aevaluate it is one of the major problems. It's on the TODO list.
1N/AHere's one strategy: If you have a fixed-size footer, you can get footers
1N/Aby checking $FORMAT_LINES_LEFT before each write() and print the footer
1N/Ayourself if necessary.
1N/AHere's another strategy: Open a pipe to yourself, using C<open(MYSELF, "|-")>
1N/AHave your child process massage its STDIN to rearrange headers and footers
1N/Ahowever you like. Not very convenient, but doable.
1N/A=head2 Accessing Formatting Internals
1N/AFor low-level access to the formatting mechanism. you may use formline()
1N/Aand access C<$^A> (the $ACCUMULATOR variable) directly.
1N/A $str = formline <<'END', 1,2,3;
1N/A print "Wow, I just stored `$^A' in the accumulator!\n";
1N/AOr to make an swrite() subroutine, which is to write() what sprintf()
1N/Ais to printf(), do this:
1N/A croak "usage: swrite PICTURE ARGS" unless @_;
1N/A formline($format,@_);
1N/A $string = swrite(<<'END', 1, 2, 3);
1N/AThe lone dot that ends a format can also prematurely end a mail
1N/Amessage passing through a misconfigured Internet mailer (and based on
1N/Aexperience, such misconfiguration is the rule, not the exception). So
1N/Awhen sending format code through mail, you should indent it so that
1N/Athe format-ending dot is not on the left margin; this will prevent
1N/ALexical variables (declared with "my") are not visible within a
1N/Aformat unless the format is declared within the scope of the lexical
1N/Avariable. (They weren't visible at all before version 5.001.)
1N/AFormats are the only part of Perl that unconditionally use information
1N/Afrom a program's locale; if a program's environment specifies an
1N/ALC_NUMERIC locale, it is always used to specify the decimal point
1N/Acharacter in formatted output. Perl ignores all other aspects of locale
1N/Ahandling unless the C<use locale> pragma is in effect. Formatted output
1N/Acannot be controlled by C<use locale> because the pragma is tied to the
1N/Ablock structure of the program, and, for historical reasons, formats
1N/Aexist outside that block structure. See L<perllocale> for further
1N/Adiscussion of locale handling.
1N/AWithin strings that are to be displayed in a fixed length text field,
1N/Aeach control character is substituted by a space. (But remember the
1N/Aspecial meaning of C<\r> when using fill mode.) This is done to avoid
1N/Amisalignment when control characters "disappear" on some output media.