.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Bio::Root::Storable 3pm"
.TH Bio::Root::Storable 3pm "2012-03-02" "perl v5.14.2" "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 \- object serialisation methods
.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, \fI_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 heirarchy. 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 "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "Mailing Lists"
User feedback is an integral part of the evolution of this and other
Bioperl modules. Send your comments and suggestions preferably to one
of the Bioperl mailing lists.  Your participation is much appreciated.
.PP
.Vb 1
\&  bioperl\-l@bio.perl.org
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
rather than to the module maintainer directly. Many experienced and 
reponsive experts will be able look at the problem and quickly 
address it. Please include a thorough description of the problem 
with code and data examples if at all possible.
.SS "Reporting Bugs"
.IX Subsection "Reporting Bugs"
Report bugs to the Bioperl bug tracking system to help us keep track
the bugs and their resolution. Bug reports can be submitted via the
web:
.PP
.Vb 1
\&  https://redmine.open\-bio.org/projects/bioperl/
.Ve
.SH "AUTHOR \- Will Spooner"
.IX Header "AUTHOR - Will Spooner"
Email whs@sanger.ac.uk
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _
.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 normaly 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