NAME

ESPPlus::Storage::Reader - Reads ESP+ Storage repository files

SYNOPSIS

use ESPPlus::Storage;
my $st = ESPPlus::Storage->new
    ( { filename => $Repository,
        uncompress_function => \&uncompress } );
my $rd = $st->reader;

local *RC;
while ( my $record = $rd->next_record_body ) {
    my $filename = $rd->record_number() . ".met";
    open RC, ">", $filename or die "Couldn't open $filename for writing: $!";
    print RC $$record;
    close RC;
}

DESCRIPTION

ESPPlus::Storage::Reader provides some methods for reading an ESP+ Storage .REP repository database. In general the expectation is that you will read the database serially - start with the first record and continue pulling until there are no more records left. You can alter this by seeking on the internal handle and changing the record_number.

Please also see ESPPlus::Storage for a sample uncompress wrapper function.

ESPPlus::Storage::Reader::Tie provides an alternate and even easier reader interface.

CONSTRUCTOR

new

$rd = ESPPlus::Storage::Reader->new(
    { uncompress_function => \&uncompress,
      handle              => $io_file_handle } );

The new() method has exactly two parameters, both of which are required. In normal operation the ESPPlus::Storage::Reader-new> method is only used internally by ESPPlus::Storage objects.

uncompress_function (as noted on ESPPlus::Storage) is a reference to a function which is expected to receive a reference to a .Z compressed string and should return a reference to an uncompressed string.

handle is an already opened IO::File object.

METHODS / PROPERTIES

next_record

This is the primary focus of this module. It returns a ESPPlus::Storage::Record object for the next record in the ESP+ Storage .REP repository. You should call this method every time you need the next object.

while( my $rc_obj = $d->next_record ) {
    # ...
}

next_record_body

This returns a reference to the uncompressed content of the next record. In contrast to next_record, this doesn't return a ESPPlus::Storage::Record object.

while( my $rc = $d->next_record_body ) {
    # ...
}

handle

This returns the internal IO::Handle. If you seek or read from the handle be sure to set the reader object's record_number value appropriately and flush the internal buffer in ->{'_buffer'}. If you do that, you are responsible for ensuring that both _buffer and the IO::Handle are correctly set.

record_number

Returns the current record number.

uncompress_function

Returns the .Z uncompress function. See the ESPPlus::Storage page for a sample function you can use.

COPYRIGHT AND LICENSE

Copyright 2003, Joshua b. Jore. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of either:

a) the GNU General Public License as published by the Free Software Foundation; version 2, or

b) the "Artistic License" which comes with Perl.

SEE ALSO

ESPPlus::Storage::Reader::Tie ESPPlus::Storage ESPPlus::Storage::Record