NAME

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

SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::Persistent;
 
 ##========================================================================
 ## disk usage, timestamp
 
 @files = $obj->diskFiles();
 $nbytes = $obj->du();
 $mtime = $obj->mtime();
 $timestamp = $obj->timestamp();
 $bool = $obj->unlink();
 
 ##========================================================================
 ## 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();
 $obj = $CLASS_OR_OBJECT->loadHeaderData($data_or_undef);
 $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 usage, timestamp

diskFiles

 @files = $obj->diskFiles();

returns disk storage files, used by du() and timestamp(). 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.

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)

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 $CLASS_OR_OBJECT->loadHeaderData().

loadHeaderFile

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

wraps $CLASS_OR_OBJECT->loadHeaderData().

loadHeader

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

wraps $CLASS_OR_OBJECT->loadHeaderFile($headerFile//$CLASS_OR_OBJ->headerFile())

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 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

dcdb-create.per(1), dcdb-query.perl(1), dcdb-info.perl(1), dcdb-export.perl(1), dcdb-dump.perl(1), DiaColloDB(3pm), perl(1), ...