Chapter 11

Creating Reports


CONTENTS

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.

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, "<format.dat");

@lines = <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.

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 is 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, "<format.dat");

@lines = <FILE>;

close(FILE);



foreach (@lines) {

    chop;

    ($album, $artist, $price) = (split(/!/));

    $album  = "" if !defined($album);  These lines assign null

    $artist = "" if !defined($artist); strings if no info is

    $price  = "" if !defined($price);  present in the record.

    print("Album=$album   Artist=$artist   Price=$price\n");

}

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 heading and have 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 (refer to 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 never are 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.50

The 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.1 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.

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 is 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, "<format.dat");

@lines = <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 six-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

  -----------------  ----------------  -------

  The Lion King                        $  0.00

  Tumbleweed Connec  Elton John        $123.32

  Photographs & Mem  Jim Croce         $  4.95

  Heads & Tales      Harry Chapin      $ 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 also might 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.

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 is 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 probably will 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, "<format.dat");

@lines = <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 Consulting

Let 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 probably should 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 probably is not the behavior you would 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.

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 is 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, "<format.dat");

@lines = <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 also can 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.

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, "<format.dat");

@lines = <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.77

This 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.

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 then would 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.

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 is 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-Using a Format with STDOUT

format CD _REPORT =

  Album=@<<<<<<<<<<<<<  Artist=@>>>>>>>>>>>>  Price=$@##.##

        $album,                $artist,              $price

.



open(FILE, "<format.dat");

@lines = <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. Listing 11.10 shows how to use an alternative format statement.

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, "<format.dat");

@lines = <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.77

The 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 probably already have guessed that the [0] notation then is 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 also can use word-wrapping to display long pieces of text in your reports.

Directing a report to a file instead of to STDOUT requires 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

Answers to Review Questions are in Appendix A.

  1. What is the syntax of the format statement?
  2. What is a footer?
  3. What fuNCtion is used to invoke the format statement?
  4. How can you change a detail format line into a header format line?
  5. What is the > format character used for?
  6. What is the $^L variable used for?
  7. Can associative array variables be used in value lines?
  8. What will the following line of code do?

    select((select(ANNUAL_RPT), $^ = "REGIONAL_SALES")[0]);

Review Exercises

  1. Modify the program in Listing 11.4 to display the second field as left-justified instead of right-justified.
  2. Create a report that has both a price and a tax column. Use a tax rate of seven percent.
  3. Modify the program in Listing 11.7 to display an average of the CD prices instead of the total of the prices.
  4. 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.
  5. 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.
  6. Create a report that uses a detail line format with more than one line. How would this affect the program written for Exercise 5?