Use Perl Builtins Safely: Context, Lists, Files and Errors

You will finish with a small Perl workflow that reads lines, transforms a list, writes a result, and reports failures without guessing what a builtin returned. The examples target Perl 5.38.2, the installed version on this machine. Allow about fifteen minutes. You need Perl and a writable working directory; no elevated privileges are required.

The perlfunc(1) manual covers the whole builtin library, from chomp and map to open, eval and system. The useful starting point is not memorising every function. It is understanding context, precedence, return values and the difference between reading data and changing state.

1. Confirm the Perl version and compile a script

Check the interpreter before relying on a feature. This guide uses ordinary builtins and does not need a module installation:

$ perl -v
This is perl 5, version 38, subversion 2 (v5.38.2)
$ perl -c -e 'use strict; use warnings; print "syntax ok\n"'
syntax ok

use strict catches accidental barewords and undeclared variables. use warnings reports suspicious operations, including some cases where Perl's function-like syntax is easy to misread.

2. Make context explicit

Perl builtins can behave differently in list and scalar context. An array in list context supplies its elements; in scalar context it supplies its element count:

use strict;
use warnings;

my @numbers = (10, 20, 30);
my @copy = @numbers;
my $count = @numbers;

print "copy: ", join(", ", @copy), "\n";
print "count: $count\n";

$ perl context.pl
copy: 10, 20, 30
count: 3

Do not assume that a function's scalar result is simply the list result reduced to one value. The manual explicitly warns that each function chooses its own scalar behaviour. Write scalar @numbers when the count is the point of the code. That makes reviews and later edits less error-prone.

3. Avoid the function-parenthesis trap

Some builtins are list operators, so omitting parentheses lets precedence change the argument they receive. These two expressions are not equivalent:

use strict;
use warnings;

print 1 + 2 + 4;       # prints 7
print(1 + 2) + 4;      # prints 3, then evaluates + 4
print +(1 + 2) + 4;    # prints 7

For a builtin with a complicated expression, use parentheses or a temporary variable rather than relying on visual intuition. Run the code with warnings while developing it; Perl can report that print (...) was interpreted as a function and that an addition was useless in void context.

A no-argument builtin such as time is a separate case: time + 86400 means time() + 86400. The syntax is compact, but the context and precedence rules still apply.

4. Transform input with chomp, map and grep

Keep input cleanup, transformation and selection as distinct operations. This example uses an in-memory list so it is safe to paste and run:

use strict;
use warnings;

my @raw = ("  apple\n", "pear\n", "  plum\n");
chomp @raw;
my @trimmed = map { s/^\s+|\s+$//gr } @raw;
my @long = grep { length($_) > 4 } @trimmed;

print join(", ", @long), "\n";

$ perl lists.pl
apple, plum

chomp removes the current input record separator, normally the line ending. map returns a transformed list. grep returns elements for which its condition is true. A common distraction is accidentally changing the source list inside a block; the substitution above uses /r to return a changed copy and leave @raw alone.

5. Open a file and check every state change

Opening for writing changes the filesystem and can truncate an existing file. The example uses a new destination name. Do not point it at a valuable file until you have checked the path:

use strict;
use warnings;

my $output = "report.txt";
open my $fh, '>', $output or die "open $output: $!\n";
print {$fh} "apple\nplum\n" or die "write $output: $!\n";
close $fh or die "close $output: $!\n";

print "wrote $output\n";

Run it as an ordinary user in a test directory:

$ mkdir -p perlfunc-demo
$ cd perlfunc-demo
$ perl ../write-report.pl
wrote report.txt
$ test -s report.txt && cat report.txt
apple
plum

The three checks matter. open can fail because of the path or permissions, print can fail after opening, and close can expose a final write error. The $! value describes the operating-system error for these syscall-like functions.

6. Handle expected exceptions with eval

Use a block eval when a failure is expected and the caller can recover. Check $@ immediately after the block:

use strict;
use warnings;

my $result = eval {
    die "input rejected\n";
};

if ($@) {
    print "handled: $@";
} else {
    print "result: $result\n";
}

$ perl recover.pl
handled: input rejected

Do not use eval STRING for ordinary data: compiling generated text introduces code-execution risk and makes errors harder to locate. For a simple fatal error where recovery is not useful, die is clearer. For a system command, remember that system has its own exit-status handling; do not treat a defined return value as proof that the child succeeded.

Common failure modes

• Unexpected list output: inspect whether the caller requested scalar or list context and add scalar where a count is intended.
• Strange print output: add parentheses around the arguments and rerun with use warnings.
• Missing line endings: call chomp on input before transforming it, but remember that it removes the input record separator rather than arbitrary whitespace.
• Silent file failure: use the three checks around open, print and close; inspect $! before another operation overwrites the useful error context.