NAME

DiaColloDB::PackedFile - diachronic collocation db: flat fixed-length record-oriented files

SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::PackedFile;
 
 ##========================================================================
 ## Constructors etc.
 
 $pf = $CLASS_OR_OBJECT->new(%opts);
 
 ##========================================================================
 ## API: open/close
 
 $pf   = $pf->open();
 $bool = $pf->opened();
 $bool = $pf->close();
 $bool = $pf->setsize($nrecords);
 $bool = $pf->truncate();
 $bool = $pf->flush();
 
 ##========================================================================
 ## API: filters
 
 $pf = $pf->setFilters($packfmt);
 
 ##========================================================================
 ## API: positioning
 
 $nrecords = $pf->size();
 $bool  = $pf->seek($recno);
 $recno = $pf->tell();
 $bool  = $pf->reset();
 $bool  = $pf->seekend();
 $bool  = $pf->eof();
 
 ##========================================================================
 ## API: record access: read
 
 $bool = $pf->read(\$buf);
 $bool = $pf->readraw(\$buf, $nrecords);
 
 $value_or_undef = $pf->get();
 \$buf_or_undef  = $pf->getraw(\$buf);
 
 $value_or_undef = $pf->fetch($index);
 $buf_or_undef   = $pf->fetchraw($index,\$buf);
 
 ##========================================================================
 ## API: record access: write
 
 $bool = $pf->write($buf)
 
 $value_or_undef = $pf->set($value);
 $value_or_undef = $pf->store($index,$value);
 $value_or_undef = $pf->push($value);
 
 ##========================================================================
 ## API: batch I/O
 
 \@data = $pf->toArray(%opts);
 $pf    = $pf->fromArray(\@data,%opts);
 
 $pdl   = $pf->toPdl(%opts);
 
 ##========================================================================
 ## API: binary search
 
 $index_or_undef = $pf->bsearch($key, %opts);
 
 ##========================================================================
 ## disk usage, timestamp, etc
 
 @files = $obj->diskFiles();
 
 ##========================================================================
 ## I/O: header
 
 @keys = $coldb->headerKeys();
 
 ##========================================================================
 ## I/O: text
 
 $bool = $pf->loadTextFh($fh, %opts);
 $bool = $pf->saveTextFh($fh, %opts);
 
 ##========================================================================
 ## API: tie interface
 
 $tied = tie(@array, $CLASS, $file, $flags, %opts);
 $tied = $CLASS->TIEARRAY($file, $flags, %opts);

DESCRIPTION

DiaColloDB::PackedFile provides an object-oriented interface for static fixed-length record sets accessed via direct file I/O.

Globals & Constants

Variable: @ISA

DiaColloDB::PackedFile inherits from DiaColloDB::Persistent.

Constructors etc.

new

 $pf = CLASS_OR_OBJECT->new(%opts);

%opts, %$pf:

 ##-- user options
 file     => $filename,   ##-- default: undef (none)
 flags    => $flags,      ##-- fcntl flags or open-mode (default='r')
 perms    => $perms,      ##-- creation permissions (default=(0666 &~umask))
 reclen   => $reclen,     ##-- record-length in bytes: (default: guess from pack format if available)
 packas   => $packas,     ##-- pack-format or array; see DiaColloDB::Utils::packFilterStore();
 ##
 ##-- filters
 filter_fetch => $filter, ##-- DB_File-style filter for fetch
 filter_store => $filter, ##-- DB_File-style filter for store
 ##
 ##-- low-level data
 fh       => $fh,         ##-- underlying filehandle

API: open/close

open

 $pf = $pf->open();
 $pf = $pf->open($file)
 $pf = $pf->open($file,$flags,%opts)

%opts are as for new(); $file defaults to $pf->{file}.

opened

 $bool = $pf->opened();

returns true iff underlying file is opened.

close

 $bool = $pf->close();

close underlying file. Implicitly calls flush() if opened for writing.

setsize

 $bool = $pf->setsize($nrecords);

set the size of the underlying file to contain $nrecords records.

truncate

 $bool = $pf->truncate();

truncates $pf->{fh} or $pf->{file}; otherwise a no-nop.

flush

 $bool = $pf->flush();

writes header-file and attempts to flush underlying filehandle (may not work on all systems without subsequent close()).

API: filters

setFilters

 $pf = $pf->setFilters($packfmt);
 $pf = $pf->setFilters([$packfmt, $unpackfmt])
 $pf = $pf->setFilters([\&packsub,\&unpacksub])

%opts : override (but don't clobber) $pf->{packfmt}

API: positioning

size

 $nrecords = $pf->size();

returns number of records in the underlying file.

seek

 $bool = $pf->seek($recno);

seek to record-number $recno

tell

 $recno = $pf->tell();

report current record-number

reset

 $bool = $pf->reset();

reset position to beginning of file

seekend

 $bool = $pf->seekend();

seek to end-of file

eof

 $bool = $pf->eof();

returns true iff current position is end-of-file

API: record access: read

read

 $bool = $pf->read(\$buf);

read a raw record into \$buf

readraw

 $bool = $pf->readraw(\$buf, $nrecords);

batch-reads $nrecords into \$buf

get

 $value_or_undef = $pf->get();

get (unpacked) value of current record, increments filehandle position to next record

getraw

 \$buf_or_undef = $pf->getraw(\$buf);

get (packed) value of current record, increments filehandle position to next record

fetch

 $value_or_undef = $pf->fetch($index);

get (unpacked) value of record $index

fetchraw

 $buf_or_undef = $pf->fetchraw($index,\$buf);

get (packed) value of record $index

API: record access: write

write

 $bool = $pf->write($buf);

write a raw record $buf to current position; increments position

set

 $value_or_undef = $pf->set($value);

set (packed) value of current record, increments filehandle position to next record

store

 $value_or_undef = $pf->store($index,$value);

store (packed) $value as record-number $index

push

 $value_or_undef = $pf->push($value);

store (packed) $value at end of record

API: batch I/O

toArray

 \@data = $pf->toArray(%opts);

read entire file contents to an array. %opts : override %$pf:

 packas => $packas

fromArray

 $pf = $pf->fromArray(\@data,%opts);

write file contents from a perl array. %opts : override %$pf:

 packas => $packas

toPdl

 $pdl = $pf->toPdl(%opts);

Returns a flat PDL object representing $pf; currently only supports unary integer pack-templates. Requires PDL and PDL::IO::FastRaw. Supported %opts:

 type => $pdl_type,    ##-- pdl type (default:'auto':guess)
 swap => $bool_or_sub, ##-- byte-swap? (default:'auto':guess)
 mmap => $bool,        ##-- mmap data? (default: 0)
 ...                   ##-- other options passed to DiaColloDB::Utils::readPdlFile()

API: binary search

bsearch

 $index_or_undef = $pf->bsearch($key, %opts);

%opts:

 lo => $ilo,        ##-- index lower-bound for search (default=0)
 hi => $ihi,        ##-- index upper-bound for search (default=size)
 packas => $packas, ##-- key-pack template (default=$pf->{packas})

returns the minimum index $i such that unpack($packas,$pf->[$i]) == $key and $ilo <= $j < $i, or undef if no such $i exists.

$key must be a numeric value, and records must be stored in ascending order by numeric value of key (as unpacked by $packas) between $ilo and $ihi.

disk usage, timestamp, etc

DiaColloDB::Persistent overrides.

diskFiles

 @files = $obj->diskFiles();

returns disk storage files, used by du() and timestamp().

I/O: header

headerKeys

 @keys = $coldb->headerKeys();

keys to save as header

I/O: text

See also DiaColloDB::Persistent.

saveTextFh

 $bool = $pf->saveTextFh($fh, %opts);

save from text file with lines of the form "KEY? VALUE(s)...". %opts:

 keys=>$bool,    ##-- do/don't save keys (default=true)
 key2s=>$key2s,  ##-- code-ref for key formatting, called as $s=$key2s->($key)

loadTextFh

$bool = $pf->loadTextFh($fh, %opts);

Load from text file with lines of the form "KEY? VALUE(s)...". %opts:

 keys=>$bool,     ##-- expect keys in input? (default=true)
 gaps=>$bool,     ##-- expect gaps or out-of-order elements in input? (default=false; implies keys=>1)

API: tie interface

TIEARRAY

 $tied = tie(@array, $CLASS, $file, $flags, %opts);
 $tied = $CLASS->TIEARRAY($file, $flags, %opts);

Transparently tie a DiaColloDB::PackedFile object to a perl array.

TODO

write mmap subclass

AUTHOR

Bryan Jurish <moocow@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2015-2016 by Bryan Jurish

This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.2 or, at your option, any later version of Perl 5 you may have available.

SEE ALSO

DiaColloDB::Persistent(3pm), DiaColloDB(3pm), perl(1), ...

cpanm DiaColloDB

perl -MCPAN -e shell
install DiaColloDB