/ 
DiaColloDB-0.09.003
River stage one • 1 direct dependent • 1 total dependent
/ DiaColloDB::Persistent

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();

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

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

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