NAME

DiaColloDB::Persistent - diachronic collocation db, generic persistent objects

SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::Persistent;
 
 ##========================================================================
 ## Disk File Access
 
 @files     = $obj->diskFiles();
 $nbytes    = $obj->du();
 $mtime     = $obj->mtime();
 $timestamp = $obj->timestamp();
 $bool      = $obj->unlink();
 $bool      = $obj->copyto($todir,%opts);
 $bool      = $obj->copyto_a($todir,%opts);
 $bool      = $obj->moveto($todir,%opts);
 
 ##========================================================================
 ## I/O: Header
 
 @keys = $obj->headerKeys();
 $hdr = $obj->headerData();
 $filename = $obj->headerFile();
 
 $str = $obj->saveHeaderString(%opts);
 $bool = $obj->saveHeaderFile($filename_or_handle, %opts);
 $bool = $obj->saveHeader();
 
 $hdr = $CLASS_OR_OBJECT->readHeaderFile($filename_or_handle, %opts);
 $hdr = $CLASS_OR_OBJECT->readHeader();
 $obj = $CLASS_OR_OBJECT->loadHeaderData($data_or_undef);
 $obj = $CLASS_OR_OBJECT->loadHeaderString($string,%opts);
 $obj = $CLASS_OR_OBJECT->loadHeaderFile($filename_or_handle, %opts);
 $bool = $CLASS_OR_OBJECT->loadHeader();
 
 ##========================================================================
 ## I/O: JSON
 
 $thingy = $obj->TO_JSON();
 $str = $obj->saveJsonString(%opts);
 $bool = $obj->saveJsonFile($filename_or_handle, %opts);
 $obj = $CLASS_OR_OBJECT->loadJsonData( $data,%opts);
 $obj = $CLASS_OR_OBJECT->loadJsonString( $string,%opts);
 $obj = $CLASS_OR_OBJECT->loadJsonFile($filename_or_handle,%opts);
 
 ##========================================================================
 ## I/O: Text
 
 $bool = $obj->saveTextFh($fh, %opts);
 $bool = $obj->saveTextFile($filename_or_handle, %opts);
 $obj = $CLASS_OR_OBJECT->loadTextFh($fh, %opts);
 $bool = $CLASS_OR_OBJECT->loadTextFile($filename_or_handle, %opts);
 

DESCRIPTION

DiaColloDB::Persistent is a generic base class for persistent objects in the DiaColloDB class hierarchy. It provides flexible methods for determining disk usage and file timestamps, text I/O, and object metadata I/O via JSON header files.

Globals & Constants

Variable: @ISA

DiaColloDB::Persistent inherits from DiaColloDB::Logger.

Disk File Access

diskFiles

 @files = $obj->diskFiles();

Returns disk storage files, used by du(), timestamp(), etc. Default implementation returns $obj->{file} or glob("$obj->{base}*").

du

 $nbytes = $obj->du();

default implementation wraps DiaColloDB::Utils::du_file($obj->diskFiles).

mtime

 $mtime = $obj->mtime();

default returns newest mtime for $obj->diskFiles().

timestamp

 $timestamp = $obj->timestamp();

default returns DiaColloDB::Utils::timestamp( $obj->mtime() ).

unlink

 $bool = $obj->unlink();

unlinks disk files; implcitly calls $obj->close() if available.

copyto

 $bool = $obj->copyto($todir, %opts)

Copies object file(s) to $todir, creating $todir if it doesn't already exist; wraps DiaColloDB::Utils::copyto(). Options %opts:

 method => \&method,   ##-- use CODE-ref \&method(\@srcfiles,$todir,%opts) to copy file(s) (default=\&DiaColloDB::Utils::copyto)
 close  => $bool,      ##-- implicitly close() object before operation? (default=0)
 #...                  ##-- other options are passed to \&method

copyto_a

 $bool = $obj->copyto_a($todir, %opts)

Wrapper for which attempts to preserve timestamps, ownership and permissions of the copied file(s) using DiaColloDB::Utils::copyto_a().

moveto

 $bool = $obj->moveto_a($todir, %opts)

Wrapper for which moves the underlying file(s) to $todir using DiaColloDB::Utils::moveto().

I/O: Header

headerKeys

 @keys = $obj->headerKeys();

keys to save as header; default implementation returns all keys of all non-references.

headerData

 $hdr = $obj->headerData();

returns reference to object header data; default returns anonymous HASH-ref for $obj->headerKeys()

headerFile

 $filename = $obj->headerFile();

returns header filename; default returns "$obj->{base}.hdr" or "$obj->{dbdir}/header.json"

saveHeaderString

 $str = $obj->saveHeaderString(%opts);

returns JSON string for object header data

saveHeaderFile

 $bool = $obj->saveHeaderFile($filename_or_handle, %opts);

Save object JSON header to $filename_or_handle.

saveHeaderFh

 $bool = $obj->saveHeaderFh  ($fh, %opts);

Save object JSON header to $fh.

saveHeader

 $bool = $obj->saveHeader();
 $bool = $obj->saveHeader($headerFile,%opts);

wraps $obj->saveHeaderFile($headerFile//$obj->headerFile(), %opts)

readHeaderFile

 $hdr = $CLASS_OR_OBJECT->readHeaderFile($filename_or_handle, %opts);
 $hdr = $CLASS_OR_OBJECT->readHeaderFh  ($filename_or_handle, %opts);

wraps DiaColloDB::Utils::loadJsonFile($filename_or_handle, %opts): reads and decodes JSON header data from $filename_or_handle and returns the resulting structure without loading any data into the calling object.

readHeader

 $hdr = $CLASS_OR_OBJECT->readHeader();
 $hdr = $CLASS_OR_OBJECT->readHeader($headerFile,%opts);

wraps $CLASS_OR_OBJECT->readHeaderFile($headerFile//$CLASS_OR_OBJ->headerFile()): reads and decodes JSON header data from the default header-file and returns the result without loading any data into the calling object.

loadHeaderData

 $obj = $CLASS_OR_OBJECT->loadHeaderData($data_or_undef);

instantiates header data from $data; default just sets @$obj{keys %$data} = values %$data and clobbers $obj->{class}=ref($obj).

loadHeaderString

 $obj = $CLASS_OR_OBJECT->loadHeaderString( $string,%opts)
 $obj = $CLASS_OR_OBJECT->loadHeaderString(\$string,%opts)

loads header data from JSON string $string; wraps the loadHeaderData() and readHeader() methods.

loadHeaderFile

 $obj = $CLASS_OR_OBJECT->loadHeaderFile($filename_or_handle, %opts);

loads header data from $filename_or_handle; wraps the loadHeaderData() and readHeader() methods.

loadHeader

 $bool = $CLASS_OR_OBJECT->loadHeader();
 $bool = $CLASS_OR_OBJECT->loadHeader($headerFile,%opts);

loads header data from the default header file or $headerFile; wraps the loadHeaderData() and readHeader() methods.

I/O: JSON

TO_JSON

 $thingy = $obj->TO_JSON();

JSON module wrapper; default just returns anonymous HASH-ref (including non-header keys).

saveJsonString

 $str = $obj->saveJsonString(%opts);

wraps DiaColloDB::Utils::saveJsonString().

saveJsonFile

 $bool = $obj->saveJsonFile($filename_or_handle, %opts);

wraps DiaColloDB::Utils::saveJsonFile();

loadJsonData

 $obj = $CLASS_OR_OBJECT->loadJsonData( $data,%opts);

guts for loadJsonString(), loadJsonFile()

loadJsonString

 $obj = $CLASS_OR_OBJECT->loadJsonString( $string,%opts);
 $obj = $CLASS_OR_OBJECT->loadJsonString(\$string,%opts);

loadJsonFile

 $obj = $CLASS_OR_OBJECT->loadJsonFile($filename_or_handle,%opts);

wraps $CLASS_OR_OBJECT->loadJsonData(DiaColloDB::Utils::loadJsonFile(@_))

I/O: Text

saveTextFh

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

save text representation to a filehandle (abstract method; should be overridden in subclasses supporting text I/O)

saveTextFile

 $bool = $obj->saveTextFile($filename_or_handle, %opts);

wraps saveTextFh()

loadTextFh

 $obj = $CLASS_OR_OBJECT->loadTextFh($fh, %opts);

load object from a text filehandle (abstract method; should be overridden in subclasses supporting text I/O)

loadTextFile

 $bool = $CLASS_OR_OBJECT->loadTextFile($filename_or_handle, %opts);

wraps loadTextFh()

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::Logger(3pm), DiaColloDB::EnumFile(3pm), DiaColloDB::MultiMapFile(3pm), DiaColloDB::PackedFile(3pm), DiaColloDB::Relation(3pm), DiaColloDB(3pm), perl(1), ...