# Creating Reports
Perl has a few special features that let you create simple reports. The
reports can have a header area where you can place a title, page number, and
other information that stays the same from one page to the next. Perl will track
how many lines have been used in the report and automatically generate new pages
as needed.
Compared to learning about regular expressions, learning how to create
reports will be a breeze. There are only a few tricky parts, which I'll be sure
to point out.
This chapter starts out by using the print() function to display a
CD collection and then gradually moves from displaying the data to a fully
formatted report. The data file shown in Listing 11.1 is used for all of the
examples in this chapter. The format is pretty simple: the CD album's title, the
artist's name, and the album's price.
|
Listing 11.1-FORMAT.DAT - The Data File |
The Lion King!
Tumbleweed Connection!Elton John!123.32
Photographs & Memories!Jim Croce!4.95
Heads & Tales!Harry Chapin!12.50
|
You'll find that Perl is very handy for small text-based data files like
this. You can create them in any editor and use any field delimiter you like. In
this file, I used an exclamation point to delimit the field. However, I could
just as easily have used a caret, a tilde, or any other character.
Now that we have some data, let's look at Listing 11.2, which is a program
that reads the data file and displays the information.
| Pseudocode |
|
Open the FORMAT.DAT file.
Read all the file's lines and place them in the @lines array.
Each line becomes a different element in the array.
Close the file.
Iterate over the @lines array. $_ is set to a
different array element each time through the loop.
Remove the linefeed character from the end of the string.
Split the string into three fields using the exclamation point as the
delimiter. Place each field into the $album, $artist,
and $price variables.
Print the variables. |
|
Listing 11.2-11LIST02.PL - A Program to Read and Display the Data
File |
open(FILE, ";
close(FILE);
foreach (@lines) {
chop;
($album, $artist, $price) = (split(/!/));
print("Album=$album Artist=$artist Price=$price\n");
}
|
This program displays:
Use of uninitialized value at 11lst02.pl line 8.
Album=The Lion King Artist= Price=
Album=Tumbleweed Connection Artist=Elton John Price=123.32
Album=Photographs & Memories Artist=Jim Croce Price=4.95
Album=Heads & Tales Artist=Harry Chapin Price=12.50
Why is an
error being displayed on the first line of the output? If you said that the
split() function was returning the undefined value when there was no
matching field in the input file, you were correct. The first input line was the
following:
The Lion King!
There are no entries for the Artist or Price
fields. Therefore, the $artist and $price variables were
assigned the undefined value, which resulted in Perl complaining about
uninitialized values. You can avoid this problem by assigning the empty string
to any variable that has the undefined value. Listing 11.3 shows a program that
does this.
| Pseudocode |
|
Open the FORMAT.DAT file, read all the lines into
@lines, and then close the file.
Iterate over the @lines array.
Remove the linefeed character.
Split the string into three fields.
If any of the three fields are not present in the line, provide a
default value of an empty string.
Print the variables. |
|
Listing 11.3-11LST03.PL - How to Avoid the Uninitialized Error When
Using the Split() Function |
open(FILE, ";
close(FILE);
foreach (@lines) {
chop;
($album, $artist, $price) = (split(/!/));
$album = "" if !defined($album);
$artist = "" if !defined($artist);
$price = "" if !defined($price);
print("Album=$album Artist=$artist Price=$price\n");
}
|
| Clarification
Note |
The following code lines are responsible for
assigning a null string value to the three variables if no information was
present in the record: $album = "" if !defined($album);
$artist = "" if !defined($artist);
$price = "" if !defined($price);
The defined() function is used to see if each variable is defined. If a
variable has no value, then the "" string is assigned to
it. |
| Errata
Note |
| The printed version of this book showed the split
call to be: ($album, $artist, $price) = (split(/::/));
which was incorrect. |
The first four lines this program displays are the following: Album=The Lion King Artist= Price=
Album=Tumbleweed Connection Artist=Elton John Price=123.32
Album=Photographs & Memories Artist=Jim Croce Price=4.95
Album=Heads & Tales Artist=Harry Chapin Price=12.50
The error
has been eliminated, but it is still very hard to read the output because the
columns are not aligned. The rest of this chapter is devoted to turning this
jumbled output into a report.
Perl reports have both heading and detail lines. A heading is
used to identify the report title, the page number, the date, and any other
information that needs to appear at the top of each page. Detail lines are used
to show information about each record in the report. In the data file being used
for the examples in this chapter (see Listing 11.1), each CD has its own detail
line.
Headings and detail lines are defined by using format statements, which are
discussed in the next section.
## What's a Format Statement?
Perl uses formats as guidelines when writing report information. A format is
used to tell Perl what static text is needed and where variable information
should be placed. Formats are defined by using the format statement.
The syntax for the format statement is
format FORMATNAME =
FIELD_LINE
VALUE_LINE
.The FORMATNAME is usually the same name as the file handle
that is used to accept the report output. The section "Example:
Changing Formats," later in this chapter, talks about using the
format statement where the FORMATNAME is different from the
file handle. If you don't specify a FORMATNAME, Perl uses
STDOUT. The FIELD_LINE part of the format statement consists
of text and field holders. A field holder represents a given line width
that Perl will fill with the value of a variable. The VALUE_LINE line
consists of a comma-delimited list of expressions used to fill the field holders
in FIELD_LINE.
Report headings, which appear at the top of each page, have the following
format:
format FORMATNAME_TOP =
FIELD_LINE
VALUE_LINE
.Yes, the only difference between a detail line and a heading is that
_TOP is appended to the FORMATNAME.
| Note |
| The location of format statements is
unimportant because they define only a format and are never executed. I
feel that they should appear either at the beginning of a program or the
end of a program, rarely in the middle. Placing format statements
in the middle of your program might make them hard to find when they need
to be changed. Of course, you should be consistent where you place
them. |
A typical format statement might look like this:
format =
The total amount is $@###.##
$total
.The at character @ is used to start a field holder. In this
example, the field holder is seven characters long (the at sign and decimal
point count, as well as the pound signs #). The next section, "Example:
Using Field Lines," goes into more detail about field lines and field
holders.
Format statements are used only when invoked by the write()
function. The write() function takes only one parameter: a file handle
to send output to. Like many things in Perl, if no parameter is specified, a
default is provided. In this case, STDOUT will be used when no
FORMATNAME is specified. In order to use the preceding format, you
simply assign a value to $total and then call the write()
function. For example:
$total = 243.45;
write();
$total = 50.00;
write();
These lines will display:
The total amount is $ 243.45
The total amount is $ 50.50The output will be sent to
STDOUT. Notice that the decimal points are automatically lined up when
the lines are displayed.
### Example: Using Field Lines
The field lines of a format statement control what is displayed and how. The
simplest field line contains only static text. You can use static or
unchanging text as labels for variable information, dollar signs in front of
amounts, a separator character such as a comma between first and last name, or
whatever else is needed. However, you'll rarely use just static text in your
format statement. Most likely, you'll use a mix of static text and field
holders.
You saw a field holder in action in the last section in which I demonstrated
sending the report to STDOUT. I'll repeat the format statement
here so you can look at it in more detail:
format =
The total amount is $@###.##
$total
.The character sequence The total amount is $ is static text.
It will not change no matter how many times the report is printed. The character
sequence @###.##, however, is a field holder. It reserves seven spaces
in the line for a number to be inserted. The third line is the value line; it
tells Perl which variable to use with the field holder. Table 11.11 contains a
list of the different format characters you can use in field lines.
Table 11.1 - Field Holder Formats
| Format Character |
Description |
| @ |
This character represents the start of a field
holder. |
| < |
This character indicates that the field should be
left-justified. |
| > |
This character indicates that the field should be
right-justified. |
| | |
This character indicates that the field should be
centered. |
| # |
This character indicates that the field will be numeric. If
used as the first character in the line, it indicates that the entire line
is a comment. |
| . |
This character indicates that a decimal point should be
used with numeric fields. |
| ^ |
This character also represents the start of a field holder.
Moreover, it tells Perl to turn on word-wrap mode. See the section "Example:
Using Long Pieces of Text in Reports" later in this chapter for more
information about word-wrapping. |
| ~ |
This character indicates that the line should not be
written if it is blank. |
| ~~ |
This sequence indicates that lines should be written as
needed until the value of a variable is completely written to the output
file. |
| @* |
This sequence indicates that a multi-line field will be
used. |
Let's start using some of these formatting characters by formatting a report
to display information about the FORMAT.DAT file we used earlier. The
program in Listing 11.4 displays the information in nice, neat columns.
| Pseudocode |
|
Declare a format for the STDOUT file handle.
Open the FORMAT.DAT file, read all the lines into
@lines, and then close the file.
Iterate over the @lines array.
Remove the linefeed character.
Split the string into three fields.
If any of the three fields are not present in the line, provide a
default value of an empty string. Notice that a numeric value must be
given to $price instead of the empty string.
Invoke the format statement by using the write()
function. |
|
Listing 11.4-11LST04.PL - Using a Format with
STDOUT |
format =
Album=@<<<<<<<<<<<<< Artist=@>>>>>>>>>>>> Price=$@##.##
$album, $artist, $price
.
open(FILE, ";
close(FILE);
foreach (@lines) {
chop;
($album, $artist, $price) = (split(/!/));
$album = "" if !defined($album);
$artist = "" if !defined($artist);
$price = 0 if !defined($price);
write();
}
|
This program displays the following:
Album=The Lion King Artist= Price=$ 0.00
Album=Tumbleweed Con Artist= Elton John Price=$123.32
Album=Photographs & Artist= Jim Croce Price=$ 4.95
Album=Heads & Tales Artist= Harry Chapin Price=$ 12.50
You can
see that the columns are now neatly aligned. This was done with the
format statement and the write() function. The format
statement used in this example used three field holders. The first field holder,
@<<<<<<<<<<<<<, created a
left-justified spot for a 14-character-wide field filled by the value in
$album. The second field holder,
@>>>>>>>>>>>>, created a
right-justified spot for a 12-character-wide field filled by the value in
$artist. The last field holder, @##.##, created a
6-character-wide field filled by the numeric value in $price.
You might think it's wasteful to have the field labels repeated on each line,
and I would agree with that. Instead of placing field labels on the line, you
can put them in the report heading. The next section discusses how to do this.
### Example: Report Headings
Format statements for a report heading use the same format as the detail line
format statement, except that _TOP is appended to the file
handle. In the case of STDOUT, you must specify STDOUT_TOP.
Simply using _TOP will not work.
To add a heading to the report about the CD collection, you might use the
following format statement:
format STDOUT_TOP =
@|||||||||||||||||||||||||||||||||||| Pg @<
"CD Collection of David Medinets", $%
Album Artist Price
----------------- ---------------- -------
.
Adding this format statement to Listing 11.4 produces this
output:
CD Collection of David Medinets Pg 1
Album Artist Price
----------------- ---------------- -------
Album=The Lion King Artist= Price=$ 0.00
Album=Tumbleweed Con Artist= Elton John Price=$123.32
Album=Photographs & Artist= Jim Croce Price=$ 4.95
Album=Heads & Tales Artist= Harry Chapin Price=$ 12.50
Whenever
a new page is generated, the heading format is automatically invoked. Normally,
a page is 60 lines long. However, you can change this by setting the $=
special variable.
Another special variable, $%, holds the current page number. It will
be initialized to zero when your program starts. Then, just before invoking the
heading format, it is incremented so its value is one. You can change
$% if you need to change the page number for some reason.
You might notice that the | formatting character was used to center
the report title over the columns. You might also notice that placing the field
labels into the heading allows the columns to be expanded in width.
Unfortunately, Perl does not truly have any facility for adding footer detail
lines. However, you can try a bit of "magic" in order to fool Perl into creating
footers with static text. The $^L variable holds the string that Perl
writes before every report page except for the first, and the $=
variable holds the number of lines per page. By changing $^L to hold
your footer and by reducing the value in $= by the number of lines your
footer will need, you can create primitive footers. Listing 11.5 displays the CD
collection report on two pages by using this technique.
| Pseudocode |
|
Declare a format for the STDOUT file handle.
Declare a heading format for the STDOUT file handle.
Open the FORMAT.DAT file, read all the lines into
@lines, and then close the file.
Assign a value of 6 to $=. Normally, it has a value
of 60. Changing the value to 6 will create very short
pages - ideal for small example programs.
Assign a string to $^L, which usually is equal to the
form-feed character. The form-feed character causes printers to eject a
page.
Iterate over the @lines array.
Remove the linefeed character.
Split the string into three fields.
If any of the three fields are not present in the line, provide a
default value of an empty string. Notice that a numeric value must be
given to $price instead of the empty string.
Invoke the format statement using the write()
function.
Print the footer on the last page. You need to explicitly do this
because the last page of the report will probably not be a full
page. |
|
Listing 11.5-11LST05.PL - Tricking Perl into Creating Primitive
Footers |
format =
Album=@<<<<<<<<<<<<< Artist=@>>>>>>>>>>>> Price=$@##.##
$album, $artist, $price
.
format STDOUT_TOP =
@|||||||||||||||||||||||||||||||||||| Pg @<
"CD Collection of David Medinets", $%
Album Artist Price
----------------- ---------------- -------
.
open(FILE, ";
close(FILE);
$= = 6;
$^L = '-' x 60 . "\n" .
"Copyright, 1996, Eclectic Consulting\n" .
"\n\n";
foreach (@lines) {
chop();
($album, $artist, $price) = (split(/!/));
$album = "" if !defined($album);
$artist = "" if !defined($artist);
$price = 0 if !defined($price);
write();
}
print("$^L");
|
This program displays the following:
CD Collection of David Medinets Pg 1
Album Artist Price
----------------- ---------------- -------
Album=The Lion King Artist= Price=$ 0.00
Album=Tumbleweed Con Artist= Elton John Price=$123.32
------------------------------------------------------------
Copyright, 1996, Eclectic Consulting
CD Collection of David Medinets Pg 2
Album Artist Price
----------------- ---------------- -------
Album=Photographs & Artist= Jim Croce Price=$ 4.95
Album=Heads & Tales Artist= Harry Chapin Price=$ 12.50
------------------------------------------------------------
Copyright, 1996, Eclectic ConsultingLet me explain the assignment to
$^L in more detail. The assignment is duplicated here for your
convenience:
$^L = '-' x 60 . "\n" .
"Copyright, 1996 by Eclectic Consulting\n" .
"\n\n";The first part of the assignment, '-' x 60,
creates a line of 60 dash characters. Then a newline character is concatenated
to the line of dashes. Next, the copyright line is appended. Finally, two more
linefeeds are appended to separate the two pages of output. Normally, you
wouldn't add the ending linefeeds because the form-feed character makes them
unnecessary. Here's how the code would look when designed to be sent to a
printer:
$^L = '-' x 60 . "\n" .
"Copyright, 1996 by Eclectic Consulting" .
"\014";The "\014" string is the equivalent of a
form-feed character because the ASCII value for a form-feed is 12, which is 14
in octal notation.
| Note |
| I feel that it's important to say that the coding
style in this example is not really recommended for "real" programming. I
concatenated each footer element separately so I could discuss what each
element did. The last three elements in the footer assignment should
probably be placed inside one string literal for
efficiency. |
| Tip |
This example is somewhat incomplete. If the last
page of the report ends at line 20 and there are 55 lines per page, simply
printing the $^L variable will not place the footer at the bottom
of the page. Instead, the footer will appear after line 20. This is
probably not the behavior you'd like. Try the following statement to fix
this problem:
print("\n" x $- . "$^L");
This will concatenate enough linefeeds to the beginning of the footer
variable to place the footer at the bottom of the
page. |
### Example: Using Functions in the Value Line
You've already seen the value line in action. Most of the time, its use will be very simple: create the field holder
in the field line and then put the variable name in the value line. But there
are some other value line capabilities you should know about. In addition to
simple scalar variables, you can specify array variables and even functions on
the value line. Listing 11.6 shows a program that uses a function to add
ellipses to a string if it is too wide for a column.
| Pseudocode |
|
Declare a format for the STDOUT file handle. In this example,
the value line calls the dotize() function.
Declare a heading format for the STDOUT file handle.
Declare the dotize() function.
Initialize local variables called $width and $string.
If the width of $string is greater than $width,
return a value that consists of $string shortened to
$width-3 with ... appended to the end; otherwise, return
$string.
Open the FORMAT.DAT file, read all the lines into
@lines, and then close the file.
Iterate over the @lines array.
Remove the linefeed character.
Split the string into three fields.
If any of the three fields are not present in the line, provide a
default value of an empty string. Notice that a numeric value must be
given to $price instead of the empty string.
Invoke the format statement by using the write()
function. |
|
Listing 11.6-11LIST05.PL - Using a Function with a Value
Line |
format =
@<<<<<<<<<<<<<<<< @<<<<<<<<<<<<<<< $@##.##
dotize(17, $album), dotize(16, $artist), $price
.
format STDOUT_TOP =
@|||||||||||||||||||||||||||||||||||| Pg @<
"CD Collection of David Medinets", $%
Album Artist Price
----------------- ---------------- -------
.
sub dotize {
my($width, $string) = @_;
if (length($string) > $width) {
return(substr($string, 0, $width - 3) . "...");
}
else {
return($string);
}
}
open(FILE, ";
close(FILE);
foreach (@lines) {
chop();
($album, $artist, $price) = (split(/!/));
$album = "" if !defined($album);
$artist = "" if !defined($artist);
$price = 0 if !defined($price);
write();
}
|
This program displays the following:
CD Collection of David Medinets Pg 1
Album Artist Price
----------------- ---------------- -------
The Lion King $ 0.00
Tumbleweed Con... Elton John $123.32
Photographs & ... Jim Croce $ 4.95
Heads & Tales Harry Chapin $ 12.50
The second and third
detail lines have benefited from the dotize() function. You can use a
similar technique to invoke any function in the value line. You can also use
expressions directly in the value line, but it might be harder to maintain
because the intent of the expression might not be clear.
### Example: Changing Formats
So far, you've seen only how to use a single format statement per report. If Perl
could handle only one format per report, it wouldn't have much utility as a
reporting tool. Fortunately, by using the $~ special variable, you can
control which format is used for any given write() function call.
Listing 11.7 shows a program that tracks the price of the CDs in the collection
and displays the total using an alternate format statement.
| Pseudocode |
|
Declare a format for the STDOUT file handle.
Declare a format for the total price information.
Declare a heading format for the STDOUT file handle.
Declare the dotize() function.
Initialize local variables called $width and $string.
If the width of $string is greater than $width,
return a value that consists of $string shortened to
$width-3 with ... appended to the end; otherwise, return
$string.
Open the FORMAT.DAT file, read all the lines into
@lines, and then close the file.
Initialize the $total variable to zero.
Iterate over the @lines array.
Remove the linefeed character.
Split the string into three fields.
Provide a default value for any empty variables.
Invoke the format statement by using the write() function.
Change the current format by assigning a value to the $~
special variable.
Invoke the format statement by using the write()
function. |
|
Listing 11.7-11LST07.PL - Using an Alternative format
Statement |
format =
@<<<<<<<<<<<<<<<< @<<<<<<<<<<<<<<< $@###.##
dotize(17, $album), dotize(16, $artist), $price
.
format STDOUT_TOTAL =
---------------------------------------------
$@###.##
$total
.
format STDOUT_TOP =
@|||||||||||||||||||||||||||||||||||| Pg @<
"CD Collection of David Medinets", $%
Album Artist Price
----------------- ---------------- --------
.
sub dotize {
my($width, $string) = @_;
if (length($string) > $width) {
return(substr($string, 0, $width - 3) . "...");
}
else {
return($string);
}
}
open(FILE, ";
close(FILE);
$total = 0;
foreach (@lines) {
chop();
($album, $artist, $price) = (split(/!/));
$album = "" if !defined($album);
$artist = "" if !defined($artist);
$price = 0 if !defined($price);
write();
$total += $price;
}
$~ = "STDOUT_TOTAL";
write();
|
This program displays the following:
CD Collection of David Medinets Pg 1
Album Artist Price
----------------- ---------------- --------
The Lion King $ 0.00
Tumbleweed Con... Elton John $ 123.32
Photographs & ... Jim Croce $ 4.95
Heads & Tales Harry Chapin $ 12.50
---------------------------------------------
$ 140.77This example shows you
how to keep a running total and how to switch to an alternative detail line
format. If you need to switch to an alternative heading format, assign the new
header format name to the $^ special variable.
### Example: Using Long Pieces of Text in Reports
By using the ^, ~, and ~~ formatting characters in your format statements, you can use long
pieces of text in a report: for example, the first paragraph of a paper's
abstract or some notes associated with a database record. Listing 11.8 shows a
program that prints the definition of a word. The definition is too long to fit
in one column, so the ^ formatting character is used to split the text
onto multiple lines.
| Pseudocode |
|
Declare a format for the STDOUT file handle. The field and
value lines are repeated enough times to print the entire length of the
expected output.
Initialize the $word and $definition variables. The
$definition variable is initialized by using concatenated strings
to avoid line breaks caused by the book printing process.
A line of asterisks is printed.
The format is invoked.
Another line of asterisks is printed. |
|
Listing 11.8-11LST08.PL - Using the ^ Formatting Character to
Print Long Text Values |
format =
^<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
$word, $definition
^<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
$word, $definition
^<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
$word, $definition
^<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
$word, $definition
^<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
$word, $definition
^<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
$word, $definition
.
$word = "outlier";
$definition = "1. someone sleeping outdoors. " .
"2. someone whose office is not at home. " .
"3. an animal who strays from the fold. " .
"4. something that has been separated from the main body.";
print("****************\n");
write();
print("****************\n");
|
This program displays the following:
****************
outlier 1. someone sleeping outdoors. 2.
someone whose office is not at
home. 3. an animal who strays from
the fold. 4. something that has
been separated from the main body.
****************The ^ formatting character causes Perl to do
word-wrapping on the specified variable. Word-wrapping means that Perl
will accumulate words into a temporary buffer, stopping when the next word will
cause the length of the accumulated string to exceed the length of the field.
The accumulated string is incorporated into the report, and the accumulated
words are removed from the variable. Therefore, the next time Perl looks at the
variable, it can start accumulating words that have not been used yet.
| Note |
| Any linefeed characters in the variable are ignored
when the ^ formatting character is used in the format
statement. |
| Caution |
| Because the value of the variable used in the value
line changes when word-wrapping is being used, make sure to use only
copies of variables in the format statement. By using copies of
the variables, you'll still have the original value available for further
processing. |
The asterisks in the preceding example were printed to show that a blank line
was printed by the format. This was caused because the $definition
variable ran out of words before the format ran out of space. Extra blank lines
can be eliminated by placing the ~ character somewhere - usually at the
beginning or end - of the field line. The format statement would then
look like this:
format =
^<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~
$word, $definition
^<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~
$word, $definition
^<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~
$word, $definition
^<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~
$word, $definition
^<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~
$word, $definition
^<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~
$word, $definition
.
The new report would not have a blank line.
****************
outlier 1. someone sleeping outdoors. 2.
someone whose office is not at
home. 3. an animal who strays from
the fold. 4. something that has
been separated from the main body.
****************It is rather wasteful to have to repeat the field
lines often enough to account for the longest possible length of
$definition. In fact, if you are reading the definitions from a file,
you might not know how long the definitions could be ahead of time. Perl
provides the ~~ character sequence to handle situations like this. By
placing ~~ on the field line, Perl will repeat the field line as often
as needed until a blank line would be printed. Using this technique would change
the format statement to this:
format =
^<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~
$word, $definition
.
You might be wondering how Perl decides when a word ends. This
behavior is controlled by the $: variable. The default value for
$: is a string consisting of the space, newline, and dash characters.
### Example: Writing to a File Instead of STDOUT
Up to this point in the chapter, we've
only looked at writing a report to the display or STDOUT. This was done
to simplify and shorten the examples . Writing a report to a file requires that
you open a file for output and specify the file handle as a parameter to the
write() function. All functionality you've seen so far can be used with
files.
Listing 11.9 shows how easy it is to convert an existing program from using
STDOUT to using a file. The program shown is a reworking of the program
in Listing 11.4. Four changes needed to be made for the conversion. The format
statement was changed to specify a format name identical to the file handle used
in the second open() statement. A second open() statement was
added. The write() function was changed to specify the file handle to
use, and a second close() statement was added.
| Pseudocode |
|
Declare a format for the CD_REPORT file handle.
Open the FORMAT.DAT file, read all the lines into
@lines, and then close the file.
Open the FORMAT.RPT file for output to hold the report.
Iterate over the @lines array.
Remove the linefeed character.
Split the string into three fields.
If any of the three fields are not present in the line, provide a
default value of an empty string. Notice that a numeric value must be
given to $price instead of the empty string.
Invoke the format statement by using the write()
function specifying the file handle to use.
Close the FORMAT.RPT file. |
|
Listing 11.9-11LST09.PL - Saving a Report in a
File |
format CD_REPORT =
Album=@<<<<<<<<<<<<< Artist=@>>>>>>>>>>>> Price=$@##.##
$album, $artist, $price
.
open(FILE, ";
close(FILE);
open(CD_REPORT, ">format.rpt");
foreach (@lines) {
chop;
($album, $artist, $price) = (split(/!/));
$album = "" if !defined($album);
$artist = "" if !defined($artist);
$price = 0 if !defined($price);
write(CD_REPORT);
}
close(CD_REPORT);
|
This program creates a file called FORMAT.RPT that contains the
following:
Album=The Lion King Artist= Price=$ 0.00
Album=Tumbleweed Con Artist= Elton John Price=$123.32
Album=Photographs & Artist= Jim Croce Price=$ 4.95
Album=Heads & Tales Artist= Harry Chapin Price=$ 12.50
The
contents of FORMAT.RPT are identical to the display created by the
program in Listing 11.4.
Using more than one format in reports destined for files is slightly more
complicated than it was when STDOUT was used. The process is more
involved because you need to make the output file handle the default file handle
before setting the $~ or $^ special variables.
| Pseudocode |
|
Declare a format for the CD_REPORT file handle.
Declare a format for the total price information using
CD_REPORT_TOTAL as the format name.
Declare a heading format for the CD_REPORT file handle using
CD_REPORT_TOP as the format name.
Declare the dotize() function.
Initialize local variables called $width and $string.
If the width of $string is greater than $width,
return a value that consists of $string shortened to
$width-3 with ... appended to the end; otherwise, return
$string.
Open the FORMAT.DAT file, read all the lines into
@lines, and then close the file.
Open the FORMAT.RPT file for output to hold the report.
Initialize the $total variable to zero.
Iterate over the @lines array.
Remove the linefeed character.
Split the string into three fields.
Provide a default value for any empty variables.
Invoke the format statement by using the write()
function specifying the CD_REPORT file name.
Change the current format by assigning a value to the $~
special variable. This statement uses some advanced concepts and is
explained further after the listing.
Invoke the format statement by using the write()
function.
Close the FORMAT.RPT file. |
|
Listing 11.10-11LST10.PL - Using an Alternative format
Statement |
format CD_REPORT =
@<<<<<<<<<<<<<<<< @<<<<<<<<<<<<<<< $@###.##
dotize(17, $album), dotize(16, $artist), $price
.
format CD_REPORT_TOTAL =
---------------------------------------------
$@###.##
$total
.
format CD_REPORT_TOP =
@|||||||||||||||||||||||||||||||||||| Pg @<
"CD Collection of David Medinets", $%
Album Artist Price
----------------- ---------------- --------
.
sub dotize {
my($width, $string) = @_;
if (length($string) > $width) {
return(substr($string, 0, $width - 3) . "...");
}
else {
return($string);
}
}
open(FILE, ";
close(FILE);
open(CD_REPORT, ">format.rpt");
$total = 0;
foreach (@lines) {
chop();
($album, $artist, $price) = (split(/!/));
$album = "" if !defined($album);
$artist = "" if !defined($artist);
$price = 0 if !defined($price);
write(CD_REPORT);
$total += $price;
}
select((select(CD_REPORT), $~ = "CD_REPORT_TOTAL")[0]);
write(CD_REPORT);
close(CD_REPORT);
|
This program creates a file called FORMAT.RPT that contains the
following:
CD Collection of David Medinets Pg 1
Album Artist Price
----------------- ---------------- --------
The Lion King $ 0.00
Tumbleweed Con... Elton John $ 123.32
Photographs & ... Jim Croce $ 4.95
Heads & Tales Harry Chapin $ 12.50
---------------------------------------------
$ 140.77The contents of
FORMAT.RPT are identical to the display created by the program in
Listing 11.7.
The statement that changes a default file handle and format name is a little
complicated. Let's take a closer look at it.
select((select(CD_REPORT), $~ = "CD_REPORT_TOTAL")[0]);
In order
to understand most statements, you need to look at the innermost parenthesis
first, and this one is no different. The innermost expression to evaluate is
select(CD_REPORT), $~ = "CD_REPORT_TOTAL"
You might recall that
the comma operator lets you place one or more statements where normally you can
place only one. That's what is happening here. First, CD_REPORT is
selected as the default file handle for the print and write
statements, and then the $~ variable is changed to the new format name.
By enclosing the two statements inside parentheses, their return values are used
in an array context. You have probably already guessed that the [0]
notation is then used to retrieve the first element of the array: the value
returned from the select() function. Because the select()
function returns the value of the previous default file handle, after executing
the second select(), the default file handle is restored to its
previous value.
This bit of code could have been written like this:
$oldhandle = select(CD_REPORT);
$~ = "CD_REPORT_TOTAL";
select($oldhandle);
## Summary
In this chapter, you learned how to create simple reports that incorporate headers, footers, and detail lines. Headers are
used at the top of each page and can consist of both static text and values from
variables. Footers are used at the bottom of each page and can consist only of
static text. Detail lines make up the body of a report.
Header and detail lines are defined by using format statements that
have alternating field and value lines. The field lines hold the static text and
field holders while the value lines hold a comma-delimited list of expressions.
You can use several different format characters when creating the field
holder to have left-justified, right-justified, or centered fields. You can also
use word-wrapping to display long pieces of text in your reports.
Directing a report to a file instead of to STDOUT required some
simple steps. The output file needs to be opened; the file handle needs to be
specified as the format name in the format statement; the format name
needs to be specified in the write statement; and the output file needs
to be closed.
The next chapter focuses on special variables. All the different special
variables you have seen so far - and more - are discussed along with some
examples of how to use them .
## Review Questions
- What is the syntax of the format statement?
- What is a footer?
- What function is used to invoke the format statement?
- How can you change a detail format line into a header format line?
- What is the > format character used for?
- What is the $^L variable used for?
- Can associative array variables be used in value lines?
- What will the following line of code do?
select((select(ANNUAL_RPT), $^ = "REGIONAL_SALES")[0]);
## Review Exercises
- Modify the program in Listing 11.4 to display the second field as
left-justified instead of right-justified.
- Create a report that has both a price and a tax column. Use a tax rate of
7 percent.
- Modify the program in Listing 11.7 to display an average of the CD prices
instead of the total of the prices.
- Create a program that sends the report in the preceding exercise to a
file. Use the select statement to change the default file handle so
that a file handle does not need to be passed to the write()
function.
- Modify Listing 11.5 so that each pass through the loop checks the value of
$-. When the value of $- is one less than $=,
change the value of $^L to emulate a footer with variable text.
- Create a report that uses a detail line format with more than one line.
How would this affect the program written for Exercise 5?