DiaColloDB::PackedFile - diachronic collocation db: flat fixed-length record-oriented files
##======================================================================== ## 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);
DiaColloDB::PackedFile provides an object-oriented interface for static fixed-length record sets accessed via direct file I/O.
DiaColloDB::PackedFile inherits from DiaColloDB::Persistent.
$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
$pf = $pf->open(); $pf = $pf->open($file) $pf = $pf->open($file,$flags,%opts)
%opts are as for new(); $file defaults to $pf->{file}.
$bool = $pf->opened();
returns true iff underlying file is opened.
$bool = $pf->close();
close underlying file. Implicitly calls flush() if opened for writing.
$bool = $pf->setsize($nrecords);
set the size of the underlying file to contain $nrecords records.
$bool = $pf->truncate();
truncates $pf->{fh} or $pf->{file}; otherwise a no-nop.
$bool = $pf->flush();
writes header-file and attempts to flush underlying filehandle (may not work on all systems without subsequent close()).
$pf = $pf->setFilters($packfmt); $pf = $pf->setFilters([$packfmt, $unpackfmt]) $pf = $pf->setFilters([\&packsub,\&unpacksub])
%opts : override (but don't clobber) $pf->{packfmt}
$nrecords = $pf->size();
returns number of records in the underlying file.
$bool = $pf->seek($recno);
seek to record-number $recno
$recno = $pf->tell();
report current record-number
$bool = $pf->reset();
reset position to beginning of file
$bool = $pf->seekend();
seek to end-of file
$bool = $pf->eof();
returns true iff current position is end-of-file
$bool = $pf->read(\$buf);
read a raw record into \$buf
$bool = $pf->readraw(\$buf, $nrecords);
batch-reads $nrecords into \$buf
$value_or_undef = $pf->get();
get (unpacked) value of current record, increments filehandle position to next record
\$buf_or_undef = $pf->getraw(\$buf);
get (packed) value of current record, increments filehandle position to next record
$value_or_undef = $pf->fetch($index);
get (unpacked) value of record $index
$buf_or_undef = $pf->fetchraw($index,\$buf);
get (packed) value of record $index
$bool = $pf->write($buf);
write a raw record $buf to current position; increments position
$value_or_undef = $pf->set($value);
set (packed) value of current record, increments filehandle position to next record
$value_or_undef = $pf->store($index,$value);
store (packed) $value as record-number $index
$value_or_undef = $pf->push($value);
store (packed) $value at end of record
\@data = $pf->toArray(%opts);
read entire file contents to an array. %opts : override %$pf:
packas => $packas
$pf = $pf->fromArray(\@data,%opts);
write file contents from a perl array. %opts : override %$pf:
$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()
$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.
$i
unpack($packas,$pf->[$i]) == $key
$ilo <= $j < $i
undef
$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.
$key
$packas
$ilo
$ihi
DiaColloDB::Persistent overrides.
@files = $obj->diskFiles();
returns disk storage files, used by du() and timestamp().
@keys = $coldb->headerKeys();
keys to save as header
See also DiaColloDB::Persistent.
$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)
$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)
$tied = tie(@array, $CLASS, $file, $flags, %opts); $tied = $CLASS->TIEARRAY($file, $flags, %opts);
Transparently tie a DiaColloDB::PackedFile object to a perl array.
write mmap subclass
Bryan Jurish <moocow@cpan.org>
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.
DiaColloDB::Persistent(3pm), DiaColloDB(3pm), perl(1), ...
To install DiaColloDB, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DiaColloDB
CPAN shell
perl -MCPAN -e shell install DiaColloDB
For more information on module installation, please visit the detailed CPAN module installation guide.