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

=cut

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

=head1 NAME

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

=cut

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

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

=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 usage, timestamp

=over 4

=item diskFiles

 @files = $obj->diskFiles();

returns disk storage files, used by du() and timestamp().
default implementation returns $obj-E<gt>{file} or glob("$obj-E<gt>{base}*").

=item du

 $nbytes = $obj->du();

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

=item mtime

 $mtime = $obj->mtime();

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

=item timestamp

 $timestamp = $obj->timestamp();

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

=item unlink

 $bool = $obj->unlink();

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

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

=item loadHeaderFile

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

wraps $CLASS_OR_OBJECT-E<gt>loadHeaderData().

=item loadHeader

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

wraps $CLASS_OR_OBJECT-E<gt>loadHeaderFile($headerFile//$CLASS_OR_OBJ-E<gt>headerFile())

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



=cut

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

=head1 AUTHOR

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

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

=head1 SEE ALSO

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



=cut
