This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlform: #109408
[perl5.git] / pod / perlform.pod
CommitLineData
a0d0e21e 1=head1 NAME
d74e8afc 2X<format> X<report> X<chart>
a0d0e21e
LW
3
4perlform - Perl formats
5
6=head1 DESCRIPTION
7
8Perl has a mechanism to help you generate simple reports and charts. To
54310121
PP
9facilitate this, Perl helps you code up your output page close to how it
10will look when it's printed. It can keep track of things like how many
11lines are on a page, what page you're on, when to print page headers,
12etc. Keywords are borrowed from FORTRAN: format() to declare and write()
13to execute; see their entries in L<perlfunc>. Fortunately, the layout is
14much more legible, more like BASIC's PRINT USING statement. Think of it
15as a poor man's nroff(1).
d74e8afc 16X<nroff>
54310121
PP
17
18Formats, like packages and subroutines, are declared rather than
19executed, so they may occur at any point in your program. (Usually it's
20best to keep them all together though.) They have their own namespace
21apart from all the other "types" in Perl. This means that if you have a
22function named "Foo", it is not the same thing as having a format named
23"Foo". However, the default name for the format associated with a given
a0d0e21e 24filehandle is the same as the name of the filehandle. Thus, the default
7b8d334a
GS
25format for STDOUT is named "STDOUT", and the default format for filehandle
26TEMP is named "TEMP". They just look the same. They aren't.
a0d0e21e
LW
27
28Output record formats are declared as follows:
29
30 format NAME =
31 FORMLIST
32 .
33
a1b95068
LW
34If the name is omitted, format "STDOUT" is defined. A single "." in
35column 1 is used to terminate a format. FORMLIST consists of a sequence
36of lines, each of which may be one of three types:
a0d0e21e
LW
37
38=over 4
39
40=item 1.
41
42A comment, indicated by putting a '#' in the first column.
43
44=item 2.
45
46A "picture" line giving the format for one output line.
47
48=item 3.
49
50An argument line supplying values to plug into the previous picture line.
51
52=back
53
a1b95068
LW
54Picture lines contain output field definitions, intermingled with
55literal text. These lines do not undergo any kind of variable interpolation.
56Field definitions are made up from a set of characters, for starting and
57extending a field to its desired width. This is the complete set of
58characters for field definitions:
d74e8afc
ITB
59X<format, picture line>
60X<@> X<^> X<< < >> X<< | >> X<< > >> X<#> X<0> X<.> X<...>
61X<@*> X<^*> X<~> X<~~>
f4084e39 62
a1b95068
LW
63 @ start of regular field
64 ^ start of special field
9c7085be 65 < pad character for left justification
a1b95068 66 | pad character for centering
9c7085be 67 > pad character for right justification
6dd37ebe 68 # pad character for a right-justified numeric field
a1b95068
LW
69 0 instead of first #: pad number with leading zeroes
70 . decimal point within a numeric field
71 ... terminate a text field, show "..." as truncation evidence
72 @* variable width field for a multi-line value
73 ^* variable width field for next line of a multi-line value
74 ~ suppress line with all fields empty
75 ~~ repeat line until all fields are exhausted
76
77Each field in a picture line starts with either "@" (at) or "^" (caret),
78indicating what we'll call, respectively, a "regular" or "special" field.
79The choice of pad characters determines whether a field is textual or
80numeric. The tilde operators are not part of a field. Let's look at
81the various possibilities in detail.
82
83
84=head2 Text Fields
d74e8afc 85X<format, text field>
a1b95068
LW
86
87The length of the field is supplied by padding out the field with multiple
88"E<lt>", "E<gt>", or "|" characters to specify a non-numeric field with,
89respectively, left justification, right justification, or centering.
90For a regular field, the value (up to the first newline) is taken and
91printed according to the selected justification, truncating excess characters.
92If you terminate a text field with "...", three dots will be shown if
93the value is truncated. A special text field may be used to do rudimentary
94multi-line text block filling; see L</Using Fill Mode> for details.
95
96 Example:
97 format STDOUT =
98 @<<<<<< @|||||| @>>>>>>
99 "left", "middle", "right"
100 .
101 Output:
102 left middle right
103
104
105=head2 Numeric Fields
d74e8afc 106X<#> X<format, numeric field>
a1b95068
LW
107
108Using "#" as a padding character specifies a numeric field, with
109right justification. An optional "." defines the position of the
110decimal point. With a "0" (zero) instead of the first "#", the
111formatted number will be padded with leading zeroes if necessary.
112A special numeric field is blanked out if the value is undefined.
113If the resulting value would exceed the width specified the field is
114filled with "#" as overflow evidence.
115
116 Example:
117 format STDOUT =
118 @### @.### @##.### @### @### ^####
119 42, 3.1415, undef, 0, 10000, undef
120 .
121 Output:
122 42 3.142 0.000 0 ####
123
124
6dd37ebe 125=head2 The Field @* for Variable-Width Multi-Line Text
d74e8afc 126X<@*>
a1b95068
LW
127
128The field "@*" can be used for printing multi-line, nontruncated
129values; it should (but need not) appear by itself on a line. A final
130line feed is chomped off, but all other characters are emitted verbatim.
131
132
6dd37ebe 133=head2 The Field ^* for Variable-Width One-line-at-a-time Text
d74e8afc 134X<^*>
a1b95068 135
6dd37ebe 136Like "@*", this is a variable-width field. The value supplied must be a
a1b95068
LW
137scalar variable. Perl puts the first line (up to the first "\n") of the
138text into the field, and then chops off the front of the string so that
139the next time the variable is referenced, more of the text can be printed.
140The variable will I<not> be restored.
141
142 Example:
143 $text = "line 1\nline 2\nline 3";
144 format STDOUT =
145 Text: ^*
146 $text
147 ~~ ^*
148 $text
149 .
150 Output:
151 Text: line 1
152 line 2
153 line 3
154
155
156=head2 Specifying Values
d74e8afc 157X<format, specifying values>
a1b95068
LW
158
159The values are specified on the following format line in the same order as
160the picture fields. The expressions providing the values must be
161separated by commas. They are all evaluated in a list context
a0d0e21e
LW
162before the line is processed, so a single list expression could produce
163multiple list elements. The expressions may be spread out to more than
164one line if enclosed in braces. If so, the opening brace must be the first
a034a98d
DD
165token on the first line. If an expression evaluates to a number with a
166decimal part, and if the corresponding picture specifies that the decimal
167part should appear in the output (that is, any picture except multiple "#"
168characters B<without> an embedded "."), the character used for the decimal
903eb63f
NT
169point is determined by the current LC_NUMERIC locale if C<use locale> is in
170effect. This means that, if, for example, the run-time environment happens
171to specify a German locale, "," will be used instead of the default ".". See
a034a98d 172L<perllocale> and L<"WARNINGS"> for more information.
a0d0e21e 173
a1b95068
LW
174
175=head2 Using Fill Mode
d74e8afc 176X<format, fill mode>
a1b95068
LW
177
178On text fields the caret enables a kind of fill mode. Instead of an
179arbitrary expression, the value supplied must be a scalar variable
180that contains a text string. Perl puts the next portion of the text into
181the field, and then chops off the front of the string so that the next time
a0d0e21e
LW
182the variable is referenced, more of the text can be printed. (Yes, this
183means that the variable itself is altered during execution of the write()
a1b95068 184call, and is not restored.) The next portion of text is determined by
6dd37ebe 185a crude line-breaking algorithm. You may use the carriage return character
a1b95068
LW
186(C<\r>) to force a line break. You can change which characters are legal
187to break on by changing the variable C<$:> (that's
188$FORMAT_LINE_BREAK_CHARACTERS if you're using the English module) to a
a0d0e21e
LW
189list of the desired characters.
190
a1b95068
LW
191Normally you would use a sequence of fields in a vertical stack associated
192with the same scalar variable to print out a block of text. You might wish
193to end the final field with the text "...", which will appear in the output
194if the text was too long to appear in its entirety.
195
196
197=head2 Suppressing Lines Where All Fields Are Void
d74e8afc 198X<format, suppressing lines>
a1b95068
LW
199
200Using caret fields can produce lines where all fields are blank. You can
201suppress such lines by putting a "~" (tilde) character anywhere in the
202line. The tilde will be translated to a space upon output.
203
204
205=head2 Repeating Format Lines
d74e8afc 206X<format, repeating lines>
a1b95068
LW
207
208If you put two contiguous tilde characters "~~" anywhere into a line,
209the line will be repeated until all the fields on the line are exhausted,
210i.e. undefined. For special (caret) text fields this will occur sooner or
211later, but if you use a text field of the at variety, the expression you
212supply had better not give the same value every time forever! (C<shift(@f)>
213is a simple example that would work.) Don't use a regular (at) numeric
214field in such lines, because it will never go blank.
215
216
217=head2 Top of Form Processing
d74e8afc 218X<format, top of form> X<top> X<header>
a0d0e21e 219
54310121 220Top-of-form processing is by default handled by a format with the
a0d0e21e 221same name as the current filehandle with "_TOP" concatenated to it.
a2eb9003 222It's triggered at the top of each page. See L<perlfunc/write>.
a0d0e21e
LW
223
224Examples:
225
226 # a report on the /etc/passwd file
227 format STDOUT_TOP =
228 Passwd File
229 Name Login Office Uid Gid Home
230 ------------------------------------------------------------------
231 .
232 format STDOUT =
233 @<<<<<<<<<<<<<<<<<< @||||||| @<<<<<<@>>>> @>>>> @<<<<<<<<<<<<<<<<<
234 $name, $login, $office,$uid,$gid, $home
235 .
236
237
238 # a report from a bug report form
239 format STDOUT_TOP =
240 Bug Reports
241 @<<<<<<<<<<<<<<<<<<<<<<< @||| @>>>>>>>>>>>>>>>>>>>>>>>
242 $system, $%, $date
243 ------------------------------------------------------------------
244 .
245 format STDOUT =
246 Subject: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
247 $subject
248 Index: @<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
249 $index, $description
250 Priority: @<<<<<<<<<< Date: @<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
251 $priority, $date, $description
252 From: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
253 $from, $description
254 Assigned to: @<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
255 $programmer, $description
256 ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
257 $description
258 ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
259 $description
260 ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
261 $description
262 ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
263 $description
264 ~ ^<<<<<<<<<<<<<<<<<<<<<<<...
265 $description
266 .
267
268It is possible to intermix print()s with write()s on the same output
1fef88e7 269channel, but you'll have to handle C<$-> (C<$FORMAT_LINES_LEFT>)
a0d0e21e
LW
270yourself.
271
272=head2 Format Variables
d74e8afc
ITB
273X<format variables>
274X<format, variables>
a0d0e21e 275
1fef88e7
JM
276The current format name is stored in the variable C<$~> (C<$FORMAT_NAME>),
277and the current top of form format name is in C<$^> (C<$FORMAT_TOP_NAME>).
278The current output page number is stored in C<$%> (C<$FORMAT_PAGE_NUMBER>),
279and the number of lines on the page is in C<$=> (C<$FORMAT_LINES_PER_PAGE>).
748a9306 280Whether to autoflush output on this handle is stored in C<$|>
1fef88e7
JM
281(C<$OUTPUT_AUTOFLUSH>). The string output before each top of page (except
282the first) is stored in C<$^L> (C<$FORMAT_FORMFEED>). These variables are
a0d0e21e
LW
283set on a per-filehandle basis, so you'll need to select() into a different
284one to affect them:
285
54310121 286 select((select(OUTF),
a0d0e21e
LW
287 $~ = "My_Other_Format",
288 $^ = "My_Top_Format"
289 )[0]);
290
291Pretty ugly, eh? It's a common idiom though, so don't be too surprised
292when you see it. You can at least use a temporary variable to hold
293the previous filehandle: (this is a much better approach in general,
6dd37ebe 294because not only does legibility improve, you now have an intermediary
a0d0e21e
LW
295stage in the expression to single-step the debugger through):
296
297 $ofh = select(OUTF);
298 $~ = "My_Other_Format";
299 $^ = "My_Top_Format";
300 select($ofh);
301
302If you use the English module, you can even read the variable names:
303
a1ce9542 304 use English '-no_match_vars';
a0d0e21e
LW
305 $ofh = select(OUTF);
306 $FORMAT_NAME = "My_Other_Format";
307 $FORMAT_TOP_NAME = "My_Top_Format";
308 select($ofh);
309
310But you still have those funny select()s. So just use the FileHandle
68dc0745 311module. Now, you can access these special variables using lowercase
a0d0e21e
LW
312method names instead:
313
314 use FileHandle;
315 format_name OUTF "My_Other_Format";
316 format_top_name OUTF "My_Top_Format";
317
318Much better!
319
320=head1 NOTES
321
54310121 322Because the values line may contain arbitrary expressions (for at fields,
748a9306 323not caret fields), you can farm out more sophisticated processing
a0d0e21e
LW
324to other functions, like sprintf() or one of your own. For example:
325
54310121 326 format Ident =
a0d0e21e
LW
327 @<<<<<<<<<<<<<<<
328 &commify($n)
329 .
330
331To get a real at or caret into the field, do this:
332
54310121 333 format Ident =
a0d0e21e
LW
334 I have an @ here.
335 "@"
336 .
337
338To center a whole line of text, do something like this:
339
54310121 340 format Ident =
a0d0e21e
LW
341 @|||||||||||||||||||||||||||||||||||||||||||||||
342 "Some text line"
343 .
344
345There is no builtin way to say "float this to the right hand side
346of the page, however wide it is." You have to specify where it goes.
347The truly desperate can generate their own format on the fly, based
348on the current number of columns, and then eval() it:
349
5a964f20
TC
350 $format = "format STDOUT = \n"
351 . '^' . '<' x $cols . "\n"
352 . '$entry' . "\n"
353 . "\t^" . "<" x ($cols-8) . "~~\n"
354 . '$entry' . "\n"
a0d0e21e
LW
355 . ".\n";
356 print $format if $Debugging;
54310121 357 eval $format;
a0d0e21e
LW
358 die $@ if $@;
359
360Which would generate a format looking something like this:
361
54310121 362 format STDOUT =
a0d0e21e
LW
363 ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
364 $entry
365 ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~
366 $entry
367 .
368
369Here's a little program that's somewhat like fmt(1):
370
54310121 371 format =
a0d0e21e
LW
372 ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~
373 $_
374
375 .
376
377 $/ = '';
378 while (<>) {
379 s/\s*\n\s*/ /g;
380 write;
54310121 381 }
a0d0e21e
LW
382
383=head2 Footers
d74e8afc 384X<format, footer> X<footer>
a0d0e21e
LW
385
386While $FORMAT_TOP_NAME contains the name of the current header format,
387there is no corresponding mechanism to automatically do the same thing
388for a footer. Not knowing how big a format is going to be until you
389evaluate it is one of the major problems. It's on the TODO list.
390
391Here's one strategy: If you have a fixed-size footer, you can get footers
392by checking $FORMAT_LINES_LEFT before each write() and print the footer
393yourself if necessary.
394
54310121 395Here's another strategy: Open a pipe to yourself, using C<open(MYSELF, "|-")>
3573d649 396(see L<perlfunc/open>) and always write() to MYSELF instead of STDOUT.
54310121
PP
397Have your child process massage its STDIN to rearrange headers and footers
398however you like. Not very convenient, but doable.
a0d0e21e
LW
399
400=head2 Accessing Formatting Internals
d74e8afc 401X<format, internals>
a0d0e21e
LW
402
403For low-level access to the formatting mechanism. you may use formline()
404and access C<$^A> (the $ACCUMULATOR variable) directly.
405
406For example:
407
408 $str = formline <<'END', 1,2,3;
409 @<<< @||| @>>>
410 END
411
ccf3535a 412 print "Wow, I just stored '$^A' in the accumulator!\n";
a0d0e21e 413
5a964f20 414Or to make an swrite() subroutine, which is to write() what sprintf()
a0d0e21e
LW
415is to printf(), do this:
416
a0d0e21e
LW
417 use Carp;
418 sub swrite {
748a9306
LW
419 croak "usage: swrite PICTURE ARGS" unless @_;
420 my $format = shift;
421 $^A = "";
422 formline($format,@_);
423 return $^A;
54310121 424 }
a0d0e21e
LW
425
426 $string = swrite(<<'END', 1, 2, 3);
427 Check me out
428 @<<< @||| @>>>
429 END
430 print $string;
431
a034a98d 432=head1 WARNINGS
a0d0e21e 433
5a964f20 434The lone dot that ends a format can also prematurely end a mail
6aa7c346
CS
435message passing through a misconfigured Internet mailer (and based on
436experience, such misconfiguration is the rule, not the exception). So
5a964f20 437when sending format code through mail, you should indent it so that
6aa7c346 438the format-ending dot is not on the left margin; this will prevent
5a964f20 439SMTP cutoff.
6aa7c346 440
748a9306
LW
441Lexical variables (declared with "my") are not visible within a
442format unless the format is declared within the scope of the lexical
1e29b8f3 443variable.
a034a98d 444
903eb63f
NT
445If a program's environment specifies an LC_NUMERIC locale and C<use
446locale> is in effect when the format is declared, the locale is used
447to specify the decimal point character in formatted output. Formatted
448output cannot be controlled by C<use locale> at the time when write()
449is called. See L<perllocale> for further discussion of locale handling.
c380484f 450
6dd37ebe 451Within strings that are to be displayed in a fixed-length text field,
a1b95068
LW
452each control character is substituted by a space. (But remember the
453special meaning of C<\r> when using fill mode.) This is done to avoid
454misalignment when control characters "disappear" on some output media.
c380484f 455