/ 
DiaColloDB-0.12.020
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 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() ).

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