ext/Storable/Storable.pm

10 package Storable; @ISA = qw(Exporter DynaLoader);
52     Storable::init_perinterp();
60 $Storable::downgrade_restricted = 1;
61 $Storable::accept_future_minor = 1;
62 bootstrap Storable;
94 # To recognize the data files of the Perl module Storable,
98 0	string	perl-store	perl Storable(v0.6) data
104 0	string	pst0	perl Storable(v0.7) data
198 			logcarp "Storable::lock_store: fcntl/flock emulation broken on $^O";
322 			logcarp "Storable::lock_store: fcntl/flock emulation broken on $^O";
374 Storable - persistence for Perl data structures
378  use Storable;
382  use Storable qw(nstore store_fd nstore_fd freeze thaw dclone);
402  use Storable qw(lock_store lock_nstore lock_retrieve)
409 The Storable package brings persistence to your Perl data structures
454 Storable and directly store your objects by invoking C<store> as
463 The Storable engine can also store data into a Perl scalar instead, to
479 Storable provides you with a C<dclone> interface which does not create
503 The heart of Storable is written in C for decent speed. Extra low-level
509 Normally, Storable stores elements of hashes in the order they are
511 C<$Storable::canonical> to some C<TRUE> value, Storable will store
522 Since Storable version 2.05, CODE references may be serialized with
524 C<$Storable::Deparse> to a true value. To enable deserializazion,
525 C<$Storable::Eval> should be set to a true value. Be aware that
527 Storable file contains malicious data. You can set C<$Storable::Eval>
532 If C<$Storable::Deparse> and/or C<$Storable::Eval> are set to false
533 values, then the value of C<$Storable::forgive_me> (see below) is
538 This release of Storable can be used on a newer version of Perl to
540 Storable will attempt to do the right thing, by C<croak()>ing if it
551 Storable serializes them as utf8.  By default, if an older version of
553 To change this behaviour so that Storable deserializes utf8 encoded
555 set C<$Storable::drop_utf8> to some C<TRUE> value.  This is a form of
564 By default, when Storable encounters a restricted hash on a perl
567 all values unlocked.  To make Storable C<croak()> instead, set
568 C<$Storable::downgrade_restricted> to a C<FALSE> value.  To restore
571 =item files from future versions of Storable
573 Earlier versions of Storable would immediately croak if they encountered
574 a file with a higher internal version number than the reading Storable
577 format.  This meant that a newer Storable module had no way of writing a
578 file readable by an older Storable, even if the writer didn't store newer
581 This version of Storable will defer croaking until it encounters a data
583 continue to read files generated by newer Storable modules which are careful
584 in what they write out, making it easier to upgrade Storable modules in a
588 C<$Storable::accept_future_minor> to some C<FALSE> value.
597 Storable uses the "exception" paradigm, in that it does not try to workaround
602 When Storable croaks, it tries to report the error via the C<logcroak()>
648 extra references that you wish to let the Storable engine serialize.
654 return an empty list.  That will signal the Storable engine to further
674 Wrong: the Storable engine creates an empty one for you.  If you know Eiffel,
685 have been processed courtesy of the Storable engine).
687 When the Storable engine does not find any C<STORABLE_thaw> hook routine,
703 them with the Storable package name.
707 =item C<Storable::last_op_in_netorder>
709 The C<Storable::last_op_in_netorder()> predicate will tell you whether
713 =item C<Storable::is_storing>
717 =item C<Storable::is_retrieving>
725 With hooks comes the ability to recurse back to the Storable engine.
726 Indeed, hooks are regular Perl code, and Storable is convenient when
768 aimed to replace Storable's dclone() some day.  However, it does not currently
769 support Storable hooks to redefine the way deep cloning is performed.
771 =head1 Storable magic
781 STDOUT by invoking Storable::show_file_magic().  Note that the GNU
783 is expected to contain support for recognising Storable files
788 Here are some code samples showing a possible usage of Storable:
790 	use Storable qw(store retrieve freeze thaw dclone);
816 	use Storable qw(freeze thaw);
822 	local $Storable::Deparse = 1;
823 	local $Storable::Eval = sub { $safe->reval($_[0]) };
850 descriptors that you pass to Storable functions.
862 for those operations, feel free to enhance Storable so that it can
866 unless you set C<$Storable::forgive_me> to some C<TRUE> value. In that
870 Setting C<$Storable::canonical> may not yield frozen strings that
882 As Storable neither knows nor cares about character sets (although it
890 C<Storable::drop_utf8> is a blunt tool.  There is no facility either to
894 Prior to Storable 2.01, no distinction was made between signed and
895 unsigned integers on storing.  By default Storable prefers to store a
905 by Storable 2.02 or earlier on perl 5.6.0 or 5.6.1 on Unix or Linux which
912 Storable writes a file header which contains the sizes of various C
913 language types for the C compiler that built Storable (when not writing in
914 network order), and will refuse to load files written by a Storable not
926 Storable generates its header, nothing in the Storable file header reflected
928 that Storable was storing some data differently in the file.  Hence Storable
934 Storable has now been changed to write out and read in a file header with
938 backwards compatibility mode.  Hence this Storable defaults to the new,
941 What this means is that if you have data written by Storable 1.x running
943 then by default this Storable will refuse to read it, giving the error
945 should set C<$Storable::interwork_56_64bit> to a true value to make this
946 Storable read and write files with the old header.  You should also
948 current version of Storable.
952 not only will Storable on an identically configured perl refuse to load them,
953 but Storable a differently configured perl will load them believing them
982 a binary incompatibility for the Storable image starting at version
984 Murray Nesbitt made Storable thread-safe.  Marc Lehmann added overloading
989 Storable was written by Raphael Manfredi F<E<lt>Raphael_Manfredi@pobox.comE<gt>>
995 Storable, and your message will be delayed while he forwards it to us.