Enhancing Terminal Output in Perl

The Perl Journal July 2003

By Shay Harding

Shay has worked with transaction processing systems at CCBill LLC, for the last five years and can be contacted at [email protected].

This article discusses how to make terminal output easier to read and monitor. If you are like me and spend most of the day at a UNIX command prompt, you'll probably benefit from using Term::Report and Term::StatusBar, two modules I created for making terminal output easier to track. They can be used separately, but are best if used together. These modules have few dependencies, which are loaded as required, so there is no need to install anything new.

Typically, programs send their output to STDOUT or STDERR. If there are too many lines sent to the terminal, they end up scrolling and may be irretrievable depending on your terminal's buffer size. You can send the output to a file, but then how do you monitor the program to make sure everything is going well? You could tail -f <file>, but then you run into the same problem of output scrolling off of the screen.

The most important components of useful terminal output are:

1. The ability to see that the program is processing.

2. The ability to see what the program is doing.

3. The ability to track the program's progress.

With these criteria met, there is no doubt about whether the program has hung or what progress it has made in processing the data.

Standard Terminal Output

A simple example of terminal output seen in many scripts is shown in Listing 1. This first example will not utilize Term::Report or Term::StatusBar. This will be modified later in order to show how the Term modules work and how they can be useful.

This listing prints the output to the terminal. If there were thousands of items to iterate over, the output would end up scrolling off the screen. Another problem is that there is no way to gauge progress and tell how long it might take to finish. The data sent to the terminal ends up being cluttered and not very useful. In processing larger data sets, it would be difficult to determine the program's output by using this method.

Cleaning up the Output

The previous output can be organized with the help of Term::Report. With minor alterations, the amount of output can be reduced, thus improving readability; see Listing 2.

The use of Term::Report usually doesn't get any more complicated than the aforementioned example. But even this simple implementation of Term::Report makes the output more organized and easier to follow. It is readily apparent that the program is working and what data it is processing. Two important criteria for useful terminal output have been met.

If there are thousands of items to iterate over, the constructor can be changed as shown below:

my $report = Term::Report->new(startRow => 1, numFormat => 1);
</PRE>


This would format numbers using <i>Number::Format</i> (i.e., 1000 becomes 1,000). This makes it even easier to read the output quickly.</p>



The last criterion, the ability to track the program's progress, is accomplished by using <i>Term::StatusBar</i>. Rather than create a separate object, use <i>Term::Report</i>'s ability to wrap the <i>Term::StatusBar</i> module. (See <A NAME="rl3"><A HREF="#l3">Listing 3</A>.)</p>



Notice that <i>Term::Report</i> has been used to create a status bar. The status bar needs to know how many items there are to process. Then it's just a matter of calling <i>StatusBar->update()</i> with each iteration of data processing.</p>



When updating the inventory in the aforementioned example, the status bar is reset rather than creating a new object. To tell the status bar to empty rather than fill, pass <i>reverse => 1</i> to the <i>reset()</i> method. This is a recent addition to <i>Term::StatusBar</i>. Calling the <i>printBarReport() </i>method outputs our statistics summary. This prints a horizontal bar chart based on the final values and scale of the status bar.</p>



With these minor changes, all three criteria for useful terminal output are satisfied. Use the <i>subText</i> and <i>subTextAlign</i> methods of <i>Term::StatusBar</i> to enhance the output further. These place information just under the status bar to show what the program is currently processing.</p>

<PRE>
my $report = Term::Report->new(
   startRow => 4,
   numFormat => 1,
   statusBar => [
      label => 'Widget Analysis: ',
      subText => 'Locating widgets',
      subTextAlign => 'center'
   ],
);
...
if (!($_%int((rand(10)+rand(10)+1)))){
   $report->finePrint('discarded', 0, ++$discard);
   $status->subText("Discarding bad widget");
}
else{
   $status->subText("Locating widgets");
}

my $report = Term::Report->new(
   startRow => 5,
   numFormat => 1,
   statusBar => [
      label => 'Widget Analysis: ',
      subText => 'Locating widgets',
      subTextAlign => 'center',
      showTime => 1
   ],);

Caveats and Possible Enhancements

Listing 1

#!/usr/bin/perl

$|++;
use Time::HiRes qw(usleep);

my ($items, $discard) = (100,0);

## Monitor inventory (L=Locating; D=Discarding)
for (1..$items){
   if (!($_%int((rand(10)+rand(10)+1)))){
      $discard++;
      print " D ";
   }
   else {
      print "L";
   }

   usleep(50000);
}
print "\n";

## Update inventory
for (1..($items-$discard)){
   print "U";
}

print "\n\n\n    Summary for widgets: \n\n".
      "       Total:        $items\n".
      "       Good Widgets: ".($items-$discard)."\n".
      "       Bad Widgets:  $discard\n\n";

Listing 2

#/usr/bin/perl

$|++;
use Time::HiRes qw(usleep);
use Term::Report;

my $report = Term::Report->new(startRow => 1);
my ($items, $discard) = (100,0);

$report->savePoint('total', "Total widgets: ", 1);
$report->savePoint('discarded', "\n  Widgets discarded: ", 1);

## Monitor inventory 
for (1..$items){
   $report->finePrint('total', 0, $_);

   if (!($_%int((rand(10)+rand(10)+1)))){
      $report->finePrint('discarded', 0, ++$discard);
   }

   usleep(50000);
}

## Update inventory
$report->savePoint('inventory', "\n\nInventorying widgets... ", 1);

for (1..($items-$discard)){
   $report->finePrint('inventory', 0, $_);
}

$report->printLine("\n\n\n\n    Summary for widgets: \n\n");
$report->printLine("       Total:        $items\n");
$report->printLine("       Good Widgets: ".($items-$discard)."\n");
$report->printLine("       Bad Widgets:  $discard\n");

Listing 3

#!/usr/bin/perl

$|++;
use Time::HiRes qw(usleep);
use Term::Report;

my $report = Term::Report->new(
   startRow => 4,
   numFormat => 1,
   statusBar => [
      label => 'Widget Analysis: ',
   ],
);
my ($items, $discard) = (100,0);

my $status = $report->{statusBar};
$status->setItems($items);
$status->start;

$report->savePoint('total', "Total widgets: ", 1);
$report->savePoint('discarded', "\n  Widgets discarded: ", 1);

## Monitor inventory
for (1..$items){
   $report->finePrint('total', 0, $_);

   if (!($_%int((rand(10)+rand(10)+1)))){
      $report->finePrint('discarded', 0, ++$discard);
   }

   usleep(50000);
   $status->update;
}

## Update inventory
$status->reset({
    reverse=>1, 
    setItems=>($items-$discard), 
    start=>1
});

$report->savePoint(
   'inventory', 
   "\n\nInventorying widgets... ", 
   1
);

for (1..($items-$discard)){
   $report->finePrint('inventory', 0, $_);
   $status->update;
}

   $report->printBarReport(
      "\n\n\n\n    Summary for widgets: \n\n",
      {
            "       Total:        " => $items,
            "       Good Widgets: " => $items-$discard,
            "       Bad Widgets:  " => $discard,
      }
   );

Back to Article