Debian Codegraph @

upstream/debian-unstable/man1/perlform.1

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