Title

Previous Chapter
Next Chapter

Links
Sections
Chapters
Copyright

Sections

What's a Format Statement?

Summary

Review Questions

Review Exercises

Chapters

ERRATA

Welcome!

Introduction

Part I: Basic Perl

01-Getting Your Feet Wet

02-Numeric and String Literals

03-Variables

04-Operators

05-Functions

06-Statements

07-Control Statements

08-References

Part II: Intermediate Perl

09-Using Files

10-Regular Expressions

11-Creating Reports

Part III: Advanced Perl

12-Using Special Variables

13-Handling Errors and Signals

14-What Are Objects?

15-Perl Modules

16-Debugging Perl

17-Command line Options

Part IV: Perl and the Internet

18-Using Internet Protocols

ftplib.pl

19-What is CGI?

20-Form Processing

21-Using Perl with Web Servers

22-Internet Resources

Appendixes

A-Review Questions

B-Glossary

C-Function List

D-The Windows Registry

E-What's On the CD?

     

11 - 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, "<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.

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

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, "<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.

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, "<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 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

  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 7 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?

Top of Page | Sections | Chapters | Copyright