NAME

DTA::CAB::Persistent - abstract class for persistent & configurable objects

SYNOPSIS

 use DTA::CAB::Persistent;
 
 ##========================================================================
 ## Constructors etc.
 
 $obj = $obj->clone();
 
 ##========================================================================
 ## Methods: Persistence: Perl
 
 @keys = $class_or_obj->noSaveKeys();
 $saveRef = $obj->savePerlRef();
 $loadedObj = $CLASS_OR_OBJ->loadPerlRef($ref);
 
 $rc = $obj->savePerlFile($filename_or_fh, @args);
 $obj = $CLASS_OR_OBJ->loadPerlFile($filename_or_fh, %args);
 
 $str = $obj->savePerlString(%args);
 $obj = $CLASS_OR_OBJ->loadPerlString($str,%args);
 
 ##========================================================================
 ## Methods: Persistence: Binary
 
 @keys = $class_or_obj->noSaveBinKeys();
 $saveRef = $obj->saveBinRef();
 $loadedObj = $CLASS_OR_OBJ->loadBinRef($ref);
 
 $rc = $obj->saveBinFile($filename_or_fh, @args);
 $obj = $CLASS_OR_OBJ->loadBinFile($filename_or_fh, %args);
 
 $str = $obj->saveBinString(%args);
 $obj = $CLASS_OR_OBJ->loadBinString($str,%args);
 
 ##========================================================================
 ## Methods: Persistence: Generic
 
 $mode = $CLASS_OR_OBJ->guessFileMode($filename);
 
 $rc = $obj->saveFile($filename_or_fh, %args);
 $obj = $CLASS_OR_OBJ->loadFile($filename_or_fh, %args);
 
 $str = $obj->saveString(%args);
 $obj = $CLASS_OR_OBJ->loadString($str,%args);

DESCRIPTION

Constructors etc.

clone

 $obj = $obj->clone();

Deep clone using Storable::dclone().

Methods: Persistence: Perl

noSaveKeys

 @keys = $class_or_obj->noSaveKeys();

Should returns list of object keys not to be saved on "savePerlRef"() (e.g. CODE-refs and anything else which Data::Dumper and/or Storable::Storable can't handle).

Default implementation just returns an empty list.

savePerlRef

 $saveRef = $obj->savePerlRef();

Return a reference to be saved. Default implementation assumes $obj is HASH-ref

loadPerlRef

 $loadedObj = $CLASS_OR_OBJ->loadPerlRef($ref);

Returns an object-reference constructed from the saved representation $ref, which should be a reference as returned by "savePerlRef". Default implementation just clobbers $CLASS_OR_OBJ with $ref and blesses it.

savePerlFile

 $rc = $obj->savePerlFile($filename_or_fh, @args);

Save $obj as perl code to $filename_or_fh. Calls $obj->savePerlString(@args)

loadPerlFile

 $obj = $CLASS_OR_OBJ->loadPerlFile($filename_or_fh, %args);

Load a (new) object from perl code in $filename_or_fh. Calls $CLASS_OR_OBJ->loadPerlString(var=>undef,src=>$filename_or_fh, %args).

savePerlString

 $str = $obj->savePerlString(%args);

Save $obj as perl code, returns perl code string.

Known %args:

 var => $perl_var_name,  ##-- default=$obj

loadPerlString

 $obj = $CLASS_OR_OBJ->loadPerlString($str,%args);

Load an object from a perl code string $str. Returns new object.

Known %args:

 var=>$perl_var_name, ##-- default='$index'
 src=>$src_name,      ##-- default=(substr($str,0,42).'...')
 %more_obj_args,      ##-- literally inserted into $obj

Methods: Persistence: Binary

noSaveBinKeys

 @keys = $class_or_obj->noSaveKeys();

Should returns list of object keys not to be saved on "saveBinRef"() (e.g. CODE-refs and anything else which Storable can't handle).

Default implementation just returns an empty list.

saveBinRef

 $saveRef = $obj->saveBinRef();

Return a reference to be saved in binary mode. Default implementation assumes $obj is HASH-ref

loadBinRef

 $loadedObj = $CLASS_OR_OBJ->loadBinRef($ref);

Just a wrapper for the local "loadPerlRef" method, used for binary loading (in case sub-classes override loadPerlRef()).

saveBinFile

 $rc = $obj->saveBinFile($filename_or_fh, %args);

Save binary $obj to $filename_or_fh using Storable module Calls $obj->saveBinFh(%args)

loadBinFile

 $obj = $CLASS_OR_OBJ->loadBinFile($filename_or_fh, %args);

Load a (new) object from binary file or handle $filename_or_fh. Calls $CLASS_OR_OBJ->loadBinFh($fh,%args).

saveBinString

 $str = $obj->saveBinString(%args);

Returns binary byte-string representing $obj. Calls $CLASS_OR_OBJ->saveBinFh($fh,%args).

loadBinString

 $obj = $CLASS_OR_OBJ->loadBinString($str,%args);

Load an object from a binary string $str. Returns new object.

saveBinFh

 $str = $obj->saveBinFh($fh,%args);

Save binary format $obj to filehandle $fh.

Known %args:

 netorder => $bool,  ##-- if true (default), save data in "network" order where possible

loadBinFh

 $obj = $CLASS_OR_OBJ->loadBinFh($fh,%args);

Load an object from a binary filehandle $fh. Returns new object.

Methods: Persistence: Generic

The I/O methods documented in this section recognize the following keyword %args:

 mode  => $mode,  ##-- one of: 'bin' or 'perl' (default: guessFileMode($file))
 file  => $file,  ##-- any filename, used to guess mode

guessFileMode

 $mode = $CLASS_OR_OBJ->guessFileMode($filename)

Guess I/O mode ('bin' or 'perl') from a filename.

saveFile

 $obj_or_undef = $obj->saveFile($filename_or_fh,%args)

Save to a generic filename or handle $filename_or_fh.

loadFile

 $loaded_obj = $CLASS_OR_OBJ->loadFile($filename_or_fh,%args)

Load from a generic filename or handle $filename_or_fh.

saveString

 $str = $obj->saveString(%args)

Save to a generic string.

loadString

 $loaded_obj = $CLASS_OR_OBJ->loadString($str,%args)

Load from a generic string $str.

AUTHOR

Bryan Jurish <moocow@cpan.org>

COPYRIGHT AND LICENSE

This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.24.1 or, at your option, any later version of Perl 5 you may have available.