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