1Text::Reform(3) User Contributed Perl Documentation Text::Reform(3)
2
6 Text::Reform - Manual text wrapping and reformatting
7
9 This document describes version 1.11 of Text::Reform, released May 7,
10 2003.
11
13 use Text::Reform;
14 print form $template,
16 $data, $to, $fill, $it, $with;
17 use Text::Reform qw( tag );
19 print tag 'B', $enboldened_text;
21
23 The "form" sub
24 The "form()" subroutine may be exported from the module. It takes a
26 series of format (or "picture") strings followed by replacement values,
27 interpolates those values into each picture string, and returns the
28 result. The effect is similar to the inbuilt perl "format" mechanism,
29 although the field specification syntax is simpler and some of the for‐
30 matting behaviour is more sophisticated.
31 A picture string consists of sequences of the following characters:
33 < Left-justified field indicator. A series of two or more
35 sequential <'s specify a left-justified field to be filled by a
36 subsequent value. A single < is formatted as the literal char‐
37 acter '<'
38 > Right-justified field indicator. A series of two or more
40 sequential >'s specify a right-justified field to be filled by
41 a subsequent value. A single < is formatted as the literal
42 character '<'
43 <<<>>> Fully-justified field indicator. Field may be of any width,
45 and brackets need not balance, but there must be at least 2 '<'
46 and 2 '>'.
47 ^ Centre-justified field indicator. A series of two or more
49 sequential ^'s specify a centred field to be filled by a subse‐
50 quent value. A single ^ is formatted as the literal character
51 '<'
52 >>>.<<<<
54 A numerically formatted field with the specified number of dig‐
55 its to either side of the decimal place. See "Numerical format‐
56 ting" below.
57 [ Left-justified block field indicator. Just like a < field,
59 except it repeats as required on subsequent lines. See below.
60 A single [ is formatted as the literal character '['
61 ] Right-justified block field indicator. Just like a > field,
63 except it repeats as required on subsequent lines. See below.
64 A single ] is formatted as the literal character ']'
65 [[[]]] Fully-justified block field indicator. Just like a <<<>>>
67 field, except it repeats as required on subsequent lines. See
68 below. Field may be of any width, and brackets need not bal‐
69 ance, but there must be at least 2 '[' and 2 ']'.
70 ⎪ Centre-justified block field indicator. Just like a ^ field,
72 except it repeats as required on subsequent lines. See below.
73 A single ⎪ is formatted as the literal character '⎪'
74 ]]].[[[[
76 A numerically formatted block field with the specified number
77 of digits to either side of the decimal place. Just like a
78 >>>.<<<< field, except it repeats as required on subsequent
79 lines. See below.
80 ~ A one-character wide block field.
82 \ Literal escape of next character (e.g. "\~" is formatted as
84 '~', not a one character wide block field).
85 Any other character
87 That literal character.
88 Any substitution value which is "undef" (either explicitly so, or
90 because it is missing) is replaced by an empty string.
91 Controlling line filling.
93 Note that, unlike the a perl "format", "form" preserves whitespace
95 (including newlines) unless called with certain options.
96 The "squeeze" option (when specified with a true value) causes any
98 sequence of spaces and/or tabs (but not newlines) in an interpolated
99 string to be replaced with a single space.
100 A true value for the "fill" option causes (only) newlines to be
102 squeezed.
103 To minimize all whitespace, you need to specify both options. Hence:
105 $format = "EG> [[[[[[[[[[[[[[[[[[[[[";
107 $data = "h e\t l lo\nworld\t\t\t\t\t";
108 print form $format, $data; # all whitespace preserved:
110 #
111 # EG> h e l lo
112 # EG> world
113 print form {squeeze=>1}, # only newlines preserved:
115 $format, $data; #
116 # EG> h e l lo
117 # EG> world
118 print form {fill=>1}, # only spaces/tabs preserved:
120 $format, $data; #
121 # EG> h e l lo world
122 print form {squeeze=>1, fill=>1}, # no whitespace preserved:
124 $format, $data; #
125 # EG> h e l lo world
126 Whether or not filling or squeezing is in effect, "form" can also be
128 directed to trim any extra whitespace from the end of each line it for‐
129 mats, using the "trim" option. If this option is specified with a true
130 value, every line returned by "form" will automatically have the sub‐
131 stitution "s/[ \t]+$//gm" applied to it.
132 Hence:
134 print length form "[[[[[[[[[[", "short";
136 # 11
137 print length form {trim=>1}, "[[[[[[[[[[", "short";
139 # 6
140 It is also possible to control the character used to fill lines that
142 are too short, using the 'filler' option. If this option is specified
143 the value of the 'filler' flag is used as the fill string, rather than
144 the default " ".
145 For example:
147 print form { filler=>'*' },
149 "Pay bearer: ^^^^^^^^^^^^^^^^^^^",
150 '$123.45';
151 prints:
153 Pay bearer: ******$123.45******
155 If the filler string is longer than one character, it is truncated to
157 the appropriate length. So:
158 print form { filler=>'-->' },
160 "Pay bearer: ]]]]]]]]]]]]]]]]]]]",
161 ['$1234.50', '$123.45', '$12.34'];
162 prints:
164 Pay bearer: ->-->-->-->$1234.50
166 Pay bearer: -->-->-->-->$123.45
167 Pay bearer: >-->-->-->-->$12.34
168 If the value of the 'filler' option is a hash, then it's 'left' and
170 'right' entries specify separate filler strings for each side of an
171 interpolated value. So:
172 print form { filler=>{left=>'->', right=>'*'} },
174 "Pay bearer: <<<<<<<<<<<<<<<<<<",
175 '$123.45',
176 "Pay bearer: >>>>>>>>>>>>>>>>>>",
177 '$123.45',
178 "Pay bearer: ^^^^^^^^^^^^^^^^^^",
179 '$123.45';
180 prints:
182 Pay bearer: $123.45***********
184 Pay bearer: >->->->->->$123.45
185 Pay bearer: >->->$123.45******
186 Temporary and permanent default options
188 If "form" is called with options, but no template string or data, it
190 resets it's defaults to the options specified. If called in a void con‐
191 text:
192 form { squeeze => 1, trim => 1 };
194 the options become permanent defaults.
196 However, when called with only options in non-void context, "form"
198 resets its defaults to those options and returns an object. The reset
199 default values persist only until that returned object is destroyed.
200 Hence to temporarily reset "form"'s defaults within a single subrou‐
201 tine:
202 sub single {
204 my $tmp = form { squeeze => 1, trim => 1 };
205 # do formatting with the obove defaults
207 } # form's defaults revert to previous values as $tmp object destroyed
209 Multi-line format specifiers and interleaving
211 By default, if a format specifier contains two or more lines (i.e. one
213 or more newline characters), the entire format specifier is repeatedly
214 filled as a unit, until all block fields have consumed their corre‐
215 sponding arguments. For example, to build a simple look-up table:
216 my @values = (1..12);
218 my @squares = map { sprintf "%.6g", $_**2 } @values;
220 my @roots = map { sprintf "%.6g", sqrt($_) } @values;
221 my @logs = map { sprintf "%.6g", log($_) } @values;
222 my @inverses = map { sprintf "%.6g", 1/$_ } @values;
223 print form
225 " N N**2 sqrt(N) log(N) 1/N",
226 "=====================================================",
227 "⎪ [[ ⎪ [[[ ⎪ [[[[[[[[[[ ⎪ [[[[[[[[[ ⎪ [[[[[[[[[ ⎪
228 -----------------------------------------------------",
229 \@values, \@squares, \@roots, \@logs, \@inverses;
230 The multiline format specifier:
232 "⎪ [[ ⎪ [[[ ⎪ [[[[[[[[[[ ⎪ [[[[[[[[[ ⎪ [[[[[[[[[ ⎪
234 -----------------------------------------------------",
235 is treated as a single logical line. So "form" alternately fills the
237 first physical line (interpolating one value from each of the arrays)
238 and the second physical line (which puts a line of dashes between each
239 row of the table) producing:
240 N N**2 sqrt(N) log(N) 1/N
242 =====================================================
243 ⎪ 1 ⎪ 1 ⎪ 1 ⎪ 0 ⎪ 1 ⎪
244 -----------------------------------------------------
245 ⎪ 2 ⎪ 4 ⎪ 1.41421 ⎪ 0.693147 ⎪ 0.5 ⎪
246 -----------------------------------------------------
247 ⎪ 3 ⎪ 9 ⎪ 1.73205 ⎪ 1.09861 ⎪ 0.333333 ⎪
248 -----------------------------------------------------
249 ⎪ 4 ⎪ 16 ⎪ 2 ⎪ 1.38629 ⎪ 0.25 ⎪
250 -----------------------------------------------------
251 ⎪ 5 ⎪ 25 ⎪ 2.23607 ⎪ 1.60944 ⎪ 0.2 ⎪
252 -----------------------------------------------------
253 ⎪ 6 ⎪ 36 ⎪ 2.44949 ⎪ 1.79176 ⎪ 0.166667 ⎪
254 -----------------------------------------------------
255 ⎪ 7 ⎪ 49 ⎪ 2.64575 ⎪ 1.94591 ⎪ 0.142857 ⎪
256 -----------------------------------------------------
257 ⎪ 8 ⎪ 64 ⎪ 2.82843 ⎪ 2.07944 ⎪ 0.125 ⎪
258 -----------------------------------------------------
259 ⎪ 9 ⎪ 81 ⎪ 3 ⎪ 2.19722 ⎪ 0.111111 ⎪
260 -----------------------------------------------------
261 ⎪ 10 ⎪ 100 ⎪ 3.16228 ⎪ 2.30259 ⎪ 0.1 ⎪
262 -----------------------------------------------------
263 ⎪ 11 ⎪ 121 ⎪ 3.31662 ⎪ 2.3979 ⎪ 0.0909091 ⎪
264 -----------------------------------------------------
265 ⎪ 12 ⎪ 144 ⎪ 3.4641 ⎪ 2.48491 ⎪ 0.0833333 ⎪
266 -----------------------------------------------------
267 This implies that formats and the variables from which they're filled
269 need to be interleaved. That is, a multi-line specification like this:
270 print form
272 "Passed: ##
273 [[[[[[[[[[[[[[[ # single format specification
274 Failed: # (needs two sets of data)
275 [[[[[[[[[[[[[[[", ##
276 \@passes, \@fails; ## data for previous format
278 would print:
280 Passed:
282 <pass 1>
283 Failed:
284 <fail 1>
285 Passed:
286 <pass 2>
287 Failed:
288 <fail 2>
289 Passed:
290 <pass 3>
291 Failed:
292 <fail 3>
293 because the four-line format specifier is treated as a single unit, to
295 be repeatedly filled until all the data in @passes and @fails has been
296 consumed.
297 Unlike the table example, where this unit filling correctly put a line
299 of dashes between lines of data, in this case the alternation of passes
300 and fails is probably not the desired effect.
301 Judging by the labels, it is far more likely that the user wanted:
303 Passed:
305 <pass 1>
306 <pass 2>
307 <pass 3>
308 Failed:
309 <fail 4>
310 <fail 5>
311 <fail 6>
312 To achieve that, either explicitly interleave the formats and their
314 data sources:
315 print form
317 "Passed:", ## single format (no data required)
318 " [[[[[[[[[[[[[[[", ## single format (needs one set of data)
319 \@passes, ## data for previous format
320 "Failed:", ## single format (no data required)
321 " [[[[[[[[[[[[[[[", ## single format (needs one set of data)
322 \@fails; ## data for previous format
323 or instruct "form" to do it for you automagically, by setting the
325 'interleave' flag true:
326 print form {interleave=>1}
328 "Passed: ##
329 [[[[[[[[[[[[[[[ # single format
330 Failed: # (needs two sets of data)
331 [[[[[[[[[[[[[[[", ##
332 ## data to be automagically interleaved
334 \@passes, \@fails; # as necessary between lines of previous
335 ## format
336 How "form" hyphenates
338 Any line with a block field repeats on subsequent lines until all block
340 fields on that line have consumed all their data. Non-block fields on
341 these lines are replaced by the appropriate number of spaces.
342 Words are wrapped whole, unless they will not fit into the field at
344 all, in which case they are broken and (by default) hyphenated. Simple
345 hyphenation is used (i.e. break at the N-1th character and insert a
346 '-'), unless a suitable alternative subroutine is specified instead.
347 Words will not be broken if the break would leave less than 2 charac‐
349 ters on the current line. This minimum can be varied by setting the
350 'minbreak' option to a numeric value indicating the minumum total bro‐
351 ken characters (including hyphens) required on the current line. Note
352 that, for very narrow fields, words will still be broken (but unhyphen‐
353 ated). For example:
354 print form '~', 'split';
356 would print:
358 s
360 p
361 l
362 i
363 t
364 whilst:
366 print form {minbreak=>1}, '~', 'split';
368 would print:
370 s-
372 p-
373 l-
374 i-
375 t
376 Alternative breaking subroutines can be specified using the "break"
378 option in a configuration hash. For example:
379 form { break => \&my_line_breaker }
381 $format_str,
382 @data;
383 "form" expects any user-defined line-breaking subroutine to take three
385 arguments (the string to be broken, the maximum permissible length of
386 the initial section, and the total width of the field being filled).
387 The "hypenate" sub must return a list of two strings: the initial (bro‐
388 ken) section of the word, and the remainder of the string respec‐
389 tively).
390 For example:
392 sub tilde_break = sub($$$)
394 {
395 (substr($_[0],0,$_[1]-1).'~', substr($_[0],$_[1]-1));
396 }
397 form { break => \&tilde_break }
399 $format_str,
400 @data;
401 makes '~' the hyphenation character, whilst:
403 sub wrap_and_slop = sub($$$)
405 {
406 my ($text, $reqlen, $fldlen) = @_;
407 if ($reqlen==$fldlen) { $text =~ m/\A(\s*\S*)(.*)/s }
408 else { ("", $text) }
409 }
410 form { break => \&wrap_and_slop }
412 $format_str,
413 @data;
414 wraps excessively long words to the next line and "slops" them over the
416 right margin if necessary.
417 The Text::Reform package provides three functions to simplify the use
419 of variant hyphenation schemes. The exportable subroutine
420 "Text::Reform::break_wrap" generates a reference to a subroutine imple‐
421 menting the "wrap-and-slop" algorithm shown in the last example, which
422 could therefore be rewritten:
423 use Text::Reform qw( form break_wrap );
425 form { break => break_wrap }
427 $format_str,
428 @data;
429 The subroutine "Text::Reform::break_with" takes a single string argu‐
431 ment and returns a reference to a sub which hyphenates by cutting off
432 the text at the right margin and appending the string argument. Hence
433 the first of the two examples could be rewritten:
434 use Text::Reform qw( form break_with );
436 form { break => break_with('~') }
438 $format_str,
439 @data;
440 The subroutine "Text::Reform::break_at" takes a single string argument
442 and returns a reference to a sub which hyphenates by breaking immedi‐
443 ately after that string. For example:
444 use Text::Reform qw( form break_at );
446 form { break => break_at('-') }
448 "[[[[[[[[[[[[[[",
449 "The Newton-Raphson methodology";
450 # returns:
452 #
453 # "The Newton-
454 # Raphson
455 # methodology"
456 Note that this differs from the behaviour of "break_with", which would
458 be:
459 form { break => break_with('-') }
461 "[[[[[[[[[[[[[[",
462 "The Newton-Raphson methodology";
463 # returns:
465 #
466 # "The Newton-R-
467 # aphson metho-
468 # dology"
469 Hence "break_at" is generally a better choice.
471 The subroutine "Text::Reform::break_TeX" returns a reference to a sub
473 which hyphenates using Jan Pazdziora's TeX::Hyphen module. For example:
474 use Text::Reform qw( form break_wrap );
476 form { break => break_TeX }
478 $format_str,
479 @data;
480 Note that in the previous examples there is no leading '\&' before
482 "break_wrap", "break_with", or "break_TeX", since each is being
483 directly called (and returns a reference to some other suitable subrou‐
484 tine);
485 The "form" formatting algorithm
487 The algorithm "form" uses is:
489 1. If interleaving is specified, split the first string in the
491 argument list into individual format lines and add a
492 terminating newline (unless one is already present).
493 Otherwise, treat the entire string as a single "line" (like
494 /s does in regexes)
495 2. For each format line...
497 2.1. determine the number of fields and shift
499 that many values off the argument list and
500 into the filling list. If insufficient
501 arguments are available, generate as many
502 empty strings as are required.
503 2.2. generate a text line by filling each field
505 in the format line with the initial contents
506 of the corresponding arg in the filling list
507 (and remove those initial contents from the arg).
508 2.3. replace any <,>, or ^ fields by an equivalent
510 number of spaces. Splice out the corresponding
511 args from the filling list.
512 2.4. Repeat from step 2.2 until all args in the
514 filling list are empty.
515 3. concatenate the text lines generated in step 2
517 4. repeat from step 1 until the argument list is empty
519 "form" examples
521 As an example of the use of "form", the following:
523 $count = 1;
525 $text = "A big long piece of text to be formatted exquisitely";
526 print form q
528 q{ ⎪⎪⎪⎪ <<<<<<<<<< },
529 $count, $text,
530 q{ ---------------- },
531 q{ ^^^^ ]]]]]]]]]]⎪ },
532 $count+11, $text,
533 q{ =
534 ]]].[[[ },
535 "123 123.4\n123.456789";
536 produces the following output:
538 1 A big long
540 ----------------
541 12 piece of⎪
542 text to be⎪
543 formatted⎪
544 exquisite-⎪
545 ly⎪
546 =
547 123.0
548 =
549 123.4
550 =
551 123.456
552 Note that block fields in a multi-line format string, cause the entire
554 multi-line format to be repeated as often as necessary.
555 Picture strings and replacement values are interleaved in the tradi‐
557 tional "format" format, but care is needed to ensure that the correct
558 number of substitution values are provided. Another example:
559 $report = form
561 'Name Rank Serial Number',
562 '==== ==== =============',
563 '<<<<<<<<<<<<< ^^^^ <<<<<<<<<<<<<',
564 $name, $rank, $serial_number,
565 ''
566 'Age Sex Description',
567 '=== === ===========',
568 '^^^ ^^^ [[[[[[[[[[[',
569 $age, $sex, $description;
570 How "form" consumes strings
572 Unlike "format", within "form" non-block fields do consume the text
574 they format, so the following:
575 $text = "a line of text to be formatted over three lines";
577 print form "<<<<<<<<<<\n <<<<<<<<\n <<<<<<\n",
578 $text, $text, $text;
579 produces:
581 a line of
583 text to
584 be fo-
585 not:
587 a line of
589 a line
590 a line
591 To achieve the latter effect, convert the variable arguments to inde‐
593 pendent literals (by double-quoted interpolation):
594 $text = "a line of text to be formatted over three lines";
596 print form "<<<<<<<<<<\n <<<<<<<<\n <<<<<<\n",
597 "$text", "$text", "$text";
598 Although values passed from variable arguments are progressively con‐
600 sumed within "form", the values of the original variables passed to
601 "form" are not altered. Hence:
602 $text = "a line of text to be formatted over three lines";
604 print form "<<<<<<<<<<\n <<<<<<<<\n <<<<<<\n",
605 $text, $text, $text;
606 print $text, "\n";
607 will print:
609 a line of
611 text to
612 be fo-
613 a line of text to be formatted over three lines
614 To cause "form" to consume the values of the original variables passed
616 to it, pass them as references. Thus:
617 $text = "a line of text to be formatted over three lines";
619 print form "<<<<<<<<<<\n <<<<<<<<\n <<<<<<\n",
620 \$text, \$text, \$text;
621 print $text, "\n";
622 will print:
624 a line of
626 text to
627 be fo-
628 rmatted over three lines
629 Note that, for safety, the "non-consuming" behaviour takes precedence,
631 so if a variable is passed to "form" both by reference and by value,
632 its final value will be unchanged.
633 Numerical formatting
635 The ">>>.<<<" and "]]].[[[" field specifiers may be used to format
637 numeric values about a fixed decimal place marker. For example:
638 print form '(]]]]].[[)', <<EONUMS;
640 1
641 1.0
642 1.001
643 1.009
644 123.456
645 1234567
646 one two
647 EONUMS
648 would print:
650 ( 1.0 )
652 ( 1.0 )
653 ( 1.00)
654 ( 1.01)
655 ( 123.46)
656 (#####.##)
657 (?????.??)
658 (?????.??)
659 Fractions are rounded to the specified number of places after the deci‐
661 mal, but only significant digits are shown. That's why, in the above
662 example, 1 and 1.0 are formatted as "1.0", whilst 1.001 is formatted as
663 "1.00".
664 You can specify that the maximal number of decimal places always be
666 used by giving the configuration option 'numeric' a value that matches
667 /\bAllPlaces\b/i. For example:
668 print form { numeric => AllPlaces },
670 '(]]]]].[[)', <<'EONUMS';
671 1
672 1.0
673 EONUMS
674 would print:
676 ( 1.00)
678 ( 1.00)
679 Note that although decimal digits are rounded to fit the specified
681 width, the integral part of a number is never modified. If there are
682 not enough places before the decimal place to represent the number, the
683 entire number is replaced with hashes.
684 If a non-numeric sequence is passed as data for a numeric field, it is
686 formatted as a series of question marks. This querulous behaviour can
687 be changed by giving the configuration option 'numeric' a value that
688 matches /\bSkipNaN\b/i in which case, any invalid numeric data is sim‐
689 ply ignored. For example:
690 print form { numeric => 'SkipNaN' }
692 '(]]]]].[[)',
693 <<EONUMS;
694 1
695 two three
696 4
697 EONUMS
698 would print:
700 ( 1.0 )
702 ( 4.0 )
703 Filling block fields with lists of values
705 If an argument corresponding to a field is an array reference, then
707 "form" automatically joins the elements of the array into a single
708 string, separating each element with a newline character. As a result,
709 a call like this:
710 @values = qw( 1 10 100 1000 );
712 print form "(]]]].[[)", \@values;
713 will print out
715 ( 1.00)
717 ( 10.00)
718 ( 100.00)
719 (1000.00)
720 as might be expected.
722 Note however that arrays must be passed by reference (so that "form"
724 knows that the entire array holds data for a single field). If the pre‐
725 vious example had not passed @values by reference:
726 @values = qw( 1 10 100 1000 );
728 print form "(]]]].[[)", @values;
729 the output would have been:
731 ( 1.00)
733 10
734 100
735 1000
736 This is because @values would have been interpolated into "form"'s
738 argument list, so only $value[0] would have been used as the data for
739 the initial format string. The remaining elements of @value would have
740 been treated as separate format strings, and printed out "verbatim".
741 Note too that, because arrays must be passed using a reference, their
743 original contents are consumed by "form", just like the contents of
744 scalars passed by reference.
745 To avoid having an array consumed by "form", pass it as an anonymous
747 array:
748 print form "(]]]].[[)", [@values];
750 Headers, footers, and pages
752 The "form" subroutine can also insert headers, footers, and page-feeds
754 as it formats. These features are controlled by the "header", "footer",
755 "pagefeed", "pagelen", and "pagenum" options.
756 The "pagenum" option takes a scalar value or a reference to a scalar
758 variable and starts page numbering at that value. If a reference to a
759 scalar variable is specified, the value of that variable is updated as
760 the formatting proceeds, so that the final page number is available in
761 it after formatting. This can be useful for multi-part reports.
762 The "pagelen" option specifies the total number of lines in a page
764 (including headers, footers, and page-feeds).
765 The "pagewidth" option specifies the total number of columns in a page.
767 If the "header" option is specified with a string value, that string is
769 used as the header of every page generated. If it is specified as a
770 reference to a subroutine, that subroutine is called at the start of
771 every page and its return value used as the header string. When called,
772 the subroutine is passed the current page number.
773 Likewise, if the "footer" option is specified with a string value, that
775 string is used as the footer of every page generated. If it is speci‐
776 fied as a reference to a subroutine, that subroutine is called at the
777 start of every page and its return value used as the footer string.
778 When called, the footer subroutine is passed the current page number.
779 Both the header and footer options can also be specified as hash refer‐
781 ences. In this case the hash entries for keys "left", "centre" (or
782 "center"), and "right" specify what is to appear on the left, centre,
783 and right of the header/footer. The entry for the key "width" specifies
784 how wide the footer is to be. If the "width" key is omitted, the
785 "pagewidth" configuration option (which defaults to 72 characters) is
786 used.
787 The "left", "centre", and "right" values may be literal strings, or
789 subroutines (just as a normal header/footer specification may be.) See
790 the second example, below.
791 Another alternative for header and footer options is to specify them as
793 a subroutine that returns a hash reference. The subroutine is called
794 for each page, then the resulting hash is treated like the hashes
795 described in the preceding paragraph. See the third example, below.
796 The "pagefeed" option acts in exactly the same way, to produce a page‐
798 feed which is appended after the footer. But note that the pagefeed is
799 not counted as part of the page length.
800 All three of these page components are recomputed at the start of each
802 new page, before the page contents are formatted (recomputing the
803 header and footer first makes it possible to determine how many lines
804 of data to format so as to adhere to the specified page length).
805 When the call to "form" is complete and the data has been fully format‐
807 ted, the footer subroutine is called one last time, with an extra argu‐
808 ment of 1. The string returned by this final call is used as the final
809 footer.
810 So for example, a 60-line per page report, starting at page 7, with
812 appropriate headers and footers might be set up like so:
813 $page = 7;
815 form { header => sub { "Page $_[0]\n\n" },
817 footer => sub { my ($pagenum, $lastpage) = @_;
818 return "" if $lastpage;
819 return "-"x50 . "\n"
820 .form ">"x50, "...".($pagenum+1);
821 },
822 pagefeed => "\n\n",
823 pagelen => 60
824 pagenum => \$page,
825 },
826 $template,
827 @data;
828 Note the recursive use of "form" within the "footer" option!
830 Alternatively, to set up headers and footers such that the running head
832 is right justified in the header and the page number is centred in the
833 footer:
834 form { header => { right => "Running head" },
836 footer => { centre => sub { "Page $_[0]" } },
837 pagelen => 60
838 },
839 $template,
840 @data;
841 The footer in the previous example could also have been specified the
843 other way around, as a subroutine that returns a hash (rather than a
844 hash containing a subroutine):
845 form { header => { right => "Running head" },
847 footer => sub { return {centre => "Page $_[0]"} },
848 pagelen => 60
849 },
850 $template,
851 @data;
852 The "cols" option
854 Sometimes data to be used in a "form" call needs to be extracted from a
856 nested data structure. For example, whilst it's easy to print a table
857 if you already have the data in columns:
858 @name = qw(Tom Dick Harry);
860 @score = qw( 88 54 99);
861 @time = qw( 15 13 18);
862 print form
864 '-------------------------------',
865 'Name Score Time',
866 '-------------------------------',
867 '[[[[[[[[[[[[[[ ⎪⎪⎪⎪⎪ ⎪⎪⎪⎪',
868 \@name, \@score, \@time;
869 if the data is aggregrated by rows:
871 @data = (
873 { name=>'Tom', score=>88, time=>15 },
874 { name=>'Dick', score=>54, time=>13 },
875 { name=>'Harry', score=>99, time=>18 },
876 );
877 you need to do some fancy mapping before it can be fed to "form":
879 print form
881 '-------------------------------',
882 'Name Score Time',
883 '-------------------------------',
884 '[[[[[[[[[[[[[[ ⎪⎪⎪⎪⎪ ⎪⎪⎪⎪',
885 [map $$_{name}, @data],
886 [map $$_{score}, @data],
887 [map $$_{time} , @data];
888 Or you could just use the 'cols' option:
890 use Text::Reform qw(form columns);
892 print form
894 '-------------------------------',
895 'Name Score Time',
896 '-------------------------------',
897 '[[[[[[[[[[[[[[ ⎪⎪⎪⎪⎪ ⎪⎪⎪⎪',
898 { cols => [qw(name score time)],
899 from => \@data
900 };
901 This option takes an array of strings that specifies the keys of the
903 hash entries to be extracted into columns. The 'from' entry (which must
904 be present) also takes an array, which is expected to contain a list of
905 references to hashes. For each key specified, this option inserts into
906 "form"'s argument list a reference to an array containing the entries
907 for that key, extracted from each of the hash references supplied by
908 'from'. So, for example, the option:
909 { cols => [qw(name score time)],
911 from => \@data
912 }
913 is replaced by three array references, the first containing the 'name'
915 entries for each hash inside @data, the second containing the 'score'
916 entries for each hash inside @data, and the third containing the 'time'
917 entries for each hash inside @data.
918 If, instead, you have a list of arrays containing the data:
920 @data = (
922 # Time Name Score
923 [ 15, 'Tom', 88 ],
924 [ 13, 'Dick', 54 ],
925 [ 18, 'Harry', 99 ],
926 );
927 the 'cols' option can extract the appropriate columns for that too. You
929 just specify the required indices, rather than keys:
930 print form
932 '-----------------------------',
933 'Name Score Time',
934 '-----------------------------',
935 '[[[[[[[[[[[[[[ ⎪⎪⎪⎪⎪ ⎪⎪⎪⎪',
936 { cols => [1,2,0],
937 from => \@data
938 }
939 Note that the indices can be in any order, and the resulting arrays are
941 returned in the same order.
942 If you need to merge columns extracted from two hierarchical data
944 structures, just concatenate the data structures first, like so:
945 print form
947 '---------------------------------------',
948 'Name Score Time Ranking
949 '---------------------------------------',
950 '[[[[[[[[[[[[[[ ⎪⎪⎪⎪⎪ ⎪⎪⎪⎪ ⎪⎪⎪⎪⎪⎪⎪',
951 { cols => [1,2,0],
952 from => [@data, @olddata],
953 }
954 Of course, this only works if the columns are in the same positions in
956 both data sets (and both datasets are stored in arrays) or if the col‐
957 umns have the same keys (and both datasets are in hashes). If not, you
958 would need to format each dataset separately, like so:
959 print form
961 '-----------------------------',
962 'Name Score Time'
963 '-----------------------------',
964 '[[[[[[[[[[[[[[ ⎪⎪⎪⎪⎪ ⎪⎪⎪⎪',
965 { cols=>[1,2,0], from=>\@data },
966 '[[[[[[[[[[[[[[ ⎪⎪⎪⎪⎪ ⎪⎪⎪⎪',
967 { cols=>[3,8,1], from=>\@olddata },
968 '[[[[[[[[[[[[[[ ⎪⎪⎪⎪⎪ ⎪⎪⎪⎪',
969 { cols=>[qw(name score time)], from=>\@otherdata };
970 The "tag" sub
972 The "tag" subroutine may be exported from the module. It takes two
974 arguments: a tag specifier and a text to be entagged. The tag specifier
975 indicates the indenting of the tag, and of the text. The sub generates
976 an end-tag (using the usual "/tag" variant), unless an explicit end-tag
977 is provided as the third argument.
978 The tag specifier consists of the following components (in order):
980 An optional vertical spacer (zero or more whitespace-separated new‐
982 lines)
983 One or more whitespace characters up to a final mandatory newline.
984 This vertical space is inserted before the tag and after the end-
985 tag
986 An optional tag indent
988 Zero or more whitespace characters. Both the tag and the end-tag
989 are indented by this whitespace.
990 An optional left (opening) tag delimiter
992 Zero or more non-"word" characters (not alphanumeric or '_'). If
993 the opening delimiter is omitted, the character '<' is used.
994 A tag
996 One or more "word" characters (alphanumeric or '_').
997 Optional tag arguments
999 Any number of any characters
1000 An optional right (closing) tag delimiter
1002 Zero or more non-"word" characters which balance some sequential
1003 portion of the opening tag delimiter. For example, if the opening
1004 delimiter is "<-(" then any of the following are acceptible closing
1005 delimiters: ")->", "->", or ">". If the closing delimiter is omit‐
1006 ted, the "inverse" of the opening delimiter is used (for example,
1007 ")->"),
1008 An optional vertical spacer (zero or more newlines)
1010 One or more whitespace characters up to a mandatory newline. This
1011 vertical space is inserted before and after the complete text.
1012 An optional text indent
1014 Zero or more space of tab characters. Each line of text is indented
1015 by this whitespace (in addition to the tag indent).
1016 For example:
1018 $text = "three lines\nof tagged\ntext";
1020 print tag "A HREF=#nextsection", $text;
1022 prints:
1024 <A HREF=#nextsection>three lines
1026 of tagged
1027 text</A>
1028 whereas:
1030 print tag "[-:GRIN>>>\n", $text;
1032 prints:
1034 [-:GRIN>>>:-]
1036 three lines
1037 of tagged
1038 text
1039 [-:/GRIN>>>:-]
1040 and:
1042 print tag "\n\n <BOLD>\n\n ", $text, "<END BOLD>";
1044 prints:
1046 <BOLD>
1050 three lines
1052 of tagged
1053 text
1054 <END BOLD>
1056 (with the indicated spacing fore and aft).
1060
1062 Damian Conway (damian@conway.org)
1063
1065 There are undoubtedly serious bugs lurking somewhere in code this funky
1066 :-) Bug reports and other feedback are most welcome.
1067
1069 Copyright (c) 1997-2000, Damian Conway. All Rights Reserved. This mod‐
1070 ule is free software. It may be used, redistributed and/or modified
1071 under the terms of the Perl Artistic License
1072 (see http://www.perl.com/perl/misc/Artistic.html)
1073perl v5.8.8 2003-05-07 Text::Reform(3)