Problem

You'd like to treat a text file as an array of lines with read-write privileges. You might want to do that so you could easily update the Nth line.

Solution

The DB_File module lets you tie a text file to an array.

use DB_File;

tie(@array, "DB_File", "/tmp/textfile", O_RDWR|O_CREAT, 0666, $DB_RECNO)
    or die "Cannot open file 'text': $!\en" ;

$array[4] = "a new line";
untie @array;

Description

Updating a textfile in place is surprisingly tricky, as noted in Chapter 7, File Access. The RECNO binding provides a nice way to address the file as though it were a simple array of lines  - the way everyone always seems to think they can.

Working with files this way can be odd. For one thing, the zeroth element of the tied array is the first line of the file. More importantly, tied arrays aren't as fully featured as tied hashes are. This will be fixed in a future version of Perl  - patches are already available, in fact.

As you can see from the example above, the tied array interface is limited. To make the interface more useful, methods supplied with DB_File simulate the standard array operations that are not currently implemented in Perl's tied array interface. Save the return value from tie function or retrieve it later from the tied hash using the tied function. Use this object to access the following methods:

$X->push(LIST)

Pushes elements of LIST to the end of the array.

$value = $X->pop

Removes and returns the last element of the array.

$X->shift

Removes and returns the first element of the array.

$X->unshift(LIST)

Pushes elements of LIST to the start of the array.

$X->length

Returns the number of elements in the array.

Example 14.5 is a more complete example using methods described above. It also accesses the direct API interface as described in the DB_File module documentation. (Much of this recipe is derived from the DB_File module documentation, courtesy of Paul Marquess, author of the Perl port of Berkeley DB. This material is used with his permission.)

#!/usr/bin/perl -w
# recno_demo - show how to use the raw API on recno bindings
use strict;
use vars qw(@lines $dbobj $file $i);
use DB_File;

$file = "/tmp/textfile";
unlink $file;               # just in case

$dbobj = tie(@lines, "DB_File", $file, O_RDWR|O_CREAT, 0666, $DB_RECNO)
    or die "Cannot open file $file: $!\n";

# first create a text file to play with
$lines[0] = "zero";
$lines[1] = "one";
$lines[2] = "two";
$lines[3] = "three";
$lines[4] = "four";

# Print the records in order.
#
# The length method is needed here because evaluating a tied
# array in a scalar context does not return the number of
# elements in the array.

print "\nORIGINAL\n";
foreach $i (0 .. $dbobj->length - 1) {
    print "$i: $lines[$i]\n";
}

# use the push & pop methods
$a = $dbobj->pop;
$dbobj->push("last");
print "\nThe last record was [$a]\n";

# and the shift & unshift methods
$a = $dbobj->shift;
$dbobj->unshift("first");
print "The first record was [$a]\n";

# Use the API to add a new record after record 2.
$i = 2;
$dbobj->put($i, "Newbie", R_IAFTER);
    
# and a new record before record 1.
$i = 1;
$dbobj->put($i, "New One", R_IBEFORE);

# delete record 3
$dbobj->del(3);

# now print the records in reverse order
print "\nREVERSE\n";
for ($i = $dbobj->length - 1; $i >= 0; -- $i) {
    print "$i: $lines[$i]\n";
}

# same again, but use the API functions instead
print "\nREVERSE again\n";
my ($s, $k, $v)  = (0, 0, 0);
for ($s = $dbobj->seq($k, $v, R_LAST);
     $s == 0;
     $s = $dbobj->seq($k, $v, R_PREV))
{
    print "$k: $v\n"
}

undef $dbobj;
untie @lines;

This is what it outputs:

ORIGINAL
0: zero
1: one
2: two
3: three
4: four

The last record was [four]
The first record was [zero]

REVERSE
5: last
4: three
3: Newbie
2: one
1: New One
0: first

REVERSE again
5: last
4: three
3: Newbie
2: one
1: New One
0: first

Note that rather than iterating through the array, @lines, like this:

    foreach $item (@lines) { }

you must use either this:

    foreach $i (0 .. $dbobj->length - 1) { }

or this:

    for ($done_yet = $dbobj->get($k, $v, R_FIRST);
         not $done_yet;
         $done_yet = $dbobj->get($k, $v, R_NEXT) )
    {
        # process key or value
    }

Also, when we used the put method, we specified the record index using a variable, $i, rather than passing the literal value itself. This is because put returns the record number of the inserted line in that parameter, altering its contents.

See Also

The documentation for the standard DB_File module, also in Chapter 7 of Programming Perl, in its discussion of $DB_RECNO bindings.