Perhaps the most basic thing you might wish to do from a program is to read what a user types in:

use strict;
use warnings;
print "Enter your name: ";
my $name = <STDIN>;
chomp($name);
print "Hello, $name!\n";

If you run this program, it will print Enter your name: and wait for you to enter something and hit enter. Then it will print that “something”. So if you entered Ovid for your name, you would see this:

Enter your name: Ovid
Hello, Ovid!

The <STDIN> syntax looks a bit odd. You already know the angle brackets are generally wrapped around a filehandle to read from that filehandle, but what’s STDIN? We need to give a bit of a long explanation for you to understand how this work.

For Perl, and in fact, for many modern programming languages, you have one input stream of data (STDIN) and two output streams of data, one for normal output (STDOUT) and one for error output (STDERR). STDIN, STDOUT, and STDERR are all special filehandles and a stream is the sequence of data made available over time. So when you type your name in the program above, you can take your time typing each character until you finally hit enter. When you hit enter is when Perl reads the data from the STDIN and returns it, in this case by assigning it to the $name variable. The STDIN filehandle also returns the newline, so we call chomp() to remove that newline.

When you print something in Perl, by default it prints to STDOUT. You may recall that you can print something to a filehandle like this:

open my $fh, '>', $filename
  or die "Cannot open $filename for writing: $!";
print $fh "Here is a line of text\n";

What happens when you omit the filehandle? Perl uses STDOUT by default. Thus, the following two lines mean the same thing:

print "Hello, $name!'n";
print STDOUT "Hello, $name!'n";

When you warn or die, the message is instead printed to STDERR. The following two lines are almost the same thing:

print STDERR "This is a warning!\n";
warn "This is a warning!\n";

print STDERR "This is a warning!\n";
warn "This is a warning!\n";

When data sent to STDOUT and STDERR show up on your terminal, they look the same, but because they are sent to different streams, they won’t also show up in the same order your program output them. Normally this is not a problem, but it’s something you should be aware of.

The reason STDOUT and STDERR are sent to separate streams is because you can get more control over them. From the command line, you could redirect STDERR to a log file and have STDOUT show up in the terminal, and vice-versa. We won’t really cover much more of that, but it’s part of what’s tricky about understanding data streams when you’re programming. Just remember than when you print something, it usually does what you want it to do.

Since STDIN is a stream, you can read from it multiple times:

use strict;
use warnings;
print "Enter your name: ";
my $name = <STDIN>;
chomp($name);
print "Hello, $name!\n";
print "Anything else you want to bore me with? ";
my $inane_reply = <STDIN>;
chomp($inane_reply);
print "You bored me with: $inane_reply\n";

Any time you want to read from STDIN, it’s there, waiting for you patiently, like some creepy little stalker.

You’ve seen several examples in this book of reading from @ARGV. @ARGV, as you know, contains arguments supplied on the command line. So you could save this as dump_args.pl:

use strict;
use warnings;
use Data::Dumper;
print Dumper(\@ARGV);

And then run it with:

perl dump_args.pl this is a list of arguments

And you should get the following output:

$VAR1 = [
          'this',
          'is',
          'a',
          'list',
          'of',
          'arguments'
        ];

Many times, however, we want to pass arguments to our program and give them specific names to make it easier for our program to understand them. For example, you may recall that in Chapter 7, Subroutines we had a program called maze.pl. In that program, you needed to specify the height and width of the maze. A common way of doing this would be as follows:

perl maze.pl --height 20 --width 40

There are many ways you could handle that, including writing your own parser, but there are plenty of modules on the CPAN to do this for you. Most of these are in the Getopt:: namespace. We’ll use Getopt::Long, by Johan Vromans, as this is one of the most popular choices:

use strict;
use warnings;
use Getopt::Long;
my ( $height, $width );
GetOptions(
    'height=i' => \$height,
    'width=i'  => \$width,
) or die "Could not parse options";
# the rest of your program here

When you use Getopt::Long, it exports a GetOptions function. This function expects an even size list of name/variable pairs. The “name” of each option is actually a specification of how to read that option from the command line. In this example, the =i in height=i says “the --height option must have an integer value”. Of course, that integer value could be negative, so you may need to do some validation after.

The variable $height gets passed as a reference. Because we’re passing by reference instead of value, the Getopt::Long module is able to modify the variable’s value directly. Thus, with the above code, passing either of the following command lines will set $height and $width to 20 and 30, respectively (because the = sign is optional):

perl maze.pl --height 20 --width 30
perl maze.pl --height=20 --width=30

What’s going on is that when you run the program, @ARGV contains all of the values passed in the command line. For the two examples above, @ARGV will contain this:

# perl maze.pl --height 20 --width 30
@ARGV = ('--height', '20', '--width', '30');
# perl maze.pl --height=20 --width=30
@ARGV = ('--height=20', '--width=30');

Getopt::Long will remove all arguments from @ARGV that it can parse, leaving the remaining arguments in @ARGV. For example, if you have a program named print_it.pl:

use strict;
use warnings;
use Getopt::Long;
my $times = 1;
GetOptions(
    'times=i' => \$times,
) or die "Could not parse options";
if ( $times < 1 ) {
   die "The --times argument must be greater than zero";
}
my $args = join '-', @ARGV;
for ( 1 .. $times ) {
    print "$args\n";
}

And you run it with:

perl print_it.pl --times 3 bob dobbs

It will print out the following:

bob-dobbs
bob-dobbs
bob-dobbs

Getopt::Long will also take the minimum unique string for each option (the single dash is optional):

perl maze.pl -h 20 -w 30

Sometimes you don’t want to assign a value to an option, you just want to know if it’s present. For example, you program might print out additional information such as the directories it’s creating, the data it has read from a configuration file, and so on. But you might only want this information displayed if you request it with a --verbose switch:

perl some_program.pl --verbose

And in your program:

use Getopt::Long;
my $is_verbose;
GetOptions(
   'verbose' => \$is_verbose,
) or die "Could not parse options";

With this, $is_verbose will have a true value if you included --verbose (or -v) on the command line, or a false value if you omitted it.

If you include =s with the option name, it expects a string:

use Getopt::Long;
my $name = "Ovid";
GetOptions(
    'name=s' => \$name,
) or die "Could not parse options";
print "Hello, $name\n";

And run that with:

perl get_name.pl --name Bob

That will print Hello, Bob. If you do not supply an argument, the $name value will default to Ovid because GetOptions will not overwrite a value if there is no corresponding value on the command line.

If you string has whitespace in it, you’ll need to quote it:

perl get_name.pl --name 'Bob Dobbs'

That’s because when you run your program with the above arguments, @ARGV would be this without the quoting:

@ARGV = ('--name', 'Bob', 'Dobbs');

And this with the quoting:

@ARGV = ('--name', 'Bob Dobbs');

When using Getopt::Long, you’ll find that standalone arguments (like our --verbose example), string arguments (--name='Bob') and integer arguments (--height and --width) are the most common types of command line arguments, but there are many more ways of handling your parsing. See perldoc Getopt::Long for more details.

While we’re going in-depth about how to run Perl programs from the command line, it would be a bad thing to forget to mention the oft-overlooked perlrun documentation. By reading perldoc perlrun, you will learn many things about how to create useful Perl one-liners to solve thorny problems, or perhaps interesting switches that can make your life easier. For example, the -I switch tells Perl which paths to include when searching for modules to use or require. For example, we often included this line in our sample programs:

use lib 'lib/';

That line tells Perl to also search for Perl modules in the lib/ directory. However, you can use the -I switch to do this from the command line:

perl -Ilib/ some_program.pl

You can specify this more than once:

perl -Ilib/ -I../mylib/ some_program.pl

The -e switch is for executing the text that follows, instead of assuming it’s a program. That’s sometimes used with the -l switch that automatically adds a newline after every print statement. Here’s one way of finding out which version of Moose you have installed:

perl -l -e 'use Moose; print Moose->VERSION'

At the present time on my system, that prints something like:

$ perl -l -e 'use Moose; print Moose->VERSION'
2.0402
$

Note that the $ prompt is on a line by itself. Without the -l switch, you get the following output:

$ perl -l -e 'use Moose; print Moose->VERSION'
2.0402$

That may be annoying to you, so the -l switch makes it nicer to read.

If the switches don’t take arguments, you can “bundle” them together. For example, instead of perl -l -e, you can use perl -le:

perl -le 'use Moose; print Moose->VERSION'

The -n switch wraps a while (<>) { ... } loop around your program. As you might recall, the while(<>) { ... } syntax will read each successive line from filenames found in @ARGV and assigns the line values to $_. Thus, to print out all of the comments in a few programs:

perl -ne 'print if /^\s*#/' program1.pl program2.pl program3.pl

That’s more or less equivalent to this:

use strict;
use warnings;
PROGRAM: foreach my $program (@ARGV) {
    if (open my $fh, '<', $program) {
        while (<$fh>) {
            print $_ if /^\s*#/;
        }
    }
    else {
        warn "Could not open $program for reading: $!";
        next PROGRAM;
    }
}

As you can see, the command line switches documented in perlrun give you a lot of power from the command line, but they can be daunting to learn. Hit your favorite search engine and search for “perl one liners” to see many more examples. They’re very popular.

And don’t forget to dive into perldoc perlrun.

Try it out Query the Google API from the command line

In Chapter 15, The Interwebs, we had a sample program that allowed you to query Google directions from the command line. However, we had hard-coded the start and end locations into the program. That’s not very useful. Now we’re going to rewrite this to allow us to change our start and end locations from the command line.

1. Type in the following program and save it as listing_17_1_directions.pl.

use strict;
use warnings;
use WWW::Mechanize;
use HTML::Strip;
use JSON::Any;
use URI::Encode 'uri_encode';
use utf8::all;
use Getopt::Long;
my ( $start, $end );
GetOptions(
    'start=s' => \$start,
    'end=s'   => \$end,
) or die "Could not parse options";
unless ( $start and $end ) {
    die "Both --start and --end arguments must be supplied";
}
if ( @ARGV ) {
    my $args = join ', ', @ARGV;
    die <<"END";
Your \@ARGV contained '$args'. Did you forget to quote something?
--start=$start
--end=$end
END
}
print "Searching for directions from '$start' to '$end'\n";
$start = uri_encode($start);
$end   = uri_encode($end);
my $url   = "http://maps.googleapis.com/maps/api/directions/json";
my $query = "origin=$start&destination=$end&sensor=false";
my $mech = WWW::Mechanize->new;
$mech->get("$url?$query");
my $object = JSON::Any->new->decode( $mech->content );
unless ( 'OK' eq $object->{status} ) {
    die $object->{status};
}
my $route      = $object->{routes}[0];
my $copyrights = $route->{copyrights};
my $warnings   = $route->{warnings};
my $legs       = $route->{legs}[0];         # only take the first
my $distance   = $legs->{distance}{text};
my $duration   = $legs->{duration}{text};
print "$copyrights\nThe trip is $distance long and "
  . "lasts $duration\n\n";
print join "\n" => @$warnings;
print "\n";
my $strip = HTML::Strip->new;
foreach my $step ( @{ $legs->{steps} } ) {
    my $distance     = $step->{distance}{text};
    my $duration     = $step->{duration}{text};
    my $instructions = $strip->parse($step->{html_instructions});
    $strip->eof;
    print "$instructions for $distance ($duration)\n";
}

Note

listing_17_1_directions.pl available for download at Wrox.com.

2. Run the program with the following command line:

perl listing_17_1_directions.pl \
  --start='Paris, France' --end='London, UK'

You should see output similar to the following (truncated for length):

Continue onto Bd Ornano for 0.8 km (1 min)
Right onto Av. de la Porte de Clignancourt for 0.4 km (1 min)
Continue onto Av. Michelet/D14 Follow D14 for 1.9 km (3 mins)
Turn right onto Rue Francisque Poulbot/D410 for 0.5 km (1 min)
# many lines truncated
Slight left to stay on Westminster Bridge Rd/A302
  Continue to follow A302 Toll road for 0.5 km (1 min)
Right onto Victoria Embankment/A3211 Toll road for 0.6 km (1 min)
Left onto Northumberland Ave/A400 Toll road for 0.4 km (1 min)
At the roundabout, take the 4th exit onto Trafalgar Square/A4/A400
  Continue to follow Trafalgar Square/A400 Toll road
  Destination will be on the left for 0.2 km (1 min)

How it works

Most of this program has already been explained in a Try it out in Chapter 15, The Interwebs, but here’s the entire new section:

  1:  use Getopt::Long;
  2:  my ( $start, $end );
  3:  GetOptions(
  4:      'start=s' => \$start,
  5:      'end=s'   => \$end,
  6:  ) or die "Could not parse options";
  7:
  8:  unless ( $start and $end ) {
  9:      die "Both --start and --end arguments must be supplied";
 10:  }
 11:  if ( @ARGV ) {
 12:      my $args = join ', ', @ARGV;
 13:      die <<"END";
 14:  \@ARGV contained '$args'. Did you forget to quote something?
 15:  --start=$start
 16:  --end=$end
 17:  END
 18:  }
 19:
 20:  print "Searching for directions from '$start' to '$end'\n";
 21:
 22:  $start = uri_encode($start);
 23:  $end   = uri_encode($end);

We use Getopt::Long to capture our command line arguments to the $start and $end variables. That’s lines 3 through 6.

Lines 8 through 10 verify that we’ve received values for both $start and $end. Note how we called this in our example:

perl directions.pl --start='Paris, France' --end='London, UK'

We had to quote the arguments to make sure that our shell knows to pass these arguments as one “chunk” to Perl, rather than as separate bits. If we had done this:

perl directions.pl --start=Paris, France --end=London, UK

We would have set $start to Paris, (with the comma) and $end to London, (again, with the comma) and we would have had the strings France and UK left in our @ARGV. We trap this error and display this in lines 11 through 18. If you had used the above command line, you would have received this error:

@ARGV contained 'France, UK'. Did you forget to quote something?
--start=Paris,
--end=London,

Finally, line 20 prints out expected start and end destinations and lines 22 and 23 do the expected URI encoding and everything else is exactly as we saw in Chapter 15, The Interwebs.

Perl offers a variety of ways of running an external program. We’ll show you how to handle the most common ways of doing this. Table 17.1, “Table 17-1” shows the tools we will cover.

Some of the commands listed in Table 17.1, “Table 17-1” overlap and the choice of each depends on your needs.

The most basic way of running another program is the system() command. This builtin is useful when you want to run an external program and only care about its success or failure, not its output. For example, if you are running a Perl program that has written several megabytes of output in separate files in a directory, you might wish to compress those files into a single file and remove the directory afterwards.

Without going into too much detail, one way to compress a directory of files is to use the tar command:

tar cjf archive.tgz mydir/

That will create a file named archive.tgz, containing the contents of the mydir/ directory. You can later extract (similar to “unzip”) this archive with the following command:

tar xjf archive.tgz

So to compress a directory’s contents into a single file and then delete that directory, we can do this:

use strict;
use warnings;
use DateTime;
# concatenating a string to the end of the DateTime object triggers
# its string overloading. This example will create a string
# representation of the current date and time
my $dir = DateTime->now . "";
# lots of code to write data to the $dir directory
my @command = ('tar', 'cjf', "$dir.tgz", $dir);
system(@command) == 0
  or die "Could not '@command': $?";
@command = ('rm', '-fr', $dir);
system(@command) == 0
  or die "Could not '@command': $?";

This looks a bit strange (and to be fair, system programming often does when you’re not used to it), but let’s look at our first system command and see what’s going on.

my @command = ('tar', 'cjf', "$dir.tgz", $dir);
system(@command) == 0
  or die "Could not '@command': $?";

For this, our @command array has the command as the first element, followed by the arguments to the command as successive elements. For this example, we only put the external tar command into a separate variable to make it easier to report the command failure in the die statement.

The system() command takes a string or a list of strings and executes them. You could pack everything into a single string:

my $command = "tar cjf $dir.tgz $dir";
system($command) == 0
  or die "Could not '$command': $?";

However, putting the command and its arguments into a single string is not recommended because that will call your operating system’s shell to execute the command instead of executing the command directly. We won’t go into detail, but suffice it to say that if you call your operating system’s shell to execute the command, not only is it slower, it also can open up serious security holes. Passing a list to system is faster and, while it can still be dangerous if you don’t know what you’re doing, it’s a touch safer than using a string.

So why do we test that it returns 0? Because on most operating systems, programs have return values. If that value is 0 (zero), the program completed successfully. Thus, what Perl considers to be a false value is returned upon success! If we didn’t test for system(@command) == 0, we’d have to write this:

system(@command)
  and die "Could not '@command': $?";

While that shows up in many programs that use the system command, it’s very confusing to read.

eval { some_func() };
if ( my $error = $@ ) {
    warn $error;
    # do cleanup
    exit 1;
}

The status returned by the last pipe close, backtick (``) command,
successful call to wait() or waitpid(), or from the system()
operator. This is just the 16-bit status word returned by the
traditional Unix wait() system call (or else is made up to look
like it). Thus, the exit value of the subprocess is really
("$? >> 8"), and "$? & 127" gives which signal, if any, the
process died from, and "$? & 128" reports whether there was a core
dump.

Some times you will find yourself running another program and wanting to read its output. Both backticks (``) and the qx// operator help with this (they’re the same thing but with different syntax) and they’re documented in perldoc perlop. So in a Unix system, the uptime command tells you how long the computer has been running since its last reboot or powerup:

print `uptime`;
print qx(uptime);

On my system, that currently prints:

21:42  up 21 days,  4:41, 3 users, load averages: 0.96 0.92 0.91
21:42  up 21 days,  4:41, 3 users, load averages: 0.96 0.92 0.91

print qx(uptime);
print qx/uptime/;
print qx'uptime';
print qx"uptime";
print qx<uptime>;

my $program = 'uptime';
print qx<$program>;

print qx'$uptime';
print qx<\$uptime>;

If you prefer you can also use what is known as a “piped open” to read program output. Just place the pipe, |, after the program name:

open my $read_fh, "$program |"
  or die "Cannot execute '$program |': $!";
while ( my $output = <$read_fh> ) {
    print $output;
}

This can be very useful if you want to pass a function a filehandle and not care if the output is coming from a file or another program.

If you don’t want shell metacharacters to be expanded when using a piped open, use -| instead of a bare |:

open my $read_fh, "$program -|"
  or die "Cannot execute '$program -|': $!";

These methods only capture a program’s STDOUT. To capture its STDERR, you will need to redirect it:

my $stderr = qx/program 2>&1/;

Unfortunately, the 2>&1 is a bit cryptic and it’s not portable. We’ll see Capture::Tiny later in this chapter. This module provides an easy, portable solution.

Sometimes instead of reading from another program, you need to write to it. You can do this by placing the pipe in front of the command:

open my $fh, "| $command"
  or die "Could not open a pipe to $command: $!";

Better still is to use the three argument form of open, with |- to prevent shell expansion:

open my $fh, "|-", $command
  or die "Could not open a pipe to $command: $!";

For example, let’s say you have a block of text and you’d like to know how many lines, words and characters it has. You could use the Unix wc utility:

use strict;
use warnings;
my $text = <<'END';
I will not be pushed, filed, stamped, indexed,
briefed, debriefed, or numbered.
END
open my $fh, '|-', 'wc' or die $!;
print $fh $text;

And that will print out:

2      12      79

That output says we have two lines, twelve words, and seventy-nine characters. The reason why this text is printed out is because wc's default output goes to STDOUT. We effectively use wc to filter our output.

http://sourceforge.net/projects/gnuwin32/files/coreutils/5.3.0/coreutils-5.3.0.exe/download

This can also be useful if you want to change how your own STDOUT behaves. For example, if you want your program’s output to go through a pager such as less, you could do this (we use |- to avoid calling the shell):

my $pager = $ENV{PAGER} || '/usr/bin/less';
open STDOUT, "|-", $pager
  or die "Could not open STDOUT to $pager: $!";

Now your program’s STDOUT output will be using the pager instead of spewing lots of information that might scroll past their terminal window.

If you need to read and write at the same time, see IPC::Open2 and IPC::Open3, both of which are core modules. Or you can install IPC::Run from the CPAN. It’s much more flexible.

The topic has generated many questions over the years and perldoc perlfaq8 has more relevant information. Unfortunately, as of this writing, the perlipc information is a touch out of date.

Earlier we showed you how to capture an external program’s STDERR instead of its STDOUT.

my $stderr = qx/program 2>&1/;

Even if you know you’re only going to be running your program on Linux, perhaps you want to capture both STDOUT and STDERR? That’s where Capture::Tiny comes in.

use Capture::Tiny 'capture';
my ($stdout, $stderr, @result) = capture {
    print "This goes to STDOUT\n";
    warn "This goes to STDERR\n";
    return qw(These are the results);
};
print "STDOUT: $stdout";
print "STDERR: $stderr";
print "Results: @result";

Running the code snippet will output:

STDOUT: This goes to STDOUT
STDERR: This goes to STDERR
Results: These are the results

Capture::Tiny can be used with capturing STDOUT, STDERR and return values from a regular chunk of code. In the case of an external program, it works just the same. Save the following program as example_17_1_poets.pl.

use strict;
use warnings;
my @favorite_poets = (
    'Publius Ovidius Naso',
    'John Davidson',
    'Alfred, Lord Tennyson',
    'Christina Rossetti',
);
foreach my $poet (@favorite_poets) {
    print "$poet\n";
}
warn "We're done here";

It should be pretty clear what happens if you run that, but let’s capture the output in a different program named example_17_2_capture.pl.

use strict;
use warnings;
use Data::Dumper;
use Capture::Tiny 'capture';
my $program = "$^X example_17_1_poets.pl";
my ( $stdout, $stderr, @result ) = capture { qx"$program" };
print Dumper $stdout, $stderr, \@result;

Running that should produce the following output:

$VAR1 = '';
$VAR2 = 'We\'re done here at example_17_1_poets.pl line 14.
';
$VAR3 = [
          'Publius Ovidius Naso
',
          'John Davidson
',
          'Alfred, Lord Tennyson
',
          'Christina Rossetti
'
        ];

In this case, $VAR1 is $stdout, $VAR2 is $stderr, and $VAR3 is the @output. We actually didn’t have any STDOUT to capture because the qx operator captured that for us and returned it as the @output of the qx command. The warning from example_17_1_poets.pl was captured and returned as the $stderr.

Capture::Tiny tries very hard to be cross-platform friendly and generally works on Windows, OS X and Unix/Linux systems. However, the author, David Golden, states that portability is a goal, not a guarantee.

Try it out Parsing wc output

Earlier we showed you how to write data to an external utility, but that generally doesn’t give you much control as the data is dumped directly to STDOUT. It’s important thing to keep in mind with piped opens is that your program and the program you’re piping data to share the same STDIN, STDOUT and STDERR. Thus, when you print $fh $text and are using a piped open it’s the same thing as directly printing the output. Instead, we’d like to capture the output in case we would like to do something different with it.

1. Type in the following program and save it as listing_17_2_wc.pl.

use strict;
use warnings;
my $text = <<'END';
I will not be pushed, filed, stamped, indexed,
briefed, debriefed, or numbered.
END
use Capture::Tiny 'capture';
my ( $stdout, $stderr, @output ) = capture {
    open my $fh, '|-', 'wc' or die $!;
    print $fh $text;
    close $fh or die "Cannot close piped open to wc: $!";
};
my ( $lines, $words, $characters )
  = ( $stdout =~ /(\d+)\s+(\d+)\s+(\d+)/ );
print "Lines: $lines Words: $words Characters: $characters\n";

Note

wc.pl available for download at Wrox.com.

2. Run the program with perl listing_17_2_wc.pl. You should see the following output:

Lines: 2 Words: 12 Characters: 79

How it works

Again, if you’ve been following along, this one is pretty straightforward.

my ( $stdout, $stderr, @output ) = capture {
    open my $fh, '|-', 'wc' or die $!;
    print $fh $text;
    close $fh or die "Cannot close piped open to wc: $!";
};

In our capture() subroutine, we have a piped open to the wc executable and then we print out text to its filehandle. Because a piped open shares the same STDOUT as our parent process (the program that prints the filehandle), the standard output from wc goes to our own STDOUT, thus ensuring that capture() returns this to our $stdout variable. We then use a regular expression to extract the line, word and character count and print them out:

my ( $lines, $words, $characters )
  = ( $stdout =~ /(\d+)\s+(\d+)\s+(\d+)/ );
print "Lines: $lines Words: $words Characters: $characters\n";