/ 
DiaColloDB-0.12.020
River stage one • 1 direct dependent • 1 total dependent
/ DiaColloDB::PackedFile

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()
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-2020 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), ...