##========================================================================
## POD DOCUMENTATION, auto-generated by podextract.perl

##========================================================================
## NAME
=pod

=head1 NAME

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

=cut

##========================================================================
## SYNOPSIS
=pod

=head1 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);
 

=cut

##========================================================================
## DESCRIPTION
=pod

=head1 DESCRIPTION

DiaColloDB::Persistent is a generic base class for persistent objects
in the L<DiaColloDB|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.

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Persistent: Globals & Constants
=pod

=head2 Globals & Constants

=over 4

=item Variable: @ISA

DiaColloDB::Persistent
inherits from L<DiaColloDB::Logger|DiaColloDB::Logger>.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Persistent: disk usage, timestamp
=pod

=head2 Disk File Access

=over 4

=item diskFiles

 @files = $obj->diskFiles();

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

=item du

 $nbytes = $obj->du();

default implementation wraps
L<DiaColloDB::Utils::du_file($obj-E<gt>diskFiles)|DiaColloDB::Utils/du_file>.

=item mtime

 $mtime = $obj->mtime();

default returns newest mtime for L<$obj-E<gt>diskFiles()|/diskFiles>.

=item timestamp

 $timestamp = $obj->timestamp();

default returns C<L<DiaColloDB::Utils::timestamp|DiaColloDB::Utils/timestamp>( $obj-E<gt>L<mtime|/mtime>() )>.

=item unlink

 $bool = $obj->unlink();

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

=item copyto

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

Copies object file(s) to C<$todir>, creating C<$todir> if it doesn't already exist;
wraps L<DiaColloDB::Utils::copyto()|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

=item copyto_a

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

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

=item moveto

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

Wrapper for L<|/copyto> which moves the underlying file(s) to C<$todir>
using L<DiaColloDB::Utils::moveto()|DiaColloDB::Utils/moveto>.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Persistent: I/O: Header
=pod

=head2 I/O: Header

=over 4

=item headerKeys

 @keys = $obj->headerKeys();

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

=item headerData

 $hdr = $obj->headerData();

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

=item headerFile

 $filename = $obj->headerFile();

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

=item saveHeaderString

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

returns JSON string for object header data

=item saveHeaderFile

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

Save object JSON header to $filename_or_handle.

=item saveHeaderFh

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

Save object JSON header to $fh.

=item saveHeader

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

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

=item readHeaderFile

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

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

=item readHeader

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

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

=item 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-E<gt>{class}=ref($obj).

=item loadHeaderString

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

loads header data from JSON string $string;
wraps the L<loadHeaderData|/loadHeaderData>()
and L<readHeader|/readHeader>() methods.

=item loadHeaderFile

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

loads header data from C<$filename_or_handle>;
wraps the L<loadHeaderData|/loadHeaderData>()
and L<readHeader|/readHeader>() methods.


=item loadHeader

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

loads header data from the default header file or C<$headerFile>;
wraps the L<loadHeaderData|/loadHeaderData>()
and L<readHeader|/readHeader>() methods.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Persistent: I/O: JSON
=pod

=head2 I/O: JSON

=over 4

=item TO_JSON

 $thingy = $obj->TO_JSON();

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

=item saveJsonString

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

wraps DiaColloDB::Utils::saveJsonString().

=item saveJsonFile

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

wraps DiaColloDB::Utils::saveJsonFile();

=item loadJsonData

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

guts for loadJsonString(), loadJsonFile()

=item loadJsonString

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

=item loadJsonFile

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

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

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Persistent: I/O: Text
=pod

=head2 I/O: Text

=over 4

=item saveTextFh

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

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

=item saveTextFile

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

wraps saveTextFh()

=item 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)

=item loadTextFile

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

wraps loadTextFh()

=back

=cut

##========================================================================
## END POD DOCUMENTATION, auto-generated by podextract.perl

##======================================================================
## Footer
##======================================================================
=pod

=head1 AUTHOR

Bryan Jurish E<lt>moocow@cpan.orgE<gt>

=head1 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.

=head1 SEE ALSO

L<DiaColloDB::Logger(3pm)|DiaColloDB::Logger>,
L<DiaColloDB::EnumFile(3pm)|DiaColloDB::EnumFile>,
L<DiaColloDB::MultiMapFile(3pm)|DiaColloDB::MultiMapFile>,
L<DiaColloDB::PackedFile(3pm)|DiaColloDB::PackedFile>,
L<DiaColloDB::Relation(3pm)|DiaColloDB::Relation>,
L<DiaColloDB(3pm)|DiaColloDB>,
L<perl(1)|perl>,
...



=cut
