Formats (Perl in a Nutshell, 2nd Edition)

4.12. Formats

Formats are a mechanism for generating formatted reports for outputting data and are defined with the format keyword. The general form looks like:

format name =
 ...template lines...
 ...argument line...
.

Most of your format names will be the same as the filehandle names for which they are used. The default format for a filehandle is the one with the same name.

The format definition is like a subroutine definition. It doesn't contain immediately executed code and can therefore be placed anywhere in the file with the rest of the program; they are commonly placed near the end of the file with subroutine definitions . To output to a format, use the write function instead of print.

The template lines contain literal text and fieldholders. Fieldholders contain symbols that describe the size and positioning of the area on the line where data is output. An argument line immediately follows a template line that contains the fields to be replaced by data. The argument line is a list of variables (or expressions), separated by commas, that fill the fields in the previous line in the order they are listed.

Here's an example of a template line with two fieldholders and the argument line that follows:

Hello, my name is @<<<<<<<<<< and I'm @<< years old.
$name, $age

The fieldholders are @<<<<<<<<<< and @<<, which specify left-justified text fields with 11 and 3 characters, respectively.

Most fieldholders start with @. The characters following @ indicate the type of field, while the number of characters (including @) indicate the field width. The following fieldholder characters determine the positioning of text fields:

<<<< (left angle brackets): A left-justified field; if the value is shorter than the field width, it will be padded on the right with spaces.
>>>> (right angle brackets): A right-justified field; if the value is too short, it will be padded on the left with spaces.
|||| (vertical bars)

Another kind of fieldholder is a fixed-precision numeric field. This field also begins with @, and is followed by one or more hashmarks (###) with an optional dot (indicating a decimal point). For example:

format MONEY =
Assets: @#####.## Liabilities: @#####.## Net: @#####.##
$assets, $liabilities, $assets-$liabilities
.

The multiline fieldholder allows you to include a value that may have many lines of information. This fieldholder is denoted by @* on a line by itself. The next line defines the value that will be substituted into the field, which in this case may be an expression that results in a value that contains many newlines.

Another kind of fieldholder is a filled field. This fieldholder allows you to create a filled paragraph, breaking the text into conveniently sized lines at word boundaries, wrapping the lines as needed. A filled field is denoted by replacing the @ marker in a text fieldholder with a caret (^<<<, for example). The corresponding value for a filled field (on the following line of the format) must be a scalar variable containing text, rather than an expression that returns a scalar value. When Perl is filling the filled field, it takes the value of the variable and removes as many words as will fit in the field. Subsequent calls for the variable in a filled field will continue where the last one left off.

If the variable's contents are exhausted before the number of fields, you will simply end up with blank lines. You can suppress blank lines by placing a tilde (~) on the line. Any line that contains a tilde character is not output if the line would have otherwise printed blank (i.e., just whitespace). The tilde itself always prints as a blank and can be placed anywhere a space could have been placed in the line.

If the text in the variable is longer than what can be filled in the fields, output continues only until the fields run out . The shortcut to get the string to print until it ends is to use two consecutive tildes (~~) on a line. This causes the line to repeat automatically until the result is a completely blank line (which will be suppressed).

Default values for format parameters all relate to the format of the currently selected filehandle. The currently selected filehandle starts out as STDOUT, which makes it easy to print things on the standard output. However, you can change the currently selected filehandle with the select function, which takes a single filehandle (or a scalar variable containing the name of a filehandle) as an argument. Once the currently selected filehandle is changed, it affects all future operations that depend on the currently selected filehandle.