Diamond Operator

2026-01-03

Two angle brackets. Empty:

<>

The diamond operator. Also called the null filehandle. Every Perl scripter uses it, often without knowing its name.

It reads from files or STDIN, magically.

Part 1: THE MAGIC

while (<>)
{
    print;
}

Run this script three ways:

perl script.pl file1.txt file2.txt    # Reads both files
cat data.txt | perl script.pl          # Reads from pipe
perl script.pl                         # Reads from keyboard

The diamond figures out what you meant. Files on command line? Read those. Nothing? Read STDIN. It just works.

Part 2: HOW IT WORKS

The diamond reads from @ARGV if it has files, otherwise from STDIN.

Step by step:

1. Check @ARGV
2. If files exist, open and read the first one
3. When exhausted, move to the next file in @ARGV
4. If @ARGV is empty, read from STDIN

It's the behavior that makes Unix filter programs work:

grep pattern file.txt      # Read from file
cat file.txt | grep pattern    # Read from pipe

Same command, different input sources.

      .--.
     |o_o |
     |:_/ |
    //   \ \
   (|     | )
  /'\_   _/`\
  \___)=(___/

Part 3: THE -n AND -p SWITCHES

The diamond is why -n and -p work:

perl -ne 'print if /pattern/' file.txt

This wraps your code in:

while (<>)
{
    print if /pattern/;
}

The diamond handles the file automatically.

Part 4: MULTIPLE FILES

Process many files seamlessly:

perl -ne 'print "$ARGV: $_"' *.txt

$ARGV contains the current filename. The diamond reads each file in sequence.

Output:

file1.txt: first line of file1
file1.txt: second line of file1
file2.txt: first line of file2
...

Part 5: LINE NUMBERS

$. is the line number:

while (<>)
{
    print "$.: $_";
}

But here's a gotcha: $. doesn't reset between files!

perl -ne 'print "$.: $_"' file1.txt file2.txt

If file1.txt has 10 lines, file2.txt starts at line 11.

To reset, close ARGV explicitly:

while (<>)
{
    print "$ARGV:$.: $_";
}
continue
{
    close ARGV if eof;    # Reset $. for next file
}

Part 6: MODIFYING @ARGV

You can manipulate @ARGV before the loop:

# Only process .log files
@ARGV = grep { /\.log$/ } @ARGV;

while (<>)
{
    # ...
}

Or add files programmatically:

push @ARGV, '/var/log/syslog' unless @ARGV;

while (<>)
{
    # ...
}

Default to syslog if no files given.

Part 7: THE DASH TRICK

A single dash means STDIN:

perl script.pl file1.txt - file2.txt

This reads file1, then STDIN, then file2. Useful for mixing file input with piped data.

echo "injected line" | perl script.pl before.txt - after.txt

Part 8: IN-PLACE EDITING

The diamond enables -i (in-place editing):

perl -i.bak -pe 's/old/new/g' file.txt

This:

1. Reads file.txt via diamond
2. Processes each line
3. Writes back to the same file
4. Saves original as file.txt.bak

The diamond is doing all the file handling.

Part 9: READING ALL AT ONCE

Slurp mode reads entire file:

local $/ = undef;    # Unset record separator
my $content = <>;    # Read entire file(s)

Or multiple files into an array:

my @all_lines = <>;    # All lines from all files

Warning: memory-intensive for large files.

Part 10: EXPLICIT FILEHANDLES

Diamond reads from ARGV implicitly. For explicit control:

open my $fh, '<', 'file.txt' or die;
while (<$fh>)
{
    # ...
}

Or the old-school bareword:

open FH, '<', 'file.txt' or die;
while (<FH>)
{
    # ...
}

Diamond is for when you want the magic.

Part 11: THE SECURITY PROBLEM

Here's the dark side. The diamond uses two-argument open:

while (<>)    # Internally: open(ARGV, $ARGV[0])

Two-argument open interprets special characters:

perl script.pl 'rm -rf / |'

This doesn't read a file called "rm -rf / |". It EXECUTES that command and reads its output.

Dangerous if @ARGV comes from untrusted input.

Fix: use the double diamond (next tutorial) or validate @ARGV.

Part 12: USEFUL PATTERNS

Count lines in multiple files:

my $total = 0;
while (<>)
{
    $total++;
}
print "Total lines: $total\n";

Search and report with filenames:

while (<>)
{
    print "$ARGV:$.: $_" if /pattern/;
}
continue
{
    close ARGV if eof;
}

Concatenate files with headers:

my $current = '';
while (<>)
{
    if ($ARGV ne $current)
    {
        print "=** $ARGV **=\n";
        $current = $ARGV;
    }
    print;
}

Part 13: THE NAME

Look at it:

<>

It's a diamond shape. Or an empty box. Or angle brackets with nothing inside.

"Null filehandle" is the technical name. "Diamond operator" is what everyone calls it.

The angles point outward like rays of magic, pulling input from wherever it needs to come from.

                <>
               /  \
              /    \
             <      >
              \    /
               \  /
                \/

     Magic input since Perl 1

perl.gg