ESPPlus::Storage - An interface to ESP+ Storage repository files
use ESPPlus::Storage; my $st = ESPPlus::Storage->new ( { filename => $Repository, uncompress_function => \&uncompress } );
This module provides an interface to the ESP+ Storage repository files. It allows you to read a .REP file as a series of original records. See ESPPlus::Storage::Reader::Tie for an especially easy interface for reading databases.
For an even easier interface, see ESPPlus::Storage::Reader::Tie. It wraps the interface described below and in ESPPlus::Storage::Reader and ESPPlus::Storage::Record.
$db = ESPPlus::Storage->new( { compress_function => \ &compress, uncompress_function => \ &uncompress, ( $handle ? ( handle => $handle ) : ( filename => $filename ) ) } )
This is the class constructor and it takes four optional arguments, two of them contradictory. It returns a new ESPPlus::Storage object. All of the arguments are passed in data in a hash reference.
ESPPlus::Storage
The compress_function and uncompress_function parameters both expect code references. uncompress_function is expected to accept a reference to a .Z compressed string and is expected to return a reference to an uncompressed string. This is required for reading .REP repository records.
compress_function
uncompress_function
compress_function is the exact opposite, it is needed for writing to .REP repositories, accepts a reference to uncompressed data and returns a reference to .Z compressed data.
Currently there is no LZW implementation on www.cpan.org so the current expectation is that you will write a wrapper over /usr/bin/uncompress. A sample wrapper is included farther down in the documentation.
The two parameters filename and handle are complementary. If you supply only a filename then it will be opened for you otherwise pass in an already opened handle to a .REP file via handle.
filename
handle
When called without arguments it returns the ESPPlus::Storage object's stored compress_function code reference. When called with a value, it saves that as the new value.
my $c = $db->compress_function; $db->compress_function( $new_c );
When called without arguments it returns the ESPPlus::Storage object's stored uncompress_function code reference. When called with a value, it saves that as the new value.
my $c = $db->uncompress_function; $db->uncompress_function( $new_c );
When called without arguments it returns the ESPPlus::Storage object's stored filename. When called with a value, it saves that as the new value.
my $f = $db->filename; $db->filename( $new_f );
When called without arguments it returns a stored IO::File object if there is one. If there isn't then it attempts to open one by using filename. When called with a value it saves that as the new value.
IO::File
my $h = $db->handle; $db->handle( $h );
This returns a ESPPlus::Storage::Reader object. This is what reads a .REP database file.
ESPPlus::Storage::Reader
This returns a ESPPlus::Storage::Writer object. This creates .REP database files.
ESPPlus::Storage::Writer
The following function is a sample implementation of a function suitable for passing into <uncompress_function>. our $TempFile = `mktemp /tmp/esp.XXX`; our $Uncompress = "/usr/bin/uncompress"; sub uncompress { my $compressed = shift; { my $out = IO::File->new; sysopen $out, $TempFile, O_WRONLY or die "Couldn't open $TempFile: $!"; flock $out, LOCK_EX or die "Couldn't get an exclusive lock on $TempFile: $!"; truncate $out, 0 or die "Couldn't truncate $TempFile: $!"; binmode $out or die "Could binmode $TempFile: $!"; print $out $$compressed or die "Couldnt write to $TempFile: $!"; close $out or die "Couldn't close $TempFile: $!"; } # add error processing as above my $in = IO::Handle->new; { my $sleep_count = 0; my $pid = open $in, "-|", $Uncompress, '-c', $TempFile or die "Can't exec $Uncompress: $!"; unless (defined $pid) { warn "Cannot fork: $!"; die "Bailing out" if $sleep_count++ > 6; sleep 10; redo; } } local $/; binmode $in or die "Couldn't binmode \$in: $!"; my $uncompressed = <$in>; close $in or warn "$Uncompress exited $?"; return \ $uncompressed; }
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.
ESPPlus::Storage::Reader ESPPlus::Storage::Reader::Tie ESPPlus::Storage::Writer ESPPlus::Storage::Record
To install ESPPlus::Storage, copy and paste the appropriate command in to your terminal.
cpanm
cpanm ESPPlus::Storage
CPAN shell
perl -MCPAN -e shell install ESPPlus::Storage
For more information on module installation, please visit the detailed CPAN module installation guide.