.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::Root::Storable 3pm"
.TH Bio::Root::Storable 3pm "2020-10-28" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::Root::Storable \- Safely store/retrieve objects from disk
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  my $storable = Bio::Root::Storable\->new();
\&
\&  # Store/retrieve using class retriever
\&  my $token     = $storable\->store();
\&  my $storable2 = Bio::Root::Storable\->retrieve( $token );
\&
\&  # Store/retrieve using object retriever
\&  my $storable2 = $storable\->new_retrievable();
\&  $storable2\->retrieve();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Generic module that allows objects to be safely stored/retrieved from
disk.  Can be inhereted by any BioPerl object. As it will not usually
be the first class in the inheretence list, \fB_initialise_storable()\fR
should be called during object instantiation.
.PP
Object storage is recursive; If the object being stored contains other
storable objects, these will be stored separately, and replaced by a
skeleton object in the parent hierarchy. When the parent is later
retrieved, its children remain in the skeleton state until explicitly
retrieved by the parent. This lazy-retrieve approach has obvious
memory efficiency benefits for certain applications.
.PP
By default, objects are stored in binary format (using the Perl
Storable module). Earlier versions of Perl5 do not include Storable as
a core module. If this is the case, \s-1ASCII\s0 object storage (using the
Perl Data::Dumper module) is used instead.
.PP
\&\s-1ASCII\s0 storage can be enabled by default by setting the value of
\&\f(CW$Bio::Root::Storable::BINARY\fR to false.
.SH "AUTHOR Will Spooner"
.IX Header "AUTHOR Will Spooner"
.SS "new"
.IX Subsection "new"
.Vb 8
\&  Arg [1]   : \-workdir  => filesystem path,
\&              \-template => tmpfile template,
\&              \-suffix   => tmpfile suffix,
\&  Function  : Builds a new Bio::Root::Storable inhereting object
\&  Returntype: Bio::Root::Storable inhereting object
\&  Exceptions:
\&  Caller    :
\&  Example   : $storable = Bio::Root::Storable\->new()
.Ve
.SS "_initialise_storable"
.IX Subsection "_initialise_storable"
.Vb 6
\&  Arg [1]   : See \*(Aqnew\*(Aq method
\&  Function  : Initialises storable\-specific attributes
\&  Returntype: boolean
\&  Exceptions:
\&  Caller    :
\&  Example   :
.Ve
.SS "statefile"
.IX Subsection "statefile"
.Vb 8
\&  Arg [1]   : string (optional)
\&  Function  : Accessor for the file to write state into.
\&              Should not normally use as a setter \- let Root::IO
\&              do this for you.
\&  Returntype: string
\&  Exceptions:
\&  Caller    : Bio::Root::Storable\->store
\&  Example   : my $statefile = $obj\->statefile();
.Ve
.SS "workdir"
.IX Subsection "workdir"
.Vb 6
\&  Arg [1]   : string (optional) (TODO \- convert to array for x\-platform)
\&  Function  : Accessor for the statefile directory. Defaults to File::Spec\->tmpdir
\&  Returntype: string
\&  Exceptions:
\&  Caller    :
\&  Example   : $obj\->workdir(\*(Aq/tmp/foo\*(Aq);
.Ve
.SS "template"
.IX Subsection "template"
.Vb 6
\&  Arg [1]   : string (optional)
\&  Function  : Accessor for the statefile template. Defaults to XXXXXXXX
\&  Returntype: string
\&  Exceptions:
\&  Caller    :
\&  Example   : $obj\->workdir(\*(AqRES_XXXXXXXX\*(Aq);
.Ve
.SS "suffix"
.IX Subsection "suffix"
.Vb 6
\&  Arg [1]   : string (optional)
\&  Function  : Accessor for the statefile template.
\&  Returntype: string
\&  Exceptions:
\&  Caller    :
\&  Example   : $obj\->suffix(\*(Aq.state\*(Aq);
.Ve
.SS "new_retrievable"
.IX Subsection "new_retrievable"
.Vb 10
\&  Arg [1]   : Same as for \*(Aqnew\*(Aq
\&  Function  : Similar to store, except returns a \*(Aqskeleton\*(Aq of the calling
\&              object, rather than the statefile.
\&              The skeleton can be repopulated by calling \*(Aqretrieve\*(Aq. This
\&              will be a clone of the original object.
\&  Returntype: Bio::Root::Storable inhereting object
\&  Exceptions:
\&  Caller    :
\&  Example   : my $skel = $obj\->new_retrievable(); # skeleton
\&              $skel\->retrieve();                  # clone
.Ve
.SS "retrievable"
.IX Subsection "retrievable"
.Vb 7
\&  Arg [1]   : none
\&  Function  : Reports whether the object is in \*(Aqskeleton\*(Aq state, and the
\&              \*(Aqretrieve\*(Aq method can be called.
\&  Returntype: boolean
\&  Exceptions:
\&  Caller    :
\&  Example   : if( $obj\->retrievable ){ $obj\->retrieve }
.Ve
.SS "token"
.IX Subsection "token"
.Vb 7
\&  Arg [1]   : None
\&  Function  : Accessor for token attribute
\&  Returntype: string. Whatever retrieve needs to retrieve.
\&              This base implementation returns the statefile
\&  Exceptions:
\&  Caller    :
\&  Example   : my $token = $obj\->token();
.Ve
.SS "store"
.IX Subsection "store"
.Vb 5
\&  Arg [1]   : none
\&  Function  : Saves a serialised representation of the object structure
\&              to disk. Returns the name of the file that the object was
\&              saved to.
\&  Returntype: string
\&
\&  Exceptions:
\&  Caller    :
\&  Example   : my $token = $obj\->store();
.Ve
.SS "serialise"
.IX Subsection "serialise"
.Vb 11
\&  Arg [1]   : none
\&  Function  : Prepares the the serialised representation of the object.
\&              Object attribute names starting with \*(Aq_\|_\*(Aq are skipped.
\&              This is useful for those that do not serialise too well
\&              (e.g. filehandles).
\&              Attributes are examined for other storable objects. If these
\&              are found they are serialised separately using \*(Aqnew_retrievable\*(Aq
\&  Returntype: string
\&  Exceptions:
\&  Caller    :
\&  Example   : my $serialised = $obj\->serialise();
.Ve
.SS "retrieve"
.IX Subsection "retrieve"
.Vb 8
\&  Arg [1]   : string; filesystem location of the state file to be retrieved
\&  Function  : Retrieves a stored object from disk.
\&              Note that the retrieved object will be blessed into its original
\&              class, and not the
\&  Returntype: Bio::Root::Storable inhereting object
\&  Exceptions:
\&  Caller    :
\&  Example   : my $obj = Bio::Root::Storable\->retrieve( $token );
.Ve
.SS "clone"
.IX Subsection "clone"
.Vb 6
\&  Arg [1]   : none
\&  Function  : Returns a clone of the calling object
\&  Returntype: Bio::Root::Storable inhereting object
\&  Exceptions:
\&  Caller    :
\&  Example   : my $clone = $obj\->clone();
.Ve
.SS "remove"
.IX Subsection "remove"
.Vb 6
\&  Arg [1]   : none
\&  Function  : Clears the stored object from disk
\&  Returntype: boolean
\&  Exceptions:
\&  Caller    :
\&  Example   : $obj\->remove();
.Ve
.SS "_freeze"
.IX Subsection "_freeze"
.Vb 8
\&  Arg [1]   : variable
\&  Function  : Converts whatever is in the the arg into a string.
\&              Uses either Storable::freeze or Data::Dumper::Dump
\&              depending on the value of $Bio::Root::BINARY
\&  Returntype:
\&  Exceptions:
\&  Caller    :
\&  Example   :
.Ve
.SS "_thaw"
.IX Subsection "_thaw"
.Vb 10
\&  Arg [1]   : string
\&  Function  : Converts the string into a perl \*(Aqwhatever\*(Aq.
\&              Uses either Storable::thaw or eval depending on the
\&              value of $Bio::Root::BINARY.
\&              Note; the string arg should have been created with
\&              the _freeze method, or strange things may occur!
\&  Returntype: variable
\&  Exceptions:
\&  Caller    :
\&  Example   :
.Ve