The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Tie::FlatFile::Array - Treat a flatfile database as an array of arrays.

SYNOPSIS

    use Tie::FlatFile::Array;
    use Fcntl;

    tie @flat, 'Tie::FlatFile::Array', 'data.file',
            O_RDWR | O_CREAT, 0644, { packformat => 'A30L' };
    
    @flat = (
            [www.yahoo.com => 3601],
            [www.google.com => 5214]
            );

    untie @flat;

DESCRIPTION

This module allows the programmer to treat a flatfile database as as array of arrays. For example, let's say you have a datafile that has fixed-length records like so:

  Field-name    Type
  URL           ASCII characters, length 30
  Referals      Integer, 4 bytes, binary in network order

If you were going to use pack to create a record like this, you'd use a format string of A30N. Since Tie::FlatFile::Array does the packing and unpacking behind the scenes, you would use that pack format string in the call to tie:

  tie @flat, 'Tie::FlatFile::Array', 'data.file',
        O_RDWR | O_CREAT, 0644, { packformat => 'A30N' }
        or die("Tie failure: $!");

To insert an item into the data file, you would assign an array reference to one of the array's elements like so:

  $flat[0] = [ 'www.yahoo.com', 3601 ];

Behind the scenes, code something like this will be executed:

  seek($fh, 0, SEEK_SET);
  print $fh pack('A30N', @{['www.yahoo.com', 3601]});

If you were to assign something to the second element in the tied array:

  $flat[1] = [ 'www.google.com', 5814 ];

Something like this would happen:

  seek($fh, 34, SEEK_SET);
  print $fh pack('A30N', @{['www.google.com', 5814]});

When you insert data into the file, you must use an array reference, and when you extract data from the file you receive an array reference. This code should display the file's contents:

    use Tie::FlatFile::Array;
    use Fcntl;

    tie @flat, 'Tie::FlatFile::Array', 'data.file',
        O_RDWR | O_CREAT, 0644, { packformat => 'A30N' };

    foreach my $index (0..$#flat) {
        my $ref = $flat[$index];
        print "@{$ref}\n";
    }

    untie @flat;

Note that fetching beyond the bounds of the array results in undef.

SEE ALSO

See perltie, "perldoc -f pack" and possibly Tie::Array and Carp.

AUTHOR

  Copywright 2007-2009 Mumia Wotse
  Mumia Wotse <mumia.w.18.spam+nospam [at] earthlink.net>

This program is under the General Public License (GPL).